feat(host/windows): capture the secure desktop in HDR via DDA (no SDR drop)

The secure-desktop DDA leg went black with HDR on: legacy DuplicateOutput (the SDR-era
API) can't capture an FP16/HDR desktop, and dropping the SudoVDA out of HDR is denied on
the Winlogon desktop (so the SDR-drop attempt just churned and stayed black).

Instead capture HDR natively on the DDA path — the capturer already has the full
FP16→BT.2020 PQ→R10G10B10A2 conversion (hdr_fp16 path), it just never requested FP16.
Thread a want_hdr flag into duplicate_output: for an HDR session request
DuplicateOutput1 with FP16 first and retry it (5×) instead of bailing to the
HDR-incapable legacy fallback. The secure-desktop mux now reads the monitor's real HDR
state and opens DDA in HDR when set — no advanced-color toggling at all. The
normal-desktop DDA overlay/flip issues that pushed us to WGC don't apply to the composed
Winlogon UI. want_hdr is threaded through every (re)duplication incl. ACCESS_LOST recovery.

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

.gitea/workflows/android.yml

@@ -0,0 +1,68 @@
+# Android client CI (Gitea Actions). Builds the Rust JNI core (crates/punktfunk-android) via
+# cargo-ndk for both 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).
+name: android
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  android:
+    runs-on: ubuntu-24.04
+    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"
+
+      - 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 x86_64-linux-android
+
+      - name: Android SDK
+        uses: android-actions/setup-android@v3
+
+      - name: NDK r28 LTS + 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.
+        # Keep platforms;android-36 (android-37 isn't in the runner's sdkmanager channel yet —
+        # "Failed to find package"); AGP auto-installs the compileSdk-37 platform during the build.
+        run: sdkmanager "platform-tools" "platforms;android-36" "build-tools;36.0.0" "ndk;28.2.13676358" "cmake;3.22.1"
+
+      - name: Caches (cargo + 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
+
+      - name: assembleDebug (cargo-ndk → jniLibs → APK)
+        working-directory: clients/android
+        run: ./gradlew :app:assembleDebug --stacktrace

.gitea/workflows/audit.yml

@@ -0,0 +1,33 @@
+# Supply-chain advisory scan for the (network-facing, crypto-heavy) Rust dependency tree.
+# Runs `cargo audit` against the RustSec advisory DB: weekly (catch newly-disclosed CVEs in
+# pinned deps), on every Cargo.lock change (catch a bad dep the moment it lands), and on demand.
+# To silence a known-unfixable advisory, add it to `.cargo/audit.toml` ([advisories] ignore = [...]).
+name: audit
+
+on:
+  schedule:
+    - cron: '0 6 * * 1'   # Mondays 06:00 UTC
+  push:
+    branches: [main]
+    paths: ['Cargo.lock', '.gitea/workflows/audit.yml']
+  workflow_dispatch:
+
+jobs:
+  cargo-audit:
+    runs-on: ubuntu-24.04
+    container:
+      image: git.unom.io/unom/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
+          key: cargo-audit-${{ hashFiles('Cargo.lock') }}
+          restore-keys: cargo-audit-
+      - name: cargo audit
+        run: |
+          git config --global --add safe.directory "$PWD"
+          command -v cargo-audit >/dev/null 2>&1 || cargo install --locked cargo-audit
+          cargo audit

.gitea/workflows/bench-gpu.yml

@@ -0,0 +1,32 @@
+# Tier-3 real-world GPU benchmark — the actual capture → zero-copy → NVENC → punktfunk/1 → reassemble
+# pipeline, measuring encode time / throughput / end-to-end latency. The GPU-less CI containers
+# (ci.yml `bench` job) can only run the Tier-1/2 GPU-free benchmarks; this runs on a SELF-HOSTED GPU
+# runner — a dev box with an NVIDIA GPU + a KWin session.
+#
+# Runner setup (one-time, on the GPU box): register a Gitea act_runner with the labels below, e.g.
+#   act_runner register --instance https://git.unom.io --token <REPO_RUNNER_TOKEN> \
+#     --labels gpu:host --name <box>-gpu
+# It runs jobs directly on the host (no container) so it can reach the GPU, PipeWire and the
+# compositor. A persistent KWin session helps (else the script brings up a headless one).
+#
+# Report-only: the script flags regressions vs scripts/bench/gpu-baseline.json but never fails the
+# job. Refresh the baseline on the runner with `scripts/bench/gpu-stream.sh <mode> <secs> --update`.
+name: bench-gpu
+
+on:
+  workflow_dispatch:
+    inputs:
+      mode:
+        description: "stream mode WxHxHz"
+        default: "1920x1080x120"
+  schedule:
+    - cron: "0 6 * * *" # nightly
+
+jobs:
+  gpu-stream:
+    runs-on: [self-hosted, gpu]
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@v4
+      - name: Tier-3 GPU stream benchmark
+        run: bash scripts/bench/gpu-stream.sh "${{ inputs.mode || '1920x1080x120' }}" 12

.gitea/workflows/ci.yml

@@ -42,8 +42,12 @@ jobs:
       - uses: actions/cache@v4
         with:
           path: target
-          key: cargo-target-${{ env.rustc }}-${{ hashFiles('Cargo.lock') }}
+          # -v3-: the prior `cargo-target-<rustc>-*` cache was poisoned when the runner ran
-          restore-keys: cargo-target-${{ env.rustc }}-
+          # out of disk mid-build and actions/cache saved a truncated target/ (a dep's .rmeta
+          # went missing -> E0463 "can't find crate"). A suffix bump wouldn't help — restore-keys
+          # would fall back to the poisoned prefix — so the prefix itself is versioned.
+          key: cargo-target-v3-${{ env.rustc }}-${{ hashFiles('Cargo.lock') }}
+          restore-keys: cargo-target-v3-${{ env.rustc }}-
 
       - name: Format
         run: cargo fmt --all --check
@@ -115,3 +119,25 @@ 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

.gitea/workflows/deb.yml

@@ -13,7 +13,10 @@ name: deb
 on:
   push:
     branches: [main]
-    tags: ['v*']
+    # HOST-scoped tags only. The Apple client uses `v*` (release.yml); those must NOT trigger a
+    # host publish — a `v0.1.1` client tag previously shipped a host package versioned 0.1.1 that
+    # outranked every rolling build (the version-shadow). Host releases use `host-v*`.
+    tags: ['host-v*']
   workflow_dispatch:
 
 env:
@@ -31,6 +34,20 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
+      - name: Version
+        # host-vX.Y.Z tag -> X.Y.Z (a real host release). A main push -> 0.2.0~ciN.g<sha>: the '~'
+        # sorts it BELOW the eventual 0.2.0 tag, it climbs monotonically by run number, AND it sits
+        # ABOVE the stray 0.1.1, so `apt upgrade` truly moves boxes forward. Computed BEFORE the
+        # build so it's stamped into the binary (PUNKTFUNK_BUILD_VERSION -> build.rs -> --version).
+        run: |
+          SHORT=$(echo "$GITHUB_SHA" | cut -c1-8)
+          case "$GITHUB_REF" in
+            refs/tags/host-v*) V="${GITHUB_REF_NAME#host-v}" ;;
+            *)                 V="0.2.0~ci${GITHUB_RUN_NUMBER}.g${SHORT}" ;;
+          esac
+          echo "VERSION=$V" >> "$GITHUB_ENV"
+          echo "package version $V"
+
       # dpkg-shlibdeps (Depends resolution) + dpkg-deb live in dpkg-dev. The client's link
       # deps are also baked into the rust-ci image, but this job runs against the image
       # from the PREVIOUS push (docker.yml bootstrap note) — keep it green across image
@@ -54,31 +71,47 @@ jobs:
       - uses: actions/cache@v4
         with:
           path: target
-          key: cargo-target-${{ env.rustc }}-${{ hashFiles('Cargo.lock') }}
+          # -v3-: bypass a target cache poisoned by a disk-full build (see ci.yml). Shares the
-          restore-keys: cargo-target-${{ env.rustc }}-
+          # key with ci.yml so the release build reuses its clean artifacts.
+          key: cargo-target-v3-${{ env.rustc }}-${{ hashFiles('Cargo.lock') }}
+          restore-keys: cargo-target-v3-${{ env.rustc }}-
 
       - name: Build release host + client
+        env:
+          PUNKTFUNK_BUILD_VERSION: ${{ env.VERSION }}   # stamped into the binary (build.rs)
         run: |
           git config --global --add safe.directory "$PWD"
           cargo build --release -p punktfunk-host -p punktfunk-client-linux --locked
 
-      - name: Version
+      - name: Build + smoke-boot web console (node-server preset)
-        # Tag v1.2.3 -> 1.2.3 (a real release); a main push -> 0.0.1~ciN.g<sha>, which sorts
+        # Gate the .deb on a real node boot: the punktfunk-web .deb runs `node .output/server`,
-        # BEFORE 0.0.1 (the '~') yet monotonically increases by run number, so `apt upgrade`
+        # so prove the node-server build exists, isn't a bun bundle, and actually serves /login.
-        # always moves the boxes to the newest main build.
         run: |
-          SHORT=$(echo "$GITHUB_SHA" | cut -c1-8)
+          # bun builds the console. It's baked into the rust-ci image, but bootstrap it here too so
-          case "$GITHUB_REF" in
+          # the job stays green against the PREVIOUS image (docker.yml bootstrap lag).
-            refs/tags/v*) V="${GITHUB_REF_NAME#v}" ;;
+          command -v bun >/dev/null || {
-            *)            V="0.0.1~ci${GITHUB_RUN_NUMBER}.g${SHORT}" ;;
+            apt-get install -y --no-install-recommends unzip
-          esac
+            curl -fsSL https://bun.sh/install | bash
-          echo "VERSION=$V" >> "$GITHUB_ENV"
+          }
-          echo "package version $V"
+          export PATH="$HOME/.bun/bin:$PATH"
+          cd web
+          bun install --frozen-lockfile
+          bun run build
+          if grep -q 'Bun\.serve' .output/server/index.mjs; then
+            echo "ERROR: web build is a bun bundle (Bun.serve) — need the node-server preset"; exit 1
+          fi
+          PORT=3009 HOST=127.0.0.1 PUNKTFUNK_UI_PASSWORD=ci node .output/server/index.mjs &
+          NP=$!; sleep 3
+          code=$(curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1:3009/login || echo 000)
+          kill "$NP" 2>/dev/null || true
+          echo "web console smoke: /login -> $code"
+          [ "$code" = 200 ] || { echo "ERROR: web console failed to boot under node"; exit 1; }
 
       - name: Build .debs
         run: |
           VERSION="$VERSION" bash packaging/debian/build-deb.sh
           VERSION="$VERSION" bash packaging/debian/build-client-deb.sh
+          VERSION="$VERSION" bash packaging/debian/build-web-deb.sh
 
       - name: Publish to the Gitea apt registry
         env:

.gitea/workflows/decky.yml

@@ -0,0 +1,126 @@
+# Build the punktfunk Decky Loader plugin (Gaming-Mode QAM launcher) into a distribution zip
+# and publish it to Gitea's GENERIC package registry, giving Decky's "install from URL" a
+# stable link. On tags the zip is ALSO attached to the Gitea release.
+#
+#   PUT/GET  https://git.unom.io/api/packages/unom/generic/punktfunk-decky/<version>/punktfunk.zip
+#
+# The plugin backend is PURE PYTHON (clients/decky/main.py — no compiled binary), so we do NOT
+# need the Decky CLI (which requires Docker + rust-nightly only to compile native backends).
+# We build the frontend with pnpm and assemble the store-layout zip by hand:
+#
+#   punktfunk.zip
+#     punktfunk/                  <- single top-level dir == plugin.json "name"
+#       plugin.json   [required]
+#       package.json  [required]
+#       main.py       [required: python backend]
+#       dist/index.js [required: rollup output]
+#       README.md     (recommended)
+#       LICENSE       [required by the plugin store]
+#
+# REGISTRY_TOKEN: repo Actions secret, a PAT with write:package scope (shared with deb/rpm/docker).
+name: decky
+
+on:
+  push:
+    branches: [main]
+    tags: ['v*']
+  workflow_dispatch:
+
+env:
+  REGISTRY: git.unom.io
+  OWNER: unom
+  PACKAGE: punktfunk-decky        # generic-registry package name
+  PLUGIN: punktfunk               # plugin.json "name" == zip top-level dir
+
+jobs:
+  build-publish:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 30
+    container:
+      image: node:22-bookworm     # node + corepack(pnpm); matches the @decky toolchain
+    defaults:
+      run:
+        working-directory: clients/decky
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: pnpm
+        run: |
+          corepack enable
+          # The repo's pnpm-lock.yaml + package.json devDeps target pnpm 9 (the version the
+          # @decky toolchain and the local build use). Pin it so --frozen-lockfile holds.
+          corepack prepare pnpm@9 --activate
+
+      - name: Build frontend
+        run: |
+          pnpm install --frozen-lockfile
+          pnpm run build          # rollup -> clients/decky/dist/index.js
+
+      - name: Version
+        # Tag v1.2.3 -> 1.2.3; main push -> 0.0.1-ciN.g<sha>. Used only for the registry
+        # version path + the zip name (the plugin.json version is the source of truth Decky
+        # reads after install).
+        working-directory: ${{ gitea.workspace }}
+        run: |
+          SHORT=$(echo "$GITHUB_SHA" | cut -c1-8)
+          case "$GITHUB_REF" in
+            refs/tags/v*) V="${GITHUB_REF_NAME#v}" ;;
+            *)            V="0.0.1-ci${GITHUB_RUN_NUMBER}.g${SHORT}" ;;
+          esac
+          echo "VERSION=$V" >> "$GITHUB_ENV"
+          echo "decky version $V"
+
+      - name: Assemble store-layout zip
+        working-directory: ${{ gitea.workspace }}
+        run: |
+          apt-get update && apt-get install -y --no-install-recommends zip >/dev/null
+          STAGE="$RUNNER_TEMP/decky"
+          DEST="$STAGE/$PLUGIN"
+          rm -rf "$STAGE"; mkdir -p "$DEST/dist"
+          cp clients/decky/plugin.json   "$DEST/"
+          cp clients/decky/package.json  "$DEST/"
+          cp clients/decky/main.py       "$DEST/"
+          cp clients/decky/dist/index.js "$DEST/dist/"
+          cp clients/decky/README.md     "$DEST/"
+          # Store requires a LICENSE in the plugin root; the project is MIT OR Apache-2.0.
+          cp LICENSE-MIT                 "$DEST/LICENSE"
+          ( cd "$STAGE" && zip -r "$RUNNER_TEMP/punktfunk.zip" "$PLUGIN" )
+          ls -lh "$RUNNER_TEMP/punktfunk.zip"
+          unzip -l "$RUNNER_TEMP/punktfunk.zip"
+
+      - name: Publish to the Gitea generic registry
+        working-directory: ${{ gitea.workspace }}
+        env:
+          TOKEN: ${{ secrets.REGISTRY_TOKEN }}
+        run: |
+          BASE="https://$REGISTRY/api/packages/$OWNER/generic/$PACKAGE"
+          # 1) Immutable, versioned URL.
+          curl -fsS --user "enricobuehler:$TOKEN" --upload-file "$RUNNER_TEMP/punktfunk.zip" \
+            "$BASE/$VERSION/punktfunk.zip"
+          echo "published $BASE/$VERSION/punktfunk.zip"
+          # 2) Stable `latest/punktfunk.zip` — this is the link to paste into Decky's
+          #    "install from URL". The generic registry rejects re-uploading an existing
+          #    version/file (409), so delete the prior `latest` first (ignore 404 on run #1).
+          curl -fsS -o /dev/null --user "enricobuehler:$TOKEN" -X DELETE \
+            "$BASE/latest/punktfunk.zip" || true
+          curl -fsS --user "enricobuehler:$TOKEN" --upload-file "$RUNNER_TEMP/punktfunk.zip" \
+            "$BASE/latest/punktfunk.zip"
+          echo "install-from-URL link: $BASE/latest/punktfunk.zip"
+
+      - name: Attach zip to the Gitea release (tags only)
+        if: startsWith(gitea.ref, 'refs/tags/')
+        working-directory: ${{ gitea.workspace }}
+        env:
+          TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          API="${{ gitea.server_url }}/api/v1/repos/${{ gitea.repository }}"
+          ID=$(curl -sf -X POST "$API/releases" \
+                 -H "Authorization: token $TOKEN" -H 'Content-Type: application/json' \
+                 -d "{\"tag_name\":\"$GITHUB_REF_NAME\",\"name\":\"$GITHUB_REF_NAME\"}" \
+               | python3 -c 'import json,sys;print(json.load(sys.stdin)["id"])' \
+               || curl -sf "$API/releases/tags/$GITHUB_REF_NAME" -H "Authorization: token $TOKEN" \
+               | python3 -c 'import json,sys;print(json.load(sys.stdin)["id"])')
+          curl -sf -X POST "$API/releases/$ID/assets?name=punktfunk-${VERSION}.zip" \
+            -H "Authorization: token $TOKEN" \
+            -F "attachment=@$RUNNER_TEMP/punktfunk.zip" >/dev/null
+          echo "attached punktfunk-${VERSION}.zip to release $GITHUB_REF_NAME"

.gitea/workflows/docker.yml

@@ -42,6 +42,11 @@ jobs:
           - 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
 
@@ -53,7 +58,7 @@ jobs:
 
       - name: Build
         run: |
-          docker build --pull \
+          docker build --pull ${{ matrix.buildargs }} \
             -f "${{ matrix.dockerfile }}" \
             -t "$REGISTRY/$OWNER/${{ matrix.image }}:latest" \
             -t "$REGISTRY/$OWNER/${{ matrix.image }}:sha-${GITHUB_SHA::8}" \

.gitea/workflows/flatpak.yml

@@ -0,0 +1,143 @@
+# Build the native punktfunk Linux CLIENT as a single-file Flatpak bundle and publish it to
+# Gitea's GENERIC package registry, so the Steam Deck (and any flatpak distro) installs it
+# the SteamOS-native, update-survivable way: `flatpak install --user <downloaded>.flatpak`.
+# (The HOST stays an RPM/deb — it needs unsandboxed /dev/uinput + zero-copy NVENC; only the
+# CLIENT is sandbox-friendly. See packaging/README.md and packaging/flatpak/README.md.)
+#
+# Gitea has NO flatpak/ostree registry, so the bundle lives in the generic registry:
+#   PUT  https://git.unom.io/api/packages/unom/generic/punktfunk-client-flatpak/<version>/<file>
+#   GET  https://git.unom.io/api/packages/unom/generic/punktfunk-client-flatpak/<version>/<file>
+# On tags the bundle is ALSO attached to the Gitea release (mirrors release.yml's DMG).
+#
+# PRIVILEGED-BUILD CONSTRAINT: flatpak-builder runs bubblewrap, which needs user namespaces.
+# In a Gitea/act_runner Docker executor that means the job container must be --privileged
+# (the same runner already runs `docker build` in docker.yml, so its Docker daemon allows it).
+# If your runner CANNOT grant --privileged, this job will fail at `flatpak-builder` with
+# "Creating new namespace failed: Operation not permitted" — see the fallback in
+# packaging/flatpak/README.md (build on the Deck via org.flatpak.Builder, or on a Linux box,
+# then upload with the curl line below).
+#
+# REGISTRY_TOKEN: repo Actions secret, a PAT with write:package scope (shared with deb/rpm/docker).
+name: flatpak
+
+on:
+  push:
+    branches: [main]
+    # The flatpak is the CLIENT — only rebuild when the client/core/manifest change, not on every
+    # docs/host push (this is a heavy flatpak-builder run). Tags (v*, the client release) build too.
+    paths:
+      - 'crates/punktfunk-client-linux/**'
+      - 'crates/punktfunk-core/**'
+      - 'packaging/flatpak/**'
+      - 'Cargo.lock'
+      - '.gitea/workflows/flatpak.yml'
+    tags: ['v*']
+  workflow_dispatch:
+
+env:
+  REGISTRY: git.unom.io
+  OWNER: unom
+  APP_ID: io.unom.Punktfunk
+  MANIFEST: packaging/flatpak/io.unom.Punktfunk.yml
+  PACKAGE: punktfunk-client-flatpak     # generic-registry package name
+
+jobs:
+  build-publish:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 120
+    container:
+      # Fedora ships a recent flatpak + flatpak-builder + the kernel userns support.
+      # --privileged is required for bubblewrap inside the Docker executor (see header).
+      image: fedora:43
+      options: --privileged
+    steps:
+      # fedora:43 has no node, but actions/checkout (a JS action) needs it. A plain `run:` step
+      # executes via the container shell (no node needed), so install node BEFORE checkout.
+      - name: node for the JS actions
+        run: dnf -y install nodejs
+
+      - uses: actions/checkout@v4
+
+      - name: Tooling
+        run: |
+          # flatpak-cargo-generator.py (master) needs aiohttp + tomlkit (NOT the old `toml`).
+          dnf -y install flatpak flatpak-builder git python3 python3-aiohttp python3-tomlkit curl jq
+          # Flathub provides the GNOME runtime/SDK + the rust-stable + ffmpeg-full extensions.
+          flatpak remote-add --user --if-not-exists flathub \
+            https://dl.flathub.org/repo/flathub.flatpakrepo
+          git config --global --add safe.directory "$PWD"
+
+      - name: Version
+        # Tag v1.2.3 -> 1.2.3; a main push -> 0.0.1-ciN.g<sha> (sorts before a real release,
+        # increases by run number — newest main build always wins). The generic registry
+        # version string allows letters/dots/hyphens.
+        run: |
+          SHORT=$(echo "$GITHUB_SHA" | cut -c1-8)
+          case "$GITHUB_REF" in
+            refs/tags/v*) V="${GITHUB_REF_NAME#v}" ;;
+            *)            V="0.0.1-ci${GITHUB_RUN_NUMBER}.g${SHORT}" ;;
+          esac
+          echo "VERSION=$V" >> "$GITHUB_ENV"
+          echo "BUNDLE=punktfunk-client-${V}.flatpak" >> "$GITHUB_ENV"
+          echo "flatpak version $V"
+
+      - name: Generate offline cargo sources
+        # flatpak builds with no network; vendor every crate from Cargo.lock into
+        # cargo-sources.json next to the manifest (referenced by the manifest's
+        # punktfunk-client module).
+        run: |
+          curl -fsSL -o /tmp/flatpak-cargo-generator.py \
+            https://raw.githubusercontent.com/flatpak/flatpak-builder-tools/master/cargo/flatpak-cargo-generator.py
+          python3 /tmp/flatpak-cargo-generator.py Cargo.lock \
+            -o packaging/flatpak/cargo-sources.json
+
+      - name: Build the flatpak (install deps from Flathub, offline build)
+        run: |
+          # --install-deps-from=flathub pulls everything the manifest declares: the GNOME 50
+          # runtime/SDK + the rust-stable (//25.08, rustc 1.96) and llvm20 SDK extensions, plus
+          # the runtime's auto codecs-extra (HEVC libavcodec). --disable-rofiles-fuse is the
+          # container-safe path (no FUSE).
+          flatpak-builder --user --force-clean --disable-rofiles-fuse \
+            --install-deps-from=flathub \
+            --repo="$PWD/repo" \
+            "$PWD/build-dir" "$MANIFEST"
+
+      - name: Export single-file bundle
+        run: |
+          flatpak build-bundle "$PWD/repo" "$BUNDLE" "$APP_ID"
+          ls -lh "$BUNDLE"
+
+      - name: Publish to the Gitea generic registry
+        env:
+          TOKEN: ${{ secrets.REGISTRY_TOKEN }}
+        run: |
+          BASE="https://$REGISTRY/api/packages/$OWNER/generic/$PACKAGE"
+          # 1) Immutable, versioned URL.
+          curl -fsS --user "enricobuehler:$TOKEN" --upload-file "$BUNDLE" \
+            "$BASE/$VERSION/$BUNDLE"
+          echo "published $BASE/$VERSION/$BUNDLE"
+          # 2) Stable `latest/punktfunk-client.flatpak` alias for the Decky fallback + scripts.
+          #    The generic registry rejects re-uploading an existing version/file (409), so
+          #    delete the prior `latest` file first (ignore 404 on the first ever run).
+          curl -fsS -o /dev/null --user "enricobuehler:$TOKEN" -X DELETE \
+            "$BASE/latest/punktfunk-client.flatpak" || true
+          curl -fsS --user "enricobuehler:$TOKEN" --upload-file "$BUNDLE" \
+            "$BASE/latest/punktfunk-client.flatpak"
+          echo "published $BASE/latest/punktfunk-client.flatpak"
+
+      - name: Attach bundle to the Gitea release (tags only)
+        if: startsWith(gitea.ref, 'refs/tags/')
+        env:
+          TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          API="${{ gitea.server_url }}/api/v1/repos/${{ gitea.repository }}"
+          ID=$(curl -sf -X POST "$API/releases" \
+                 -H "Authorization: token $TOKEN" -H 'Content-Type: application/json' \
+                 -d "{\"tag_name\":\"$GITHUB_REF_NAME\",\"name\":\"$GITHUB_REF_NAME\"}" \
+               | python3 -c 'import json,sys;print(json.load(sys.stdin)["id"])' \
+               || curl -sf "$API/releases/tags/$GITHUB_REF_NAME" -H "Authorization: token $TOKEN" \
+               | python3 -c 'import json,sys;print(json.load(sys.stdin)["id"])')
+          curl -sf -X POST "$API/releases/$ID/assets?name=$BUNDLE" \
+            -H "Authorization: token $TOKEN" \
+            -F "attachment=@$BUNDLE" >/dev/null
+          echo "attached $BUNDLE to release $GITHUB_REF_NAME"

.gitea/workflows/release.yml

@@ -1,19 +1,43 @@
 # Production Apple client builds — runs on the macos-arm64 runner (home-mac-mini-1).
 #
 #   Tag v* (or workflow_dispatch):
-#     macOS  -> Developer ID signed + notarized + stapled .dmg, attached to a Gitea
+#     macOS (Developer ID) -> sandboxed, signed, notarized + stapled .dmg, attached to a
-#               release on tag pushes
+#               Gitea release on tag pushes
+#     macOS (App Store)    -> archive + upload to TestFlight (App Store Connect)
 #     iOS    -> archive + upload straight to TestFlight (App Store Connect)
-#     tvOS   -> not built: the Rust core needs tier-3 targets (nightly -Zbuild-std)
+#     tvOS   -> archive + upload to TestFlight (Rust core built from tier-3 targets,
-#     macOS App Store/TestFlight -> deferred: needs App Sandbox entitlements first
+#               nightly -Zbuild-std, in build-xcframework.sh)
-#               (network client + Bonjour); the Developer ID build covers macOS today.
 #
 # One App Store listing for all platforms (universal purchase): every target shares the
 # bundle ID io.unom.punktfunk.
 #
-# Secrets: DEVID_CERT_P12_B64 / DEVID_CERT_PASSWORD (Developer ID Application cert),
+# The macOS app is App-SANDBOXED for both channels (Config/Punktfunk-macOS.entitlements —
-# ASC_API_KEY_P8 / ASC_API_KEY_ID / ASC_API_ISSUER_ID (App Store Connect API key —
+# app-sandbox + network client/server + audio-input + bluetooth/usb device access; the
-# notarization, TestFlight upload, and automatic-signing profile fetch).
+# shared Config/Punktfunk.entitlements stays iOS/tvOS-only, where app-sandbox is invalid).
+# The Developer ID DMG is codesigned with the SAME macOS entitlements, so what we test
+# locally equals what App Store users get.
+#
+# macOS App Store prerequisites (one-time, Apple portal — NOT done by this workflow; the
+# step is continue-on-error until they exist):
+#   * App Store Connect: add the macOS platform to the io.unom.punktfunk app record
+#     (universal purchase).
+#   * A "Punktfunk macOS App Store Distribution" provisioning profile installed on the
+#     runner (under ~/Library/Developer/Xcode/UserData/Provisioning Profiles/).
+#   * The "3rd Party Mac Developer Installer" (Mac Installer Distribution) certificate in
+#     the runner's login keychain, in addition to "Apple Distribution" — the App Store
+#     .pkg is installer-signed with it.
+#
+# Signing setup (NOT secret-based anymore): the runner is a LaunchAgent in the user's
+# logged-in Aqua session, so it uses the **login keychain** directly. Install the signing
+# identities there once via Xcode (Settings -> Accounts -> Manage Certificates): Developer
+# ID Application + Apple Distribution, with the WWDR intermediate present (so they show as
+# *valid*). xcodebuild/codesign then sign exactly like a local build — no throwaway keychain.
+# One-time, to avoid headless "codesign wants to use the key" prompts, grant codesign access:
+#   security set-key-partition-list -S apple-tool:,apple:,codesign: -s -k <login-pw> \
+#     ~/Library/Keychains/login.keychain-db
+#
+# Secrets: only ASC_API_KEY_P8 / ASC_API_KEY_ID / ASC_API_ISSUER_ID (App Store Connect API
+# key — notarization, TestFlight upload, automatic-signing profile fetch).
 #
 # Needs a RELEASE Xcode on the runner (App Store rejects beta-SDK builds); the workflow
 # picks the first non-beta /Applications/Xcode*.app and only falls back to a beta with a
@@ -70,59 +94,19 @@ jobs:
           echo "BUILD_NUM=$GITHUB_RUN_NUMBER" >> "$GITHUB_ENV"
           echo "version $V build $GITHUB_RUN_NUMBER"
 
-      - name: Rust toolchain (mac + iOS slices)
+      - name: Rust toolchain (mac + iOS + tvOS slices)
         run: |
           RUSTUP="$(command -v rustup || echo "$HOME/.cargo/bin/rustup")"
           dirname "$RUSTUP" >> "$GITHUB_PATH"
           "$RUSTUP" target add aarch64-apple-darwin x86_64-apple-darwin \
             aarch64-apple-ios aarch64-apple-ios-sim x86_64-apple-ios
+          # tvOS targets are tier-3 (no prebuilt std) — build-xcframework.sh compiles them with
+          # nightly + -Zbuild-std, so ensure nightly + rust-src are present.
+          "$RUSTUP" toolchain install nightly --profile minimal
+          "$RUSTUP" component add rust-src --toolchain nightly
 
-      - name: Build PunktfunkCore.xcframework (mac + iOS)
+      - name: Build PunktfunkCore.xcframework (mac + iOS + tvOS)
-        run: BUILD_IOS=1 bash scripts/build-xcframework.sh
+        run: BUILD_IOS=1 BUILD_TVOS=1 bash scripts/build-xcframework.sh
-
-      - name: Import signing certificates (throwaway keychain)
-        env:
-          P12_B64: ${{ secrets.DEVID_CERT_P12_B64 }}
-          P12_PASSWORD: ${{ secrets.DEVID_CERT_PASSWORD }}
-          IOS_P12_B64: ${{ secrets.IOS_DIST_CERT_P12_B64 }}
-          IOS_P12_PASSWORD: ${{ secrets.IOS_DIST_CERT_PASSWORD }}
-        run: |
-          KEYCHAIN="$RUNNER_TEMP/punktfunk-ci.keychain-db"
-          KEYCHAIN_PASS="$(uuidgen)"
-          echo "KEYCHAIN=$KEYCHAIN" >> "$GITHUB_ENV"
-          security create-keychain -p "$KEYCHAIN_PASS" "$KEYCHAIN"
-          security set-keychain-settings -lut 7200 "$KEYCHAIN"
-          security unlock-keychain -p "$KEYCHAIN_PASS" "$KEYCHAIN"
-          # xcodebuild's signing lookup consults the DEFAULT keychain — being on the
-          # search list alone isn't enough (find-identity sees the cert, export doesn't).
-          security default-keychain -d user -s "$KEYCHAIN"
-          # Apple's intermediates — without the issuing CA in the chain the identity is
-          # "invalid" and xcodebuild reports "No signing certificate ... found" even
-          # though the cert imported fine (fresh boxes don't ship all WWDR/Developer ID
-          # intermediates).
-          for ca in DeveloperIDG2CA AppleWWDRCAG3 AppleWWDRCAG4; do
-            curl -sf "https://www.apple.com/certificateauthority/$ca.cer" \
-              -o "$RUNNER_TEMP/$ca.cer" \
-              && security import "$RUNNER_TEMP/$ca.cer" -k "$KEYCHAIN" -t cert >/dev/null \
-              || echo "::warning::could not stage intermediate $ca"
-          done
-          printf '%s' "$P12_B64" | base64 -d > "$RUNNER_TEMP/devid.p12"
-          security import "$RUNNER_TEMP/devid.p12" -k "$KEYCHAIN" -P "$P12_PASSWORD" \
-            -T /usr/bin/codesign -T /usr/bin/security
-          rm -f "$RUNNER_TEMP/devid.p12"
-          # iOS App Store distribution identity (optional — imported only when the secret is
-          # set; the iOS/TestFlight job stays best-effort until it is). The WWDR intermediates
-          # fetched above also chain this Apple Distribution cert.
-          if [ -n "$IOS_P12_B64" ]; then
-            printf '%s' "$IOS_P12_B64" | base64 -d > "$RUNNER_TEMP/ios-dist.p12"
-            security import "$RUNNER_TEMP/ios-dist.p12" -k "$KEYCHAIN" -P "$IOS_P12_PASSWORD" \
-              -T /usr/bin/codesign -T /usr/bin/security
-            rm -f "$RUNNER_TEMP/ios-dist.p12"
-          fi
-          security set-key-partition-list -S apple-tool:,apple:,codesign: \
-            -s -k "$KEYCHAIN_PASS" "$KEYCHAIN" >/dev/null
-          security list-keychains -d user -s "$KEYCHAIN" login.keychain-db
-          security find-identity -v -p codesigning "$KEYCHAIN"
 
       - name: Stage App Store Connect API key
         env:
@@ -131,69 +115,35 @@ jobs:
           printf '%s' "$ASC_P8" > "$RUNNER_TEMP/asc.p8"
           chmod 600 "$RUNNER_TEMP/asc.p8"
 
-      - name: Archive macOS (unsigned — signed by codesign below)
+      - name: macOS — archive, codesign Developer ID, notarize, DMG
         run: |
-          # Archive WITHOUT signing, then codesign with Developer ID in the next step. We do
+          # Archive UNSIGNED, then codesign with the Developer ID Application identity from the
-          # NOT let xcodebuild sign during archive because the app's keychain-access-groups
+          # login keychain. Unsigned archive sidesteps Xcode's keychain-access-groups
-          # entitlement is the "Keychain Sharing" capability, and Xcode's archive gate demands
+          # provisioning-profile gate; codesign just needs the (now valid) identity + the
-          # a provisioning profile for it under BOTH automatic and manual signing — even
+          # team-prefixed entitlements, no profile (App Sandbox + the network/device
-          # though a Developer ID app honours that team-prefixed entitlement at RUNTIME with
+          # capabilities are self-asserted for Developer ID — no profile entry needed).
-          # no profile (the gate is an Xcode build-phase check, not a real requirement). Raw
+          # Bundle is a single static binary.
-          # codesign has no such gate. Safe because the bundle is a single statically-linked
-          # binary: static PunktfunkCore.xcframework, SPM static products, macOS 14 target (no
-          # embedded Swift dylibs), and no Embed-Frameworks phase — so nothing nested to sign.
           DEVELOPER_DIR="$XCODE_DEV_DIR" xcodebuild archive \
             -project "$PROJECT" -scheme Punktfunk \
             -destination 'generic/platform=macOS' \
             -archivePath "$RUNNER_TEMP/Punktfunk-macos.xcarchive" \
+            -skipMacroValidation -skipPackagePluginValidation \
             MARKETING_VERSION="$VERSION" CURRENT_PROJECT_VERSION="$BUILD_NUM" \
             CODE_SIGNING_ALLOWED=NO
-
-      - name: Sign macOS app (Developer ID, hardened runtime)
-        run: |
           APP="$RUNNER_TEMP/Punktfunk-macos.xcarchive/Products/Applications/Punktfunk.app"
-          # codesign does NOT expand $(AppIdentifierPrefix) (an Xcode build-setting var), so
+          # Sandboxed Developer ID: sign with the SAME macOS entitlements the App Store build
-          # resolve it to the real team prefix — otherwise keychain-access-groups would be the
+          # uses. codesign won't expand $(AppIdentifierPrefix) — resolve it to the team prefix.
-          # literal string instead of the team-scoped group.
+          RESOLVED="$RUNNER_TEMP/macos.entitlements"
-          RESOLVED="$RUNNER_TEMP/Punktfunk.entitlements"
           sed "s/\$(AppIdentifierPrefix)/${TEAM_ID}./g" \
-            clients/apple/Config/Punktfunk.entitlements > "$RESOLVED"
+            clients/apple/Config/Punktfunk-macOS.entitlements > "$RESOLVED"
-          # codesign must be pointed at the throwaway keychain explicitly: on this runner the
-          # default keychain search list does not reliably carry across steps, so a bare
-          # --sign "Developer ID Application" reports "no identity found" even though the
-          # import step found it there. Re-assert the search list + default keychain in THIS
-          # step's context (no password needed — it stays unlocked with a codesign-allowed
-          # partition list from the import step) AND scope codesign to it with --keychain.
-          security list-keychains -d user -s "$KEYCHAIN" login.keychain-db
-          security default-keychain -d user -s "$KEYCHAIN"
-          echo "signing identity keychain: $KEYCHAIN"
-          security find-identity -v -p codesigning "$KEYCHAIN"
-          # Inside-out: sign any nested Mach-O first (defensive — the static build normally
-          # has none), then the app bundle with the resolved entitlements + hardened runtime +
-          # secure timestamp, which is what notarization requires.
-          if [ -d "$APP/Contents/Frameworks" ]; then
-            find "$APP/Contents/Frameworks" -depth \( -name '*.framework' -o -name '*.dylib' \) \
-              -print0 | while IFS= read -r -d '' f; do
           codesign --force --options runtime --timestamp \
-                  --keychain "$KEYCHAIN" \
-                  --sign "Developer ID Application" "$f"
-              done
-          fi
-          codesign --force --options runtime --timestamp \
-            --keychain "$KEYCHAIN" \
             --entitlements "$RESOLVED" \
             --sign "Developer ID Application" "$APP"
           codesign --verify --strict --verbose=2 "$APP"
-          # Stage where the DMG step expects it ($RUNNER_TEMP/export-devid/Punktfunk.app).
+          # Notarized DMG.
-          mkdir -p "$RUNNER_TEMP/export-devid"
-          rm -rf "$RUNNER_TEMP/export-devid/Punktfunk.app"
-          cp -R "$APP" "$RUNNER_TEMP/export-devid/Punktfunk.app"
-
-      - name: Notarized DMG
-        run: |
           STAGE="$RUNNER_TEMP/dmg-stage"
           mkdir -p "$STAGE"
-          cp -R "$RUNNER_TEMP/export-devid/Punktfunk.app" "$STAGE/"
+          cp -R "$APP" "$STAGE/"
           ln -s /Applications "$STAGE/Applications"
           DMG="$RUNNER_TEMP/Punktfunk-$VERSION.dmg"
           hdiutil create -volname "Punktfunk" -srcfolder "$STAGE" -ov -format UDZO "$DMG"
@@ -222,40 +172,88 @@ jobs:
             -F "attachment=@$DMG" >/dev/null
           echo "attached Punktfunk-$VERSION.dmg to release $GITHUB_REF_NAME"
 
-      - name: Archive iOS + upload to TestFlight
+      - name: macOS App Store — archive + upload to TestFlight
         if: gitea.event_name != 'workflow_dispatch' || inputs.testflight == 'true'
-        # Best-effort until the App Store Connect app record for io.unom.punktfunk
+        # Best-effort until the App Store Connect record has the macOS platform + the
-        # exists — the upload errors without one. Drop this once TestFlight onboarding
+        # "Punktfunk macOS App Store Distribution" profile and the "3rd Party Mac Developer
-        # is done so real upload failures fail the run.
+        # Installer" cert are on the runner (see the header). The macOS app is sandboxed
+        # (Config/Punktfunk-macOS.entitlements) — mandatory for the Mac App Store.
         continue-on-error: true
         run: |
-          # The iOS platform SDK is a separate Xcode component and isn't installed on every
+          # Separate archive from the Developer ID one above: App Store needs a profile-signed
-          # runner; without it `archive` dies with "iOS 26.5 is not installed". Skip cleanly
+          # archive (manual signing), not the unsigned-then-codesign DMG path. Same App-Manager
-          # (this is best-effort anyway) instead of a red step — install it on the runner with
+          # ASC-key constraint as iOS/tvOS — MANUAL signing, NOT -allowProvisioningUpdates
-          # `xcodebuild -downloadPlatform iOS` when iOS/TestFlight is ready to go live.
+          # (cloud signing the key can't do). Quit Xcode so it can't prune the dropped profile.
-          if ! DEVELOPER_DIR="$XCODE_DEV_DIR" xcodebuild -showsdks 2>/dev/null | grep -q iphoneos; then
+          osascript -e 'tell application "Xcode" to quit' >/dev/null 2>&1 || true
-            echo "::warning::iOS platform SDK not installed on this runner — skipping iOS/TestFlight."
+          pkill -x Xcode 2>/dev/null || true
-            exit 0
+          PROFILE="Punktfunk macOS App Store Distribution"
-          fi
+          DEVELOPER_DIR="$XCODE_DEV_DIR" xcodebuild archive \
-          # App Store signing uses the Apple Distribution identity imported above from
+            -project "$PROJECT" -scheme Punktfunk \
-          # IOS_DIST_CERT_P12_B64. Skip cleanly until that secret exists; re-assert the
+            -destination 'generic/platform=macOS' \
-          # throwaway keychain on the search list + as default so automatic signing finds it
+            -archivePath "$RUNNER_TEMP/Punktfunk-macos-appstore.xcarchive" \
-          # (the search list doesn't reliably carry across steps on this runner).
+            MARKETING_VERSION="$VERSION" CURRENT_PROJECT_VERSION="$BUILD_NUM" \
-          if ! security find-identity -v -p codesigning "$KEYCHAIN" | grep -q "Apple Distribution"; then
+            CODE_SIGN_STYLE=Manual \
-            echo "::warning::no Apple Distribution identity present — set IOS_DIST_CERT_P12_B64. Skipping iOS/TestFlight."
+            CODE_SIGN_IDENTITY="Apple Distribution" \
-            exit 0
+            DEVELOPMENT_TEAM="$TEAM_ID" \
-          fi
+            PROVISIONING_PROFILE_SPECIFIER="$PROFILE"
-          security list-keychains -d user -s "$KEYCHAIN" login.keychain-db
+          cat > "$RUNNER_TEMP/export-macos-appstore.plist" <<EOF
-          security default-keychain -d user -s "$KEYCHAIN"
+          <?xml version="1.0" encoding="UTF-8"?>
+          <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+          <plist version="1.0">
+          <dict>
+            <key>method</key><string>app-store-connect</string>
+            <key>destination</key><string>upload</string>
+            <key>teamID</key><string>$TEAM_ID</string>
+            <key>signingStyle</key><string>manual</string>
+            <key>signingCertificate</key><string>Apple Distribution</string>
+            <key>installerSigningCertificate</key><string>3rd Party Mac Developer Installer</string>
+            <key>provisioningProfiles</key>
+            <dict><key>io.unom.punktfunk</key><string>$PROFILE</string></dict>
+          </dict>
+          </plist>
+          EOF
+          DEVELOPER_DIR="$XCODE_DEV_DIR" xcodebuild -exportArchive \
+            -archivePath "$RUNNER_TEMP/Punktfunk-macos-appstore.xcarchive" \
+            -exportOptionsPlist "$RUNNER_TEMP/export-macos-appstore.plist" \
+            -exportPath "$RUNNER_TEMP/export-macos-appstore" \
+            -authenticationKeyPath "$RUNNER_TEMP/asc.p8" \
+            -authenticationKeyID "${{ secrets.ASC_API_KEY_ID }}" \
+            -authenticationKeyIssuerID "${{ secrets.ASC_API_ISSUER_ID }}"
+
+      - name: iOS — archive + upload to TestFlight
+        if: gitea.event_name != 'workflow_dispatch' || inputs.testflight == 'true'
+        # Best-effort until the App Store Connect app record for io.unom.punktfunk exists.
+        continue-on-error: true
+        run: |
+          # MANUAL App Store signing: the local (valid) Apple Distribution identity + the App
+          # Store provisioning profile. NOT -allowProvisioningUpdates — with an App-Manager-role
+          # ASC key that forces Xcode's CLOUD-managed signing, which the role can't do ("Cloud
+          # signing permission error"). The profile must be installed on the runner under
+          # ~/Library/Developer/Xcode/UserData/Provisioning Profiles/ (install it once with
+          # Xcode.app quit, or it prunes the manually-dropped distribution profile).
+          # A running Xcode.app prunes unrecognized profiles from that dir — quit it so the App
+          # Store profile survives this build; headless xcodebuild doesn't need the GUI app.
+          osascript -e 'tell application "Xcode" to quit' >/dev/null 2>&1 || true
+          pkill -x Xcode 2>/dev/null || true
+          PROFILE="Punktfunk iOS App Store Distribution"
+          # Scope signing to the iOS device SDK via an xcconfig — see the tvOS step below for the
+          # full rationale. A global (CLI) profile specifier would also be forced onto the shared
+          # macOS-host SwiftPM macro plugins, which reject it and fail the archive; [sdk=iphoneos*]
+          # in an xcconfig lands it on the app/framework slices only.
+          SIGN_XCCONFIG="$RUNNER_TEMP/sign-ios.xcconfig"
+          cat > "$SIGN_XCCONFIG" <<XCCONF
+          CODE_SIGN_STYLE = Manual
+          DEVELOPMENT_TEAM = $TEAM_ID
+          CODE_SIGN_IDENTITY[sdk=iphoneos*] = Apple Distribution
+          PROVISIONING_PROFILE_SPECIFIER[sdk=iphoneos*] = $PROFILE
+          XCCONF
           DEVELOPER_DIR="$XCODE_DEV_DIR" xcodebuild archive \
             -project "$PROJECT" -scheme Punktfunk-iOS \
             -destination 'generic/platform=iOS' \
             -archivePath "$RUNNER_TEMP/Punktfunk-ios.xcarchive" \
-            MARKETING_VERSION="$VERSION" CURRENT_PROJECT_VERSION="$BUILD_NUM" \
+            -skipMacroValidation -skipPackagePluginValidation \
-            -allowProvisioningUpdates \
+            -xcconfig "$SIGN_XCCONFIG" \
-            -authenticationKeyPath "$RUNNER_TEMP/asc.p8" \
+            MARKETING_VERSION="$VERSION" CURRENT_PROJECT_VERSION="$BUILD_NUM"
-            -authenticationKeyID "${{ secrets.ASC_API_KEY_ID }}" \
-            -authenticationKeyIssuerID "${{ secrets.ASC_API_ISSUER_ID }}"
           cat > "$RUNNER_TEMP/export-appstore.plist" <<EOF
           <?xml version="1.0" encoding="UTF-8"?>
           <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
@@ -264,6 +262,10 @@ jobs:
             <key>method</key><string>app-store-connect</string>
             <key>destination</key><string>upload</string>
             <key>teamID</key><string>$TEAM_ID</string>
+            <key>signingStyle</key><string>manual</string>
+            <key>signingCertificate</key><string>Apple Distribution</string>
+            <key>provisioningProfiles</key>
+            <dict><key>io.unom.punktfunk</key><string>$PROFILE</string></dict>
           </dict>
           </plist>
           EOF
@@ -271,15 +273,62 @@ jobs:
             -archivePath "$RUNNER_TEMP/Punktfunk-ios.xcarchive" \
             -exportOptionsPlist "$RUNNER_TEMP/export-appstore.plist" \
             -exportPath "$RUNNER_TEMP/export-appstore" \
-            -allowProvisioningUpdates \
             -authenticationKeyPath "$RUNNER_TEMP/asc.p8" \
             -authenticationKeyID "${{ secrets.ASC_API_KEY_ID }}" \
             -authenticationKeyIssuerID "${{ secrets.ASC_API_ISSUER_ID }}"
 
-      - name: Clean up keychain + API key
+      - name: tvOS — archive + upload to TestFlight
-        if: always()
+        if: gitea.event_name != 'workflow_dispatch' || inputs.testflight == 'true'
+        # Needs tvOS added to the App Store Connect app record + the tvOS platform installed
+        # on the runner (xcodebuild -downloadPlatform tvOS).
+        continue-on-error: true
         run: |
-          security default-keychain -d user -s login.keychain-db 2>/dev/null || true
+          # Same manual App Store signing as iOS (the App-Manager ASC key can't cloud-sign).
-          [ -n "${KEYCHAIN:-}" ] && security delete-keychain "$KEYCHAIN" 2>/dev/null || true
+          osascript -e 'tell application "Xcode" to quit' >/dev/null 2>&1 || true
-          security list-keychains -d user -s login.keychain-db
+          pkill -x Xcode 2>/dev/null || true
-          rm -f "$RUNNER_TEMP/asc.p8"
+          PROFILE="Punktfunk tvOS App Store Distribution"
+          # Scope signing to the tvOS device SDK via an xcconfig. A global (CLI) profile specifier
+          # hits EVERY target, including the shared SwiftPM macro plugins (OnceMacro/SwizzlingMacro/
+          # AssociationMacro) which build for the macOS host and reject a provisioning profile
+          # ("<macro> does not support provisioning profiles"), failing the archive. Conditionals
+          # work only in an xcconfig (xcodebuild mis-parses a CLI "SETTING[sdk=..]=val"), and a
+          # command-line -xcconfig outranks target settings, so [sdk=appletvos*] puts the profile on
+          # the app/framework slices only — the macosx-host macros get nothing. (The macOS archive
+          # above is immune: its host-SDK macros are CODE_SIGNING_ALLOWED=NO, so a global specifier
+          # is ignored there.)
+          SIGN_XCCONFIG="$RUNNER_TEMP/sign-tvos.xcconfig"
+          cat > "$SIGN_XCCONFIG" <<XCCONF
+          CODE_SIGN_STYLE = Manual
+          DEVELOPMENT_TEAM = $TEAM_ID
+          CODE_SIGN_IDENTITY[sdk=appletvos*] = Apple Distribution
+          PROVISIONING_PROFILE_SPECIFIER[sdk=appletvos*] = $PROFILE
+          XCCONF
+          DEVELOPER_DIR="$XCODE_DEV_DIR" xcodebuild archive \
+            -project "$PROJECT" -scheme Punktfunk-tvOS \
+            -destination 'generic/platform=tvOS' \
+            -archivePath "$RUNNER_TEMP/Punktfunk-tvos.xcarchive" \
+            -skipMacroValidation -skipPackagePluginValidation \
+            -xcconfig "$SIGN_XCCONFIG" \
+            MARKETING_VERSION="$VERSION" CURRENT_PROJECT_VERSION="$BUILD_NUM"
+          cat > "$RUNNER_TEMP/export-tvos.plist" <<EOF
+          <?xml version="1.0" encoding="UTF-8"?>
+          <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+          <plist version="1.0">
+          <dict>
+            <key>method</key><string>app-store-connect</string>
+            <key>destination</key><string>upload</string>
+            <key>teamID</key><string>$TEAM_ID</string>
+            <key>signingStyle</key><string>manual</string>
+            <key>signingCertificate</key><string>Apple Distribution</string>
+            <key>provisioningProfiles</key>
+            <dict><key>io.unom.punktfunk</key><string>$PROFILE</string></dict>
+          </dict>
+          </plist>
+          EOF
+          DEVELOPER_DIR="$XCODE_DEV_DIR" xcodebuild -exportArchive \
+            -archivePath "$RUNNER_TEMP/Punktfunk-tvos.xcarchive" \
+            -exportOptionsPlist "$RUNNER_TEMP/export-tvos.plist" \
+            -exportPath "$RUNNER_TEMP/export-tvos" \
+            -authenticationKeyPath "$RUNNER_TEMP/asc.p8" \
+            -authenticationKeyID "${{ secrets.ASC_API_KEY_ID }}" \
+            -authenticationKeyIssuerID "${{ secrets.ASC_API_ISSUER_ID }}"

.gitea/workflows/rpm.yml

@@ -13,19 +13,31 @@ name: rpm
 on:
   push:
     branches: [main]
-    tags: ['v*']
+    # HOST-scoped tags only — the Apple client's `v*` tags (release.yml) must NOT publish a host
+    # RPM (a `v0.1.1` client tag previously shipped a host 0.1.1 that shadowed every rolling build).
+    tags: ['host-v*']
   workflow_dispatch:
 
 env:
   REGISTRY: git.unom.io
   OWNER: unom
-  RPM_GROUP: bazzite
 
 jobs:
   build-publish:
     runs-on: ubuntu-24.04
+    # One RPM per target whose ffmpeg soname must match (a binary RPM is soname-coupled to its
+    # base): Fedora 43 == Bazzite (libavcodec.so.61), Fedora 44 == the Fedora KDE spin (.so.62).
+    # Each builds in its matching builder image and publishes to its own registry group.
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - image: punktfunk-fedora-rpm     # Fedora 43 == Bazzite base
+            group: bazzite
+          - image: punktfunk-fedora44-rpm   # Fedora 44 == Fedora KDE spin
+            group: fedora-44
     container:
-      image: git.unom.io/unom/punktfunk-fedora-rpm:latest
+      image: git.unom.io/unom/${{ matrix.image }}:latest
     timeout-minutes: 90
     env:
       CARGO_HOME: /usr/local/cargo
@@ -40,6 +52,14 @@ jobs:
         run: |
           git config --global --add safe.directory "$PWD"
           dnf -y install gtk4-devel libadwaita-devel SDL3-devel
+          # bun builds the punktfunk-web console (--with web). Baked into the image; install it
+          # here too so the job stays green against the PREVIOUS image (docker.yml bootstrap note).
+          command -v bun >/dev/null || {
+            dnf -y install unzip
+            curl -fsSL https://bun.sh/install | bash
+            install -m0755 "$HOME/.bun/bin/bun" /usr/local/bin/bun
+          }
+          bun --version
       - uses: actions/cache@v4
         with:
           path: /usr/local/cargo/registry
@@ -47,21 +67,30 @@ jobs:
           restore-keys: cargo-home-
 
       - name: Version
-        # Tag v1.2.3 -> 1.2.3-1 (release); main push -> 0.0.1-0.ciN.g<sha>, whose release "0."
+        # host-vX.Y.Z tag -> X.Y.Z-1 (a real host release); main push -> 0.2.0-0.ciN.g<sha>, whose
-        # sorts BEFORE the eventual "1" yet increases by run number, so `rpm-ostree upgrade`
+        # "0." release sorts BELOW the eventual 0.2.0-1 yet climbs by run number AND outranks the
-        # always moves to the newest main build.
+        # stray 0.1.1, so `rpm-ostree upgrade` truly moves to the newest build. The spec %build
+        # stamps PUNKTFUNK_BUILD_VERSION from these macros into the binary (--version provenance).
         run: |
           SHORT=$(echo "$GITHUB_SHA" | cut -c1-8)
           case "$GITHUB_REF" in
-            refs/tags/v*) V="${GITHUB_REF_NAME#v}"; R="1" ;;
+            refs/tags/host-v*) V="${GITHUB_REF_NAME#host-v}"; R="1" ;;
-            *)            V="0.0.1"; R="0.ci${GITHUB_RUN_NUMBER}.g${SHORT}" ;;
+            *)                 V="0.2.0"; R="0.ci${GITHUB_RUN_NUMBER}.g${SHORT}" ;;
           esac
           echo "PF_VERSION=$V" >> "$GITHUB_ENV"
           echo "PF_RELEASE=$R" >> "$GITHUB_ENV"
           echo "rpm $V-$R"
 
       - name: Build RPM
-        run: PF_VERSION="$PF_VERSION" PF_RELEASE="$PF_RELEASE" bash packaging/rpm/build-rpm.sh
+        # PF_WITH_WEB=1 → also build the noarch punktfunk-web subpackage (the publish loop below
+        # globs it in; the host RPM Recommends it). Needs bun (ensured in Prep).
+        run: PF_VERSION="$PF_VERSION" PF_RELEASE="$PF_RELEASE" PF_WITH_WEB=1 bash packaging/rpm/build-rpm.sh
+
+      - name: Sign RPMs (dormant until RPM_GPG_PRIVATE_KEY is set — see packaging/rpm/README.md)
+        env:
+          RPM_GPG_PRIVATE_KEY: ${{ secrets.RPM_GPG_PRIVATE_KEY }}
+          RPM_GPG_PASSPHRASE: ${{ secrets.RPM_GPG_PASSPHRASE }}
+        run: bash packaging/rpm/sign-rpms.sh
 
       - name: Publish to the Gitea RPM registry
         env:
@@ -72,6 +101,6 @@ jobs:
             case "$rpm" in *debuginfo*|*debugsource*) echo "skip $rpm"; continue;; esac
             echo "uploading $rpm"
             curl -fsS --user "enricobuehler:$TOKEN" --upload-file "$rpm" \
-              "https://$REGISTRY/api/packages/$OWNER/rpm/$RPM_GROUP/upload"
+              "https://$REGISTRY/api/packages/$OWNER/rpm/${{ matrix.group }}/upload"
           done
-          echo "published to $OWNER/rpm/$RPM_GROUP"
+          echo "published to $OWNER/rpm/${{ matrix.group }}"

.gitea/workflows/windows-msix.yml

@@ -0,0 +1,90 @@
+# Build the punktfunk Windows client as a signed MSIX and publish it to Gitea's generic package
+# registry, so Windows boxes can download + install a real package (Start tile, clean
+# install/uninstall) instead of a loose exe. Runs on the self-hosted Windows runner (host mode;
+# scripts/ci/setup-windows-runner.ps1) — the MSVC/WinUI/FFmpeg toolchain + the Windows SDK's
+# makeappx/signtool are baked into the runner's daemon env, same as windows.yml.
+#
+# Registry (public, unom org): https://git.unom.io/unom/-/packages  (generic group)
+# Packaging internals: crates/punktfunk-client-windows/packaging/README.md. BOM/MAX_PATH runner
+# gotchas baked into the daemon env + windows.yml: see that workflow.
+#
+# Versioning — MSIX requires a strictly 4-part numeric version (no ~/- suffixes), so:
+#   win-vX.Y.Z tag -> X.Y.Z.0  (a real Windows-client release; `win-v*` is its own tag namespace,
+#                               kept off the host's `host-v*` and the Apple `v*` to avoid the
+#                               version-shadow class of bug — see deb.yml).
+#   main push / dispatch -> 0.2.<run_number>.0  (rolling; climbs monotonically by run number).
+#
+# 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).
+name: windows-msix
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'crates/punktfunk-client-windows/**'
+      - 'crates/punktfunk-core/**'
+      - 'Cargo.lock'
+      - 'Cargo.toml'
+      - '.gitea/workflows/windows-msix.yml'
+    tags: ['win-v*']
+  workflow_dispatch:
+
+env:
+  REGISTRY: git.unom.io
+  OWNER: unom
+  PKG: punktfunk-client-windows
+
+jobs:
+  package:
+    runs-on: windows-amd64
+    timeout-minutes: 60
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Configure + version
+        shell: pwsh
+        run: |
+          # windows-reactor's build.rs unwraps CARGO_WORKSPACE_DIR; CARGO_TARGET_DIR=C:\t dodges the
+          # MAX_PATH wall in the CMake-from-source crates (see windows.yml). Both via GITHUB_ENV.
+          "CARGO_WORKSPACE_DIR=$env:GITHUB_WORKSPACE" | Out-File -FilePath $env:GITHUB_ENV -Append -Encoding utf8
+          "CARGO_TARGET_DIR=C:\t" | Out-File -FilePath $env:GITHUB_ENV -Append -Encoding utf8
+          $parts = if ($env:GITHUB_REF -like 'refs/tags/win-v*') {
+            ($env:GITHUB_REF_NAME -replace '^win-v', '').Split('.')
+          } else {
+            @('0', '2', $env:GITHUB_RUN_NUMBER)
+          }
+          while ($parts.Count -lt 4) { $parts += '0' }
+          $v = ($parts[0..3] -join '.')
+          "MSIX_VERSION=$v" | Out-File -FilePath $env:GITHUB_ENV -Append -Encoding utf8
+          Write-Output "MSIX version $v"
+
+      - name: Build (release)
+        shell: pwsh
+        run: cargo build --release -p punktfunk-client-windows
+
+      - name: Pack + sign MSIX
+        shell: pwsh
+        env:
+          MSIX_CERT_PFX_B64: ${{ secrets.MSIX_CERT_PFX_B64 }}
+          MSIX_CERT_PASSWORD: ${{ secrets.MSIX_CERT_PASSWORD }}
+        run: |
+          & crates/punktfunk-client-windows/packaging/pack-msix.ps1 `
+            -Version $env:MSIX_VERSION -TargetDir C:\t\release -OutDir C:\t\msix
+
+      - name: Publish to Gitea generic registry
+        shell: pwsh
+        env:
+          REGISTRY_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
+        run: |
+          $files = @($env:MSIX_PATH, $env:MSIX_CER_PATH) | Where-Object { $_ -and (Test-Path $_) }
+          if (-not $files) { throw "pack produced no artifacts to publish" }
+          foreach ($f in $files) {
+            $name = Split-Path $f -Leaf
+            $url = "https://$($env:REGISTRY)/api/packages/$($env:OWNER)/generic/$($env:PKG)/$($env:MSIX_VERSION)/$name"
+            curl.exe -fsS --user "enricobuehler:$($env:REGISTRY_TOKEN)" --upload-file "$f" "$url"
+            Write-Output "published $name -> $url"
+          }

.gitea/workflows/windows.yml

@@ -0,0 +1,72 @@
+# Windows client CI — runs on the self-hosted Windows runner (home-windows-1, host mode; see
+# scripts/ci/setup-windows-runner.ps1). Build + clippy + fmt + test the WinUI 3 client
+# (windows-reactor + D3D11/SwapChainPanel + WASAPI + SDL3) on x86_64-pc-windows-msvc.
+#
+# The MSVC/WinUI/FFmpeg toolchain (cargo/rustup on ASCII paths, NASM, CMake, LLVM, FFmpeg,
+# CARGO_HOME, CMAKE_POLICY_VERSION_MINIMUM, …) is baked into the runner's daemon env. Two
+# per-checkout 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
+#                          CMake-from-source builds (audiopus_sys / SDL3) — MSBuild's tracker then
+#                          can't create its .tlog (DirectoryNotFoundException -> MSB6003). A short
+#                          root keeps every nested path well under the limit.
+#
+# 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.
+# The runner's daemon wrapper puts C:\Program Files\PowerShell\7 on PATH so the job finds pwsh.
+name: windows
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'crates/punktfunk-client-windows/**'
+      - 'crates/punktfunk-core/**'
+      - 'Cargo.lock'
+      - 'Cargo.toml'
+      - '.gitea/workflows/windows.yml'
+  pull_request:
+    paths:
+      - 'crates/punktfunk-client-windows/**'
+      - 'crates/punktfunk-core/**'
+      - 'Cargo.lock'
+      - 'Cargo.toml'
+      - '.gitea/workflows/windows.yml'
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: windows-amd64
+    timeout-minutes: 60
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Configure + toolchain versions
+        shell: pwsh
+        run: |
+          "CARGO_WORKSPACE_DIR=$env:GITHUB_WORKSPACE" | Out-File -FilePath $env:GITHUB_ENV -Append -Encoding utf8
+          "CARGO_TARGET_DIR=C:\t" | Out-File -FilePath $env:GITHUB_ENV -Append -Encoding utf8
+          rustc --version
+          cargo --version
+          node --version
+          Write-Output "workspace: $env:GITHUB_WORKSPACE"
+
+      - name: Build
+        shell: pwsh
+        run: cargo build -p punktfunk-client-windows
+
+      - name: Clippy (-D warnings)
+        shell: pwsh
+        run: cargo clippy -p punktfunk-client-windows --all-targets -- -D warnings
+
+      - name: Rustfmt check
+        shell: pwsh
+        run: cargo fmt -p punktfunk-client-windows -- --check
+
+      - name: Test
+        shell: pwsh
+        run: cargo test -p punktfunk-client-windows

.gitignore

@@ -16,3 +16,7 @@ xcuserdata/
 
 # Debian package build output
 /dist/
+
+# Windows App SDK staging by windows-reactor build.rs
+/temp/
+/winmd/

CLAUDE.md

@@ -37,12 +37,16 @@ Low-latency desktop/game streaming stack, Linux-first, with a shared Rust protoc
   0xC8 (incl. **gamepads** — incremental events accumulated into the uinput xpad), **Opus
   audio** 0xC9 (48 kHz stereo, 5 ms, host→client), **rumble** 0xCA (host→client). **Trust:**
   host serves its persistent identity (`~/.config/punktfunk/cert.pem`, shared with GameStream
-  pairing) and logs the SHA-256 fingerprint; clients pin it (TOFU on first connect —
+  pairing) and logs the SHA-256 fingerprint; clients pin it, established by a **SPAKE2 PIN pairing
-  `endpoint::client_pinned`), and a **SPAKE2 PIN pairing ceremony** (host arms pairing and displays a
+  ceremony** (host arms pairing and displays a 4-digit PIN; a PAKE binds both cert fingerprints so an
-  4-digit PIN; a PAKE binds both cert fingerprints so an attacker gets one online guess,
+  attacker gets one online guess, no offline dictionary attack) — PIN pairing is the default for new
-  no offline dictionary attack) establishes mutual trust:
+  hosts. **TOFU on first connect** (`endpoint::client_pinned`) stays as an explicit host opt-in
-  clients present persistent identities via QUIC client auth, the host stores paired
+  (`m3-host --allow-tofu` / `serve --open`, advertised as `pair=optional`) for fully trusted LANs;
-  fingerprints (`punktfunk1-paired.json`) and can gate sessions with `--require-pairing`.
+  clients only offer the TOFU "Trust" path for a host that advertised `pair=optional`, route every
+  other new host straight to the PIN ceremony, and on a pinned-fingerprint change force re-pairing
+  (no re-TOFU shortcut). Clients present persistent identities via QUIC client auth, the host stores
+  paired fingerprints (`punktfunk1-paired.json`) and gates sessions with `--require-pairing` (the
+  default; `--allow-tofu`/`--open` accept unpaired clients).
   **LAN auto-discovery**: both `serve --native` and `m3-host` advertise the native service over
   mDNS (`_punktfunk._udp`, `crate::discovery`) with TXT `proto`/`fp`(cert fingerprint to
   pin)/`pair`(required|optional)/`id`; `punktfunk-client-rs --discover` lists hosts, Apple clients
@@ -108,15 +112,38 @@ Low-latency desktop/game streaming stack, Linux-first, with a shared Rust protoc
    Intel/AMD client box to live-verify the hw path. Next: the stage-2 raw-Wayland
    presenter (wp_presentation feedback, tearing-control, Vulkan Video on NVIDIA) —
    **wgpu/winit rejected** (no dmabuf import / presentation feedback / shortcuts-inhibit).
+   **Windows stage 1 done 2026-06-15** (`crates/punktfunk-client-windows`, binary
+   `punktfunk-client`): pure-Rust **WinUI 3** UI via **windows-reactor** (a declarative React-like
+   framework backed by WinUI; PR #4499 added the `SwapChainPanel` widget + `set_swap_chain`). The
+   video is a **`SwapChainPanel`** bound to a **D3D11 composition swapchain** (WARP fallback for
+   the GPU-less dev box; runtime-compiled fullscreen-triangle shaders, Contain-fit letterbox),
+   driven by reactor's per-frame `on_rendering`. **FFmpeg software HEVC decode** (D3D11VA hw decode
+   is the follow-up), **WASAPI** render + mic capture, **SDL3** gamepads (rumble/lightbar/DualSense),
+   `mdns-sd` discovery, and the full trust surface — all **in-app**: host list (live mDNS + saved +
+   manual), settings (resolution/refresh/mic), SPAKE2 PIN pairing screen, TOFU, pinned-fp-mismatch
+   re-pair. **Stream input** is Win32 low-level hooks (`WH_KEYBOARD_LL`/`WH_MOUSE_LL`) — reactor
+   exposes no raw key/pointer events; native Windows VK + absolute mouse (client-rect Contain-fit) +
+   wheel, Ctrl+Alt+Shift+Q capture toggle. `--headless`/`--discover` keep CLI paths. Builds + clippy
+   + fmt green on `x86_64-pc-windows-msvc` (on the dev VM). **windows-reactor is unpublished** (git
+   dep pinned to commit `b4129fcc`; `windows` pinned to the SAME commit so `IDXGISwapChain1` unifies
+   with `set_swap_chain`); its `build.rs` downloads the Win App SDK NuGets + needs `CARGO_WORKSPACE_DIR`
+   set (in the VM build env; `/temp`+`/winmd` gitignored). Gotcha: `CARGO_HOME` must be an ASCII path
+   — the `ü` in the dev box's username breaks SDL3's MSVC precompiled-header build. Next: **on-glass
+   validation** (the dev VM is headless/Session-0 → the WinUI window needs a display: RDP or the RTX
+   box), D3D11VA hw decode + 10-bit/HDR present, RAWINPUT relative-mouse pointer-lock, and a per-host
+   speed test in the UI.
 2. **Sub-frame pipelining**: overlap encode and transmit within a frame. Requires a direct
    NVENC SDK wrapper (libavcodec only emits whole AUs) — the next big latency lever (~2–4 ms
    at high res).
 3. **punktfunk/1 protocol growth**: concurrent sessions (today: one at a time, extras wait
    in the accept queue). **Done:** unified host (`serve --native` runs GameStream + the
    punktfunk/1 QUIC host in one process) with native pairing driven over the mgmt API /
-   web console (`mod native_pairing`: arm-on-demand → display PIN, paired-device list). Next
+   web console (`mod native_pairing`: arm-on-demand → display PIN, paired-device list).
-   (see roadmap): **mandatory PIN pairing by default** (TOFU-without-pairing is insecure on a
+   **Done:** PIN pairing is the default, host-gated — the host requires pairing and advertises
-   LAN) + **delegated pairing approval** (an already-paired device approves a new one).
+   `pair=required` unless opted out with `--allow-tofu`/`--open` (then `pair=optional`, accepts
+   unpaired clients); clients render TOFU only for a `pair=optional` host and force re-pairing on a
+   fingerprint change. Next (see roadmap): **delegated pairing approval** (an already-paired device
+   approves a new one).
 4. **M2 polish**: HDR/10-bit (needs HDR capture + metadata plumbing; `av1_nvenc
    -highbitdepth 1` already encodes Main10 from 8-bit input on this box),
    reconnect-at-new-mode robustness. AV1 negotiation and surround audio are implemented

Cargo.lock

@@ -46,6 +46,29 @@ dependencies = [
  "memchr",
 ]
 
+[[package]]
+name = "android_log-sys"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "84521a3cf562bc62942e294181d9eef17eb38ceb8c68677bc49f144e4c3d4f8d"
+
+[[package]]
+name = "android_logger"
+version = "0.14.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "05b07e8e73d720a1f2e4b6014766e6039fd2e96a4fa44e2a78d0e1fa2ff49826"
+dependencies = [
+ "android_log-sys",
+ "env_filter",
+ "log",
+]
+
+[[package]]
+name = "anes"
+version = "0.1.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4b46cbb362ab8752921c97e041f5e366ee6297bd428a31275b9fcf1e380f7299"
+
 [[package]]
 name = "annotate-snippets"
 version = "0.11.5"
@@ -371,7 +394,7 @@ dependencies = [
  "bitflags",
  "cexpr",
  "clang-sys",
- "itertools",
+ "itertools 0.13.0",
  "proc-macro2",
  "quote",
  "regex",
@@ -425,6 +448,12 @@ version = "3.20.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "72f5acc6cb2ba439de613abc23857ec3d78374d8ed5ac84e9d11336e87da8649"
 
+[[package]]
+name = "bytemuck"
+version = "1.25.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c8efb64bd706a16a1bdde310ae86b351e4d21550d98d056f22f8a7f7a2183fec"
+
 [[package]]
 name = "bytes"
 version = "1.11.1"
@@ -454,6 +483,12 @@ dependencies = [
  "system-deps",
 ]
 
+[[package]]
+name = "cast"
+version = "0.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "37b2a672a2cb129a2e41c10b1224bb368f9f37a2b16b612598138befd7b37eb5"
+
 [[package]]
 name = "cbc"
 version = "0.1.2"
@@ -531,6 +566,33 @@ version = "0.2.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "613afe47fcd5fac7ccf1db93babcb082c5994d996f20b8b159f2ad1658eb5724"
 
+[[package]]
+name = "ciborium"
+version = "0.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "42e69ffd6f0917f5c029256a24d0161db17cea3997d185db0d35926308770f0e"
+dependencies = [
+ "ciborium-io",
+ "ciborium-ll",
+ "serde",
+]
+
+[[package]]
+name = "ciborium-io"
+version = "0.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "05afea1e0a06c9be33d539b876f1ce3692f4afea2cb41f740e7743225ed1c757"
+
+[[package]]
+name = "ciborium-ll"
+version = "0.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "57663b653d948a338bfb3eeba9bb2fd5fcfaecb9e199e87e1eda4d9e8b240fd9"
+dependencies = [
+ "ciborium-io",
+ "half",
+]
+
 [[package]]
 name = "cipher"
 version = "0.4.4"
@@ -659,6 +721,40 @@ dependencies = [
  "libc",
 ]
 
+[[package]]
+name = "criterion"
+version = "0.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f2b12d017a929603d80db1831cd3a24082f8137ce19c69e6447f54f5fc8d692f"
+dependencies = [
+ "anes",
+ "cast",
+ "ciborium",
+ "clap",
+ "criterion-plot",
+ "is-terminal",
+ "itertools 0.10.5",
+ "num-traits",
+ "once_cell",
+ "oorandom",
+ "regex",
+ "serde",
+ "serde_derive",
+ "serde_json",
+ "tinytemplate",
+ "walkdir",
+]
+
+[[package]]
+name = "criterion-plot"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6b50826342786a51a89e2da3a28f1c32b06e387201bc2d19791f622c673706b1"
+dependencies = [
+ "cast",
+ "itertools 0.10.5",
+]
+
 [[package]]
 name = "crossbeam-deque"
 version = "0.8.6"
@@ -684,6 +780,12 @@ version = "0.8.21"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d0a5c400df2834b80a4c3327b3aad3a4c4cd4de0629063962b03235697506a28"
 
+[[package]]
+name = "crunchy"
+version = "0.2.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "460fbee9c2c2f33933d720630a6a0bac33ba7053db5344fac858d4b8952d77d5"
+
 [[package]]
 name = "crypto-common"
 version = "0.1.7"
@@ -704,6 +806,15 @@ dependencies = [
  "cipher",
 ]
 
+[[package]]
+name = "cudarc"
+version = "0.16.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "17200eb07e7d85a243aa1bf4569a7aa998385ba98d14833973a817a63cc86e92"
+dependencies = [
+ "libloading",
+]
+
 [[package]]
 name = "curve25519-dalek"
 version = "4.1.3"
@@ -838,6 +949,16 @@ dependencies = [
  "syn",
 ]
 
+[[package]]
+name = "env_filter"
+version = "0.1.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1bf3c259d255ca70051b30e2e95b5446cdb8949ac4cd22c0d7fd634d89f568e2"
+dependencies = [
+ "log",
+ "regex",
+]
+
 [[package]]
 name = "equivalent"
 version = "1.0.2"
@@ -1434,6 +1555,17 @@ dependencies = [
  "tracing",
 ]
 
+[[package]]
+name = "half"
+version = "2.7.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6ea2d84b969582b4b1864a92dc5d27cd2b77b622a8d79306834f1be5ba20d84b"
+dependencies = [
+ "cfg-if",
+ "crunchy",
+ "zerocopy",
+]
+
 [[package]]
 name = "hashbrown"
 version = "0.15.5"
@@ -1604,12 +1736,32 @@ dependencies = [
  "generic-array",
 ]
 
+[[package]]
+name = "is-terminal"
+version = "0.4.17"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3640c1c38b8e4e43584d8df18be5fc6b0aa314ce6ebf51b53313d4306cca8e46"
+dependencies = [
+ "hermit-abi",
+ "libc",
+ "windows-sys 0.61.2",
+]
+
 [[package]]
 name = "is_terminal_polyfill"
 version = "1.70.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "a6cb138bb79a146c1bd460005623e142ef0181e3d0219cb493e02f7d08a35695"
 
+[[package]]
+name = "itertools"
+version = "0.10.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b0fd2260e829bddf4cb6ea802289de2f86d6a7a690192fbe91b3f46e0f2c8473"
+dependencies = [
+ "either",
+]
+
 [[package]]
 name = "itertools"
 version = "0.13.0"
@@ -1763,7 +1915,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d7c4b02199fee7c5d21a5ae7d8cfa79a6ef5bb2fc834d6e9058e89c825efdc55"
 dependencies = [
  "cfg-if",
- "windows-link",
+ "windows-link 0.2.1 (registry+https://github.com/rust-lang/crates.io-index)",
 ]
 
 [[package]]
@@ -1912,6 +2064,39 @@ dependencies = [
  "windows-sys 0.61.2",
 ]
 
+[[package]]
+name = "nasm-rs"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "706bf8a5e8c8ddb99128c3291d31bd21f4bcde17f0f4c20ec678d85c74faa149"
+dependencies = [
+ "log",
+]
+
+[[package]]
+name = "ndk"
+version = "0.9.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c3f42e7bbe13d351b6bead8286a43aac9534b82bd3cc43e47037f012ebfd62d4"
+dependencies = [
+ "bitflags",
+ "jni-sys 0.3.1",
+ "log",
+ "ndk-sys",
+ "num_enum",
+ "raw-window-handle",
+ "thiserror 1.0.69",
+]
+
+[[package]]
+name = "ndk-sys"
+version = "0.6.0+11769913"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ee6cda3051665f1fb8d9e08fc35c96d5a244fb1be711a03b71118828afc9a873"
+dependencies = [
+ "jni-sys 0.3.1",
+]
+
 [[package]]
 name = "nix"
 version = "0.30.1"
@@ -2024,6 +2209,38 @@ dependencies = [
  "libc",
 ]
 
+[[package]]
+name = "num_enum"
+version = "0.7.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5d0bca838442ec211fa11de3a8b0e0e8f3a4522575b5c4c06ed722e005036f26"
+dependencies = [
+ "num_enum_derive",
+ "rustversion",
+]
+
+[[package]]
+name = "num_enum_derive"
+version = "0.7.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "680998035259dcfcafe653688bf2aa6d3e2dc05e98be6ab46afb089dc84f1df8"
+dependencies = [
+ "proc-macro-crate",
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "nvidia-video-codec-sdk"
+version = "0.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1b150dfc88653e761947906dfc0ea14af16ae366cfc55122caab94381761605a"
+dependencies = [
+ "cudarc",
+ "lazy_static",
+]
+
 [[package]]
 name = "oid-registry"
 version = "0.7.1"
@@ -2045,12 +2262,39 @@ version = "1.70.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "384b8ab6d37215f3c5301a95a4accb5d64aa607f1fcb26a11b5303878451b4fe"
 
+[[package]]
+name = "oorandom"
+version = "11.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d6790f58c7ff633d8771f42965289203411a5e5c68388703c06e14f24770b41e"
+
 [[package]]
 name = "opaque-debug"
 version = "0.3.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "c08d65885ee38876c4f86fa503fb49d7b507c2b62552df7c70b2fce627e06381"
 
+[[package]]
+name = "openh264"
+version = "0.9.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4a12b82c14f702c2cece4e0fc28896c6a6bed5317dc13448c86ac41df91a6f82"
+dependencies = [
+ "openh264-sys2",
+ "wide",
+]
+
+[[package]]
+name = "openh264-sys2"
+version = "0.9.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fa9e072e9b270f3b291c80488dc160abc31ecc214ab3bfde937213cfd8c83b32"
+dependencies = [
+ "cc",
+ "nasm-rs",
+ "walkdir",
+]
+
 [[package]]
 name = "openssl-probe"
 version = "0.2.1"
@@ -2126,7 +2370,7 @@ dependencies = [
  "libc",
  "redox_syscall",
  "smallvec",
- "windows-link",
+ "windows-link 0.2.1 (registry+https://github.com/rust-lang/crates.io-index)",
 ]
 
 [[package]]
@@ -2295,6 +2539,18 @@ dependencies = [
  "unarray",
 ]
 
+[[package]]
+name = "punktfunk-android"
+version = "0.0.1"
+dependencies = [
+ "android_logger",
+ "jni",
+ "log",
+ "ndk",
+ "opus",
+ "punktfunk-core",
+]
+
 [[package]]
 name = "punktfunk-client-linux"
 version = "0.0.1"
@@ -2329,6 +2585,26 @@ dependencies = [
  "tracing-subscriber",
 ]
 
+[[package]]
+name = "punktfunk-client-windows"
+version = "0.0.1"
+dependencies = [
+ "anyhow",
+ "async-channel",
+ "ffmpeg-next",
+ "mdns-sd",
+ "opus",
+ "punktfunk-core",
+ "sdl3",
+ "serde",
+ "serde_json",
+ "tracing",
+ "tracing-subscriber",
+ "wasapi",
+ "windows 0.62.2 (git+https://github.com/microsoft/windows-rs?rev=b4129fcc1ae81eec8bf1217539883db821bca3a1)",
+ "windows-reactor",
+]
+
 [[package]]
 name = "punktfunk-core"
 version = "0.0.1"
@@ -2336,6 +2612,7 @@ dependencies = [
  "aes-gcm",
  "bytes",
  "cbindgen",
+ "criterion",
  "fec-rs",
  "hmac",
  "libc",
@@ -2352,6 +2629,7 @@ dependencies = [
  "thiserror 2.0.18",
  "tokio",
  "tracing",
+ "windows-sys 0.59.0",
  "zerocopy",
  "zeroize",
 ]
@@ -2373,9 +2651,13 @@ dependencies = [
  "futures-util",
  "hex",
  "http-body-util",
+ "hyper",
+ "hyper-util",
  "khronos-egl",
  "libc",
  "mdns-sd",
+ "nvidia-video-codec-sdk",
+ "openh264",
  "opus",
  "pipewire",
  "punktfunk-core",
@@ -2391,17 +2673,22 @@ dependencies = [
  "serde_json",
  "sha2",
  "tokio",
+ "tokio-rustls",
  "tower",
  "tracing",
  "tracing-subscriber",
  "utoipa",
  "utoipa-axum",
  "utoipa-scalar",
+ "vigem-client",
+ "wasapi",
  "wayland-backend",
  "wayland-client",
  "wayland-protocols-misc",
  "wayland-protocols-wlr",
  "wayland-scanner",
+ "windows 0.62.2 (registry+https://github.com/rust-lang/crates.io-index)",
+ "windows-service",
  "x509-parser",
  "xkbcommon",
 ]
@@ -2567,6 +2854,12 @@ dependencies = [
  "rand_core 0.9.5",
 ]
 
+[[package]]
+name = "raw-window-handle"
+version = "0.6.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "20675572f6f24e9e76ef639bc5552774ed45f1c30e2951e1e99c59888861c539"
+
 [[package]]
 name = "rayon"
 version = "1.12.0"
@@ -2595,6 +2888,7 @@ checksum = "75e669e5202259b5314d1ea5397316ad400819437857b90861765f24c4cf80a2"
 dependencies = [
  "aws-lc-rs",
  "pem",
+ "ring",
  "rustls-pki-types",
  "time",
  "yasna",
@@ -2683,6 +2977,12 @@ dependencies = [
  "windows-sys 0.52.0",
 ]
 
+[[package]]
+name = "rpkg-config"
+version = "0.1.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5a2d2f3481209a6b42eec2fbb49063fb4e8d35b57023401495d4fe0f85c817f0"
+
 [[package]]
 name = "rsa"
 version = "0.9.10"
@@ -2859,6 +3159,15 @@ version = "1.0.23"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9774ba4a74de5f7b1c1451ed6cd5285a32eddb5cccb8cc655a4e50009e06477f"
 
+[[package]]
+name = "safe_arch"
+version = "0.7.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "96b02de82ddbe1b636e6170c21be622223aea188ef2e139be0a5b219ec215323"
+dependencies = [
+ "bytemuck",
+]
+
 [[package]]
 name = "same-file"
 version = "1.0.6"
@@ -2891,16 +3200,89 @@ checksum = "25bd22eb1bbc9137e914022b4994ed35591eea0884e9e3e98e6d9895cad6e1d2"
 dependencies = [
  "bitflags",
  "libc",
+ "sdl3-image-sys",
+ "sdl3-mixer-sys",
  "sdl3-sys",
+ "sdl3-ttf-sys",
 ]
 
+[[package]]
+name = "sdl3-image-src"
+version = "3.4.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fe273101c7dab94551183212eee9adef1a7bf274d407f0b7bfe72482960ab25c"
+
+[[package]]
+name = "sdl3-image-sys"
+version = "0.6.4+SDL-image-3.4.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5a445f781b39a1c1bc751f5f4612191e0402006e35ad5d02d9193281afad1cf4"
+dependencies = [
+ "cmake",
+ "pkg-config",
+ "rpkg-config",
+ "sdl3-image-src",
+ "sdl3-sys",
+ "vcpkg",
+]
+
+[[package]]
+name = "sdl3-mixer-src"
+version = "3.2.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9cd815ae87084588c7dbd027c1667b0a5e21a6b5ae7b22ecb230bc21c7063eca"
+
+[[package]]
+name = "sdl3-mixer-sys"
+version = "0.6.3+SDL-mixer-3.2.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2b5a157588924cf886bdc3a7c9d0e478cdad35d315740f26af00609a61e7c327"
+dependencies = [
+ "cmake",
+ "pkg-config",
+ "rpkg-config",
+ "sdl3-mixer-src",
+ "sdl3-sys",
+ "vcpkg",
+]
+
+[[package]]
+name = "sdl3-src"
+version = "3.4.10"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ed4dcad85f1657d3424642ca2ed8f9f185212975baefda8972ac606494755a62"
+
 [[package]]
 name = "sdl3-sys"
 version = "0.6.6+SDL-3.4.10"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "04e7f134def04ed72e6f55187c6c29c72f7dab5d359c4be0dd49c9b97fef59c7"
 dependencies = [
+ "cc",
+ "cmake",
  "pkg-config",
+ "rpkg-config",
+ "sdl3-src",
+ "vcpkg",
+]
+
+[[package]]
+name = "sdl3-ttf-src"
+version = "3.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e8deaa09c46d6aa8e8a81a601eb4685b2a57f2ce8a4ea3c59e8b623b526d1125"
+
+[[package]]
+name = "sdl3-ttf-sys"
+version = "0.6.1+SDL-ttf-3.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8137096072109d6c834d4cb30b8a617ded4f150c7766757eddc834108bbcefd2"
+dependencies = [
+ "cmake",
+ "pkg-config",
+ "rpkg-config",
+ "sdl3-sys",
+ "sdl3-ttf-src",
  "vcpkg",
 ]
 
@@ -3293,6 +3675,16 @@ dependencies = [
  "time-core",
 ]
 
+[[package]]
+name = "tinytemplate"
+version = "1.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "be4d6b5f19ff7664e8c98d03e2139cb510db9b0a60b55f8e8709b689d939b6bc"
+dependencies = [
+ "serde",
+ "serde_json",
+]
+
 [[package]]
 name = "tinyvec"
 version = "1.11.0"
@@ -3678,6 +4070,15 @@ version = "0.9.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "0b928f33d975fc6ad9f86c8f283853ad26bdd5b10b7f1542aa2fa15e2289105a"
 
+[[package]]
+name = "vigem-client"
+version = "0.1.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b857e6f99efe1e1eb1e4dfb035de8ae7ec8ec56bd1928edcbd7c6e4427634d52"
+dependencies = [
+ "winapi",
+]
+
 [[package]]
 name = "wait-timeout"
 version = "0.2.1"
@@ -3697,6 +4098,19 @@ dependencies = [
  "winapi-util",
 ]
 
+[[package]]
+name = "wasapi"
+version = "0.23.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "80c3aa5d6b0e7acc3ea10cb19c334df0c8d825060f14a30d9e3b03385e6e5175"
+dependencies = [
+ "log",
+ "num-integer",
+ "thiserror 2.0.18",
+ "windows 0.62.2 (registry+https://github.com/rust-lang/crates.io-index)",
+ "windows-core 0.62.2 (registry+https://github.com/rust-lang/crates.io-index)",
+]
+
 [[package]]
 name = "wasi"
 version = "0.11.1+wasi-snapshot-preview1"
@@ -3902,6 +4316,38 @@ dependencies = [
  "rustls-pki-types",
 ]
 
+[[package]]
+name = "wide"
+version = "0.7.33"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0ce5da8ecb62bcd8ec8b7ea19f69a51275e91299be594ea5cc6ef7819e16cd03"
+dependencies = [
+ "bytemuck",
+ "safe_arch",
+]
+
+[[package]]
+name = "widestring"
+version = "1.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "72069c3113ab32ab29e5584db3c6ec55d416895e60715417b5b883a357c3e471"
+
+[[package]]
+name = "winapi"
+version = "0.3.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5c839a674fcd7a98952e593242ea400abe93992746761e38641405d28b00f419"
+dependencies = [
+ "winapi-i686-pc-windows-gnu",
+ "winapi-x86_64-pc-windows-gnu",
+]
+
+[[package]]
+name = "winapi-i686-pc-windows-gnu"
+version = "0.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ac3b87c63620426dd9b991e5ce0329eff545bccbbb34f3be09ff6fb6ab51b7b6"
+
 [[package]]
 name = "winapi-util"
 version = "0.1.11"
@@ -3911,12 +4357,241 @@ dependencies = [
  "windows-sys 0.61.2",
 ]
 
+[[package]]
+name = "winapi-x86_64-pc-windows-gnu"
+version = "0.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "712e227841d057c1ee1cd2fb22fa7e5a5461ae8e48fa2ca79ec42cfc1931183f"
+
+[[package]]
+name = "windows"
+version = "0.62.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "527fadee13e0c05939a6a05d5bd6eec6cd2e3dbd648b9f8e447c6518133d8580"
+dependencies = [
+ "windows-collections 0.3.2 (registry+https://github.com/rust-lang/crates.io-index)",
+ "windows-core 0.62.2 (registry+https://github.com/rust-lang/crates.io-index)",
+ "windows-future 0.3.2 (registry+https://github.com/rust-lang/crates.io-index)",
+ "windows-numerics 0.3.1 (registry+https://github.com/rust-lang/crates.io-index)",
+]
+
+[[package]]
+name = "windows"
+version = "0.62.2"
+source = "git+https://github.com/microsoft/windows-rs?rev=b4129fcc1ae81eec8bf1217539883db821bca3a1#b4129fcc1ae81eec8bf1217539883db821bca3a1"
+dependencies = [
+ "windows-collections 0.3.2 (git+https://github.com/microsoft/windows-rs?rev=b4129fcc1ae81eec8bf1217539883db821bca3a1)",
+ "windows-core 0.62.2 (git+https://github.com/microsoft/windows-rs?rev=b4129fcc1ae81eec8bf1217539883db821bca3a1)",
+ "windows-future 0.3.2 (git+https://github.com/microsoft/windows-rs?rev=b4129fcc1ae81eec8bf1217539883db821bca3a1)",
+ "windows-numerics 0.3.1 (git+https://github.com/microsoft/windows-rs?rev=b4129fcc1ae81eec8bf1217539883db821bca3a1)",
+ "windows-reference",
+ "windows-time",
+]
+
+[[package]]
+name = "windows-collections"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "23b2d95af1a8a14a3c7367e1ed4fc9c20e0a26e79551b1454d72583c97cc6610"
+dependencies = [
+ "windows-core 0.62.2 (registry+https://github.com/rust-lang/crates.io-index)",
+]
+
+[[package]]
+name = "windows-collections"
+version = "0.3.2"
+source = "git+https://github.com/microsoft/windows-rs?rev=b4129fcc1ae81eec8bf1217539883db821bca3a1#b4129fcc1ae81eec8bf1217539883db821bca3a1"
+dependencies = [
+ "windows-core 0.62.2 (git+https://github.com/microsoft/windows-rs?rev=b4129fcc1ae81eec8bf1217539883db821bca3a1)",
+]
+
+[[package]]
+name = "windows-core"
+version = "0.62.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b8e83a14d34d0623b51dce9581199302a221863196a1dde71a7663a4c2be9deb"
+dependencies = [
+ "windows-implement 0.60.2 (registry+https://github.com/rust-lang/crates.io-index)",
+ "windows-interface 0.59.3 (registry+https://github.com/rust-lang/crates.io-index)",
+ "windows-link 0.2.1 (registry+https://github.com/rust-lang/crates.io-index)",
+ "windows-result 0.4.1 (registry+https://github.com/rust-lang/crates.io-index)",
+ "windows-strings 0.5.1 (registry+https://github.com/rust-lang/crates.io-index)",
+]
+
+[[package]]
+name = "windows-core"
+version = "0.62.2"
+source = "git+https://github.com/microsoft/windows-rs?rev=b4129fcc1ae81eec8bf1217539883db821bca3a1#b4129fcc1ae81eec8bf1217539883db821bca3a1"
+dependencies = [
+ "windows-implement 0.60.2 (git+https://github.com/microsoft/windows-rs?rev=b4129fcc1ae81eec8bf1217539883db821bca3a1)",
+ "windows-interface 0.59.3 (git+https://github.com/microsoft/windows-rs?rev=b4129fcc1ae81eec8bf1217539883db821bca3a1)",
+ "windows-link 0.2.1 (git+https://github.com/microsoft/windows-rs?rev=b4129fcc1ae81eec8bf1217539883db821bca3a1)",
+ "windows-result 0.4.1 (git+https://github.com/microsoft/windows-rs?rev=b4129fcc1ae81eec8bf1217539883db821bca3a1)",
+ "windows-strings 0.5.1 (git+https://github.com/microsoft/windows-rs?rev=b4129fcc1ae81eec8bf1217539883db821bca3a1)",
+]
+
+[[package]]
+name = "windows-future"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e1d6f90251fe18a279739e78025bd6ddc52a7e22f921070ccdc67dde84c605cb"
+dependencies = [
+ "windows-core 0.62.2 (registry+https://github.com/rust-lang/crates.io-index)",
+ "windows-link 0.2.1 (registry+https://github.com/rust-lang/crates.io-index)",
+ "windows-threading 0.2.1 (registry+https://github.com/rust-lang/crates.io-index)",
+]
+
+[[package]]
+name = "windows-future"
+version = "0.3.2"
+source = "git+https://github.com/microsoft/windows-rs?rev=b4129fcc1ae81eec8bf1217539883db821bca3a1#b4129fcc1ae81eec8bf1217539883db821bca3a1"
+dependencies = [
+ "windows-core 0.62.2 (git+https://github.com/microsoft/windows-rs?rev=b4129fcc1ae81eec8bf1217539883db821bca3a1)",
+ "windows-link 0.2.1 (git+https://github.com/microsoft/windows-rs?rev=b4129fcc1ae81eec8bf1217539883db821bca3a1)",
+ "windows-threading 0.2.1 (git+https://github.com/microsoft/windows-rs?rev=b4129fcc1ae81eec8bf1217539883db821bca3a1)",
+]
+
+[[package]]
+name = "windows-implement"
+version = "0.60.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "053e2e040ab57b9dc951b72c264860db7eb3b0200ba345b4e4c3b14f67855ddf"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "windows-implement"
+version = "0.60.2"
+source = "git+https://github.com/microsoft/windows-rs?rev=b4129fcc1ae81eec8bf1217539883db821bca3a1#b4129fcc1ae81eec8bf1217539883db821bca3a1"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "windows-interface"
+version = "0.59.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3f316c4a2570ba26bbec722032c4099d8c8bc095efccdc15688708623367e358"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "windows-interface"
+version = "0.59.3"
+source = "git+https://github.com/microsoft/windows-rs?rev=b4129fcc1ae81eec8bf1217539883db821bca3a1#b4129fcc1ae81eec8bf1217539883db821bca3a1"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
 [[package]]
 name = "windows-link"
 version = "0.2.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5"
 
+[[package]]
+name = "windows-link"
+version = "0.2.1"
+source = "git+https://github.com/microsoft/windows-rs?rev=b4129fcc1ae81eec8bf1217539883db821bca3a1#b4129fcc1ae81eec8bf1217539883db821bca3a1"
+
+[[package]]
+name = "windows-numerics"
+version = "0.3.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6e2e40844ac143cdb44aead537bbf727de9b044e107a0f1220392177d15b0f26"
+dependencies = [
+ "windows-core 0.62.2 (registry+https://github.com/rust-lang/crates.io-index)",
+ "windows-link 0.2.1 (registry+https://github.com/rust-lang/crates.io-index)",
+]
+
+[[package]]
+name = "windows-numerics"
+version = "0.3.1"
+source = "git+https://github.com/microsoft/windows-rs?rev=b4129fcc1ae81eec8bf1217539883db821bca3a1#b4129fcc1ae81eec8bf1217539883db821bca3a1"
+dependencies = [
+ "windows-core 0.62.2 (git+https://github.com/microsoft/windows-rs?rev=b4129fcc1ae81eec8bf1217539883db821bca3a1)",
+ "windows-link 0.2.1 (git+https://github.com/microsoft/windows-rs?rev=b4129fcc1ae81eec8bf1217539883db821bca3a1)",
+]
+
+[[package]]
+name = "windows-reactor"
+version = "0.0.0"
+source = "git+https://github.com/microsoft/windows-rs?rev=b4129fcc1ae81eec8bf1217539883db821bca3a1#b4129fcc1ae81eec8bf1217539883db821bca3a1"
+dependencies = [
+ "rustc-hash",
+ "windows-collections 0.3.2 (git+https://github.com/microsoft/windows-rs?rev=b4129fcc1ae81eec8bf1217539883db821bca3a1)",
+ "windows-core 0.62.2 (git+https://github.com/microsoft/windows-rs?rev=b4129fcc1ae81eec8bf1217539883db821bca3a1)",
+ "windows-future 0.3.2 (git+https://github.com/microsoft/windows-rs?rev=b4129fcc1ae81eec8bf1217539883db821bca3a1)",
+ "windows-numerics 0.3.1 (git+https://github.com/microsoft/windows-rs?rev=b4129fcc1ae81eec8bf1217539883db821bca3a1)",
+ "windows-reference",
+ "windows-threading 0.2.1 (git+https://github.com/microsoft/windows-rs?rev=b4129fcc1ae81eec8bf1217539883db821bca3a1)",
+ "windows-time",
+]
+
+[[package]]
+name = "windows-reference"
+version = "0.1.0"
+source = "git+https://github.com/microsoft/windows-rs?rev=b4129fcc1ae81eec8bf1217539883db821bca3a1#b4129fcc1ae81eec8bf1217539883db821bca3a1"
+dependencies = [
+ "windows-core 0.62.2 (git+https://github.com/microsoft/windows-rs?rev=b4129fcc1ae81eec8bf1217539883db821bca3a1)",
+ "windows-time",
+]
+
+[[package]]
+name = "windows-result"
+version = "0.4.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7781fa89eaf60850ac3d2da7af8e5242a5ea78d1a11c49bf2910bb5a73853eb5"
+dependencies = [
+ "windows-link 0.2.1 (registry+https://github.com/rust-lang/crates.io-index)",
+]
+
+[[package]]
+name = "windows-result"
+version = "0.4.1"
+source = "git+https://github.com/microsoft/windows-rs?rev=b4129fcc1ae81eec8bf1217539883db821bca3a1#b4129fcc1ae81eec8bf1217539883db821bca3a1"
+dependencies = [
+ "windows-link 0.2.1 (git+https://github.com/microsoft/windows-rs?rev=b4129fcc1ae81eec8bf1217539883db821bca3a1)",
+]
+
+[[package]]
+name = "windows-service"
+version = "0.7.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d24d6bcc7f734a4091ecf8d7a64c5f7d7066f45585c1861eba06449909609c8a"
+dependencies = [
+ "bitflags",
+ "widestring",
+ "windows-sys 0.52.0",
+]
+
+[[package]]
+name = "windows-strings"
+version = "0.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7837d08f69c77cf6b07689544538e017c1bfcf57e34b4c0ff58e6c2cd3b37091"
+dependencies = [
+ "windows-link 0.2.1 (registry+https://github.com/rust-lang/crates.io-index)",
+]
+
+[[package]]
+name = "windows-strings"
+version = "0.5.1"
+source = "git+https://github.com/microsoft/windows-rs?rev=b4129fcc1ae81eec8bf1217539883db821bca3a1#b4129fcc1ae81eec8bf1217539883db821bca3a1"
+dependencies = [
+ "windows-link 0.2.1 (git+https://github.com/microsoft/windows-rs?rev=b4129fcc1ae81eec8bf1217539883db821bca3a1)",
+]
+
 [[package]]
 name = "windows-sys"
 version = "0.45.0"
@@ -3935,6 +4610,15 @@ dependencies = [
  "windows-targets 0.52.6",
 ]
 
+[[package]]
+name = "windows-sys"
+version = "0.59.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1e38bc4d79ed67fd075bcc251a1c39b32a1776bbe92e5bef1f0bf1f8c531853b"
+dependencies = [
+ "windows-targets 0.52.6",
+]
+
 [[package]]
 name = "windows-sys"
 version = "0.60.2"
@@ -3950,7 +4634,7 @@ version = "0.61.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ae137229bcbd6cdf0f7b80a31df61766145077ddf49416a728b02cb3921ff3fc"
 dependencies = [
- "windows-link",
+ "windows-link 0.2.1 (registry+https://github.com/rust-lang/crates.io-index)",
 ]
 
 [[package]]
@@ -3990,7 +4674,7 @@ version = "0.53.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "4945f9f551b88e0d65f3db0bc25c33b8acea4d9e41163edf90dcd0b19f9069f3"
 dependencies = [
- "windows-link",
+ "windows-link 0.2.1 (registry+https://github.com/rust-lang/crates.io-index)",
  "windows_aarch64_gnullvm 0.53.1",
  "windows_aarch64_msvc 0.53.1",
  "windows_i686_gnu 0.53.1",
@@ -4001,6 +4685,31 @@ dependencies = [
  "windows_x86_64_msvc 0.53.1",
 ]
 
+[[package]]
+name = "windows-threading"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3949bd5b99cafdf1c7ca86b43ca564028dfe27d66958f2470940f73d86d75b37"
+dependencies = [
+ "windows-link 0.2.1 (registry+https://github.com/rust-lang/crates.io-index)",
+]
+
+[[package]]
+name = "windows-threading"
+version = "0.2.1"
+source = "git+https://github.com/microsoft/windows-rs?rev=b4129fcc1ae81eec8bf1217539883db821bca3a1#b4129fcc1ae81eec8bf1217539883db821bca3a1"
+dependencies = [
+ "windows-link 0.2.1 (git+https://github.com/microsoft/windows-rs?rev=b4129fcc1ae81eec8bf1217539883db821bca3a1)",
+]
+
+[[package]]
+name = "windows-time"
+version = "0.1.0"
+source = "git+https://github.com/microsoft/windows-rs?rev=b4129fcc1ae81eec8bf1217539883db821bca3a1#b4129fcc1ae81eec8bf1217539883db821bca3a1"
+dependencies = [
+ "windows-core 0.62.2 (git+https://github.com/microsoft/windows-rs?rev=b4129fcc1ae81eec8bf1217539883db821bca3a1)",
+]
+
 [[package]]
 name = "windows_aarch64_gnullvm"
 version = "0.42.2"

Cargo.toml

@@ -5,6 +5,8 @@ members = [
     "crates/punktfunk-host",
     "crates/punktfunk-client-rs",
     "crates/punktfunk-client-linux",
+    "crates/punktfunk-client-windows",
+    "crates/punktfunk-android",
     "tools/latency-probe",
     "tools/loss-harness",
 ]

README.md

@@ -24,13 +24,32 @@ catalog, RTSP/ENet/audio, and **video at the client's exact resolution and refre
 per-session virtual output (KWin, gamescope, Mutter, Sway backends), encoded with GPU
 **zero-copy** (dmabuf → CUDA/Vulkan → NVENC) at up to 5120×1440@240. The native
 **`punktfunk/1`** protocol adds a QUIC control plane and a GF(2¹⁶) Leopard-FEC + AES-GCM data
-plane (p50 ~0.8 ms capture→reassembled at 720p120), with a SPAKE2 PIN pairing ceremony. Both
+plane (p50 ~0.8 ms capture→reassembled at 720p120). Its trust model is **SPAKE2 PIN pairing by
+default** — a new host requires the PIN ceremony; trust-on-first-use is an explicit host opt-in
+(`m3-host --allow-tofu` / `serve --open`, advertised as `pair=optional`) for fully trusted LANs. Both
 run from **one process** (`serve --native`), managed through a REST API + web console. Builds
 against FFmpeg 7 or 8; deployed live on Bazzite. Full status: [`CLAUDE.md`](CLAUDE.md);
 roadmap, setup guides & progress: the docs site ([`docs-site/`](docs-site) — Fumadocs;
 `bun run dev`), with the canonical [roadmap](docs-site/content/docs/roadmap.md) and
 [status](docs-site/content/docs/status.md) there. Design notes stay in [`docs/`](docs).
 
+## Install (host)
+
+The package registries are the real distribution channel — pick your distro and run one command.
+Per-distro setup (add the repo, first-run, web console) lives in the linked READMEs.
+
+| Distro | One-command happy path | Details |
+|--------|------------------------|---------|
+| **Ubuntu / Debian** (apt) | `sudo apt install punktfunk-host` *(after adding the repo)* | [`packaging/debian/README.md`](packaging/debian/README.md) |
+| **Fedora / Bazzite** (rpm-ostree) | `rpm-ostree install punktfunk punktfunk-web` *(after adding the repo; or the bootc image)* | [`packaging/rpm/README.md`](packaging/rpm/README.md) |
+| **Arch / Steam Deck** (PKGBUILD / sysext) | `makepkg -si` *(Arch)* · sysext `.raw` *(SteamOS/Deck)* | [`packaging/arch/README.md`](packaging/arch/README.md) |
+
+`punktfunk-host` is the streaming host; `punktfunk-web` is the browser console (pairing + status);
+`punktfunk-client` is the GTK4 desktop client (also shipped via apt/RPM/Arch/Flatpak). After install,
+run `punktfunk-host serve --native` inside your desktop session, then pair from the web console.
+
+Building from source (below) is a fallback.
+
 ## Layout
 
 ```
@@ -46,7 +65,9 @@ tools/{latency-probe,loss-harness}/   measurement (plan §10)
 docs/{implementation-plan,roadmap,windows-host,dualsense-haptics}.md
 ```
 
-## Build & test
+## Build & test (from source)
+
+For development, or as an install fallback where no package is available:
 
 ```sh
 cargo build --workspace          # green on Linux and macOS

ci/fedora-rpm.Dockerfile

@@ -1,11 +1,15 @@
-# CI builder for the punktfunk RPM — Fedora 43 to match Bazzite's base (so the RPM's
+# CI builder for the punktfunk RPM. The Fedora version is parameterized so one Dockerfile
-# auto-generated library Requires, e.g. libavcodec.so.NN, pin to exactly what the target
+# serves every target whose ffmpeg soname must match: Fedora 43 == Bazzite's base (group
-# runs). Used by .gitea/workflows/rpm.yml; built+pushed by .gitea/workflows/docker.yml.
+# "bazzite"), Fedora 44 == the Fedora KDE spin (group "fedora-44"). The RPM's auto-generated
+# library Requires (e.g. libavcodec.so.NN) pin to exactly what the chosen base — and thus the
+# target — ships. Used by .gitea/workflows/rpm.yml; built+pushed by .gitea/workflows/docker.yml.
 #
-#   docker build -f ci/fedora-rpm.Dockerfile -t punktfunk-fedora-rpm ci
+#   docker build --build-arg FEDORA_VERSION=43 -f ci/fedora-rpm.Dockerfile -t punktfunk-fedora-rpm ci
+#   docker build --build-arg FEDORA_VERSION=44 -f ci/fedora-rpm.Dockerfile -t punktfunk-fedora44-rpm ci
 #
 # Mirrors ci/rust-ci.Dockerfile (the Ubuntu workspace builder) for the rpmbuild side.
-FROM fedora:43
+ARG FEDORA_VERSION=43
+FROM fedora:${FEDORA_VERSION}
 
 # RPM Fusion (free + nonfree) provides the NVENC-capable ffmpeg-devel the host links against.
 RUN dnf -y install \
@@ -13,7 +17,8 @@ RUN dnf -y install \
       "https://mirrors.rpmfusion.org/nonfree/fedora/rpmfusion-nonfree-release-$(rpm -E %fedora).noarch.rpm" \
   && dnf -y install \
       # rpmbuild + source-tarball tooling; nodejs runs the Gitea Actions JS (checkout/cache)
-      rpm-build rpmdevtools systemd-rpm-macros git tar gzip nodejs \
+      # AND the punktfunk-web .output at runtime; unzip is for the bun installer below.
+      rpm-build rpmdevtools systemd-rpm-macros git tar gzip nodejs unzip \
       # build toolchain + bindgen
       gcc gcc-c++ clang clang-devel cmake nasm pkgconf-pkg-config curl ca-certificates \
       # ffmpeg (NVENC), capture/audio/display link deps
@@ -23,6 +28,13 @@ RUN dnf -y install \
       gtk4-devel libadwaita-devel SDL3-devel \
   && dnf clean all
 
+# bun — the build tool for the punktfunk-web console (`bun run build` -> the node-server .output
+# the punktfunk-web RPM ships and runs with plain node). Not in Fedora repos; install the official
+# standalone binary to a system PATH dir so the rpmbuild `%build` (run as any uid) finds it.
+RUN curl -fsSL https://bun.sh/install | bash \
+    && install -m0755 /root/.bun/bin/bun /usr/local/bin/bun \
+    && bun --version
+
 # libcuda link stub — the zerocopy path links a fixed set of cuXxx driver symbols, but CI has
 # no GPU and never RUNS CUDA. Rather than drag in the NVIDIA userspace stack, synthesize a stub
 # libcuda.so.1 that just defines those symbols (the SAME approach the Ubuntu image takes with the

ci/rust-ci.Dockerfile

@@ -11,8 +11,8 @@
 FROM ubuntu:26.04
 ENV DEBIAN_FRONTEND=noninteractive
 RUN apt-get update && apt-get install -y --no-install-recommends \
-    # toolchain + bindgen; nodejs runs the JS actions (checkout/cache) inside this container
+    # toolchain + bindgen; nodejs runs the JS actions (checkout/cache); unzip is for the bun installer
-    build-essential clang libclang-dev pkg-config cmake git curl ca-certificates nodejs \
+    build-essential clang libclang-dev pkg-config cmake git curl ca-certificates nodejs unzip \
     # ffmpeg-next 8 (system FFmpeg 8 / libavcodec 62 on 26.04)
     libavcodec-dev libavformat-dev libavutil-dev libswscale-dev libavfilter-dev \
     libavdevice-dev \
@@ -24,6 +24,12 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
     libgtk-4-dev libadwaita-1-dev libsdl3-dev \
     && rm -rf /var/lib/apt/lists/*
 
+# bun — builds the punktfunk-web console in deb.yml (which runs the web build in THIS image).
+# ci.yml's web/docs jobs use the oven/bun image instead, so this is only for the deb job.
+RUN curl -fsSL https://bun.sh/install | bash \
+    && install -m0755 /root/.bun/bin/bun /usr/local/bin/bun \
+    && bun --version
+
 # libcuda link stub: the NVIDIA userspace library (no kernel module needed) provides
 # every cuXxx symbol. On 26.04 the package already ships the libcuda.so dev symlink;
 # -sf keeps this idempotent if a future package drops it again.

clients/android/.gitignore

@@ -0,0 +1,11 @@
+# Gradle / Android build artifacts
+.gradle/
+build/
+local.properties
+*.iml
+.idea/
+captures/
+.cxx/
+
+# Native libraries produced by cargo-ndk — regenerated by the :kit cargoNdk* tasks.
+**/src/main/jniLibs/

clients/android/README.md

@@ -1,20 +1,69 @@
-# punktfunk Android client (later)
+# punktfunk Android client
 
-Kotlin UI + MediaCodec (decode) + a thin JNI layer over the `punktfunk-core` C ABI.
+Native Android client for **punktfunk/1**, targeting **phone + TV** (Compose, D-pad + touch).
 
-## Wiring
+## Architecture — Rust-heavy (like the Linux client, not thin-native like Apple)
+
+Kotlin cannot `import` the cbindgen C header the way Swift can, so a native bridge is unavoidable.
+We write it in **Rust** and link `punktfunk-core` directly — so the Android client reuses the Linux
+client's orchestration (audio jitter ring, VK keymap inverse, latency/skew math, capture state
+machine, trust logic) instead of re-porting it into Kotlin.
+
+| Side | Owns |
+|------|------|
+| **Rust** (`crates/punktfunk-android` → `libpunktfunk_android.so`) | the JNI seam, `NativeClient` (QUIC control + UDP data plane), AnnexB→`AMediaCodec` decode, Opus+Oboe audio, VK keymap, latency math, trust/pairing |
+| **Kotlin** (`clients/android`) | Compose UI (host grid / settings / stream), `SurfaceView` lifecycle, input capture, `NsdManager` discovery, Keystore identity, permissions |
+
+The single seam is `io.unom.punktfunk.kit.NativeBridge` ⇄ `Java_io_unom_punktfunk_kit_NativeBridge_*`.
+
+## Layout
 
-1. Build the core as a shared library per Android ABI:
-   ```sh
-   rustup target add aarch64-linux-android armv7-linux-androideabi x86_64-linux-android
-   cargo build -p punktfunk-core --release --target aarch64-linux-android   # libpunktfunk_core.so
 ```
-   (Use `cargo-ndk` to handle the NDK toolchain/linker.)
+crates/punktfunk-android/          Rust cdylib (workspace member)
-2. JNI shim: small C/Rust glue mapping `punktfunk_*` to Kotlin `external fun`s, bundling
+  src/lib.rs                       JNI_OnLoad + abiVersion/coreVersion (native-link proof)
-   `libpunktfunk_core.so` into the APK's `jniLibs/`.
+  src/session.rs                   session handle lifecycle (connect/close); plane pumps = TODO
-3. Kotlin: client `PunktfunkSession` → `punktfunk_client_poll_frame` on a decode thread → feed
+
-   `MediaCodec` → render to a `SurfaceView` aligned to the display refresh.
+clients/android/                   Gradle project (this dir)
+  settings.gradle.kts · build.gradle.kts · gradle.properties · gradlew
+  app/                             :app — Compose application (MainActivity)
+  kit/                             :kit — Android library: NativeBridge + the cargo-ndk build
+    build.gradle.kts               cargoNdk{Debug,Release} → src/main/jniLibs/<abi>/*.so
+```
+
+## Prerequisites (already set up on the dev Mac)
+
+- Android SDK + **NDK r28 LTS** (`28.2.13676358`), `platforms;android-37.0`, `build-tools;37.0.0`
+- **JDK 21** for Gradle/AGP (the machine default JDK 25 is too new for AGP 9.2)
+- Rust + `rustup target add aarch64-linux-android x86_64-linux-android` + `cargo install cargo-ndk`
+
+Toolchain pinned: AGP 9.2.0 · Gradle 9.4.1 · Kotlin 2.3.21 · Compose BOM 2026.05.01 ·
+compileSdk 37 · targetSdk 36 · minSdk 31 · ABIs arm64-v8a + x86_64.
+
+## Build & run
+
+**Android Studio:** open `clients/android` — it uses its bundled JBR 21 automatically. The
+`cargoNdk*` task builds the `.so` as part of the normal build.
+
+**CLI** (the machine default is JDK 25, so point Gradle at JDK 21):
+
+```sh
+export JAVA_HOME="$(brew --prefix openjdk@21)/libexec/openjdk.jdk/Contents/Home"
+cd clients/android
+./gradlew :app:assembleDebug      # cargo-ndk cross-compiles libpunktfunk_android.so first
+./gradlew :app:installDebug       # onto a running emulator/device
+
+# Emulators (created during env setup):  emulator -avd pf_phone   |   emulator -avd pf_tv
+```
+
+The debug APK lands in `app/build/outputs/apk/debug/`. The scaffold screen calls
+`NativeBridge.abiVersion()` across JNI — a live ABI version proves the whole native stack is wired.
 
 ## Status
 
-Placeholder — scheduled after the Apple client (M5).
+- **Scaffold (done):** Gradle modules, cargo-ndk wiring, JNI native-link proof, phone+TV-installable
+  manifest. `crates/punktfunk-core` `rcgen` switched to the `ring` backend so the client `.so` is
+  aws-lc-free.
+- **Next (M4 Android stage 1):** video decode (`AMediaCodec` async → `SurfaceView`), audio
+  (Opus + Oboe + jitter ring), input capture → `send_input`, pairing/identity (Keystore-wrapped),
+  mDNS discovery, the phone/TV Compose UI. The Rust-side homes are stubbed in
+  `crates/punktfunk-android/src/session.rs` with port pointers to `crates/punktfunk-client-linux`.

clients/android/app/build.gradle.kts

@@ -0,0 +1,68 @@
+import org.jetbrains.kotlin.gradle.dsl.JvmTarget
+
+plugins {
+    id("com.android.application")
+    // AGP 9 built-in Kotlin: NO org.jetbrains.kotlin.android. The Compose compiler plugin is
+    // supplied by AGP, so it's applied without a version.
+    id("org.jetbrains.kotlin.plugin.compose")
+}
+
+android {
+    namespace = "io.unom.punktfunk"
+    compileSdk = 37 // Android 17 — required by androidx.core 1.19.0; targetSdk stays 36 for now.
+
+    defaultConfig {
+        applicationId = "io.unom.punktfunk"
+        minSdk = 31
+        targetSdk = 36
+        versionCode = 1
+        versionName = "0.0.1"
+        ndk { abiFilters += listOf("arm64-v8a", "x86_64") }
+    }
+
+    buildTypes {
+        release {
+            isMinifyEnabled = false // scaffold; enable R8 + shrinkResources later
+        }
+    }
+
+    buildFeatures { compose = true }
+
+    compileOptions {
+        sourceCompatibility = JavaVersion.VERSION_21
+        targetCompatibility = JavaVersion.VERSION_21
+    }
+    packaging {
+        jniLibs {
+            useLegacyPackaging = false
+            // punktfunk-core is statically linked into libpunktfunk_android.so (rlib). Its standalone
+            // cdylib (built because the core crate also declares crate-type = cdylib) is never loaded
+            // by Kotlin — drop it from the APK rather than ship ~5–9 MB of dead code.
+            excludes += "**/libpunktfunk_core.so"
+        }
+    }
+}
+
+kotlin { compilerOptions { jvmTarget.set(JvmTarget.JVM_21) } }
+
+dependencies {
+    implementation(project(":kit"))
+
+    val composeBom = platform("androidx.compose:compose-bom:2026.05.01")
+    implementation(composeBom)
+
+    implementation("androidx.core:core-ktx:1.19.0")
+    implementation("androidx.activity:activity-compose:1.13.0")
+    implementation("androidx.lifecycle:lifecycle-runtime-ktx:2.10.0")
+
+    implementation("androidx.compose.ui:ui")
+    implementation("androidx.compose.ui:ui-tooling-preview")
+    implementation("androidx.compose.foundation:foundation")
+    implementation("androidx.compose.material3:material3")
+    implementation("androidx.compose.material:material-icons-core") // bottom-bar tab icons
+    debugImplementation("androidx.compose.ui:ui-tooling")
+
+    // Android TV components (we target phone + TV) land in the TV-UI milestone:
+    //   implementation("androidx.tv:tv-material:1.1.0")
+    // The manifest already declares leanback so the scaffold installs on TV.
+}

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

@@ -0,0 +1,49 @@
+<?xml version="1.0" encoding="utf-8"?>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+
+    <!-- punktfunk/1 QUIC/UDP data plane. -->
+    <uses-permission android:name="android.permission.INTERNET" />
+    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
+    <!-- mDNS discovery of _punktfunk._udp on the LAN (NsdManager). -->
+    <uses-permission
+        android:name="android.permission.NEARBY_WIFI_DEVICES"
+        android:usesPermissionFlags="neverForLocation" />
+    <!-- Hold a MulticastLock while NsdManager discovery runs (OEM Wi-Fi power-save hedge). -->
+    <uses-permission android:name="android.permission.CHANGE_WIFI_MULTICAST_STATE" />
+    <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
+    <!-- Enforced from Android 17 (SDK 37) for ALL local-network traffic incl. the QUIC socket.
+         Harmless to declare on earlier releases. -->
+    <uses-permission android:name="android.permission.ACCESS_LOCAL_NETWORK" />
+    <!-- Mic uplink to the host's virtual microphone (requested at runtime). -->
+    <uses-permission android:name="android.permission.RECORD_AUDIO" />
+    <!-- Gamepad rumble feedback. -->
+    <uses-permission android:name="android.permission.VIBRATE" />
+
+    <!-- We target phone + TV from day one: keep the app installable on TV (no touchscreen) and on
+         devices without a gamepad. -->
+    <uses-feature android:name="android.hardware.touchscreen" android:required="false" />
+    <uses-feature android:name="android.software.leanback" android:required="false" />
+    <uses-feature android:name="android.hardware.gamepad" android:required="false" />
+
+    <application
+        android:allowBackup="false"
+        android:icon="@mipmap/ic_launcher"
+        android:roundIcon="@mipmap/ic_launcher_round"
+        android:label="@string/app_name"
+        android:supportsRtl="true"
+        android:theme="@style/Theme.PunktfunkAndroid">
+
+        <activity
+            android:name=".MainActivity"
+            android:exported="true"
+            android:configChanges="orientation|screenSize|keyboardHidden|screenLayout|density|navigation"
+            android:theme="@style/Theme.PunktfunkAndroid">
+            <intent-filter>
+                <action android:name="android.intent.action.MAIN" />
+                <category android:name="android.intent.category.LAUNCHER" />
+                <!-- TV launcher entry. -->
+                <category android:name="android.intent.category.LEANBACK_LAUNCHER" />
+            </intent-filter>
+        </activity>
+    </application>
+</manifest>

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

@@ -0,0 +1,827 @@
+package io.unom.punktfunk
+
+import android.Manifest
+import android.content.Context
+import android.content.pm.PackageManager
+import android.os.Build
+import android.os.Bundle
+import android.view.InputDevice
+import android.view.KeyEvent
+import android.view.MotionEvent
+import android.view.SurfaceHolder
+import android.view.SurfaceView
+import android.view.WindowManager
+import androidx.activity.ComponentActivity
+import androidx.activity.SystemBarStyle
+import androidx.activity.compose.BackHandler
+import androidx.activity.compose.rememberLauncherForActivityResult
+import androidx.activity.compose.setContent
+import androidx.activity.enableEdgeToEdge
+import androidx.activity.result.contract.ActivityResultContracts
+import androidx.compose.foundation.background
+import androidx.compose.foundation.gestures.awaitEachGesture
+import androidx.compose.foundation.gestures.awaitFirstDown
+import androidx.compose.foundation.layout.Box
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.Row
+import androidx.compose.foundation.layout.Spacer
+import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.height
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.layout.size
+import androidx.compose.foundation.layout.width
+import androidx.compose.foundation.rememberScrollState
+import androidx.compose.foundation.shape.CircleShape
+import androidx.compose.foundation.text.KeyboardOptions
+import androidx.compose.foundation.verticalScroll
+import androidx.compose.material.icons.Icons
+import androidx.compose.material.icons.filled.Add
+import androidx.compose.material.icons.filled.Home
+import androidx.compose.material.icons.filled.MoreVert
+import androidx.compose.material.icons.filled.Settings
+import androidx.compose.material3.AlertDialog
+import androidx.compose.material3.Button
+import androidx.compose.material3.DropdownMenu
+import androidx.compose.material3.DropdownMenuItem
+import androidx.compose.material3.ElevatedCard
+import androidx.compose.material3.ExperimentalMaterial3Api
+import androidx.compose.material3.ExtendedFloatingActionButton
+import androidx.compose.material3.Icon
+import androidx.compose.material3.IconButton
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.ModalBottomSheet
+import androidx.compose.material3.NavigationBar
+import androidx.compose.material3.NavigationBarItem
+import androidx.compose.material3.OutlinedTextField
+import androidx.compose.material3.Scaffold
+import androidx.compose.material3.Surface
+import androidx.compose.material3.Text
+import androidx.compose.material3.TextButton
+import androidx.compose.material3.darkColorScheme
+import androidx.compose.material3.rememberModalBottomSheetState
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.DisposableEffect
+import androidx.compose.runtime.LaunchedEffect
+import androidx.compose.runtime.getValue
+import androidx.compose.runtime.mutableStateOf
+import androidx.compose.runtime.remember
+import androidx.compose.runtime.rememberCoroutineScope
+import androidx.compose.runtime.setValue
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.draw.clip
+import androidx.compose.ui.graphics.vector.ImageVector
+import androidx.compose.ui.input.pointer.pointerInput
+import androidx.compose.ui.input.pointer.positionChange
+import androidx.compose.ui.platform.LocalContext
+import androidx.compose.ui.text.input.KeyboardType
+import androidx.compose.ui.text.style.TextAlign
+import androidx.compose.ui.text.style.TextOverflow
+import androidx.compose.ui.unit.dp
+import androidx.compose.ui.viewinterop.AndroidView
+import androidx.core.content.ContextCompat
+import io.unom.punktfunk.kit.Gamepad
+import io.unom.punktfunk.kit.GamepadFeedback
+import io.unom.punktfunk.kit.Keymap
+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.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 kotlin.math.abs
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.launch
+import kotlinx.coroutines.withContext
+
+class MainActivity : ComponentActivity() {
+    /**
+     * The active stream session handle (0 = not streaming). Set by [StreamScreen] while it's shown.
+     * `dispatchKeyEvent` is the earliest, most reliable key hook — above Compose's focus system —
+     * so hardware keys are forwarded to the host regardless of which view holds focus.
+     */
+    var streamHandle: Long = 0L
+
+    /** Joystick-axis state mapper for the active session (built/reset by StreamScreen). */
+    var axisMapper: Gamepad.AxisMapper? = null
+
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        // Dark, transparent system bars regardless of the system theme — our UI is always dark, so
+        // the status/nav bars blend with our surface and get light icons. (The no-arg edge-to-edge
+        // picks the *system* light/dark, which left a black status bar over our dark background.)
+        enableEdgeToEdge(
+            statusBarStyle = SystemBarStyle.dark(android.graphics.Color.TRANSPARENT),
+            navigationBarStyle = SystemBarStyle.dark(android.graphics.Color.TRANSPARENT),
+        )
+        setContent {
+            MaterialTheme(colorScheme = darkColorScheme()) {
+                Surface(modifier = Modifier.fillMaxSize()) { App() }
+            }
+        }
+    }
+
+    override fun dispatchKeyEvent(event: KeyEvent): Boolean {
+        val handle = streamHandle
+        if (handle != 0L) {
+            // Gamepad buttons (incl. DPAD only when truly from a gamepad — else KEYCODE_DPAD_* are
+            // keyboard arrows and belong to the VK path below).
+            if (event.isFromSource(InputDevice.SOURCE_GAMEPAD)) {
+                val bit = Gamepad.buttonBit(event.keyCode)
+                if (bit != 0) {
+                    when (event.action) {
+                        // repeatCount guard: don't re-send a held button as auto-repeat.
+                        KeyEvent.ACTION_DOWN ->
+                            if (event.repeatCount == 0) NativeBridge.nativeSendGamepadButton(handle, bit, true)
+                        KeyEvent.ACTION_UP -> NativeBridge.nativeSendGamepadButton(handle, bit, false)
+                    }
+                    return true // consumed
+                }
+            }
+            when (event.keyCode) {
+                // Leave these to the system even while streaming.
+                KeyEvent.KEYCODE_BACK, // → BackHandler leaves the stream
+                KeyEvent.KEYCODE_VOLUME_UP,
+                KeyEvent.KEYCODE_VOLUME_DOWN,
+                KeyEvent.KEYCODE_VOLUME_MUTE,
+                KeyEvent.KEYCODE_POWER -> {}
+                else -> {
+                    val down = when (event.action) {
+                        KeyEvent.ACTION_DOWN -> true
+                        KeyEvent.ACTION_UP -> false
+                        else -> return super.dispatchKeyEvent(event)
+                    }
+                    val vk = Keymap.toVk(event.keyCode)
+                    if (vk != 0) {
+                        NativeBridge.nativeSendKey(handle, vk, down, 0)
+                        return true // consumed — don't let the system also act on it
+                    }
+                }
+            }
+        }
+        return super.dispatchKeyEvent(event)
+    }
+
+    override fun dispatchGenericMotionEvent(event: MotionEvent): Boolean {
+        if (streamHandle != 0L && axisMapper?.onMotion(event) == true) return true
+        return super.dispatchGenericMotionEvent(event)
+    }
+}
+
+/** Bottom-bar destinations (the immersive stream view is shown full-screen, outside the bar). */
+private enum class Tab(val label: String, val icon: ImageVector) {
+    Connect("Connect", Icons.Filled.Home),
+    Settings("Settings", Icons.Filled.Settings),
+}
+
+/**
+ * A trust decision awaiting the user before a connect proceeds. [name] is the label to save the
+ * host under. Trust-on-first-use ([Kind.TRUST_NEW]) is only ever offered when the host ADVERTISED
+ * pair=optional; a pair=required host or a manually-typed/unknown-policy host goes straight to PIN
+ * pairing ([Kind.PAIR]), and a changed fingerprint forces re-pairing — never a silent re-trust.
+ */
+private data class PendingTrust(
+    val host: String,
+    val port: Int,
+    val name: String,
+    val advertisedFp: String?,
+    val kind: Kind,
+) {
+    enum class Kind { TRUST_NEW, FP_CHANGED, PAIR }
+}
+
+@Composable
+private fun App() {
+    val context = LocalContext.current
+    val settingsStore = remember { SettingsStore(context) }
+    var settings by remember { mutableStateOf(settingsStore.load()) }
+    var streamHandle by remember { mutableStateOf(0L) } // 0 = not streaming
+    var tab by remember { mutableStateOf(Tab.Connect) }
+
+    if (streamHandle != 0L) {
+        // Immersive: the stream takes the whole screen, no bottom bar.
+        StreamScreen(streamHandle, micEnabled = settings.micEnabled, onDisconnect = { streamHandle = 0L })
+    } else {
+        Scaffold(
+            bottomBar = {
+                NavigationBar {
+                    Tab.entries.forEach { t ->
+                        NavigationBarItem(
+                            selected = tab == t,
+                            onClick = { tab = t },
+                            icon = { Icon(t.icon, contentDescription = t.label) },
+                            label = { Text(t.label) },
+                        )
+                    }
+                }
+            },
+        ) { innerPadding ->
+            Box(Modifier.fillMaxSize().padding(innerPadding)) {
+                when (tab) {
+                    Tab.Connect -> ConnectScreen(settings = settings, onConnected = { streamHandle = it })
+                    Tab.Settings -> SettingsScreen(
+                        initial = settings,
+                        onChange = { settings = it; settingsStore.save(it) },
+                        onBack = { tab = Tab.Connect },
+                    )
+                }
+            }
+        }
+    }
+}
+
+@OptIn(ExperimentalMaterial3Api::class)
+@Composable
+private fun ConnectScreen(settings: Settings, onConnected: (Long) -> Unit) {
+    val scope = rememberCoroutineScope()
+    val context = LocalContext.current
+    var host by remember { mutableStateOf("") }
+    var port by remember { mutableStateOf("9777") }
+    var connecting by remember { mutableStateOf(false) }
+    var status by remember { mutableStateOf<String?>(null) }
+    // The host streams at exactly this mode; "Native" settings resolve from the device display.
+    val (w, h, hz) = settings.effectiveMode(context)
+
+    // mDNS discovery scoped to this screen; NsdManager callbacks arrive on the main thread, so the
+    // onChange callback can set Compose state directly. (Emulator SLIRP drops multicast → empty.)
+    // NsdManager discovery needs NEARBY_WIFI_DEVICES on Android 13+ (a runtime permission) — without
+    // it discoverServices silently finds nothing. Request it once, then (re)start discovery on grant.
+    val discovery = remember { HostDiscovery(context) }
+    var discovered by remember { mutableStateOf<List<DiscoveredHost>>(emptyList()) }
+    var nearbyGranted by remember { mutableStateOf(hasNearbyPermission(context)) }
+    val nearbyLauncher = rememberLauncherForActivityResult(
+        ActivityResultContracts.RequestPermission(),
+    ) { granted -> nearbyGranted = granted }
+    LaunchedEffect(Unit) {
+        if (!nearbyGranted && Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
+            nearbyLauncher.launch(Manifest.permission.NEARBY_WIFI_DEVICES)
+        }
+    }
+    DisposableEffect(nearbyGranted) {
+        discovery.onChange = { discovered = it }
+        if (nearbyGranted) discovery.start()
+        onDispose {
+            discovery.onChange = null
+            discovery.stop()
+        }
+    }
+
+    val identityStore = remember { IdentityStore(context) }
+    val knownHostStore = remember { KnownHostStore(context) }
+    var savedHosts by remember { mutableStateOf(knownHostStore.all()) }
+    // Mint-once on genuine first run; an Unrecoverable store (decrypt failure) surfaces here and
+    // refuses to connect — never silently shadow-minting a new identity (which would force re-pair).
+    var identity by remember { mutableStateOf<ClientIdentity?>(null) }
+    LaunchedEffect(Unit) {
+        runCatching { withContext(Dispatchers.IO) { obtainIdentity(identityStore) } }
+            .onSuccess { identity = it }
+            .onFailure { status = "Identity unavailable: ${it.message} — re-pair may be required" }
+    }
+    // A trust decision awaiting the user (first-connect TOFU / fp changed / PIN pairing).
+    var pendingTrust by remember { mutableStateOf<PendingTrust?>(null) }
+
+    // Issue the actual connect with identity + (optional) pin. On a TOFU connect (pinHex null),
+    // pin the fingerprint the host presented (as an unpaired known host) so the next connect goes
+    // straight through and it appears in the saved-hosts list.
+    fun doConnect(targetHost: String, targetPort: Int, name: String, pinHex: String?) {
+        val id = identity
+        if (id == null) {
+            status = "Identity not ready yet — try again in a moment"
+            return
+        }
+        connecting = true
+        status = "Connecting to $targetHost:$targetPort…"
+        discovery.stop() // free the Wi-Fi radio before the stream session
+        scope.launch {
+            val handle = withContext(Dispatchers.IO) {
+                NativeBridge.nativeConnect(
+                    targetHost, targetPort, w, h, hz,
+                    id.certPem, id.privateKeyPem, pinHex ?: "",
+                    settings.bitrateKbps, settings.compositor, settings.gamepad,
+                )
+            }
+            connecting = false
+            if (handle != 0L) {
+                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))
+                    }
+                }
+                onConnected(handle)
+            } else {
+                status = "Connection failed — check host/port, PIN, and logcat"
+                discovery.start()
+            }
+        }
+    }
+
+    // Decide pinned-reconnect vs fp-changed vs TOFU vs PIN pairing before connecting. Trust state is
+    // keyed by address:port, so a discovered and a manually-typed connection to the same host share
+    // one record. Trust-on-first-use is permitted ONLY when the host advertised pair=optional; a
+    // pair=required host, or a manual/unknown-policy host, must pair by PIN.
+    fun connect(targetHost: String, targetPort: Int, dh: DiscoveredHost? = null) {
+        val known = knownHostStore.get(targetHost, targetPort)
+        val adv = dh?.fingerprint?.lowercase()
+        val name = dh?.name ?: targetHost
+        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)
+            // 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)
+            // 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)
+            // pair=required, or a manual/unknown-policy host → PIN pairing is mandatory.
+            else -> pendingTrust =
+                PendingTrust(targetHost, targetPort, name, adv, PendingTrust.Kind.PAIR)
+        }
+    }
+
+    val sheetState = rememberModalBottomSheetState()
+    var showManualSheet by remember { mutableStateOf(false) }
+
+    Box(Modifier.fillMaxSize()) {
+        Column(
+            modifier = Modifier
+                .fillMaxSize()
+                .verticalScroll(rememberScrollState())
+                .padding(horizontal = 20.dp, vertical = 16.dp),
+            horizontalAlignment = Alignment.CenterHorizontally,
+        ) {
+            Spacer(Modifier.height(8.dp))
+            Text("Punktfunk", style = MaterialTheme.typography.headlineLarge)
+            Text(
+                "stream a remote desktop",
+                style = MaterialTheme.typography.bodyMedium,
+                color = MaterialTheme.colorScheme.onSurfaceVariant,
+            )
+            Spacer(Modifier.height(24.dp))
+
+            status?.let {
+                Text(
+                    it,
+                    style = MaterialTheme.typography.bodySmall,
+                    color = MaterialTheme.colorScheme.error,
+                    textAlign = TextAlign.Center,
+                )
+                Spacer(Modifier.height(16.dp))
+            }
+
+            if (savedHosts.isEmpty() && discovered.isEmpty()) {
+                EmptyHostsState()
+            }
+
+            if (savedHosts.isNotEmpty()) {
+                SectionLabel("Saved hosts")
+                savedHosts.forEach { kh ->
+                    HostCard(
+                        name = kh.name,
+                        address = "${kh.address}:${kh.port}",
+                        status = if (kh.paired) HostStatus.PAIRED else HostStatus.TOFU,
+                        enabled = !connecting,
+                        onConnect = { connect(kh.address, kh.port) },
+                        onForget = {
+                            knownHostStore.remove(kh.address, kh.port)
+                            savedHosts = knownHostStore.all()
+                        },
+                    )
+                }
+                Spacer(Modifier.height(20.dp))
+            }
+
+            if (discovered.isNotEmpty()) {
+                SectionLabel("Discovered on the network")
+                discovered.forEach { dh ->
+                    HostCard(
+                        name = dh.name,
+                        address = "${dh.host}:${dh.port}",
+                        status = if (dh.pairingRequired) HostStatus.PAIRING else HostStatus.TOFU,
+                        enabled = !connecting,
+                        onConnect = { connect(dh.host, dh.port, dh) },
+                        onForget = null,
+                    )
+                }
+                Spacer(Modifier.height(20.dp))
+            }
+
+            Spacer(Modifier.height(96.dp)) // clearance so the last card scrolls clear of the FAB
+        }
+
+        ExtendedFloatingActionButton(
+            onClick = { showManualSheet = true },
+            icon = { Icon(Icons.Filled.Add, contentDescription = null) },
+            text = { Text("Add host") },
+            expanded = !connecting,
+            modifier = Modifier
+                .align(Alignment.BottomEnd)
+                .padding(20.dp),
+        )
+    }
+
+    if (showManualSheet) {
+        ModalBottomSheet(
+            onDismissRequest = { showManualSheet = false },
+            sheetState = sheetState,
+        ) {
+            Column(
+                modifier = Modifier
+                    .fillMaxWidth()
+                    .padding(horizontal = 24.dp)
+                    .padding(bottom = 32.dp),
+            ) {
+                Text("Add a host", style = MaterialTheme.typography.titleLarge)
+                Spacer(Modifier.height(4.dp))
+                Text(
+                    "Enter its address. You'll pair with the host's PIN on first connect.",
+                    style = MaterialTheme.typography.bodyMedium,
+                    color = MaterialTheme.colorScheme.onSurfaceVariant,
+                )
+                Spacer(Modifier.height(20.dp))
+                OutlinedTextField(
+                    value = host,
+                    onValueChange = { host = it },
+                    label = { Text("Host") },
+                    singleLine = true,
+                    modifier = Modifier.fillMaxWidth(),
+                )
+                Spacer(Modifier.height(8.dp))
+                OutlinedTextField(
+                    value = port,
+                    onValueChange = { v -> port = v.filter { it.isDigit() }.take(5) },
+                    label = { Text("Port") },
+                    singleLine = true,
+                    keyboardOptions = KeyboardOptions(keyboardType = KeyboardType.Number),
+                    modifier = Modifier.fillMaxWidth(),
+                )
+                Spacer(Modifier.height(20.dp))
+                Button(
+                    enabled = !connecting && host.isNotBlank() && port.isNotBlank(),
+                    onClick = {
+                        val h = host.trim()
+                        val p = port.toIntOrNull() ?: 9777
+                        scope.launch { sheetState.hide() }.invokeOnCompletion {
+                            showManualSheet = false
+                            connect(h, p)
+                        }
+                    },
+                    modifier = Modifier.fillMaxWidth(),
+                ) { Text("Connect  ($w×$h@$hz)") }
+            }
+        }
+    }
+
+    pendingTrust?.let { pt ->
+        when (pt.kind) {
+            PendingTrust.Kind.TRUST_NEW -> AlertDialog(
+                onDismissRequest = { pendingTrust = null },
+                title = { Text("Trust this host?") },
+                text = {
+                    Column {
+                        Text("First connection to ${pt.host}:${pt.port}.")
+                        pt.advertisedFp?.let { Text("Fingerprint ${it.take(16)}…") }
+                        Text(
+                            "This host allows trust-on-first-use, but that can't tell an impostor " +
+                                "from the real host. Pairing with a PIN is stronger — it proves both sides.",
+                        )
+                    }
+                },
+                confirmButton = {
+                    TextButton({ pendingTrust = null; doConnect(pt.host, pt.port, pt.name, null) }) {
+                        Text("Trust (TOFU)")
+                    }
+                },
+                dismissButton = {
+                    Row {
+                        TextButton({ pendingTrust = pt.copy(kind = PendingTrust.Kind.PAIR) }) {
+                            Text("Pair with PIN…")
+                        }
+                        TextButton({ pendingTrust = null }) { Text("Cancel") }
+                    }
+                },
+            )
+            PendingTrust.Kind.FP_CHANGED -> AlertDialog(
+                onDismissRequest = { pendingTrust = null },
+                title = { Text("Host identity changed") },
+                text = {
+                    Text(
+                        "The pinned fingerprint for ${pt.host} no longer matches what it now " +
+                            "advertises. This can mean a host reinstall — or an impostor. Re-pair " +
+                            "with the host's PIN to continue.",
+                    )
+                },
+                confirmButton = {
+                    TextButton({ pendingTrust = pt.copy(kind = PendingTrust.Kind.PAIR) }) { Text("Re-pair") }
+                },
+                dismissButton = {
+                    TextButton({ pendingTrust = null }) { Text("Cancel") }
+                },
+            )
+            PendingTrust.Kind.PAIR -> {
+                var pin by remember(pt) { mutableStateOf("") }
+                var name by remember(pt) { mutableStateOf(Build.MODEL ?: "Android") }
+                var pairing by remember(pt) { mutableStateOf(false) }
+                var err by remember(pt) { mutableStateOf<String?>(null) }
+                AlertDialog(
+                    onDismissRequest = { if (!pairing) pendingTrust = null },
+                    title = { Text("Pair with PIN") },
+                    text = {
+                        Column {
+                            Text("Enter the 4-digit PIN shown on the host.")
+                            OutlinedTextField(
+                                value = pin,
+                                onValueChange = { v -> pin = v.filter { it.isDigit() }.take(4) },
+                                label = { Text("PIN") },
+                                singleLine = true,
+                                keyboardOptions = KeyboardOptions(keyboardType = KeyboardType.Number),
+                            )
+                            OutlinedTextField(
+                                value = name,
+                                onValueChange = { name = it },
+                                label = { Text("This device") },
+                                singleLine = true,
+                            )
+                            err?.let { Text(it, color = MaterialTheme.colorScheme.error) }
+                        }
+                    },
+                    confirmButton = {
+                        TextButton(
+                            enabled = !pairing && pin.length == 4 && identity != null,
+                            onClick = {
+                                val id = identity
+                                if (id != null) {
+                                    pairing = true
+                                    err = null
+                                    scope.launch {
+                                        val fp = withContext(Dispatchers.IO) {
+                                            NativeBridge.nativePair(
+                                                pt.host, pt.port, id.certPem, id.privateKeyPem, pin, name,
+                                            )
+                                        }
+                                        pairing = false
+                                        if (fp.isNotEmpty()) {
+                                            // Verified host fp — save as a paired known host.
+                                            knownHostStore.save(
+                                                KnownHost(pt.host, pt.port, pt.name, fp, paired = true),
+                                            )
+                                            savedHosts = knownHostStore.all()
+                                            pendingTrust = null
+                                            doConnect(pt.host, pt.port, pt.name, fp)
+                                        } else {
+                                            err = "Pairing failed — wrong PIN, or the host isn't armed."
+                                        }
+                                    }
+                                }
+                            },
+                        ) { Text(if (pairing) "Pairing…" else "Pair") }
+                    },
+                    dismissButton = {
+                        TextButton(enabled = !pairing, onClick = { pendingTrust = null }) { Text("Cancel") }
+                    },
+                )
+            }
+        }
+    }
+}
+
+/** NsdManager discovery needs NEARBY_WIFI_DEVICES on API 33+; below that it doesn't apply. */
+private fun hasNearbyPermission(context: Context): Boolean =
+    Build.VERSION.SDK_INT < Build.VERSION_CODES.TIRAMISU ||
+        ContextCompat.checkSelfPermission(context, Manifest.permission.NEARBY_WIFI_DEVICES) ==
+        PackageManager.PERMISSION_GRANTED
+
+/** Left-aligned section header above each block of the connect screen. */
+@Composable
+private fun SectionLabel(text: String) {
+    Text(
+        text,
+        style = MaterialTheme.typography.titleSmall,
+        color = MaterialTheme.colorScheme.primary,
+        modifier = Modifier.fillMaxWidth().padding(bottom = 8.dp),
+    )
+}
+
+/** Trust state of a host, shown as a colored pill on its card. */
+private enum class HostStatus(val label: String) {
+    PAIRED("Paired"),
+    PAIRING("PIN pairing"),
+    TOFU("Trust on first use"),
+}
+
+/**
+ * A host as an Apple-style card: a colored letter-avatar, name + address, a trust pill, and (for
+ * saved hosts) an overflow menu with Forget. Tapping the card connects.
+ */
+@Composable
+private fun HostCard(
+    name: String,
+    address: String,
+    status: HostStatus,
+    enabled: Boolean,
+    onConnect: () -> Unit,
+    onForget: (() -> Unit)?,
+) {
+    ElevatedCard(
+        onClick = onConnect,
+        enabled = enabled,
+        modifier = Modifier.fillMaxWidth().padding(vertical = 5.dp),
+    ) {
+        Row(
+            modifier = Modifier.fillMaxWidth().padding(start = 14.dp, top = 12.dp, bottom = 12.dp, end = 4.dp),
+            verticalAlignment = Alignment.CenterVertically,
+        ) {
+            HostAvatar(name)
+            Spacer(Modifier.width(14.dp))
+            Column(Modifier.weight(1f)) {
+                Text(
+                    name,
+                    style = MaterialTheme.typography.titleMedium,
+                    maxLines = 1,
+                    overflow = TextOverflow.Ellipsis,
+                )
+                Spacer(Modifier.height(2.dp))
+                Text(
+                    address,
+                    style = MaterialTheme.typography.bodySmall,
+                    color = MaterialTheme.colorScheme.onSurfaceVariant,
+                    maxLines = 1,
+                    overflow = TextOverflow.Ellipsis,
+                )
+                Spacer(Modifier.height(6.dp))
+                StatusPill(status)
+            }
+            if (onForget != null) {
+                var menu by remember { mutableStateOf(false) }
+                Box {
+                    IconButton(enabled = enabled, onClick = { menu = true }) {
+                        Icon(Icons.Filled.MoreVert, contentDescription = "More")
+                    }
+                    DropdownMenu(expanded = menu, onDismissRequest = { menu = false }) {
+                        DropdownMenuItem(
+                            text = { Text("Forget") },
+                            onClick = {
+                                menu = false
+                                onForget()
+                            },
+                        )
+                    }
+                }
+            } else {
+                Spacer(Modifier.width(8.dp))
+            }
+        }
+    }
+}
+
+/** A circular avatar with the host's first letter (Apple-contact style). */
+@Composable
+private fun HostAvatar(name: String) {
+    val letter = name.trim().firstOrNull()?.uppercaseChar()?.toString() ?: "?"
+    Box(
+        modifier = Modifier
+            .size(44.dp)
+            .clip(CircleShape)
+            .background(MaterialTheme.colorScheme.primaryContainer),
+        contentAlignment = Alignment.Center,
+    ) {
+        Text(
+            letter,
+            style = MaterialTheme.typography.titleMedium,
+            color = MaterialTheme.colorScheme.onPrimaryContainer,
+        )
+    }
+}
+
+/** A small colored dot + label for the host's trust state. */
+@Composable
+private 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)
+    }
+}
+
+/** Shown when there are no saved or discovered hosts. */
+@Composable
+private fun EmptyHostsState() {
+    Column(
+        modifier = Modifier.fillMaxWidth().padding(vertical = 56.dp),
+        horizontalAlignment = Alignment.CenterHorizontally,
+    ) {
+        Text("No hosts yet", style = MaterialTheme.typography.titleMedium)
+        Spacer(Modifier.height(8.dp))
+        Text(
+            "Hosts on your network show up here automatically.\nTap “Add host” to enter one by address.",
+            style = MaterialTheme.typography.bodyMedium,
+            color = MaterialTheme.colorScheme.onSurfaceVariant,
+            textAlign = TextAlign.Center,
+        )
+    }
+}
+
+@Composable
+private fun StreamScreen(handle: Long, micEnabled: Boolean, onDisconnect: () -> Unit) {
+    val context = LocalContext.current
+    val activity = context as? MainActivity
+    val window = activity?.window
+    // Start mic only if the user enabled it AND granted RECORD_AUDIO (else the AAudio input fails).
+    val micWanted = micEnabled && ContextCompat.checkSelfPermission(
+        context,
+        Manifest.permission.RECORD_AUDIO,
+    ) == PackageManager.PERMISSION_GRANTED
+
+    DisposableEffect(handle) {
+        window?.addFlags(WindowManager.LayoutParams.FLAG_KEEP_SCREEN_ON)
+        activity?.streamHandle = handle // route hardware keys to this session
+        activity?.axisMapper = Gamepad.AxisMapper(handle) // route joystick axes
+        // Host→client feedback (rumble + DualSense lightbar/LEDs); poll threads stopped before close.
+        val feedback = GamepadFeedback(handle).also { it.start() }
+        onDispose {
+            feedback.stop() // stop + join the poll threads BEFORE nativeClose frees the handle
+            activity?.axisMapper?.reset() // release-all so nothing sticks on the host
+            activity?.axisMapper = null
+            activity?.streamHandle = 0L
+            window?.clearFlags(WindowManager.LayoutParams.FLAG_KEEP_SCREEN_ON)
+            // Leaving the stream: stop the mic + audio + decode threads and tear down the session.
+            NativeBridge.nativeStopMic(handle)
+            NativeBridge.nativeStopAudio(handle)
+            NativeBridge.nativeStopVideo(handle)
+            NativeBridge.nativeClose(handle)
+        }
+    }
+
+    BackHandler { onDisconnect() }
+
+    Box(modifier = Modifier.fillMaxSize()) {
+        AndroidView(
+            modifier = Modifier.fillMaxSize(),
+            factory = { ctx ->
+                SurfaceView(ctx).apply {
+                    holder.addCallback(object : SurfaceHolder.Callback {
+                        override fun surfaceCreated(holder: SurfaceHolder) {
+                            NativeBridge.nativeStartVideo(handle, holder.surface)
+                            NativeBridge.nativeStartAudio(handle)
+                            if (micWanted) NativeBridge.nativeStartMic(handle)
+                        }
+
+                        override fun surfaceChanged(holder: SurfaceHolder, format: Int, width: Int, height: Int) {}
+
+                        override fun surfaceDestroyed(holder: SurfaceHolder) {
+                            NativeBridge.nativeStopMic(handle)
+                            NativeBridge.nativeStopAudio(handle)
+                            NativeBridge.nativeStopVideo(handle)
+                        }
+                    })
+                }
+            },
+        )
+        // Touch virtual-trackpad overlay: 1-finger drag → relative mouse move; tap → left click;
+        // 2-finger drag → scroll. (Physical-mouse pointer capture comes in a later increment.)
+        Box(
+            Modifier.fillMaxSize().pointerInput(handle) {
+                awaitEachGesture {
+                    val first = awaitFirstDown(requireUnconsumed = false)
+                    var moved = false
+                    var maxFingers = 1
+                    while (true) {
+                        val ev = awaitPointerEvent()
+                        val fingers = ev.changes.count { it.pressed }
+                        if (fingers == 0) break
+                        if (fingers > maxFingers) maxFingers = fingers
+                        val primary = ev.changes.firstOrNull { it.id == first.id } ?: ev.changes.first()
+                        val d = primary.positionChange()
+                        if (abs(d.x) > 0.5f || abs(d.y) > 0.5f) {
+                            moved = true
+                            if (fingers >= 2) {
+                                // screen +y down → wire +up, so negate y. Coarse divisor; tune live.
+                                val sy = (-d.y / 4f).toInt()
+                                val sx = (d.x / 4f).toInt()
+                                if (sy != 0) NativeBridge.nativeSendScroll(handle, 0, sy * 120)
+                                if (sx != 0) NativeBridge.nativeSendScroll(handle, 1, sx * 120)
+                            } else {
+                                NativeBridge.nativeSendPointerMove(handle, d.x.toInt(), d.y.toInt())
+                            }
+                        }
+                        ev.changes.forEach { it.consume() }
+                    }
+                    if (!moved && maxFingers == 1) {
+                        NativeBridge.nativeSendPointerButton(handle, 1, true)
+                        NativeBridge.nativeSendPointerButton(handle, 1, false)
+                    }
+                }
+            },
+        )
+    }
+}

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

@@ -0,0 +1,129 @@
+package io.unom.punktfunk
+
+import android.content.Context
+
+/**
+ * User-tunable stream settings, persisted in `SharedPreferences`. A `0` resolution/refresh means
+ * "native display mode" (resolved at connect time from [nativeDisplayMode]); `0` bitrate means the
+ * host's default. [compositor]/[gamepad] are the `CompositorPref`/`GamepadPref` wire bytes the host
+ * understands (0 = Auto). Mirrors the Linux/Apple clients' settings.
+ */
+data class Settings(
+    val width: Int = 0,
+    val height: Int = 0,
+    val hz: Int = 0,
+    val bitrateKbps: Int = 0,
+    val compositor: Int = 0,
+    val gamepad: Int = 0,
+    val micEnabled: Boolean = false,
+)
+
+/** Loads/saves [Settings] in the app-private `punktfunk_settings` prefs. */
+class SettingsStore(context: Context) {
+    private val prefs =
+        context.applicationContext.getSharedPreferences("punktfunk_settings", Context.MODE_PRIVATE)
+
+    fun load(): Settings = Settings(
+        width = prefs.getInt(K_W, 0),
+        height = prefs.getInt(K_H, 0),
+        hz = prefs.getInt(K_HZ, 0),
+        bitrateKbps = prefs.getInt(K_BITRATE, 0),
+        compositor = prefs.getInt(K_COMPOSITOR, 0),
+        gamepad = prefs.getInt(K_GAMEPAD, 0),
+        micEnabled = prefs.getBoolean(K_MIC, false),
+    )
+
+    fun save(s: Settings) {
+        prefs.edit()
+            .putInt(K_W, s.width)
+            .putInt(K_H, s.height)
+            .putInt(K_HZ, s.hz)
+            .putInt(K_BITRATE, s.bitrateKbps)
+            .putInt(K_COMPOSITOR, s.compositor)
+            .putInt(K_GAMEPAD, s.gamepad)
+            .putBoolean(K_MIC, s.micEnabled)
+            .apply()
+    }
+
+    private companion object {
+        const val K_W = "width"
+        const val K_H = "height"
+        const val K_HZ = "hz"
+        const val K_BITRATE = "bitrate_kbps"
+        const val K_COMPOSITOR = "compositor"
+        const val K_GAMEPAD = "gamepad"
+        const val K_MIC = "mic_enabled"
+    }
+}
+
+/**
+ * The device's native display mode as a landscape `(width, height, hz)` — the long edge is the
+ * width, since we stream a desktop. Falls back to 1920×1080@60 if the display can't be read.
+ * [context] must be a visual (Activity) context.
+ */
+fun nativeDisplayMode(context: Context): Triple<Int, Int, Int> {
+    // getDisplay() throws on a non-visual context rather than returning null — guard it.
+    val display = runCatching { context.display }.getOrNull() ?: return Triple(1920, 1080, 60)
+    val mode = display.mode
+    val w = mode.physicalWidth
+    val h = mode.physicalHeight
+    val hz = mode.refreshRate.toInt().coerceAtLeast(1)
+    return Triple(maxOf(w, h), minOf(w, h), hz)
+}
+
+/** Resolve [Settings] (with its 0=native placeholders) to the concrete mode to request. */
+fun Settings.effectiveMode(context: Context): Triple<Int, Int, Int> {
+    val native = nativeDisplayMode(context)
+    val w = if (width > 0) width else native.first
+    val h = if (height > 0) height else native.second
+    val hz = if (hz > 0) hz else native.third
+    return Triple(w, h, hz)
+}
+
+// ---- UI option tables (value, label). The first entry is always the "auto/native" default. ----
+
+/** (width, height, label). `(0,0)` = native display. */
+val RESOLUTION_OPTIONS = listOf(
+    Triple(0, 0, "Native display"),
+    Triple(1280, 720, "1280 × 720"),
+    Triple(1920, 1080, "1920 × 1080"),
+    Triple(2560, 1440, "2560 × 1440"),
+    Triple(3840, 2160, "3840 × 2160"),
+)
+
+/** (hz, label). `0` = native refresh. */
+val REFRESH_OPTIONS = listOf(
+    0 to "Native",
+    30 to "30 Hz",
+    60 to "60 Hz",
+    90 to "90 Hz",
+    120 to "120 Hz",
+    144 to "144 Hz",
+    165 to "165 Hz",
+    240 to "240 Hz",
+)
+
+/** (kbps, label). `0` = host default. */
+val BITRATE_OPTIONS = listOf(
+    0 to "Automatic",
+    10_000 to "10 Mbps",
+    20_000 to "20 Mbps",
+    50_000 to "50 Mbps",
+    100_000 to "100 Mbps",
+)
+
+/** index = CompositorPref wire byte. */
+val COMPOSITOR_OPTIONS = listOf(
+    "Automatic",
+    "KWin (KDE Plasma)",
+    "wlroots (Sway / Hyprland)",
+    "Mutter (GNOME)",
+    "gamescope",
+)
+
+/** index = GamepadPref wire byte. */
+val GAMEPAD_OPTIONS = listOf(
+    "Automatic",
+    "Xbox 360",
+    "DualSense",
+)

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

@@ -0,0 +1,152 @@
+package io.unom.punktfunk
+
+import android.Manifest
+import android.content.pm.PackageManager
+import androidx.activity.compose.BackHandler
+import androidx.activity.compose.rememberLauncherForActivityResult
+import androidx.activity.result.contract.ActivityResultContracts
+import androidx.compose.foundation.layout.Arrangement
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.Row
+import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.rememberScrollState
+import androidx.compose.foundation.verticalScroll
+import androidx.compose.material3.DropdownMenuItem
+import androidx.compose.material3.ExperimentalMaterial3Api
+import androidx.compose.material3.ExposedDropdownMenuBox
+import androidx.compose.material3.ExposedDropdownMenuAnchorType
+import androidx.compose.material3.ExposedDropdownMenuDefaults
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.OutlinedTextField
+import androidx.compose.material3.Switch
+import androidx.compose.material3.Text
+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.platform.LocalContext
+import androidx.compose.ui.unit.dp
+import androidx.core.content.ContextCompat
+
+/**
+ * Stream settings. Edits are persisted immediately via [onChange]; [onBack] returns to the connect
+ * screen. Resolution/refresh "Native" resolve from the device display at connect time.
+ */
+@Composable
+fun SettingsScreen(initial: Settings, onChange: (Settings) -> Unit, onBack: () -> Unit) {
+    var s by remember { mutableStateOf(initial) }
+    val context = LocalContext.current
+    fun update(next: Settings) {
+        s = next
+        onChange(next)
+    }
+
+    BackHandler(onBack = onBack)
+
+    Column(
+        modifier = Modifier.fillMaxSize().verticalScroll(rememberScrollState()).padding(24.dp),
+        verticalArrangement = Arrangement.spacedBy(16.dp),
+    ) {
+        Text("Settings", style = MaterialTheme.typography.headlineMedium)
+
+        val (nw, nh, nhz) = nativeDisplayMode(context)
+        SettingDropdown(
+            label = "Resolution",
+            options = RESOLUTION_OPTIONS.map { (w, h, lbl) ->
+                (w to h) to (if (w == 0) "$lbl ($nw × $nh)" else lbl)
+            },
+            selected = s.width to s.height,
+        ) { (w, h) -> update(s.copy(width = w, height = h)) }
+
+        SettingDropdown(
+            label = "Refresh rate",
+            options = REFRESH_OPTIONS.map { (hz, lbl) -> hz to (if (hz == 0) "$lbl (${nhz} Hz)" else lbl) },
+            selected = s.hz,
+        ) { hz -> update(s.copy(hz = hz)) }
+
+        SettingDropdown(
+            label = "Bitrate",
+            options = BITRATE_OPTIONS,
+            selected = s.bitrateKbps,
+        ) { kbps -> update(s.copy(bitrateKbps = kbps)) }
+
+        SettingDropdown(
+            label = "Compositor (virtual-display host backend)",
+            options = COMPOSITOR_OPTIONS.mapIndexed { i, lbl -> i to lbl },
+            selected = s.compositor,
+        ) { c -> update(s.copy(compositor = c)) }
+
+        SettingDropdown(
+            label = "Controller type",
+            options = GAMEPAD_OPTIONS.mapIndexed { i, lbl -> i to lbl },
+            selected = s.gamepad,
+        ) { g -> update(s.copy(gamepad = g)) }
+
+        // Mic uplink — turning it on requests RECORD_AUDIO; if denied, the toggle stays off.
+        val micLauncher = rememberLauncherForActivityResult(
+            ActivityResultContracts.RequestPermission(),
+        ) { granted -> update(s.copy(micEnabled = granted)) }
+        Row(modifier = Modifier.fillMaxWidth(), verticalAlignment = Alignment.CenterVertically) {
+            Column(Modifier.weight(1f)) {
+                Text("Microphone", style = MaterialTheme.typography.bodyLarge)
+                Text(
+                    "Send your mic to the host's virtual microphone",
+                    style = MaterialTheme.typography.bodySmall,
+                )
+            }
+            Switch(
+                checked = s.micEnabled,
+                onCheckedChange = { on ->
+                    when {
+                        !on -> update(s.copy(micEnabled = false))
+                        ContextCompat.checkSelfPermission(context, Manifest.permission.RECORD_AUDIO) ==
+                            PackageManager.PERMISSION_GRANTED -> update(s.copy(micEnabled = true))
+                        else -> micLauncher.launch(Manifest.permission.RECORD_AUDIO)
+                    }
+                },
+            )
+        }
+    }
+}
+
+/** A labelled read-only dropdown over [options] (value → label); calls [onSelect] on a pick. */
+@OptIn(ExperimentalMaterial3Api::class)
+@Composable
+private fun <T> SettingDropdown(
+    label: String,
+    options: List<Pair<T, String>>,
+    selected: T,
+    onSelect: (T) -> Unit,
+) {
+    var expanded by remember { mutableStateOf(false) }
+    val selectedLabel = options.firstOrNull { it.first == selected }?.second
+        ?: options.firstOrNull()?.second.orEmpty()
+    ExposedDropdownMenuBox(expanded = expanded, onExpandedChange = { expanded = it }) {
+        OutlinedTextField(
+            value = selectedLabel,
+            onValueChange = {},
+            readOnly = true,
+            label = { Text(label) },
+            trailingIcon = { ExposedDropdownMenuDefaults.TrailingIcon(expanded = expanded) },
+            modifier = Modifier
+                .menuAnchor(ExposedDropdownMenuAnchorType.PrimaryNotEditable)
+                .fillMaxWidth(),
+        )
+        ExposedDropdownMenu(expanded = expanded, onDismissRequest = { expanded = false }) {
+            options.forEach { (value, lbl) ->
+                DropdownMenuItem(
+                    text = { Text(lbl) },
+                    onClick = {
+                        onSelect(value)
+                        expanded = false
+                    },
+                )
+            }
+        }
+    }
+}

clients/android/app/src/main/res/drawable/ic_launcher_foreground.xml

@@ -0,0 +1,27 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+  Punktfunk mark: two overlapping violet circles (two "Punkte") with a lighter lens, from the
+  shared brand logo (clients/apple/.../punktfunk_Logo.icon). The source art lives in a 1001x1000
+  space; the group scales + centers it into the adaptive-icon 108dp safe zone (inner ~66dp circle).
+-->
+<vector xmlns:android="http://schemas.android.com/apk/res/android"
+    android:width="108dp"
+    android:height="108dp"
+    android:viewportWidth="108"
+    android:viewportHeight="108">
+    <group
+        android:scaleX="0.073"
+        android:scaleY="0.073"
+        android:translateX="18.94"
+        android:translateY="16.03">
+        <path
+            android:fillColor="#A79FF8"
+            android:pathData="M403.037,791.672c107.586,0 194.41,-86.824 194.41,-194.41c0,-107.586 -86.824,-194.41 -194.41,-194.41c-107.586,0 -194.41,86.824 -194.41,194.41c0,107.586 86.824,194.41 194.41,194.41Z" />
+        <path
+            android:fillColor="#6C5BF3"
+            android:pathData="M735.276,540.321c76.075,-76.075 76.075,-198.862 0,-274.937c-76.075,-76.075 -198.862,-76.075 -274.937,0c-76.075,76.075 -76.075,198.862 0,274.937c76.075,76.075 198.862,76.075 274.937,0Z" />
+        <path
+            android:fillColor="#D2C9FB"
+            android:pathData="M647.84,590.737c-64.853,17.403 -136.871,0.597 -187.885,-50.416c-51.013,-51.013 -67.819,-123.032 -50.416,-187.885c64.853,-17.403 136.871,-0.597 187.885,50.416c51.013,51.013 67.819,123.032 50.416,187.885Z" />
+    </group>
+</vector>

clients/android/app/src/main/res/drawable/ic_launcher_monochrome.xml

@@ -0,0 +1,24 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+  Themed-icon (Android 13+/Material You) layer: the Punktfunk silhouette in a single tone — the two
+  overlapping circles as one shape. The launcher recolors this to match the wallpaper, so the fill
+  colour here only needs to be opaque. Same geometry/centering as the foreground.
+-->
+<vector xmlns:android="http://schemas.android.com/apk/res/android"
+    android:width="108dp"
+    android:height="108dp"
+    android:viewportWidth="108"
+    android:viewportHeight="108">
+    <group
+        android:scaleX="0.105"
+        android:scaleY="0.105"
+        android:translateX="3.57"
+        android:translateY="-0.62">
+        <path
+            android:fillColor="#1B1B1F"
+            android:pathData="M403.037,791.672c107.586,0 194.41,-86.824 194.41,-194.41c0,-107.586 -86.824,-194.41 -194.41,-194.41c-107.586,0 -194.41,86.824 -194.41,194.41c0,107.586 86.824,194.41 194.41,194.41Z" />
+        <path
+            android:fillColor="#1B1B1F"
+            android:pathData="M735.276,540.321c76.075,-76.075 76.075,-198.862 0,-274.937c-76.075,-76.075 -198.862,-76.075 -274.937,0c-76.075,76.075 -76.075,198.862 0,274.937c76.075,76.075 198.862,76.075 274.937,0Z" />
+    </group>
+</vector>

clients/android/app/src/main/res/mipmap-anydpi-v26/ic_launcher.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="utf-8"?>
+<adaptive-icon xmlns:android="http://schemas.android.com/apk/res/android">
+    <background android:drawable="@color/ic_launcher_background" />
+    <foreground android:drawable="@drawable/ic_launcher_foreground" />
+    <monochrome android:drawable="@drawable/ic_launcher_monochrome" />
+</adaptive-icon>

clients/android/app/src/main/res/mipmap-anydpi-v26/ic_launcher_round.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="utf-8"?>
+<adaptive-icon xmlns:android="http://schemas.android.com/apk/res/android">
+    <background android:drawable="@color/ic_launcher_background" />
+    <foreground android:drawable="@drawable/ic_launcher_foreground" />
+    <monochrome android:drawable="@drawable/ic_launcher_monochrome" />
+</adaptive-icon>

clients/android/app/src/main/res/values/colors.xml

@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="utf-8"?>
+<resources>
+    <!-- Adaptive-icon background: dark indigo so the violet Punktfunk dots pop. -->
+    <color name="ic_launcher_background">#16132A</color>
+</resources>

clients/android/app/src/main/res/values/strings.xml

@@ -0,0 +1,4 @@
+<?xml version="1.0" encoding="utf-8"?>
+<resources>
+    <string name="app_name">Punktfunk</string>
+</resources>

clients/android/app/src/main/res/values/themes.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="utf-8"?>
+<resources>
+    <!-- The Activity is pure Compose; this platform theme just provides a no-action-bar host.
+         Compose draws its own Material 3 surfaces over it. -->
+    <style name="Theme.PunktfunkAndroid" parent="android:Theme.Material.NoActionBar" />
+</resources>

clients/android/build.gradle.kts

@@ -0,0 +1,11 @@
+// Root build file. AGP 9.2.0 has BUILT-IN Kotlin support — modules do NOT apply
+// 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
+// 2026.05.01 · compileSdk 37 · targetSdk 36 · minSdk 31.
+plugins {
+    id("com.android.application") version "9.2.0" apply false
+    id("com.android.library") version "9.2.0" apply false
+    id("org.jetbrains.kotlin.plugin.compose") version "2.3.21" apply false
+}

clients/android/gradle.properties

@@ -0,0 +1,16 @@
+org.gradle.jvmargs=-Xmx4g -Dfile.encoding=UTF-8
+org.gradle.caching=true
+# Configuration cache: off for now — the cargo-ndk Exec task graph is simpler to reason about
+# during the scaffold. Enable once the native-build wiring is stable.
+org.gradle.configuration-cache=false
+
+android.useAndroidX=true
+android.nonTransitiveRClass=true
+
+kotlin.code.style=official
+
+# Gradle/AGP 9.2 must RUN on JDK 17–21 — NOT this machine's default JDK 25.
+#  * Android Studio uses its bundled JBR 21 automatically (no config needed).
+#  * CLI builds: launch gradlew with JDK 21, e.g.
+#      JAVA_HOME="$(brew --prefix openjdk@21)/libexec/openjdk.jdk/Contents/Home" ./gradlew assembleDebug
+# Intentionally NOT setting org.gradle.java.home here — it would hardcode a machine-specific path.

clients/android/gradle/wrapper/gradle-wrapper.properties

@@ -0,0 +1,9 @@
+distributionBase=GRADLE_USER_HOME
+distributionPath=wrapper/dists
+distributionUrl=https\://services.gradle.org/distributions/gradle-9.4.1-bin.zip
+networkTimeout=10000
+retries=0
+retryBackOffMs=500
+validateDistributionUrl=true
+zipStoreBase=GRADLE_USER_HOME
+zipStorePath=wrapper/dists

clients/android/gradlew

@@ -0,0 +1,248 @@
+#!/bin/sh
+
+#
+# Copyright © 2015 the original authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# SPDX-License-Identifier: Apache-2.0
+#
+
+##############################################################################
+#
+#   Gradle start up script for POSIX generated by Gradle.
+#
+#   Important for running:
+#
+#   (1) You need a POSIX-compliant shell to run this script. If your /bin/sh is
+#       noncompliant, but you have some other compliant shell such as ksh or
+#       bash, then to run this script, type that shell name before the whole
+#       command line, like:
+#
+#           ksh Gradle
+#
+#       Busybox and similar reduced shells will NOT work, because this script
+#       requires all of these POSIX shell features:
+#         * functions;
+#         * expansions «$var», «${var}», «${var:-default}», «${var+SET}»,
+#           «${var#prefix}», «${var%suffix}», and «$( cmd )»;
+#         * compound commands having a testable exit status, especially «case»;
+#         * various built-in commands including «command», «set», and «ulimit».
+#
+#   Important for patching:
+#
+#   (2) This script targets any POSIX shell, so it avoids extensions provided
+#       by Bash, Ksh, etc; in particular arrays are avoided.
+#
+#       The "traditional" practice of packing multiple parameters into a
+#       space-separated string is a well documented source of bugs and security
+#       problems, so this is (mostly) avoided, by progressively accumulating
+#       options in "$@", and eventually passing that to Java.
+#
+#       Where the inherited environment variables (DEFAULT_JVM_OPTS, JAVA_OPTS,
+#       and GRADLE_OPTS) rely on word-splitting, this is performed explicitly;
+#       see the in-line comments for details.
+#
+#       There are tweaks for specific operating systems such as AIX, CygWin,
+#       Darwin, MinGW, and NonStop.
+#
+#   (3) This script is generated from the Groovy template
+#       https://github.com/gradle/gradle/blob/3d91ce3b8caaf77ad09f381f43615b715b53f72c/platforms/jvm/plugins-application/src/main/resources/org/gradle/api/internal/plugins/unixStartScript.txt
+#       within the Gradle project.
+#
+#       You can find Gradle at https://github.com/gradle/gradle/.
+#
+##############################################################################
+
+# Attempt to set APP_HOME
+
+# Resolve links: $0 may be a link
+app_path=$0
+
+# Need this for daisy-chained symlinks.
+while
+    APP_HOME=${app_path%"${app_path##*/}"}  # leaves a trailing /; empty if no leading path
+    [ -h "$app_path" ]
+do
+    ls=$( ls -ld "$app_path" )
+    link=${ls#*' -> '}
+    case $link in             #(
+      /*)   app_path=$link ;; #(
+      *)    app_path=$APP_HOME$link ;;
+    esac
+done
+
+# This is normally unused
+# shellcheck disable=SC2034
+APP_BASE_NAME=${0##*/}
+# Discard cd standard output in case $CDPATH is set (https://github.com/gradle/gradle/issues/25036)
+APP_HOME=$( cd -P "${APP_HOME:-./}" > /dev/null && printf '%s\n' "$PWD" ) || exit
+
+# Use the maximum available, or set MAX_FD != -1 to use that value.
+MAX_FD=maximum
+
+warn () {
+    echo "$*"
+} >&2
+
+die () {
+    echo
+    echo "$*"
+    echo
+    exit 1
+} >&2
+
+# OS specific support (must be 'true' or 'false').
+cygwin=false
+msys=false
+darwin=false
+nonstop=false
+case "$( uname )" in                #(
+  CYGWIN* )         cygwin=true  ;; #(
+  Darwin* )         darwin=true  ;; #(
+  MSYS* | MINGW* )  msys=true    ;; #(
+  NONSTOP* )        nonstop=true ;;
+esac
+
+
+
+# Determine the Java command to use to start the JVM.
+if [ -n "$JAVA_HOME" ] ; then
+    if [ -x "$JAVA_HOME/jre/sh/java" ] ; then
+        # IBM's JDK on AIX uses strange locations for the executables
+        JAVACMD=$JAVA_HOME/jre/sh/java
+    else
+        JAVACMD=$JAVA_HOME/bin/java
+    fi
+    if [ ! -x "$JAVACMD" ] ; then
+        die "ERROR: JAVA_HOME is set to an invalid directory: $JAVA_HOME
+
+Please set the JAVA_HOME variable in your environment to match the
+location of your Java installation."
+    fi
+else
+    JAVACMD=java
+    if ! command -v java >/dev/null 2>&1
+    then
+        die "ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH.
+
+Please set the JAVA_HOME variable in your environment to match the
+location of your Java installation."
+    fi
+fi
+
+# Increase the maximum file descriptors if we can.
+if ! "$cygwin" && ! "$darwin" && ! "$nonstop" ; then
+    case $MAX_FD in #(
+      max*)
+        # In POSIX sh, ulimit -H is undefined. That's why the result is checked to see if it worked.
+        # shellcheck disable=SC2039,SC3045
+        MAX_FD=$( ulimit -H -n ) ||
+            warn "Could not query maximum file descriptor limit"
+    esac
+    case $MAX_FD in  #(
+      '' | soft) :;; #(
+      *)
+        # In POSIX sh, ulimit -n is undefined. That's why the result is checked to see if it worked.
+        # shellcheck disable=SC2039,SC3045
+        ulimit -n "$MAX_FD" ||
+            warn "Could not set maximum file descriptor limit to $MAX_FD"
+    esac
+fi
+
+# Collect all arguments for the java command, stacking in reverse order:
+#   * args from the command line
+#   * the main class name
+#   * -classpath
+#   * -D...appname settings
+#   * --module-path (only if needed)
+#   * DEFAULT_JVM_OPTS, JAVA_OPTS, and GRADLE_OPTS environment variables.
+
+# For Cygwin or MSYS, switch paths to Windows format before running java
+if "$cygwin" || "$msys" ; then
+    APP_HOME=$( cygpath --path --mixed "$APP_HOME" )
+
+    JAVACMD=$( cygpath --unix "$JAVACMD" )
+
+    # Now convert the arguments - kludge to limit ourselves to /bin/sh
+    for arg do
+        if
+            case $arg in                                #(
+              -*)   false ;;                            # don't mess with options #(
+              /?*)  t=${arg#/} t=/${t%%/*}              # looks like a POSIX filepath
+                    [ -e "$t" ] ;;                      #(
+              *)    false ;;
+            esac
+        then
+            arg=$( cygpath --path --ignore --mixed "$arg" )
+        fi
+        # Roll the args list around exactly as many times as the number of
+        # args, so each arg winds up back in the position where it started, but
+        # possibly modified.
+        #
+        # NB: a `for` loop captures its iteration list before it begins, so
+        # changing the positional parameters here affects neither the number of
+        # iterations, nor the values presented in `arg`.
+        shift                   # remove old arg
+        set -- "$@" "$arg"      # push replacement arg
+    done
+fi
+
+
+# Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script.
+DEFAULT_JVM_OPTS='"-Xmx64m" "-Xms64m"'
+
+# Collect all arguments for the java command:
+#   * DEFAULT_JVM_OPTS, JAVA_OPTS, and optsEnvironmentVar are not allowed to contain shell fragments,
+#     and any embedded shellness will be escaped.
+#   * For example: A user cannot expect ${Hostname} to be expanded, as it is an environment variable and will be
+#     treated as '${Hostname}' itself on the command line.
+
+set -- \
+        "-Dorg.gradle.appname=$APP_BASE_NAME" \
+        -jar "$APP_HOME/gradle/wrapper/gradle-wrapper.jar" \
+        "$@"
+
+# Stop when "xargs" is not available.
+if ! command -v xargs >/dev/null 2>&1
+then
+    die "xargs is not available"
+fi
+
+# Use "xargs" to parse quoted args.
+#
+# With -n1 it outputs one arg per line, with the quotes and backslashes removed.
+#
+# In Bash we could simply go:
+#
+#   readarray ARGS < <( xargs -n1 <<<"$var" ) &&
+#   set -- "${ARGS[@]}" "$@"
+#
+# but POSIX shell has neither arrays nor command substitution, so instead we
+# post-process each arg (as a line of input to sed) to backslash-escape any
+# character that might be a shell metacharacter, then use eval to reverse
+# that process (while maintaining the separation between arguments), and wrap
+# the whole thing up as a single "set" statement.
+#
+# This will of course break if any of these variables contains a newline or
+# an unmatched quote.
+#
+
+eval "set -- $(
+        printf '%s\n' "$DEFAULT_JVM_OPTS $JAVA_OPTS $GRADLE_OPTS" |
+        xargs -n1 |
+        sed ' s~[^-[:alnum:]+,./:=@_]~\\&~g; ' |
+        tr '\n' ' '
+    )" '"$@"'
+
+exec "$JAVACMD" "$@"

clients/android/gradlew.bat

@@ -0,0 +1,82 @@
+@rem
+@rem Copyright 2015 the original author or authors.
+@rem
+@rem Licensed under the Apache License, Version 2.0 (the "License");
+@rem you may not use this file except in compliance with the License.
+@rem You may obtain a copy of the License at
+@rem
+@rem      https://www.apache.org/licenses/LICENSE-2.0
+@rem
+@rem Unless required by applicable law or agreed to in writing, software
+@rem distributed under the License is distributed on an "AS IS" BASIS,
+@rem WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+@rem See the License for the specific language governing permissions and
+@rem limitations under the License.
+@rem
+@rem SPDX-License-Identifier: Apache-2.0
+@rem
+
+@if "%DEBUG%"=="" @echo off
+@rem ##########################################################################
+@rem
+@rem  Gradle startup script for Windows
+@rem
+@rem ##########################################################################
+
+@rem Set local scope for the variables, and ensure extensions are enabled
+setlocal EnableExtensions
+
+set DIRNAME=%~dp0
+if "%DIRNAME%"=="" set DIRNAME=.
+@rem This is normally unused
+set APP_BASE_NAME=%~n0
+set APP_HOME=%DIRNAME%
+
+@rem Resolve any "." and ".." in APP_HOME to make it shorter.
+for %%i in ("%APP_HOME%") do set APP_HOME=%%~fi
+
+@rem Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script.
+set DEFAULT_JVM_OPTS="-Xmx64m" "-Xms64m"
+
+@rem Find java.exe
+if defined JAVA_HOME goto findJavaFromJavaHome
+
+set JAVA_EXE=java.exe
+%JAVA_EXE% -version >NUL 2>&1
+if %ERRORLEVEL% equ 0 goto execute
+
+echo. 1>&2
+echo ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH. 1>&2
+echo. 1>&2
+echo Please set the JAVA_HOME variable in your environment to match the 1>&2
+echo location of your Java installation. 1>&2
+
+"%COMSPEC%" /c exit 1
+
+:findJavaFromJavaHome
+set JAVA_HOME=%JAVA_HOME:"=%
+set JAVA_EXE=%JAVA_HOME%/bin/java.exe
+
+if exist "%JAVA_EXE%" goto execute
+
+echo. 1>&2
+echo ERROR: JAVA_HOME is set to an invalid directory: %JAVA_HOME% 1>&2
+echo. 1>&2
+echo Please set the JAVA_HOME variable in your environment to match the 1>&2
+echo location of your Java installation. 1>&2
+
+"%COMSPEC%" /c exit 1
+
+:execute
+@rem Setup the command line
+
+
+
+@rem Execute Gradle
+@rem endlocal doesn't take effect until after the line is parsed and variables are expanded
+@rem which allows us to clear the local environment before executing the java command
+endlocal & "%JAVA_EXE%" %DEFAULT_JVM_OPTS% %JAVA_OPTS% %GRADLE_OPTS% "-Dorg.gradle.appname=%APP_BASE_NAME%" -jar "%APP_HOME%\gradle\wrapper\gradle-wrapper.jar" %* & call :exitWithErrorLevel
+
+:exitWithErrorLevel
+@rem Use "%COMSPEC%" /c exit to allow operators to work properly in scripts
+"%COMSPEC%" /c exit %ERRORLEVEL%

clients/android/kit/build.gradle.kts

@@ -0,0 +1,99 @@
+import java.io.File
+import java.util.Properties
+import org.jetbrains.kotlin.gradle.dsl.JvmTarget
+
+plugins {
+    // AGP 9 built-in Kotlin compiles this module's Kotlin (NativeBridge) — no kotlin.android plugin.
+    id("com.android.library")
+}
+
+val ndkVer = "28.2.13676358" // r28 LTS — matches the SDK NDK installed for cargo-ndk
+
+android {
+    namespace = "io.unom.punktfunk.kit"
+    compileSdk = 37 // Android 17 — align with :app (androidx.core 1.19.0 requires it)
+    ndkVersion = ndkVer
+
+    defaultConfig {
+        minSdk = 31
+        ndk { abiFilters += listOf("arm64-v8a", "x86_64") }
+    }
+    compileOptions {
+        sourceCompatibility = JavaVersion.VERSION_21
+        targetCompatibility = JavaVersion.VERSION_21
+    }
+    packaging { jniLibs { useLegacyPackaging = false } } // 16 KB-page friendly
+}
+
+kotlin { compilerOptions { jvmTarget.set(JvmTarget.JVM_21) } }
+
+dependencies {
+    testImplementation("junit:junit:4.13.2") // JVM unit test for the pure TXT parser
+}
+
+// ------------------------------------------------------------------------------------------------
+// cargo-ndk: cross-compile crates/punktfunk-android into this module's jniLibs/<abi>/ so the
+// resulting libpunktfunk_android.so is packaged into the app (and any AAR this module produces).
+// NDK r28+ aligns to 16 KB pages by default — no extra linker flags. Prereqs (see clients/android
+// /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"
+
+// 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.
+fun androidSdkDir(): String {
+    System.getenv("ANDROID_HOME")?.let { return it }
+    System.getenv("ANDROID_SDK_ROOT")?.let { return it }
+    val lp = rootProject.file("local.properties")
+    if (lp.exists()) {
+        val props = Properties()
+        lp.inputStream().use { props.load(it) }
+        props.getProperty("sdk.dir")?.let { return it }
+    }
+    return "${System.getProperty("user.home")}/Library/Android/sdk"
+}
+
+fun registerCargoNdk(taskName: String, release: Boolean) =
+    tasks.register<Exec>(taskName) {
+        group = "rust"
+        description = "cargo-ndk build of punktfunk-android (${if (release) "release" else "debug"})"
+        workingDir = repoRoot
+        val sdk = androidSdkDir()
+        // A GUI Android Studio launch does not source the login shell, so make cargo, the NDK, and
+        // cmake (libopus builds via the cmake crate) discoverable explicitly — same as a bare CLI.
+        val cmakeBin = "$sdk/cmake/3.22.1/bin"
+        environment(
+            "PATH",
+            cargoBin + File.pathSeparator + cmakeBin + File.pathSeparator + System.getenv("PATH"),
+        )
+        environment("ANDROID_HOME", sdk)
+        environment("ANDROID_NDK_HOME", "$sdk/ndk/$ndkVer")
+        // CMake's built-in Android support (used by the cmake crate for libopus) finds the NDK via
+        // these, and uses Ninja (bundled next to the SDK cmake) since there's no `make`.
+        environment("ANDROID_NDK_ROOT", "$sdk/ndk/$ndkVer")
+        environment("ANDROID_NDK", "$sdk/ndk/$ndkVer")
+        environment("CMAKE_GENERATOR", "Ninja")
+        // audiopus_sys picks static-vs-dynamic by HOST not target — force the bundled static libopus
+        // (pure C) so the android .so links it instead of looking for the host's libopus.so.
+        environment("LIBOPUS_STATIC", "1")
+        environment("LIBOPUS_NO_PKG", "1")
+        val cmd = mutableListOf(
+            "cargo", "ndk",
+            "-t", "arm64-v8a", "-t", "x86_64",
+            // Link against the minSdk-31 sysroot so libaaudio (API 26+) is found.
+            "--platform", "31",
+            "-o", file("src/main/jniLibs").absolutePath,
+            "build", "-p", "punktfunk-android",
+        )
+        if (release) cmd += "--release"
+        commandLine(cmd)
+    }
+
+val cargoNdkDebug = registerCargoNdk("cargoNdkDebug", release = false)
+val cargoNdkRelease = registerCargoNdk("cargoNdkRelease", release = true)
+
+afterEvaluate {
+    tasks.named("preDebugBuild").configure { dependsOn(cargoNdkDebug) }
+    tasks.named("preReleaseBuild").configure { dependsOn(cargoNdkRelease) }
+}

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

@@ -0,0 +1,3 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Library module manifest. The namespace lives in build.gradle.kts (AGP 9). -->
+<manifest />

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

@@ -0,0 +1,146 @@
+package io.unom.punktfunk.kit
+
+import android.view.InputDevice
+import android.view.KeyEvent
+import android.view.MotionEvent
+
+/**
+ * Android gamepad capture → punktfunk/1 gamepad wire (the `input.rs::gamepad` contract; the host
+ * accumulates the incremental events into its virtual xpad). The Android analogue of the Linux
+ * client's `gamepad.rs` (SDL3) and the Apple client's `GamepadCapture.swift` (GameController) — all
+ * three emit byte-identical events. Single-pad model: exactly one controller forwarded as pad 0.
+ *
+ * Buttons arrive as KeyEvents (SOURCE_GAMEPAD); sticks/triggers/HAT arrive as joystick MotionEvents
+ * (SOURCE_JOYSTICK, ACTION_MOVE). The D-pad is sent as BTN_DPAD_* buttons (no hat axis on the wire),
+ * decomposed from either KEYCODE_DPAD_* (gamepad source) or AXIS_HAT_X/Y.
+ *
+ * Normalization (wire = XInput/Moonlight): sticks i16 ±32767 with **+y = up**; triggers 0..255.
+ * Android AXIS_Y/AXIS_RZ are +y = down, so Y is negated. No deadzone here — the host/game owns it
+ * (parity with the Linux/Apple clients).
+ */
+object Gamepad {
+    // Button bits — must equal punktfunk-core `input.rs::gamepad::BTN_*`.
+    const val BTN_DPAD_UP = 0x0001
+    const val BTN_DPAD_DOWN = 0x0002
+    const val BTN_DPAD_LEFT = 0x0004
+    const val BTN_DPAD_RIGHT = 0x0008
+    const val BTN_START = 0x0010
+    const val BTN_BACK = 0x0020
+    const val BTN_LS_CLICK = 0x0040
+    const val BTN_RS_CLICK = 0x0080
+    const val BTN_LB = 0x0100
+    const val BTN_RB = 0x0200
+    const val BTN_GUIDE = 0x0400
+    const val BTN_A = 0x1000
+    const val BTN_B = 0x2000
+    const val BTN_X = 0x4000
+    const val BTN_Y = 0x8000
+
+    // Axis ids — must equal `input.rs::gamepad::AXIS_*`.
+    const val AXIS_LS_X = 0
+    const val AXIS_LS_Y = 1
+    const val AXIS_RS_X = 2
+    const val AXIS_RS_Y = 3
+    const val AXIS_LT = 4
+    const val AXIS_RT = 5
+
+    /**
+     * Gamepad `KEYCODE_*` → BTN_* bit, or 0 if not a gamepad button we forward. A/B/X/Y are
+     * positional (Xbox layout; Nintendo relabeling needs device-type detection, deferred).
+     * `KEYCODE_DPAD_*` are included but must only be routed here when the event is from a gamepad
+     * (a keyboard's arrow keys share these keycodes and belong to the VK path) — see MainActivity.
+     * L2/R2 are forwarded as the analog trigger axes, never as buttons.
+     */
+    fun buttonBit(keyCode: Int): Int = when (keyCode) {
+        KeyEvent.KEYCODE_BUTTON_A -> BTN_A
+        KeyEvent.KEYCODE_BUTTON_B -> BTN_B
+        KeyEvent.KEYCODE_BUTTON_X -> BTN_X
+        KeyEvent.KEYCODE_BUTTON_Y -> BTN_Y
+        KeyEvent.KEYCODE_BUTTON_L1 -> BTN_LB
+        KeyEvent.KEYCODE_BUTTON_R1 -> BTN_RB
+        KeyEvent.KEYCODE_BUTTON_THUMBL -> BTN_LS_CLICK
+        KeyEvent.KEYCODE_BUTTON_THUMBR -> BTN_RS_CLICK
+        KeyEvent.KEYCODE_BUTTON_START -> BTN_START
+        KeyEvent.KEYCODE_BUTTON_SELECT -> BTN_BACK
+        KeyEvent.KEYCODE_BUTTON_MODE -> BTN_GUIDE
+        KeyEvent.KEYCODE_DPAD_UP -> BTN_DPAD_UP
+        KeyEvent.KEYCODE_DPAD_DOWN -> BTN_DPAD_DOWN
+        KeyEvent.KEYCODE_DPAD_LEFT -> BTN_DPAD_LEFT
+        KeyEvent.KEYCODE_DPAD_RIGHT -> BTN_DPAD_RIGHT
+        else -> 0
+    }
+
+    /**
+     * Maps joystick MotionEvents to axis (+ HAT→dpad) sends for one session, **on change only**.
+     * Holds the previous axis/hat state so an unchanged frame emits nothing. One instance per
+     * session; call [reset] on release-all (focus loss / disconnect / session stop) so nothing
+     * sticks on the host (which has no client-side held-state knowledge).
+     */
+    class AxisMapper(private val handle: Long) {
+        // Sentinel so the first real value (incl. 0) always sends once after attach (Linux parity).
+        private val last = IntArray(6) { Int.MIN_VALUE }
+        private var hatX = 0 // -1 / 0 / +1
+        private var hatY = 0
+
+        /** Returns true if this was a joystick ACTION_MOVE we consumed. */
+        fun onMotion(event: MotionEvent): Boolean {
+            if (!event.isFromSource(InputDevice.SOURCE_JOYSTICK)) return false
+            if (event.actionMasked != MotionEvent.ACTION_MOVE) return false
+
+            // Sticks: Android floats −1..1, +y = down → ±32767, negate Y for the wire's +y = up.
+            sendAxis(AXIS_LS_X, stick(event.getAxisValue(MotionEvent.AXIS_X)))
+            sendAxis(AXIS_LS_Y, stick(-event.getAxisValue(MotionEvent.AXIS_Y)))
+            sendAxis(AXIS_RS_X, stick(event.getAxisValue(MotionEvent.AXIS_Z)))
+            sendAxis(AXIS_RS_Y, stick(-event.getAxisValue(MotionEvent.AXIS_RZ)))
+
+            // Triggers: LTRIGGER/RTRIGGER if present, else BRAKE/GAS; 0..1 float → 0..255.
+            sendAxis(AXIS_LT, trigger(firstNonZero(event, MotionEvent.AXIS_LTRIGGER, MotionEvent.AXIS_BRAKE)))
+            sendAxis(AXIS_RT, trigger(firstNonZero(event, MotionEvent.AXIS_RTRIGGER, MotionEvent.AXIS_GAS)))
+
+            // HAT → dpad button transitions (track previous, emit only the deltas).
+            val hx = sign(event.getAxisValue(MotionEvent.AXIS_HAT_X))
+            if (hx != hatX) {
+                if (hatX < 0) btn(BTN_DPAD_LEFT, false) else if (hatX > 0) btn(BTN_DPAD_RIGHT, false)
+                if (hx < 0) btn(BTN_DPAD_LEFT, true) else if (hx > 0) btn(BTN_DPAD_RIGHT, true)
+                hatX = hx
+            }
+            val hy = sign(event.getAxisValue(MotionEvent.AXIS_HAT_Y))
+            if (hy != hatY) {
+                if (hatY < 0) btn(BTN_DPAD_UP, false) else if (hatY > 0) btn(BTN_DPAD_DOWN, false)
+                if (hy < 0) btn(BTN_DPAD_UP, true) else if (hy > 0) btn(BTN_DPAD_DOWN, true)
+                hatY = hy
+            }
+            return true
+        }
+
+        /** Release-all: zero every axis and clear the held dpad. */
+        fun reset() {
+            for (id in 0..5) sendAxis(id, 0)
+            if (hatX < 0) btn(BTN_DPAD_LEFT, false) else if (hatX > 0) btn(BTN_DPAD_RIGHT, false)
+            if (hatY < 0) btn(BTN_DPAD_UP, false) else if (hatY > 0) btn(BTN_DPAD_DOWN, false)
+            hatX = 0
+            hatY = 0
+        }
+
+        private fun sendAxis(id: Int, v: Int) {
+            if (last[id] == v) return
+            last[id] = v
+            NativeBridge.nativeSendGamepadAxis(handle, id, v)
+        }
+
+        private fun btn(bit: Int, down: Boolean) = NativeBridge.nativeSendGamepadButton(handle, bit, down)
+
+        // −1..1 float → ±32767 i16 (matches the Apple client's 32767 scale).
+        private fun stick(v: Float): Int = (v.coerceIn(-1f, 1f) * 32767f).toInt()
+
+        // 0..1 float → 0..255.
+        private fun trigger(v: Float): Int = (v.coerceIn(0f, 1f) * 255f).toInt()
+
+        private fun sign(v: Float): Int = if (v < -0.5f) -1 else if (v > 0.5f) 1 else 0
+
+        private fun firstNonZero(e: MotionEvent, a: Int, b: Int): Float {
+            val va = e.getAxisValue(a)
+            return if (va != 0f) va else e.getAxisValue(b)
+        }
+    }
+}

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

@@ -0,0 +1,234 @@
+package io.unom.punktfunk.kit
+
+import android.graphics.Color
+import android.hardware.lights.Light
+import android.hardware.lights.LightState
+import android.hardware.lights.LightsManager
+import android.hardware.lights.LightsRequest
+import android.os.Build
+import android.os.CombinedVibration
+import android.os.VibrationEffect
+import android.os.VibratorManager
+import android.util.Log
+import android.view.InputDevice
+import java.nio.ByteBuffer
+
+/**
+ * Host→client gamepad feedback for one session (single-pad model — pad 0 only). Two daemon poll
+ * threads drain the blocking native pulls and render in Kotlin: rumble → the controller's
+ * `VibratorManager`; HID-output → lightbar / player-LED via `LightsManager` (API 33+); adaptive
+ * triggers are parse-validated and logged (Android has no public adaptive-trigger API).
+ *
+ * Mirrors `nativeStartAudio`'s lifecycle: [start]/[stop] driven by the StreamScreen. [stop] flips a
+ * flag; the ~100 ms native pull timeout lets the threads exit, then they're joined (bounded) — and
+ * this MUST run before `nativeClose` frees the session handle.
+ *
+ * The active pad is resolved from the connected input devices (first gamepad/joystick). With none
+ * connected (emulator) rumble/lights become logged no-ops — exactly the verification path; the
+ * `Log.i` receipt lines fire regardless of rendering hardware.
+ */
+class GamepadFeedback(private val handle: Long) {
+    private companion object {
+        const val TAG = "pf.feedback"
+        const val TAG_LED: Byte = 0x01
+        const val TAG_PLAYER_LEDS: Byte = 0x02
+        const val TAG_TRIGGER: Byte = 0x03
+    }
+
+    @Volatile private var running = false
+    private var rumbleThread: Thread? = null
+    private var hidoutThread: Thread? = null
+
+    private var vm: VibratorManager? = null
+    private var vibratorIds: IntArray = IntArray(0)
+    private var amplitudeControlled = false
+
+    private var lightsSession: LightsManager.LightsSession? = null
+    private var rgbLight: Light? = null
+    private var playerLight: Light? = null
+
+    fun start() {
+        val dev = resolvePad()
+        bindRumble(dev)
+        if (Build.VERSION.SDK_INT >= 33) {
+            bindLights(dev)
+        } else {
+            Log.i(TAG, "lights need API 33 (have ${Build.VERSION.SDK_INT}) — lightbar/playerLed no-op")
+        }
+
+        running = true
+        rumbleThread = Thread({
+            while (running) {
+                val ev = NativeBridge.nativeNextRumble(handle)
+                if (ev < 0L) continue // timeout / closed
+                renderRumble(((ev ushr 16) and 0xFFFF).toInt(), (ev and 0xFFFF).toInt())
+            }
+        }, "pf-rumble").apply { isDaemon = true; start() }
+
+        hidoutThread = Thread({
+            val buf = ByteBuffer.allocateDirect(64)
+            while (running) {
+                val n = NativeBridge.nativeNextHidout(handle, buf)
+                if (n < 0) continue // timeout / closed
+                dispatchHidout(buf, n)
+            }
+        }, "pf-hidout").apply { isDaemon = true; start() }
+    }
+
+    /** Idempotent. Stops + joins the poll threads (must complete before the session handle is freed). */
+    fun stop() {
+        running = false
+        runCatching { vm?.cancel() } // drop any held rumble immediately
+        runCatching { rumbleThread?.join(500) }
+        runCatching { hidoutThread?.join(500) }
+        rumbleThread = null
+        hidoutThread = null
+        runCatching { lightsSession?.close() }
+        lightsSession = null
+        rgbLight = null
+        playerLight = null
+        vm = null
+        vibratorIds = IntArray(0)
+    }
+
+    /** First connected gamepad/joystick InputDevice, or null (→ logged no-op on the emulator). */
+    private fun resolvePad(): InputDevice? {
+        for (id in InputDevice.getDeviceIds()) {
+            val d = InputDevice.getDevice(id) ?: continue
+            val s = d.sources
+            if (s and InputDevice.SOURCE_GAMEPAD == InputDevice.SOURCE_GAMEPAD ||
+                s and InputDevice.SOURCE_JOYSTICK == InputDevice.SOURCE_JOYSTICK
+            ) {
+                return d
+            }
+        }
+        return null
+    }
+
+    // ---- Rumble ----
+
+    private fun bindRumble(dev: InputDevice?) {
+        if (dev == null) {
+            Log.i(TAG, "rumble: no controller connected — rumble no-op (emulator path)")
+            return
+        }
+        val m = dev.vibratorManager
+        val ids = m.vibratorIds
+        if (ids.isEmpty()) {
+            Log.i(TAG, "rumble: controller '${dev.name}' has no vibrators — rumble no-op")
+            return
+        }
+        vm = m
+        vibratorIds = ids
+        amplitudeControlled = ids.all { m.getVibrator(it).hasAmplitudeControl() }
+        Log.i(TAG, "rumble: bound ${ids.size} vibrators amplitudeControl=$amplitudeControlled")
+    }
+
+    /** low = heavy/left motor, high = light/right motor; both 0..0xFFFF (the host's u16 amplitudes). */
+    private fun renderRumble(low: Int, high: Int) {
+        Log.i(TAG, "rumble low=$low high=$high") // verification line — BEFORE any no-op return
+        val m = vm ?: return
+        val lo = toAmplitude(low)
+        val hi = toAmplitude(high)
+        if (lo == 0 && hi == 0) {
+            m.cancel() // (0,0) = stop
+            return
+        }
+        val combo = CombinedVibration.startParallel()
+        if (amplitudeControlled && vibratorIds.size >= 2) {
+            // ids[0] = light/right, ids[1] = heavy/left (XInput/Moonlight convention).
+            if (hi != 0) combo.addVibrator(vibratorIds[0], oneShot(hi))
+            if (lo != 0) combo.addVibrator(vibratorIds[1], oneShot(lo))
+        } else {
+            // Single motor or no amplitude control: blend both into one effect.
+            val a = (lo * 0.8 + hi * 0.33).toInt().coerceIn(1, 255)
+            for (id in vibratorIds) combo.addVibrator(id, oneShot(a))
+        }
+        runCatching { m.vibrate(combo.combine()) }
+    }
+
+    // 0..0xFFFF → 1..255 (high byte); a nonzero motor never collapses to 0.
+    private fun toAmplitude(v16: Int): Int {
+        val a = (v16 ushr 8) and 0xFF
+        return if (v16 != 0 && a == 0) 1 else a
+    }
+
+    // Long one-shot held until the next packet (the host re-sends ~periodically); cancel on zero.
+    private fun oneShot(amp: Int): VibrationEffect = VibrationEffect.createOneShot(60_000L, amp)
+
+    // ---- HID output ----
+
+    private fun dispatchHidout(buf: ByteBuffer, n: Int) {
+        buf.rewind()
+        when (buf.get()) { // kind tag
+            TAG_LED -> {
+                val r = buf.get().toInt() and 0xFF
+                val g = buf.get().toInt() and 0xFF
+                val b = buf.get().toInt() and 0xFF
+                Log.i(TAG, "hidout Led r=$r g=$g b=$b") // verification line
+                if (Build.VERSION.SDK_INT >= 33) setLightbar(Color.rgb(r, g, b))
+            }
+            TAG_PLAYER_LEDS -> {
+                val bits = buf.get().toInt() and 0x1F
+                val player = playerIndexForBits(bits)
+                Log.i(TAG, "hidout PlayerLeds bits=$bits player=$player") // verification line
+                if (Build.VERSION.SDK_INT >= 33) setPlayerId(player)
+            }
+            TAG_TRIGGER -> {
+                val which = buf.get().toInt() and 0xFF // 0 = L2, 1 = R2
+                val effLen = n - 2
+                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 Trigger which=$which effLen=$effLen mode=0x%02x (adaptive triggers unsupported on Android)".format(mode),
+                )
+            }
+            else -> Log.d(TAG, "hidout: unknown kind, dropped")
+        }
+    }
+
+    /** hid-playstation 5-LED pattern → player index 1..4 (0 = off); falls back to a bit count. */
+    private fun playerIndexForBits(bits: Int): Int = when (bits and 0x1F) {
+        0b00000 -> 0
+        0b00100 -> 1
+        0b01010 -> 2
+        0b10101 -> 3
+        0b11011 -> 4
+        else -> Integer.bitCount(bits and 0x1F).coerceIn(1, 4)
+    }
+
+    private fun bindLights(dev: InputDevice?) {
+        if (dev == null) {
+            Log.i(TAG, "lights: no controller connected — lightbar/playerLed no-op (emulator path)")
+            return
+        }
+        val lm = dev.lightsManager
+        for (l in lm.lights) {
+            if (rgbLight == null && l.hasRgbControl()) rgbLight = l
+            if (playerLight == null && l.type == Light.LIGHT_TYPE_PLAYER_ID) playerLight = l
+        }
+        if (rgbLight == null && playerLight == null) {
+            Log.i(TAG, "lights: controller '${dev.name}' exposes no controllable lights — no-op")
+            return
+        }
+        lightsSession = lm.openSession()
+        Log.i(TAG, "lights: bound rgb=${rgbLight != null} playerLed=${playerLight != null}")
+    }
+
+    private fun setLightbar(argb: Int) {
+        val s = lightsSession ?: return
+        val l = rgbLight ?: return
+        runCatching {
+            s.requestLights(LightsRequest.Builder().addLight(l, LightState.Builder().setColor(argb).build()).build())
+        }
+    }
+
+    private fun setPlayerId(player: Int) {
+        val s = lightsSession ?: return
+        val l = playerLight ?: return
+        runCatching {
+            s.requestLights(LightsRequest.Builder().addLight(l, LightState.Builder().setPlayerId(player).build()).build())
+        }
+    }
+}

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

@@ -0,0 +1,77 @@
+package io.unom.punktfunk.kit
+
+import android.view.KeyEvent
+
+/**
+ * Android `KEYCODE_*` → Windows Virtual-Key code (the punktfunk wire contract; the host maps VK →
+ * evdev via `inject::vk_to_evdev`). The Android analogue of the Linux client's evdev→VK table
+ * (`punktfunk-client-linux/src/keymap.rs`) and the Apple client's `hidToVK`. Positional/US-layout —
+ * we forward the physical key, not the typed character. Unmapped keys → 0 (the Rust side drops them).
+ * Extend this alongside `punktfunk-host/src/inject.rs::vk_to_evdev` (emit only VKs the host knows).
+ */
+object Keymap {
+    fun toVk(keyCode: Int): Int = when (keyCode) {
+        in KeyEvent.KEYCODE_A..KeyEvent.KEYCODE_Z -> 0x41 + (keyCode - KeyEvent.KEYCODE_A) // A–Z
+        in KeyEvent.KEYCODE_0..KeyEvent.KEYCODE_9 -> 0x30 + (keyCode - KeyEvent.KEYCODE_0) // 0–9 row
+        in KeyEvent.KEYCODE_F1..KeyEvent.KEYCODE_F12 -> 0x70 + (keyCode - KeyEvent.KEYCODE_F1) // F1–F12
+        in KeyEvent.KEYCODE_NUMPAD_0..KeyEvent.KEYCODE_NUMPAD_9 ->
+            0x60 + (keyCode - KeyEvent.KEYCODE_NUMPAD_0) // numpad 0–9
+
+        // Whitespace / editing
+        KeyEvent.KEYCODE_DEL -> 0x08 // Backspace (Android KEYCODE_DEL == backspace)
+        KeyEvent.KEYCODE_TAB -> 0x09
+        KeyEvent.KEYCODE_ENTER, KeyEvent.KEYCODE_NUMPAD_ENTER -> 0x0D
+        KeyEvent.KEYCODE_ESCAPE -> 0x1B
+        KeyEvent.KEYCODE_SPACE -> 0x20
+        KeyEvent.KEYCODE_CAPS_LOCK -> 0x14
+        KeyEvent.KEYCODE_BREAK -> 0x13 // Pause
+        KeyEvent.KEYCODE_SYSRQ -> 0x2C // PrintScreen
+        KeyEvent.KEYCODE_INSERT -> 0x2D
+        KeyEvent.KEYCODE_FORWARD_DEL -> 0x2E // Delete (forward)
+        KeyEvent.KEYCODE_NUM_LOCK -> 0x90
+        KeyEvent.KEYCODE_SCROLL_LOCK -> 0x91
+
+        // Navigation
+        KeyEvent.KEYCODE_PAGE_UP -> 0x21
+        KeyEvent.KEYCODE_PAGE_DOWN -> 0x22
+        KeyEvent.KEYCODE_MOVE_END -> 0x23
+        KeyEvent.KEYCODE_MOVE_HOME -> 0x24
+        KeyEvent.KEYCODE_DPAD_LEFT -> 0x25
+        KeyEvent.KEYCODE_DPAD_UP -> 0x26
+        KeyEvent.KEYCODE_DPAD_RIGHT -> 0x27
+        KeyEvent.KEYCODE_DPAD_DOWN -> 0x28
+
+        // Modifiers (L/R-specific VKs; the host folds the generic ones onto the left variant)
+        KeyEvent.KEYCODE_SHIFT_LEFT -> 0xA0
+        KeyEvent.KEYCODE_SHIFT_RIGHT -> 0xA1
+        KeyEvent.KEYCODE_CTRL_LEFT -> 0xA2
+        KeyEvent.KEYCODE_CTRL_RIGHT -> 0xA3
+        KeyEvent.KEYCODE_ALT_LEFT -> 0xA4
+        KeyEvent.KEYCODE_ALT_RIGHT -> 0xA5 // AltGr
+        KeyEvent.KEYCODE_META_LEFT -> 0x5B // Super/Win
+        KeyEvent.KEYCODE_META_RIGHT -> 0x5C
+        KeyEvent.KEYCODE_MENU -> 0x5D // Application
+
+        // Numpad operators
+        KeyEvent.KEYCODE_NUMPAD_MULTIPLY -> 0x6A
+        KeyEvent.KEYCODE_NUMPAD_ADD -> 0x6B
+        KeyEvent.KEYCODE_NUMPAD_SUBTRACT -> 0x6D
+        KeyEvent.KEYCODE_NUMPAD_DOT -> 0x6E
+        KeyEvent.KEYCODE_NUMPAD_DIVIDE -> 0x6F
+
+        // OEM punctuation (US-layout positional)
+        KeyEvent.KEYCODE_SEMICOLON -> 0xBA
+        KeyEvent.KEYCODE_EQUALS -> 0xBB
+        KeyEvent.KEYCODE_COMMA -> 0xBC
+        KeyEvent.KEYCODE_MINUS -> 0xBD
+        KeyEvent.KEYCODE_PERIOD -> 0xBE
+        KeyEvent.KEYCODE_SLASH -> 0xBF
+        KeyEvent.KEYCODE_GRAVE -> 0xC0
+        KeyEvent.KEYCODE_LEFT_BRACKET -> 0xDB
+        KeyEvent.KEYCODE_BACKSLASH -> 0xDC
+        KeyEvent.KEYCODE_RIGHT_BRACKET -> 0xDD
+        KeyEvent.KEYCODE_APOSTROPHE -> 0xDE
+
+        else -> 0 // unmapped → Rust drops it
+    }
+}

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

@@ -0,0 +1,133 @@
+package io.unom.punktfunk.kit
+
+/**
+ * The single JNI seam to `libpunktfunk_android.so` (the Rust-heavy client core).
+ *
+ * Symbols are implemented in `crates/punktfunk-android`. This object is intentionally thin —
+ * all protocol logic lives in Rust (`punktfunk-core` + the connector); Kotlin only marshals.
+ */
+object NativeBridge {
+    init {
+        System.loadLibrary("punktfunk_android")
+    }
+
+    /** punktfunk-core C-ABI version. A successful call proves the native library is linked. */
+    external fun abiVersion(): Int
+
+    /** punktfunk-core crate version string. */
+    external fun coreVersion(): String
+
+    /**
+     * Mint a fresh persistent self-signed identity, returned as
+     * `"<certPem>\n-----PUNKTFUNK-KEY-----\n<keyPem>"`, or `""` on error. Kotlin persists it
+     * (Keystore-wrapped via `IdentityStore`) and only calls this again when the store is empty.
+     */
+    external fun nativeGenerateIdentity(): String
+
+    /**
+     * Connect, presenting [certPem]/[keyPem] (both empty = anonymous) and pinning [pinHex] (empty =
+     * trust-on-first-use — read [nativeHostFingerprint] after; else 64-hex host SHA-256, mismatch →
+     * `0`). [width]/[height]/[refreshHz] are the requested virtual-output mode (the host streams at
+     * exactly this); [bitrateKbps] 0 = host default; [compositorPref]/[gamepadPref] are the
+     * `CompositorPref`/`GamepadPref` wire bytes (0 = Auto). Returns an opaque session handle, or `0`
+     * on failure. Pair with exactly one [nativeClose].
+     */
+    external fun nativeConnect(
+        host: String,
+        port: Int,
+        width: Int,
+        height: Int,
+        refreshHz: Int,
+        certPem: String,
+        keyPem: String,
+        pinHex: String,
+        bitrateKbps: Int,
+        compositorPref: Int,
+        gamepadPref: Int,
+    ): Long
+
+    /** 64-hex SHA-256 of the cert the host presented on [handle]; valid after a successful connect. */
+    external fun nativeHostFingerprint(handle: Long): String
+
+    /**
+     * Run the SPAKE2 PIN ceremony, presenting [certPem]/[keyPem]. Returns the host's verified
+     * fingerprint (64-hex) to persist + pin, or `""` on failure (wrong PIN / MITM / unreachable).
+     * Blocking — call off the main thread.
+     */
+    external fun nativePair(
+        host: String,
+        port: Int,
+        certPem: String,
+        keyPem: String,
+        pin: String,
+        name: String,
+    ): String
+
+    /** Tear down a session handle returned by [nativeConnect]. No-op on `0`. */
+    external fun nativeClose(handle: Long)
+
+    /**
+     * Start the HEVC decode thread rendering onto [surface] (a SurfaceView's surface). Decode runs
+     * entirely in Rust (NDK AMediaCodec → ANativeWindow) — no per-frame JNI. No-op if already started.
+     */
+    external fun nativeStartVideo(handle: Long, surface: android.view.Surface)
+
+    /** Stop + join the decode thread without closing the session. No-op on `0`. */
+    external fun nativeStopVideo(handle: Long)
+
+    /**
+     * Start host→client audio: Opus decode → jitter ring → AAudio (LowLatency), all in Rust. No-op
+     * if already started. Best-effort — a failure leaves video streaming.
+     */
+    external fun nativeStartAudio(handle: Long)
+
+    /** Stop + join the audio thread and close AAudio, without closing the session. No-op on `0`. */
+    external fun nativeStopAudio(handle: Long)
+
+    /**
+     * Start mic uplink: AAudio input → Opus (48 kHz stereo, 20 ms) → host (`send_mic` / 0xCB), all in
+     * Rust. No-op if already running. The caller MUST hold RECORD_AUDIO; otherwise the AAudio input
+     * stream fails to open and the rest of the session keeps streaming.
+     */
+    external fun nativeStartMic(handle: Long)
+
+    /** Stop + join the mic thread and close the AAudio input stream. No-op on `0`. */
+    external fun nativeStopMic(handle: Long)
+
+    // ---- Input: Kotlin captures, Rust forwards to the host (send_input) ----
+
+    /** Relative mouse move; dx/dy are device-pixel deltas (screen +y down). */
+    external fun nativeSendPointerMove(handle: Long, dx: Int, dy: Int)
+
+    /** One mouse-button transition. button: 1=left 2=middle 3=right 4=X1 5=X2. */
+    external fun nativeSendPointerButton(handle: Long, button: Int, down: Boolean)
+
+    /** One scroll step. axis: 0=vertical 1=horizontal. delta: signed, 120-scaled, +=up/right. */
+    external fun nativeSendScroll(handle: Long, axis: Int, delta: Int)
+
+    /** One key transition. vk: Windows VK (0 = dropped by Rust). mods: VK modifier mask (0 for now). */
+    external fun nativeSendKey(handle: Long, vk: Int, down: Boolean, mods: Int)
+
+    // ---- Gamepad: one pad forwarded as pad 0 (Rust hardcodes flags=0) ----
+
+    /** One gamepad button transition. bit: a [Gamepad].BTN_* bit. down: press/release. */
+    external fun nativeSendGamepadButton(handle: Long, bit: Int, down: Boolean)
+
+    /** One gamepad axis update. axisId: [Gamepad].AXIS_* (0..5). value: stick i16 (+y=up) / trigger 0..255. */
+    external fun nativeSendGamepadAxis(handle: Long, axisId: Int, value: Int)
+
+    // ---- Host→client gamepad feedback: Rust pulls block ~100ms, Kotlin renders (see GamepadFeedback) ----
+
+    /**
+     * Block up to ~100 ms for the next rumble update. Returns `(low shl 16) or high` (each
+     * 0..0xFFFF; 0 = stop), or -1 on timeout / session closed. Call from a dedicated poll thread.
+     */
+    external fun nativeNextRumble(handle: Long): Long
+
+    /**
+     * Block up to ~100 ms for the next DualSense HID-output event, written into [buf] (a direct
+     * ByteBuffer, capacity >= 64) as `[kind][fields…]`: Led=01 r g b, PlayerLeds=02 bits,
+     * Trigger=03 which effect…. Returns the byte count, or -1 on timeout / session closed.
+     */
+    external fun nativeNextHidout(handle: Long, buf: java.nio.ByteBuffer): Int
+}

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

@@ -0,0 +1,194 @@
+package io.unom.punktfunk.kit.discovery
+
+import android.content.Context
+import android.net.nsd.NsdManager
+import android.net.nsd.NsdServiceInfo
+import android.net.wifi.WifiManager
+import android.os.Build
+import android.util.Log
+
+private const val TAG = "PunktfunkNsd"
+
+/** DNS-SD service type punktfunk hosts advertise (host: `_punktfunk._udp.local.`). */
+const val PUNKTFUNK_SERVICE_TYPE = "_punktfunk._udp"
+const val PUNKTFUNK_PROTO = "punktfunk/1"
+
+/** One resolved host fit for the picker. [key] is the stable dedup id. */
+data class DiscoveredHost(
+    val key: String,
+    val name: String,
+    val host: String,
+    val port: Int,
+    val fingerprint: String? = null, // TXT "fp" (host cert SHA-256, advisory — TOFU still verifies)
+    val pairingRequired: Boolean = false,
+)
+
+/** Parsed TXT fields. Pure — unit-testable without Android (see ParseTxtTest). */
+data class TxtFields(
+    val proto: String?,
+    val fp: String?,
+    val pair: String?,
+    val id: String?,
+) {
+    val pairingRequired: Boolean get() = pair == "required"
+    val isPunktfunk: Boolean get() = proto == PUNKTFUNK_PROTO
+}
+
+/**
+ * Pure TXT parser. NSD hands TXT as a `Map<String, ByteArray?>` (a null/empty value = present-but-
+ * empty key). Decode UTF-8; missing keys are null, never an error.
+ */
+fun parseTxt(attrs: Map<String, ByteArray?>): TxtFields {
+    fun s(k: String): String? = attrs[k]?.takeIf { it.isNotEmpty() }?.toString(Charsets.UTF_8)
+    return TxtFields(proto = s("proto"), fp = s("fp"), pair = s("pair"), id = s("id"))
+}
+
+/**
+ * Browses `_punktfunk._udp` via NsdManager, resolves each service (the reliable
+ * `registerServiceInfoCallback` path on API 34+, legacy `resolveService` on 31–33 where its TXT is
+ * often empty), and pushes the live host set to [onChange] (invoked on the main thread).
+ *
+ * Lifecycle: [start] when the picker appears, [stop] when it leaves / on connect — holds a
+ * MulticastLock while running (an OEM Wi-Fi power-save hedge). Note: the Android emulator's SLIRP
+ * NAT drops multicast, so on the emulator discovery starts but never finds a LAN host.
+ */
+class HostDiscovery(context: Context) {
+    private val appCtx = context.applicationContext
+    private val nsd = appCtx.getSystemService(Context.NSD_SERVICE) as NsdManager
+
+    /** Invoked on the main thread whenever the resolved host set changes. */
+    var onChange: ((List<DiscoveredHost>) -> Unit)? = null
+
+    private val resolved = LinkedHashMap<String, DiscoveredHost>() // key -> host
+    private var multicastLock: WifiManager.MulticastLock? = null
+    private var discoveryListener: NsdManager.DiscoveryListener? = null
+    private val infoCallbacks = mutableListOf<NsdManager.ServiceInfoCallback>() // API 34+ registrations
+    private var running = false
+
+    @Synchronized
+    fun start() {
+        if (running) return
+        running = true
+        acquireMulticastLock()
+        val listener = makeDiscoveryListener()
+        discoveryListener = listener
+        runCatching {
+            nsd.discoverServices(PUNKTFUNK_SERVICE_TYPE, NsdManager.PROTOCOL_DNS_SD, listener)
+        }.onFailure {
+            Log.e(TAG, "discoverServices failed", it)
+            stop()
+        }
+    }
+
+    @Synchronized
+    fun stop() {
+        if (!running) return
+        running = false
+        discoveryListener?.let { runCatching { nsd.stopServiceDiscovery(it) } }
+        discoveryListener = null
+        if (Build.VERSION.SDK_INT >= 34) {
+            for (cb in infoCallbacks) runCatching { nsd.unregisterServiceInfoCallback(cb) }
+        }
+        infoCallbacks.clear()
+        releaseMulticastLock()
+        resolved.clear()
+        onChange?.invoke(emptyList())
+    }
+
+    private fun publish() {
+        onChange?.invoke(resolved.values.sortedBy { it.name.lowercase() })
+    }
+
+    private fun makeDiscoveryListener() = object : NsdManager.DiscoveryListener {
+        override fun onDiscoveryStarted(type: String) {
+            Log.d(TAG, "discovery started: $type")
+        }
+        override fun onDiscoveryStopped(type: String) {
+            Log.d(TAG, "discovery stopped: $type")
+        }
+        override fun onStartDiscoveryFailed(type: String, code: Int) {
+            Log.e(TAG, "start discovery failed: $code")
+            runCatching { nsd.stopServiceDiscovery(this) }
+        }
+        override fun onStopDiscoveryFailed(type: String, code: Int) {
+            Log.e(TAG, "stop discovery failed: $code")
+        }
+
+        override fun onServiceFound(info: NsdServiceInfo) {
+            Log.d(TAG, "found: ${info.serviceName}")
+            resolve(info)
+        }
+        override fun onServiceLost(info: NsdServiceInfo) {
+            Log.d(TAG, "lost: ${info.serviceName}")
+            // onServiceLost carries no TXT, so drop by the instance-name fallback key only.
+            if (resolved.remove(info.serviceName) != null) publish()
+        }
+    }
+
+    private fun resolve(found: NsdServiceInfo) {
+        if (Build.VERSION.SDK_INT >= 34) resolveViaCallback(found) else resolveViaLegacy(found)
+    }
+
+    private fun resolveViaCallback(found: NsdServiceInfo) {
+        val cb = object : NsdManager.ServiceInfoCallback {
+            override fun onServiceUpdated(info: NsdServiceInfo) = ingest(info)
+            override fun onServiceLost() {}
+            override fun onServiceInfoCallbackRegistrationFailed(code: Int) {
+                Log.e(TAG, "ServiceInfoCallback reg failed: $code")
+            }
+            override fun onServiceInfoCallbackUnregistered() {}
+        }
+        runCatching {
+            nsd.registerServiceInfoCallback(found, appCtx.mainExecutor, cb)
+            infoCallbacks.add(cb)
+        }.onFailure { Log.e(TAG, "registerServiceInfoCallback failed", it) }
+    }
+
+    private fun resolveViaLegacy(found: NsdServiceInfo) {
+        // A ResolveListener can't be reused — allocate one per resolve. TXT may be empty pre-34.
+        val listener = object : NsdManager.ResolveListener {
+            override fun onServiceResolved(info: NsdServiceInfo) = ingest(info)
+            override fun onResolveFailed(info: NsdServiceInfo, code: Int) {
+                Log.e(TAG, "resolve failed: $code")
+            }
+        }
+        runCatching { nsd.resolveService(found, listener) }
+            .onFailure { Log.e(TAG, "resolveService failed", it) }
+    }
+
+    @Suppress("DEPRECATION") // info.host is deprecated at API 34 (replaced by hostAddresses)
+    private fun ingest(info: NsdServiceInfo) {
+        val txt = parseTxt(info.attributes)
+        // Reject an incompatible protocol IF the host advertised one; tolerate empty TXT (pre-34).
+        if (txt.proto != null && !txt.isPunktfunk) {
+            Log.d(TAG, "skip non-punktfunk proto=${txt.proto}")
+            return
+        }
+        val ip = (if (Build.VERSION.SDK_INT >= 34) info.hostAddresses.firstOrNull() else info.host)
+            ?.hostAddress ?: return
+        val key = txt.id?.takeIf { it.isNotBlank() } ?: info.serviceName
+        resolved[key] = DiscoveredHost(
+            key = key,
+            name = info.serviceName.removeSuffix("."),
+            host = ip,
+            port = info.port,
+            fingerprint = txt.fp,
+            pairingRequired = txt.pairingRequired,
+        )
+        Log.d(TAG, "resolved: ${resolved[key]}")
+        publish()
+    }
+
+    private fun acquireMulticastLock() {
+        val wifi = appCtx.getSystemService(Context.WIFI_SERVICE) as WifiManager
+        multicastLock = wifi.createMulticastLock("punktfunk-nsd").apply {
+            setReferenceCounted(true)
+            runCatching { acquire() }
+        }
+    }
+
+    private fun releaseMulticastLock() {
+        multicastLock?.takeIf { it.isHeld }?.let { runCatching { it.release() } }
+        multicastLock = null
+    }
+}

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

@@ -0,0 +1,151 @@
+package io.unom.punktfunk.kit.security
+
+import android.content.Context
+import android.security.keystore.KeyGenParameterSpec
+import android.security.keystore.KeyProperties
+import android.security.keystore.StrongBoxUnavailableException
+import android.util.Log
+import io.unom.punktfunk.kit.NativeBridge
+import java.io.File
+import java.security.KeyStore
+import javax.crypto.Cipher
+import javax.crypto.KeyGenerator
+import javax.crypto.SecretKey
+import javax.crypto.spec.GCMParameterSpec
+
+private const val TAG = "PunktfunkIdentity"
+
+/** The delimiter the JNI uses to join the two PEMs; collision-free (PEM bodies never contain it). */
+private const val PEM_DELIM = "\n-----PUNKTFUNK-KEY-----\n"
+
+/** This device's persistent punktfunk identity (presented to hosts via TLS client auth). */
+data class ClientIdentity(val certPem: String, val privateKeyPem: String)
+
+/** Result of [IdentityStore.load] — four states so the caller never mints over a *recoverable* error. */
+sealed interface IdentityLoad {
+    data class Ok(val identity: ClientIdentity) : IdentityLoad
+
+    /** Genuine first run (no blob on disk) — mint a new identity here, and only here. */
+    object Absent : IdentityLoad
+
+    /** A blob exists but can't be decrypted (Keystore key gone, corruption). NEVER shadow-mint. */
+    data class Unrecoverable(val reason: String, val cause: Throwable?) : IdentityLoad
+}
+
+class IdentityUnrecoverableException(message: String, cause: Throwable?) : Exception(message, cause)
+
+/** Split the JNI's joined "<cert>\n-----PUNKTFUNK-KEY-----\n<key>" blob; `null` if malformed. */
+fun splitGenerated(joined: String): ClientIdentity? {
+    val i = joined.indexOf(PEM_DELIM)
+    if (i < 0) return null
+    return ClientIdentity(
+        certPem = joined.substring(0, i),
+        privateKeyPem = joined.substring(i + PEM_DELIM.length),
+    )
+}
+
+/**
+ * Load the device identity, minting *once* on genuine first run. NEVER mints over an error state:
+ * an [IdentityLoad.Unrecoverable] surfaces as a throw so the UI can tell the user (re-pair) rather
+ * than silently swapping in a new identity (which would change our fingerprint everywhere).
+ */
+fun obtainIdentity(store: IdentityStore): ClientIdentity =
+    when (val r = store.load()) {
+        is IdentityLoad.Ok -> r.identity
+        IdentityLoad.Absent -> {
+            val joined = NativeBridge.nativeGenerateIdentity()
+            val id = splitGenerated(joined)
+                ?: throw IdentityUnrecoverableException("nativeGenerateIdentity returned empty", null)
+            store.persist(id)
+            id
+        }
+        is IdentityLoad.Unrecoverable ->
+            throw IdentityUnrecoverableException(r.reason, r.cause)
+    }
+
+/**
+ * Persists the identity PEM blob to app-private storage, wrapped with an AndroidKeyStore AES-256-GCM
+ * key (never exportable; StrongBox-backed where available, TEE otherwise). On-disk layout:
+ * `[12-byte IV][GCM ciphertext+tag]`. The wrapping key never leaves the secure element, and Keystore
+ * keys don't survive backup/restore — so a restored device reads [IdentityLoad.Absent] (the blob is
+ * excluded from backup; see the manifest) and re-mints, rather than carrying a dead identity.
+ */
+class IdentityStore(context: Context) {
+    private val appCtx = context.applicationContext
+    private val file = File(appCtx.filesDir, "pf_identity.bin")
+    private val alias = "punktfunk_identity_v1"
+
+    fun load(): IdentityLoad {
+        if (!file.exists()) return IdentityLoad.Absent
+        return try {
+            val blob = file.readBytes()
+            if (blob.size <= IV_LEN) {
+                return IdentityLoad.Unrecoverable("identity blob truncated (${blob.size} B)", null)
+            }
+            val key = (keyStore().getEntry(alias, null) as? KeyStore.SecretKeyEntry)?.secretKey
+                ?: return IdentityLoad.Unrecoverable("blob present but Keystore key missing", null)
+            val iv = blob.copyOfRange(0, IV_LEN)
+            val ct = blob.copyOfRange(IV_LEN, blob.size)
+            val cipher = Cipher.getInstance(TRANSFORM)
+            cipher.init(Cipher.DECRYPT_MODE, key, GCMParameterSpec(GCM_TAG_BITS, iv))
+            val plain = String(cipher.doFinal(ct), Charsets.UTF_8)
+            splitGenerated(plain)?.let { IdentityLoad.Ok(it) }
+                ?: IdentityLoad.Unrecoverable("decrypted identity blob malformed", null)
+        } catch (e: Exception) {
+            // Decrypt/Keystore failure: the identity is unrecoverable. Do NOT mint a shadow identity.
+            Log.e(TAG, "identity load failed", e)
+            IdentityLoad.Unrecoverable("identity decrypt failed: ${e.javaClass.simpleName}", e)
+        }
+    }
+
+    fun persist(identity: ClientIdentity) {
+        val key = getOrCreateKey()
+        val cipher = Cipher.getInstance(TRANSFORM)
+        cipher.init(Cipher.ENCRYPT_MODE, key)
+        val iv = cipher.iv // GCM: a fresh random 12-byte IV per encryption
+        val plain = (identity.certPem + PEM_DELIM + identity.privateKeyPem).toByteArray(Charsets.UTF_8)
+        val ct = cipher.doFinal(plain)
+        // Write to a temp file then rename, so a crash mid-write can't leave a torn (unrecoverable) blob.
+        val tmp = File(file.parentFile, "${file.name}.tmp")
+        tmp.writeBytes(iv + ct)
+        if (!tmp.renameTo(file)) {
+            file.writeBytes(iv + ct)
+            tmp.delete()
+        }
+    }
+
+    private fun keyStore(): KeyStore = KeyStore.getInstance("AndroidKeyStore").apply { load(null) }
+
+    private fun getOrCreateKey(): SecretKey {
+        val ks = keyStore()
+        (ks.getEntry(alias, null) as? KeyStore.SecretKeyEntry)?.let { return it.secretKey }
+        // Prefer a StrongBox-backed key; fall back to TEE where StrongBox is absent (e.g. the emulator).
+        return try {
+            generateKey(strongBox = true)
+        } catch (e: StrongBoxUnavailableException) {
+            Log.i(TAG, "StrongBox unavailable — using TEE-backed key", e)
+            generateKey(strongBox = false)
+        }
+    }
+
+    private fun generateKey(strongBox: Boolean): SecretKey {
+        val spec = KeyGenParameterSpec.Builder(
+            alias,
+            KeyProperties.PURPOSE_ENCRYPT or KeyProperties.PURPOSE_DECRYPT,
+        )
+            .setBlockModes(KeyProperties.BLOCK_MODE_GCM)
+            .setEncryptionPaddings(KeyProperties.ENCRYPTION_PADDING_NONE)
+            .setKeySize(256)
+            .setIsStrongBoxBacked(strongBox)
+            .build()
+        val kg = KeyGenerator.getInstance(KeyProperties.KEY_ALGORITHM_AES, "AndroidKeyStore")
+        kg.init(spec)
+        return kg.generateKey()
+    }
+
+    private companion object {
+        const val TRANSFORM = "AES/GCM/NoPadding"
+        const val IV_LEN = 12
+        const val GCM_TAG_BITS = 128
+    }
+}

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

@@ -0,0 +1,67 @@
+package io.unom.punktfunk.kit.security
+
+import android.content.Context
+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).
+ */
+data class KnownHost(
+    val address: String,
+    val port: Int,
+    val name: String,
+    val fpHex: String,
+    val paired: Boolean,
+)
+
+/**
+ * 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.
+ */
+class KnownHostStore(context: Context) {
+    private val prefs =
+        context.applicationContext.getSharedPreferences("punktfunk_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"
+
+    /** 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)
+
+    /** Pin (or update) a trusted host — upsert by `address:port`. */
+    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)
+        prefs.edit().putString(key(host.address, host.port), json.toString()).apply()
+    }
+
+    /** Forget [address]:[port] (the next connect re-pairs / re-TOFUs). */
+    fun remove(address: String, port: Int) {
+        prefs.edit().remove(key(address, port)).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() }
+
+    private fun parse(s: String): KnownHost? = runCatching {
+        val j = JSONObject(s)
+        KnownHost(
+            address = j.getString("addr"),
+            port = j.getInt("port"),
+            name = j.getString("name"),
+            fpHex = j.getString("fp"),
+            paired = j.optBoolean("paired", false),
+        )
+    }.getOrNull()
+}

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

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

clients/android/settings.gradle.kts

@@ -0,0 +1,17 @@
+pluginManagement {
+    repositories {
+        google()
+        mavenCentral()
+        gradlePluginPortal()
+    }
+}
+dependencyResolutionManagement {
+    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
+    repositories {
+        google()
+        mavenCentral()
+    }
+}
+
+rootProject.name = "punktfunk-android"
+include(":app", ":kit")

clients/apple/Config/Punktfunk-macOS.entitlements

@@ -0,0 +1,77 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<!-- macOS-ONLY entitlements. App Sandbox is a macOS concept (iOS/tvOS are always
+	     sandboxed and REJECT this key at upload), so the macOS target points here while
+	     iOS/tvOS keep the shared Config/Punktfunk.entitlements. The single macOS app is
+	     sandboxed for BOTH channels — the Developer ID DMG is codesigned with this same
+	     file (App Sandbox is allowed, not just required, for Developer ID), so what we
+	     test locally (⌘R / DMG) is exactly what Mac App Store / TestFlight users get. -->
+
+	<!-- Required for Mac App Store / TestFlight distribution. -->
+	<key>com.apple.security.app-sandbox</key>
+	<true/>
+
+	<!-- Outbound QUIC control plane + raw-UDP data plane to the host, and NWBrowser mDNS
+	     discovery / NWConnection resolve. Every outbound socket (incl. the linked Rust
+	     core's UDP binds) needs this under the sandbox. -->
+	<key>com.apple.security.network.client</key>
+	<true/>
+
+	<!-- NOT optional, despite the client being "outbound only": the App Sandbox gates the
+	     bind() syscall itself as a network-bind ("server") operation. quinn binds its QUIC
+	     endpoint socket (quic.rs Endpoint::client 0.0.0.0:0) and the raw-UDP data plane
+	     binds a local socket to receive host→client datagrams (transport/udp.rs); both fail
+	     with deny(1) network-bind / EPERM without this, so NO video/audio/rumble ever
+	     arrives. (The classic QUIC-on-quinn-under-sandbox trap.) -->
+	<key>com.apple.security.network.server</key>
+	<true/>
+
+	<!-- Microphone uplink: SessionAudio installs an AVAudioEngine input tap → Opus → host
+	     virtual mic. TCC blocks AVAudioEngine input under the sandbox without this even with
+	     NSMicrophoneUsageDescription present. -->
+	<key>com.apple.security.device.audio-input</key>
+	<true/>
+
+	<!-- Game controllers over Bluetooth via the GameController framework
+	     (GCController.startWirelessControllerDiscovery — Xbox/DualSense). No CoreBluetooth in
+	     the app, so no NSBluetoothAlwaysUsageDescription is required, but the sandbox still
+	     gates GameController's BT HID access on this key. -->
+	<key>com.apple.security.device.bluetooth</key>
+	<true/>
+
+	<!-- Game controllers over USB + USB HID mouse/keyboard via the GameController framework.
+	     device.usb gates the IOHIDLibUserClient path the framework uses for wired devices
+	     (per Apple DTS); without it, plugged-in controllers deliver no input. Justify in App
+	     Review notes ("reads input from USB game controllers"). -->
+	<key>com.apple.security.device.usb</key>
+	<true/>
+
+	<!-- Controller rumble via CoreHaptics: GCDeviceHaptics.createEngine → CHHapticEngine
+	     (GamepadFeedback's RumbleRenderer), and AVAudioEngine playback, reach the system
+	     audio-analytics daemon `com.apple.audioanalyticsd` over Mach. The sandbox denies that
+	     global-name lookup unless it's whitelisted here, and the framework's own precondition
+	     turns the denial into a HARD CRASH ("Process is sandboxed but
+	     com.apple.security.exception.mach-lookup.global-name doesn't contain
+	     com.apple.audioanalyticsd") the moment a controller's haptics engine starts. This
+	     temporary exception is the documented, App-Store-acceptable way to permit exactly that
+	     lookup — and ONLY that service (the key takes exact names, no wildcards). App Store:
+	     declare it in App Store Connect → App Sandbox Entitlement Usage Information ("CoreHaptics
+	     gamepad rumble contacts the system audio-analytics daemon"). -->
+	<key>com.apple.security.temporary-exception.mach-lookup.global-name</key>
+	<array>
+		<string>com.apple.audioanalyticsd</string>
+	</array>
+
+	<!-- Keychain Sharing (unchanged from the shared file): a team-scoped access group so the
+	     punktfunk/1 client identity in the data-protection keychain is gated by the app's
+	     entitlement (team + bundle id), persisting across rebuilds with NO prompt — see
+	     ClientIdentityStore. $(AppIdentifierPrefix) expands to the team prefix at signing
+	     time (the Developer ID codesign step in release.yml resolves it via sed). -->
+	<key>keychain-access-groups</key>
+	<array>
+		<string>$(AppIdentifierPrefix)io.unom.punktfunk</string>
+	</array>
+</dict>
+</plist>

clients/apple/Punktfunk.xcodeproj/project.pbxproj

@@ -355,7 +355,7 @@
 			buildSettings = {
 				ASSETCATALOG_COMPILER_APPICON_NAME = punktfunk_Logo;
 				ASSETCATALOG_COMPILER_GLOBAL_ACCENT_COLOR_NAME = AccentColor;
-				CODE_SIGN_ENTITLEMENTS = Config/Punktfunk.entitlements;
+				CODE_SIGN_ENTITLEMENTS = Config/Punktfunk-macOS.entitlements;
 				CODE_SIGN_IDENTITY = "Apple Development";
 				CODE_SIGN_STYLE = Automatic;
 				COMBINE_HIDPI_IMAGES = YES;
@@ -389,7 +389,7 @@
 			buildSettings = {
 				ASSETCATALOG_COMPILER_APPICON_NAME = punktfunk_Logo;
 				ASSETCATALOG_COMPILER_GLOBAL_ACCENT_COLOR_NAME = AccentColor;
-				CODE_SIGN_ENTITLEMENTS = Config/Punktfunk.entitlements;
+				CODE_SIGN_ENTITLEMENTS = Config/Punktfunk-macOS.entitlements;
 				CODE_SIGN_IDENTITY = "Apple Development";
 				CODE_SIGN_STYLE = Automatic;
 				COMBINE_HIDPI_IMAGES = YES;

clients/apple/README.md

@@ -91,7 +91,14 @@ What's here, all compiled and tested on macOS (Xcode 26.5 / Swift 6.3):
   the host burst probe filler over the real data plane (up to the host's 3 Gbps probe
   ceiling for 2 s, roadmap §9),
   shows measured goodput · loss · a recommended bitrate (≈70% of measured), and applies
-  it in one tap.
+  it in one tap. The streaming **statistics overlay** can be turned off and moved to any
+  corner (Settings → Display → Statistics, `DefaultsKey.hudEnabled`/`hudPlacement`), and
+  toggled live with **⌘⇧S** — a Scene-level **"Stream" menu** (`StreamCommands`) that also
+  carries **Disconnect ⌘D**, so disconnect survives the HUD being hidden (on iOS a small
+  exit chip appears instead; on tvOS the Siri-Remote Menu button still disconnects). The
+  macOS Settings window is a **tabbed preferences pane** (General / Display / Audio /
+  Controllers / Advanced) — the sections are shared with the iOS single-Form layout and the
+  tvOS pushed-picker layout, defined once each.
 - **Tests** (`swift test`): byte-level Annex-B units; a real-codec round trip
   (VTCompressionSession-encoded HEVC rebuilt as the host's wire shape → `AnnexB` →
   VTDecompressionSession → pixels); table-driven DualSense trigger-effect parsing
@@ -137,6 +144,17 @@ The app target **Punktfunk** wraps the same sources as the `swift run` shell
 catalog) and links `PunktfunkKit` from the local package. Generated Info.plist, ad-hoc
 signing, bundle id `io.unom.punktfunk`. Notes:
 
+- **Entitlements (sandbox)**: the macOS target uses
+  `Config/Punktfunk-macOS.entitlements`; iOS/tvOS use the shared
+  `Config/Punktfunk.entitlements`. The macOS app is **App-Sandboxed** (mandatory for the Mac
+  App Store/TestFlight, and used for the Developer ID DMG too so the local build matches what
+  ships): `com.apple.security.app-sandbox`, `network.client` + **`network.server`** (the
+  sandbox gates `bind()`; quinn + the raw-UDP plane both bind, so receive breaks without it),
+  `device.audio-input` (mic), `device.bluetooth` + `device.usb` (GameController over BT/USB),
+  and the existing `keychain-access-groups`. `app-sandbox` is macOS-only — keep it OUT of the
+  shared iOS/tvOS file (it fails upload validation there). Verify a build is sandboxed with
+  `codesign -d --entitlements :- <built .app>`. Heads-up: `device.usb` draws some App Review
+  scrutiny — justify it in the review notes ("reads input from USB game controllers").
 - **App icon**: `App/Assets.xcassets` ships an empty `AppIcon` slot. For an Icon Composer
   `.icon`: add the file to the project (target Punktfunk), set it as the App Icon in the
   target's General tab, and delete the placeholder `AppIcon.appiconset`. Heads-up: CLI

clients/apple/Sources/PunktfunkClient/ContentView.swift

@@ -25,9 +25,13 @@ struct ContentView: View {
     @AppStorage(DefaultsKey.compositor) private var compositor = 0
     @AppStorage(DefaultsKey.gamepadType) private var gamepadType = 0
     @AppStorage(DefaultsKey.bitrateKbps) private var bitrateKbps = 0
+    @AppStorage(DefaultsKey.fullscreenWhileStreaming) private var fullscreenWhileStreaming = true
+    @AppStorage(DefaultsKey.hudEnabled) private var hudEnabled = true
+    @AppStorage(DefaultsKey.hudPlacement) private var hudPlacement = HUDPlacement.topTrailing.rawValue
     @State private var showAddHost = false
     @State private var pairingTarget: StoredHost?
     @State private var speedTestTarget: StoredHost?
+    @State private var libraryTarget: StoredHost?
     #if !os(macOS)
     @State private var showSettings = false
     #endif
@@ -57,6 +61,18 @@ struct ContentView: View {
             }
         }
         .onDisappear { model.disconnect() } // window closed mid-session (Cmd+N spawns more)
+        // Expose the session to the Scene-level Stream menu (Disconnect ⌘D works even when
+        // the HUD is hidden). tvOS has no such menu.
+        #if !os(tvOS)
+        .focusedSceneValue(\.sessionFocus, SessionFocus(
+            isStreaming: model.connection != nil,
+            disconnect: { model.disconnect() }))
+        #endif
+        #if os(macOS)
+        // Fullscreen only while a session is up (incl. the trust prompt over the blurred stream),
+        // windowed on the host list — so the picker isn't forced fullscreen. Opt-out in Settings.
+        .background(FullscreenController(active: fullscreenWhileStreaming && model.connection != nil))
+        #endif
         // On the outer Group so the sheet survives the trust-prompt → home transition
         // (the "Pair with PIN instead" path disconnects first — the host's accept loop
         // is sequential, a pairing connection would queue behind the live session).
@@ -67,6 +83,11 @@ struct ContentView: View {
         .sheet(item: $speedTestTarget) { host in
             SpeedTestSheet(host: host)
         }
+        .sheet(item: $libraryTarget) { host in
+            NavigationStack {
+                LibraryView(store: store, host: host, onLaunch: { launchTitle(host, $0) })
+            }
+        }
         #endif
     }
 
@@ -75,14 +96,17 @@ struct ContentView: View {
         HomeView(
             store: store, model: model, discovery: discovery,
             showAddHost: $showAddHost, pairingTarget: $pairingTarget,
-            speedTestTarget: $speedTestTarget,
+            speedTestTarget: $speedTestTarget, libraryTarget: $libraryTarget,
-            connect: connect, connectDiscovered: connectDiscovered, onPaired: handlePaired)
+            connect: { connect($0) }, connectDiscovered: connectDiscovered,
+            onPaired: handlePaired, onLaunchTitle: launchTitle)
         #else
         HomeView(
             store: store, model: model, discovery: discovery,
             showAddHost: $showAddHost, pairingTarget: $pairingTarget,
-            speedTestTarget: $speedTestTarget, showSettings: $showSettings,
+            speedTestTarget: $speedTestTarget, libraryTarget: $libraryTarget,
-            connect: connect, connectDiscovered: connectDiscovered, onPaired: handlePaired)
+            showSettings: $showSettings,
+            connect: { connect($0) }, connectDiscovered: connectDiscovered,
+            onPaired: handlePaired, onLaunchTitle: launchTitle)
         #endif
     }
 
@@ -121,6 +145,13 @@ struct ContentView: View {
         #if os(macOS)
         .frame(minWidth: 640, minHeight: 360)
         .background(Color.black)
+        // Fill the whole display in fullscreen, INCLUDING behind the camera housing (notch).
+        // Without this the stream is laid out in the safe area below the notch, so an
+        // aspect-fit video at the display's native mode scales down and leaves black borders.
+        // A fullscreen video behind the notch (a thin top-center strip occluded) is the
+        // expected behavior — same edge-to-edge intent as the iOS/tvOS branches below. Inert
+        // in windowed mode (no notch safe-area inset on a titled window).
+        .ignoresSafeArea()
         #elseif os(iOS)
         // Streaming is immersive: edge-to-edge under the status bar and home
         // indicator, both hidden for the session (they return with the hosts grid).
@@ -140,7 +171,8 @@ struct ContentView: View {
     }
 
     private func stream(captureEnabled: Bool) -> some View {
-        Group {
+        let placement = HUDPlacement(rawValue: hudPlacement) ?? .topTrailing
+        return Group {
             if let conn = model.connection {
                 StreamView(
                     connection: conn,
@@ -157,16 +189,51 @@ struct ContentView: View {
                     },
                     presentMeter: model.presentLatency
                 )
-                .overlay(alignment: .topTrailing) {
+                .overlay(alignment: placement.alignment) {
-                    if captureEnabled { StreamHUDView(model: model, connection: conn) }
+                    if captureEnabled && hudEnabled {
+                        StreamHUDView(model: model, connection: conn, placement: placement)
                     }
                 }
+                #if os(iOS)
+                // Touch users have no menu / ⌘D, so when the HUD (and its Disconnect button)
+                // is hidden, keep a minimal always-reachable exit in a corner. It rides a
+                // material disc (like the HUD) so the glyph stays legible over a bright frame
+                // — this is the sole touch disconnect path when stats are off.
+                .overlay(alignment: .topLeading) {
+                    if captureEnabled && !hudEnabled {
+                        Button { model.disconnect() } label: {
+                            Image(systemName: "xmark")
+                                .font(.headline.weight(.semibold))
+                                .frame(width: 36, height: 36)
+                                .background(.regularMaterial, in: Circle())
+                        }
+                        .buttonStyle(.plain)
+                        .padding(12)
+                        .accessibilityLabel("Disconnect")
+                    }
+                }
+                #endif
+            }
         }
     }
 
     // MARK: - Connect
 
-    private func connect(_ host: StoredHost) {
+    private func connect(_ host: StoredHost, launchID: String? = nil, allowTofu: Bool? = nil) {
+        // A pinned host connects on its stored fingerprint; an unpinned host may only TOFU when
+        // the host's LIVE advert says `pair=optional` (rule 3a). When the caller doesn't already
+        // know the policy (a saved-card tap / manual entry), resolve it from the current mDNS set:
+        // an unpinned host with no matching `pair=optional` advert routes to PIN pairing instead
+        // of silently entering the trust prompt (rules 3b + 4). A pinned host ignores all of this.
+        if host.pinnedSHA256 == nil {
+            let tofuOK = allowTofu ?? discovery.hosts.contains {
+                host.matches($0) && $0.allowsTofu
+            }
+            if !tofuOK {
+                pairingTarget = host
+                return
+            }
+        }
         // The gamepad-type setting resolves NOW (Automatic → match the active physical
         // controller): the host's virtual pad backend is fixed per session.
         model.connect(
@@ -178,20 +245,31 @@ struct ContentView: View {
             gamepad: GamepadManager.shared.resolveType(
                 setting: PunktfunkConnection.GamepadType(
                     rawValue: UInt32(clamping: gamepadType)) ?? .auto),
-            bitrateKbps: UInt32(clamping: bitrateKbps))
+            bitrateKbps: UInt32(clamping: bitrateKbps),
+            launchID: launchID,
+            allowTofu: host.pinnedSHA256 == nil)
+    }
+
+    /// Picked a title in the (experimental) library: dismiss the browser and start a session that
+    /// asks the host to launch it.
+    private func launchTitle(_ host: StoredHost, _ id: String) {
+        libraryTarget = nil
+        connect(host, launchID: id)
     }
 
     /// Tap a discovered host: save it (so the session has a stored identity and the trust pin
-    /// persists), then connect — TOFU shows the fingerprint, which should match the advertised
+    /// persists), then connect or pair per the host's advertised policy. The host is the policy
-    /// `fp`. A `pair=required` host goes straight to the pairing ceremony instead.
+    /// authority — TOFU is offered ONLY when it explicitly advertised `pair=optional` (rule 3a);
+    /// a `pair=required` host, or one with no/unknown `pair` field, goes straight to the PIN
+    /// pairing ceremony (rule 3b). (A pinned discovered host connects silently inside `connect`.)
     private func connectDiscovered(_ d: DiscoveredHost) {
         guard !model.isBusy else { return }
         let host = StoredHost(name: d.name, address: d.host, port: d.port)
         store.add(host)
-        if d.requiresPairing {
+        if d.allowsTofu {
-            pairingTarget = host
+            connect(host, allowTofu: true)
         } else {
-            connect(host)
+            pairingTarget = host
         }
     }
 
@@ -270,3 +348,24 @@ struct ContentView: View {
             autoTrust: true)
     }
 }
+
+#if os(macOS)
+/// Drives the hosting window in/out of native fullscreen from SwiftUI state. Mounted invisibly in
+/// the view tree; on each `active` change it captures the window and toggles fullscreen only when
+/// the current state differs (so it never fights a toggle already in flight, and never touches a
+/// window the user fullscreened manually unless `active` says otherwise).
+private struct FullscreenController: NSViewRepresentable {
+    let active: Bool
+
+    func makeNSView(context: Context) -> NSView { NSView() }
+
+    func updateNSView(_ view: NSView, context: Context) {
+        let want = active
+        DispatchQueue.main.async {
+            guard let window = view.window else { return }
+            let isFull = window.styleMask.contains(.fullScreen)
+            if want != isFull { window.toggleFullScreen(nil) }
+        }
+    }
+}
+#endif

clients/apple/Sources/PunktfunkClient/HomeView.swift

@@ -16,6 +16,7 @@ struct HomeView: View {
     @Binding var showAddHost: Bool
     @Binding var pairingTarget: StoredHost?
     @Binding var speedTestTarget: StoredHost?
+    @Binding var libraryTarget: StoredHost?
     #if !os(macOS)
     @Binding var showSettings: Bool
     #endif
@@ -23,6 +24,10 @@ struct HomeView: View {
     let connectDiscovered: (DiscoveredHost) -> Void
     /// Pairing succeeded (tvOS PairSheet route) — pin + connect (ContentView guards staleness).
     let onPaired: (StoredHost, Data) -> Void
+    /// Picked a title in the (experimental) library — start a session that launches it.
+    let onLaunchTitle: (StoredHost, String) -> Void
+    /// Experimental game-library browser (gated) — the host-card "Browse Library…" action.
+    @AppStorage(DefaultsKey.libraryEnabled) private var libraryEnabled = false
 
     var body: some View {
         NavigationStack {
@@ -81,6 +86,9 @@ struct HomeView: View {
             .navigationDestination(item: $speedTestTarget) { host in
                 SpeedTestSheet(host: host)
             }
+            .navigationDestination(item: $libraryTarget) { host in
+                LibraryView(store: store, host: host, onLaunch: { onLaunchTitle(host, $0) })
+            }
             #endif
             #if !os(tvOS)
             .toolbar {
@@ -146,7 +154,8 @@ struct HomeView: View {
     // MARK: - Cards
 
     private func hostCard(_ host: StoredHost) -> some View {
-        HostCardView(
+        let onBrowseLibrary: (() -> Void)? = libraryEnabled ? { libraryTarget = host } : nil
+        return HostCardView(
             host: host,
             isOnline: isOnline(host),
             isConnecting: model.phase == .connecting && model.activeHost?.id == host.id,
@@ -156,7 +165,8 @@ struct HomeView: View {
             onPair: { if !model.isBusy { pairingTarget = host } },
             onSpeedTest: { if !model.isBusy { speedTestTarget = host } },
             onForget: { store.forgetIdentity(host) },
-            onRemove: { store.remove(host) })
+            onRemove: { store.remove(host) },
+            onBrowseLibrary: onBrowseLibrary)
     }
 
     private var discoveredSection: some View {

clients/apple/Sources/PunktfunkClient/HostCards.swift

@@ -35,6 +35,8 @@ struct HostCardView: View {
     let onSpeedTest: () -> Void
     let onForget: () -> Void
     let onRemove: () -> Void
+    /// Open the experimental library browser — nil (no menu item) unless the feature flag is on.
+    var onBrowseLibrary: (() -> Void)? = nil
 
     var body: some View {
         let m = CardMetrics.current
@@ -104,8 +106,13 @@ struct HostCardView: View {
         .contextMenu {
             Button("Pair with PIN…", action: onPair)
             Button("Test Network Speed…", action: onSpeedTest)
+            if let onBrowseLibrary {
+                Button("Browse Library…", action: onBrowseLibrary)
+            }
             if host.pinnedSHA256 != nil {
-                Button("Forget Identity", action: onForget)
+                // Dropping the pin does NOT downgrade to TOFU: the next connect must re-pair via
+                // PIN (unless the host advertises pair=optional). Wording reflects that.
+                Button("Forget Identity (re-pair to reconnect)", action: onForget)
             }
             Button("Remove", role: .destructive, action: onRemove)
         }

clients/apple/Sources/PunktfunkClient/HostStore.swift

@@ -21,8 +21,14 @@ struct StoredHost: Identifiable, Codable, Hashable {
     var pinnedSHA256: Data?
     /// Last time a streaming session actually started (nil until the first one).
     var lastConnected: Date?
+    /// Management-API port for the library browser (distinct from the data-plane `port`). Optional
+    /// (NOT a defaulted non-optional) so older saved hosts — whose JSON lacks this key — still
+    /// decode: synthesized Decodable ignores property defaults but treats a missing Optional as
+    /// nil. Resolve via `effectiveMgmtPort`. (Auth is mTLS by the pinned identity — no token.)
+    var mgmtPort: UInt16?
 
     var displayName: String { name.isEmpty ? address : name }
+    var effectiveMgmtPort: UInt16 { mgmtPort ?? punktfunkDefaultMgmtPort }
 }
 
 extension StoredHost {
@@ -80,13 +86,15 @@ final class HostStore: ObservableObject {
         hosts[i].pinnedSHA256 = fingerprint
     }
 
-    /// Drop the pinned identity (e.g. after a legitimate host reinstall) — the next
+    /// Drop the pinned identity (e.g. after a legitimate host reinstall). This does NOT downgrade
-    /// connect goes through the trust prompt again.
+    /// to TOFU: the next connect re-pairs via the PIN ceremony, unless the host advertises
+    /// `pair=optional` (the only case the connect path still offers the trust prompt).
     func forgetIdentity(_ host: StoredHost) {
         guard let i = hosts.firstIndex(where: { $0.id == host.id }) else { return }
         hosts[i].pinnedSHA256 = nil
     }
 
+
     private func persist() {
         if let data = try? JSONEncoder().encode(hosts) {
             UserDefaults.standard.set(data, forKey: Self.key)

clients/apple/Sources/PunktfunkClient/LibraryView.swift

@@ -0,0 +1,202 @@
+// Experimental game-library browser (plan step 3, gated behind DefaultsKey.libraryEnabled).
+// Renders a poster grid of the host's library fetched over the management API. Read-only:
+// launching a chosen title is a later step. Reached from a host card's "Browse Library…"
+// context-menu action, which only appears when the feature flag is on.
+
+import PunktfunkKit
+import SwiftUI
+
+struct LibraryView: View {
+    @ObservedObject var store: HostStore
+    let host: StoredHost
+    /// Tapping a title starts a session that asks the host to launch it (the library id is passed
+    /// through). `nil` ⇒ browse-only (cards aren't tappable).
+    var onLaunch: ((String) -> Void)? = nil
+
+    @State private var games: [GameEntry] = []
+    @State private var loading = false
+    @State private var errorText: String?
+
+    var body: some View {
+        content
+            .navigationTitle("\(host.displayName) — Library")
+            #if os(iOS)
+            .navigationBarTitleDisplayMode(.inline)
+            #endif
+            .toolbar {
+                #if os(macOS)
+                ToolbarItemGroup { reloadButton }
+                #else
+                ToolbarItem(placement: .primaryAction) { reloadButton }
+                #endif
+            }
+            .task { await load() }
+    }
+
+    @ViewBuilder private var content: some View {
+        if loading && games.isEmpty {
+            ProgressView("Loading library…")
+                .frame(maxWidth: .infinity, maxHeight: .infinity)
+        } else if let errorText, games.isEmpty {
+            errorState(errorText)
+        } else if games.isEmpty {
+            emptyState
+        } else {
+            grid
+        }
+    }
+
+    private var grid: some View {
+        ScrollView {
+            LazyVGrid(columns: columns, spacing: 18) {
+                ForEach(games) { game in
+                    if let onLaunch {
+                        Button { onLaunch(game.id) } label: { GameCard(game: game) }
+                            .buttonStyle(.plain)
+                    } else {
+                        GameCard(game: game)
+                    }
+                }
+            }
+            .padding()
+        }
+    }
+
+    private var columns: [GridItem] {
+        #if os(tvOS)
+        let minW: CGFloat = 220
+        #else
+        let minW: CGFloat = 130
+        #endif
+        return [GridItem(.adaptive(minimum: minW), spacing: 18)]
+    }
+
+    private func errorState(_ text: String) -> some View {
+        VStack(spacing: 16) {
+            Image(systemName: "exclamationmark.triangle")
+                .font(.largeTitle)
+                .foregroundStyle(.secondary)
+            Text(text)
+                .multilineTextAlignment(.center)
+                .foregroundStyle(.secondary)
+                .frame(maxWidth: 420)
+            Button("Retry") { Task { await load() } }
+                .buttonStyle(.borderedProminent)
+        }
+        .padding()
+        .frame(maxWidth: .infinity, maxHeight: .infinity)
+    }
+
+    private var emptyState: some View {
+        VStack(spacing: 12) {
+            Image(systemName: "square.grid.2x2")
+                .font(.largeTitle)
+                .foregroundStyle(.secondary)
+            Text("No games found on this host.")
+                .foregroundStyle(.secondary)
+        }
+        .frame(maxWidth: .infinity, maxHeight: .infinity)
+    }
+
+    private var reloadButton: some View {
+        Button { Task { await load() } } label: {
+            Label("Reload", systemImage: "arrow.clockwise")
+        }
+        .disabled(loading)
+    }
+
+    private func load() async {
+        loading = true
+        errorText = nil
+        let current = store.hosts.first { $0.id == host.id } ?? host
+        // mTLS uses this client's persistent identity (the host paired it over QUIC). No identity
+        // yet → the user hasn't connected/paired, which is also when there's nothing to browse.
+        guard let identity = (try? ClientIdentityStore.shared.load())?.identity else {
+            games = []
+            errorText = "Connect to this host once first — the library uses the identity created "
+                + "on pairing to authenticate."
+            loading = false
+            return
+        }
+        do {
+            games = try await LibraryClient.fetch(
+                address: current.address,
+                port: current.effectiveMgmtPort,
+                certPEM: identity.certPEM,
+                keyPEM: identity.keyPEM,
+                hostFingerprint: current.pinnedSHA256)
+        } catch {
+            games = []
+            errorText = (error as? LibraryError)?.errorDescription ?? error.localizedDescription
+        }
+        loading = false
+    }
+}
+
+/// One poster tile. Steam vs custom is marked with a badge; the art walks the candidate URLs
+/// (portrait → header → hero) and finally a text placeholder.
+private struct GameCard: View {
+    let game: GameEntry
+
+    var body: some View {
+        VStack(alignment: .leading, spacing: 6) {
+            PosterImage(candidates: game.art.posterCandidates, title: game.title)
+                .aspectRatio(2.0 / 3.0, contentMode: .fit)
+                .frame(maxWidth: .infinity)
+                .clipShape(RoundedRectangle(cornerRadius: 10, style: .continuous))
+                .overlay(alignment: .topLeading) { storeBadge }
+            Text(game.title)
+                .font(.caption)
+                .lineLimit(2)
+                .foregroundStyle(.secondary)
+        }
+    }
+
+    private var storeBadge: some View {
+        Text(game.isCustom ? "Custom" : "Steam")
+            .font(.caption2.weight(.semibold))
+            .padding(.horizontal, 6)
+            .padding(.vertical, 3)
+            .background(.ultraThinMaterial, in: Capsule())
+            .padding(6)
+    }
+}
+
+/// Sequentially tries cover-art URLs, advancing past any that fail to load, then a placeholder.
+private struct PosterImage: View {
+    let candidates: [URL]
+    let title: String
+    @State private var index = 0
+
+    var body: some View {
+        if index < candidates.count {
+            AsyncImage(url: candidates[index]) { phase in
+                switch phase {
+                case .success(let image):
+                    image.resizable().scaledToFill()
+                case .failure:
+                    // Advance to the next candidate on the next render pass.
+                    Color.clear.onAppear { index += 1 }
+                case .empty:
+                    ZStack { placeholder; ProgressView() }
+                @unknown default:
+                    placeholder
+                }
+            }
+            .id(index) // recreate AsyncImage so it loads the newly-selected URL
+        } else {
+            placeholder
+        }
+    }
+
+    private var placeholder: some View {
+        ZStack {
+            Rectangle().fill(.quaternary)
+            Text(title)
+                .font(.headline)
+                .multilineTextAlignment(.center)
+                .foregroundStyle(.secondary)
+                .padding(8)
+        }
+    }
+}

clients/apple/Sources/PunktfunkClient/PunktfunkClientApp.swift

@@ -16,6 +16,11 @@ struct PunktfunkClientApp: App {
         WindowGroup("Punktfunkempfänger") {
             ContentView()
         }
+        // The Stream menu (Disconnect ⌘D, Show/Hide Statistics ⌘⇧S) — a real menu bar on
+        // macOS, hardware-keyboard shortcuts on iPad. tvOS has neither.
+        #if !os(tvOS)
+        .commands { StreamCommands() }
+        #endif
         #if os(macOS)
         Settings {
             SettingsView()

clients/apple/Sources/PunktfunkClient/SessionModel.swift

@@ -83,10 +83,18 @@ final class SessionModel: ObservableObject {
 
     var isBusy: Bool { phase != .idle }
 
+    /// `allowTofu` gates the trust-on-first-use prompt for an unpinned host: it is only true
+    /// when the host EXPLICITLY advertised `pair=optional` (rule 3a). For any other unpinned host
+    /// — `pair=required`, a manually-typed host, or a discovered host with no/unknown `pair`
+    /// field — TOFU is forbidden (rule 3b): the connect refuses rather than offering trust, and
+    /// the user is routed to PIN pairing by the caller. (A pinned host connects regardless: its
+    /// stored fingerprint is the trust decision.)
     func connect(to host: StoredHost, width: UInt32, height: UInt32, hz: UInt32,
                  compositor: PunktfunkConnection.Compositor = .auto,
                  gamepad: PunktfunkConnection.GamepadType = .auto,
                  bitrateKbps: UInt32 = 0,
+                 launchID: String? = nil,
+                 allowTofu: Bool = false,
                  autoTrust: Bool = false) {
         guard phase == .idle else { return }
         phase = .connecting
@@ -103,7 +111,7 @@ final class SessionModel: ObservableObject {
                 host: host.address, port: host.port,
                 width: width, height: height, refreshHz: hz,
                 pinSHA256: pin, identity: identity, compositor: compositor,
-                gamepad: gamepad, bitrateKbps: bitrateKbps) }
+                gamepad: gamepad, bitrateKbps: bitrateKbps, launchID: launchID) }
             await MainActor.run { [weak self] in
                 guard let self else { return }
                 // The user may have abandoned this attempt (window closed, another host
@@ -117,12 +125,24 @@ final class SessionModel: ObservableObject {
                 }
                 switch result {
                 case .success(let conn):
+                    if pin != nil || autoTrust {
                         self.connection = conn
                         self.startStatsTimer()
-                    if pin != nil || autoTrust {
                         self.beginStreaming()
-                    } else {
+                    } else if allowTofu {
+                        // Host advertised pair=optional — offer the reduced-security TOFU prompt
+                        // over the live (blurred) stream (rule 3a).
+                        self.connection = conn
+                        self.startStatsTimer()
                         self.phase = .awaitingTrust(fingerprint: conn.hostFingerprint)
+                    } else {
+                        // Unpinned and TOFU not permitted (rule 3b): never let this silently
+                        // become trustable. Drop the connection; the caller routes to pairing.
+                        Task.detached { conn.close() } // joins Rust threads — off-main
+                        self.phase = .idle
+                        self.activeHost = nil
+                        self.errorMessage = "\(host.displayName) is not paired yet. "
+                            + "Pair with its PIN before streaming."
                     }
                 case .failure:
                     self.phase = .idle

clients/apple/Sources/PunktfunkClient/SettingsView.swift

@@ -1,6 +1,10 @@
-// App settings (⌘,): the stream mode, the host compositor, and controllers. The host
+// App settings. The host creates a native virtual output at exactly the chosen size/refresh —
-// creates a native virtual output at exactly this size/refresh — there is no scaling
+// there is no scaling anywhere in the pipeline.
-// anywhere in the pipeline.
+//
+// Navigation differs per platform: macOS uses a tabbed preferences window (the sections had
+// outgrown one scrolling pane); iOS uses a single grouped Form; tvOS uses a focus-native
+// pushed-picker layout. The individual sections (`streamModeSection`, `audioSection`, …) are
+// shared across all three so a setting is defined exactly once.
 
 #if os(macOS)
 import AppKit
@@ -18,7 +22,11 @@ struct SettingsView: View {
     @AppStorage(DefaultsKey.gamepadType) private var gamepadType = 0
     @AppStorage(DefaultsKey.bitrateKbps) private var bitrateKbps = 0
     @AppStorage(DefaultsKey.presenter) private var presenter = "stage1"
+    @AppStorage(DefaultsKey.libraryEnabled) private var libraryEnabled = false
+    @AppStorage(DefaultsKey.fullscreenWhileStreaming) private var fullscreenWhileStreaming = true
     @AppStorage(DefaultsKey.micEnabled) private var micEnabled = true
+    @AppStorage(DefaultsKey.hudEnabled) private var hudEnabled = true
+    @AppStorage(DefaultsKey.hudPlacement) private var hudPlacement = HUDPlacement.topTrailing.rawValue
     @ObservedObject private var gamepads = GamepadManager.shared
     #if os(macOS)
     @AppStorage(DefaultsKey.speakerUID) private var speakerUID = ""
@@ -30,14 +38,91 @@ struct SettingsView: View {
     var body: some View {
         #if os(tvOS)
         // Native tv pattern: no inline text entry (typing numbers with a remote is
-        // miserable and the inline field chrome fights the focus system). The mode is
+        // miserable and the inline field chrome fights the focus system). Modes are
-        // a preset picker; pickers push selection lists like the system Settings app.
+        // preset pickers that push selection lists like the system Settings app.
         tvBody
+        #elseif os(macOS)
+        macBody
         #else
-        sharedBody
+        iosBody
         #endif
     }
 
+    // MARK: - macOS: tabbed preferences
+
+    #if os(macOS)
+    private var macBody: some View {
+        TabView {
+            Form {
+                streamModeSection
+                compositorSection
+            }
+            .formStyle(.grouped)
+            .tabItem { Label("General", systemImage: "gearshape") }
+
+            Form {
+                presenterSection
+                windowSection
+                statisticsSection
+            }
+            .formStyle(.grouped)
+            .tabItem { Label("Display", systemImage: "display") }
+
+            Form {
+                audioSection
+            }
+            .formStyle(.grouped)
+            .onAppear {
+                outputDevices = AudioDevices.outputs()
+                inputDevices = AudioDevices.inputs()
+            }
+            .tabItem { Label("Audio", systemImage: "speaker.wave.2") }
+
+            Form {
+                controllersSection
+            }
+            .formStyle(.grouped)
+            .onAppear {
+                gamepads.refresh()
+                gamepads.startDiscovery()
+            }
+            .onDisappear { gamepads.stopDiscovery() }
+            .tabItem { Label("Controllers", systemImage: "gamecontroller") }
+
+            Form {
+                experimentalSection
+            }
+            .formStyle(.grouped)
+            .tabItem { Label("Advanced", systemImage: "slider.horizontal.3") }
+        }
+        .frame(width: 480, height: 460)
+    }
+    #endif
+
+    // MARK: - iOS: one grouped Form
+
+    #if os(iOS)
+    private var iosBody: some View {
+        Form {
+            streamModeSection
+            audioSection
+            compositorSection
+            presenterSection
+            statisticsSection
+            experimentalSection
+            controllersSection
+        }
+        .formStyle(.grouped)
+        .onAppear {
+            gamepads.refresh()
+            gamepads.startDiscovery()
+        }
+        .onDisappear { gamepads.stopDiscovery() }
+    }
+    #endif
+
+    // MARK: - tvOS
+
     #if os(tvOS)
     private static let presets: [(label: String, tag: String)] = [
         ("720p @ 60", "1280x720x60"),
@@ -57,6 +142,10 @@ struct SettingsView: View {
             })
     }
 
+    private var hudEnabledTag: Binding<String> {
+        Binding(get: { hudEnabled ? "on" : "off" }, set: { hudEnabled = $0 == "on" })
+    }
+
     private var tvBody: some View {
         let currentTag = "\(width)x\(height)x\(hz)"
         let bounds = UIScreen.main.nativeBounds
@@ -100,6 +189,12 @@ struct SettingsView: View {
                     .foregroundStyle(.secondary)
                     .multilineTextAlignment(.center)
                     .padding(.top, 8)
+                TVSelectionRow(
+                    title: "Statistics overlay",
+                    options: [("On", "on"), ("Off", "off")], selection: hudEnabledTag)
+                TVSelectionRow(
+                    title: "Statistics position", options: Self.placementOptions,
+                    selection: $hudPlacement)
                 ForEach(gamepads.controllers) { controller in
                     controllerRow(controller)
                         .padding(.horizontal, 24)
@@ -128,6 +223,203 @@ struct SettingsView: View {
     }
     #endif
 
+    // MARK: - Sections (shared)
+
+    @ViewBuilder private var streamModeSection: some View {
+        Section {
+            HStack {
+                TextField("Resolution", value: $width, format: .number.grouping(.never))
+                Text("×")
+                TextField("", value: $height, format: .number.grouping(.never))
+                    .labelsHidden()
+            }
+            TextField("Refresh rate (Hz)", value: $hz, format: .number.grouping(.never))
+            LabeledContent("") {
+                Button("Use this display's mode") { fillFromMainScreen() }
+            }
+            #if !os(tvOS)
+            Toggle("Automatic bitrate", isOn: automaticBitrate)
+            if bitrateKbps != 0 {
+                HStack(spacing: 12) {
+                    Slider(value: bitrateSlider, in: 0...1) {
+                        Text("Bitrate")
+                    }
+                    Text(SpeedTestSheet.mbpsLabel(kbps: bitrateKbps))
+                        .monospacedDigit()
+                        .foregroundStyle(.secondary)
+                        .frame(minWidth: 76, alignment: .trailing)
+                }
+                if bitrateKbps > 1_000_000 {
+                    Label(Self.gigabitWarning, systemImage: "exclamationmark.triangle.fill")
+                        .font(.caption)
+                        .foregroundStyle(.orange)
+                }
+            }
+            #endif
+        } header: {
+            Text("Stream mode")
+        } footer: {
+            Text("The host creates a virtual output at exactly this mode — "
+                + "native resolution, no scaling. \(Self.bitrateFooter)")
+                .font(.caption)
+                .foregroundStyle(.secondary)
+        }
+    }
+
+    @ViewBuilder private var audioSection: some View {
+        Section {
+            #if os(macOS)
+            Picker("Speaker", selection: $speakerUID) {
+                Text("System default").tag("")
+                ForEach(outputDevices) { device in
+                    Text(device.name).tag(device.uid)
+                }
+                if !speakerUID.isEmpty,
+                   !outputDevices.contains(where: { $0.uid == speakerUID }) {
+                    Text("Unavailable device").tag(speakerUID)
+                }
+            }
+            #endif
+            Toggle("Send microphone to the host", isOn: $micEnabled)
+            #if os(macOS)
+            Picker("Microphone", selection: $micUID) {
+                Text("System default").tag("")
+                ForEach(inputDevices) { device in
+                    Text(device.name).tag(device.uid)
+                }
+                if !micUID.isEmpty,
+                   !inputDevices.contains(where: { $0.uid == micUID }) {
+                    Text("Unavailable device").tag(micUID)
+                }
+            }
+            .disabled(!micEnabled)
+            #endif
+        } header: {
+            Text("Audio")
+        } footer: {
+            Text("Host audio plays through the speaker; the microphone feeds the "
+                + "host's virtual mic. System default follows macOS device changes. "
+                + "Applies from the next session.")
+                .font(.caption)
+                .foregroundStyle(.secondary)
+        }
+    }
+
+    @ViewBuilder private var compositorSection: some View {
+        Section {
+            Picker("Compositor", selection: $compositor) {
+                Text("Automatic").tag(0)
+                Text("KWin (KDE Plasma)").tag(1)
+                Text("wlroots (Sway / Hyprland)").tag(2)
+                Text("Mutter (GNOME)").tag(3)
+                Text("gamescope").tag(4)
+            }
+        } header: {
+            Text("Host compositor")
+        } footer: {
+            Text("Which compositor drives the virtual output on the host. A specific "
+                + "choice is honored only if that backend is available there — "
+                + "otherwise the host falls back to auto-detection.")
+                .font(.caption)
+                .foregroundStyle(.secondary)
+        }
+    }
+
+    @ViewBuilder private var windowSection: some View {
+        #if os(macOS)
+        Section {
+            Toggle("Fullscreen while streaming", isOn: $fullscreenWhileStreaming)
+        } header: {
+            Text("Window")
+        } footer: {
+            Text("Take the window fullscreen when a session starts and restore it on the host "
+                + "list, so only the stream is fullscreen — not the picker.")
+                .font(.caption)
+                .foregroundStyle(.secondary)
+        }
+        #endif
+    }
+
+    @ViewBuilder private var presenterSection: some View {
+        Section {
+            Picker("Presenter", selection: $presenter) {
+                Text("Stage 1 (default)").tag("stage1")
+                Text("Stage 2 (experimental)").tag("stage2")
+            }
+        } header: {
+            Text("Video presenter")
+        } footer: {
+            Text("Stage 1 feeds compressed video to the system display layer (known-good). "
+                + "Stage 2 decodes explicitly and presents through Metal with a display "
+                + "link — it adds a capture→present (glass-to-glass) latency line in the HUD "
+                + "and shortens the present tail. Applies from the next session.")
+                .font(.caption)
+                .foregroundStyle(.secondary)
+        }
+    }
+
+    @ViewBuilder private var statisticsSection: some View {
+        Section {
+            Toggle("Show statistics overlay", isOn: $hudEnabled)
+            Picker("Position", selection: $hudPlacement) {
+                ForEach(HUDPlacement.allCases) { placement in
+                    Text(placement.label).tag(placement.rawValue)
+                }
+            }
+            .disabled(!hudEnabled)
+        } header: {
+            Text("Statistics")
+        } footer: {
+            Text(Self.statisticsFooter)
+                .font(.caption)
+                .foregroundStyle(.secondary)
+        }
+    }
+
+    @ViewBuilder private var experimentalSection: some View {
+        Section {
+            Toggle("Show game library", isOn: $libraryEnabled)
+        } header: {
+            Text("Experimental")
+        } footer: {
+            Text("Adds a “Browse Library…” action to each host that lists its games "
+                + "(Steam + custom) via the host's management API; tap a title to launch it. "
+                + "The host must expose that API on the LAN with a token "
+                + "(serve --mgmt-bind 0.0.0.0 --mgmt-token …).")
+                .font(.caption)
+                .foregroundStyle(.secondary)
+        }
+    }
+
+    @ViewBuilder private var controllersSection: some View {
+        Section {
+            if gamepads.controllers.isEmpty {
+                Text("No controllers detected")
+                    .foregroundStyle(.secondary)
+            } else {
+                ForEach(gamepads.controllers) { controller in
+                    controllerRow(controller)
+                }
+            }
+            Picker("Use controller", selection: $gamepads.preferredID) {
+                ForEach(controllerOptions, id: \.tag) { option in
+                    Text(option.label).tag(option.tag)
+                }
+            }
+            Picker("Controller type", selection: $gamepadType) {
+                ForEach(Self.padTypes, id: \.tag) { option in
+                    Text(option.label).tag(option.tag)
+                }
+            }
+        } header: {
+            Text("Controllers")
+        } footer: {
+            Text(Self.controllersFooter)
+                .font(.caption)
+                .foregroundStyle(.secondary)
+        }
+    }
+
     // MARK: - Bitrate
 
     /// Slider domain, log-scale: the useful range spans three orders of magnitude
@@ -197,8 +489,23 @@ struct SettingsView: View {
         }
         return options
     }
+
+    private static let placementOptions: [(label: String, tag: String)] =
+        HUDPlacement.allCases.map { ($0.label, $0.rawValue) }
     #endif
 
+    // MARK: - Statistics
+
+    private static var statisticsFooter: String {
+        let base = "The overlay shows resolution, frame rate, throughput and latency while "
+            + "streaming, in the chosen corner."
+        #if os(macOS) || os(iOS)
+        return base + " Toggle it any time with ⌘⇧S."
+        #else
+        return base
+        #endif
+    }
+
     // MARK: - Controllers
 
     private static let padTypes: [(label: String, tag: Int)] = [
@@ -272,163 +579,6 @@ struct SettingsView: View {
         }
     }
 
-    private var sharedBody: some View {
-        Form {
-            Section {
-                HStack {
-                    TextField("Resolution", value: $width, format: .number.grouping(.never))
-                    Text("×")
-                    TextField("", value: $height, format: .number.grouping(.never))
-                        .labelsHidden()
-                }
-                TextField("Refresh rate (Hz)", value: $hz, format: .number.grouping(.never))
-                LabeledContent("") {
-                    Button("Use this display's mode") { fillFromMainScreen() }
-                }
-                // (sharedBody is unused on tvOS — its body still compiles there, and
-                // Slider doesn't exist on tvOS; the tv path has its own preset picker.)
-                #if !os(tvOS)
-                Toggle("Automatic bitrate", isOn: automaticBitrate)
-                if bitrateKbps != 0 {
-                    HStack(spacing: 12) {
-                        Slider(value: bitrateSlider, in: 0...1) {
-                            Text("Bitrate")
-                        }
-                        Text(SpeedTestSheet.mbpsLabel(kbps: bitrateKbps))
-                            .monospacedDigit()
-                            .foregroundStyle(.secondary)
-                            .frame(minWidth: 76, alignment: .trailing)
-                    }
-                    if bitrateKbps > 1_000_000 {
-                        Label(Self.gigabitWarning, systemImage: "exclamationmark.triangle.fill")
-                            .font(.caption)
-                            .foregroundStyle(.orange)
-                    }
-                }
-                #endif
-            } header: {
-                Text("Stream mode")
-            } footer: {
-                Text("The host creates a virtual output at exactly this mode — "
-                    + "native resolution, no scaling. \(Self.bitrateFooter)")
-                    .font(.caption)
-                    .foregroundStyle(.secondary)
-            }
-            #if !os(tvOS)
-            Section {
-                #if os(macOS)
-                Picker("Speaker", selection: $speakerUID) {
-                    Text("System default").tag("")
-                    ForEach(outputDevices) { device in
-                        Text(device.name).tag(device.uid)
-                    }
-                    if !speakerUID.isEmpty,
-                       !outputDevices.contains(where: { $0.uid == speakerUID }) {
-                        Text("Unavailable device").tag(speakerUID)
-                    }
-                }
-                #endif
-                #if !os(tvOS)
-                Toggle("Send microphone to the host", isOn: $micEnabled)
-                #endif
-                #if os(macOS)
-                Picker("Microphone", selection: $micUID) {
-                    Text("System default").tag("")
-                    ForEach(inputDevices) { device in
-                        Text(device.name).tag(device.uid)
-                    }
-                    if !micUID.isEmpty,
-                       !inputDevices.contains(where: { $0.uid == micUID }) {
-                        Text("Unavailable device").tag(micUID)
-                    }
-                }
-                .disabled(!micEnabled)
-                #endif
-            } header: {
-                Text("Audio")
-            } footer: {
-                Text("Host audio plays through the speaker; the microphone feeds the "
-                    + "host's virtual mic. System default follows macOS device changes. "
-                    + "Applies from the next session.")
-                    .font(.caption)
-                    .foregroundStyle(.secondary)
-            }
-            #endif
-            Section {
-                Picker("Compositor", selection: $compositor) {
-                    Text("Automatic").tag(0)
-                    Text("KWin (KDE Plasma)").tag(1)
-                    Text("wlroots (Sway / Hyprland)").tag(2)
-                    Text("Mutter (GNOME)").tag(3)
-                    Text("gamescope").tag(4)
-                }
-            } header: {
-                Text("Host compositor")
-            } footer: {
-                Text("Which compositor drives the virtual output on the host. A specific "
-                    + "choice is honored only if that backend is available there — "
-                    + "otherwise the host falls back to auto-detection.")
-                    .font(.caption)
-                    .foregroundStyle(.secondary)
-            }
-            Section {
-                Picker("Presenter", selection: $presenter) {
-                    Text("Stage 1 (default)").tag("stage1")
-                    Text("Stage 2 (experimental)").tag("stage2")
-                }
-            } header: {
-                Text("Video presenter")
-            } footer: {
-                Text("Stage 1 feeds compressed video to the system display layer (known-good). "
-                    + "Stage 2 decodes explicitly and presents through Metal with a display "
-                    + "link — it adds a capture→present (glass-to-glass) latency line in the HUD "
-                    + "and shortens the present tail. Applies from the next session.")
-                    .font(.caption)
-                    .foregroundStyle(.secondary)
-            }
-            Section {
-                if gamepads.controllers.isEmpty {
-                    Text("No controllers detected")
-                        .foregroundStyle(.secondary)
-                } else {
-                    ForEach(gamepads.controllers) { controller in
-                        controllerRow(controller)
-                    }
-                }
-                Picker("Use controller", selection: $gamepads.preferredID) {
-                    ForEach(controllerOptions, id: \.tag) { option in
-                        Text(option.label).tag(option.tag)
-                    }
-                }
-                Picker("Controller type", selection: $gamepadType) {
-                    ForEach(Self.padTypes, id: \.tag) { option in
-                        Text(option.label).tag(option.tag)
-                    }
-                }
-            } header: {
-                Text("Controllers")
-            } footer: {
-                Text(Self.controllersFooter)
-                    .font(.caption)
-                    .foregroundStyle(.secondary)
-            }
-        }
-        .formStyle(.grouped)
-        .onAppear {
-            gamepads.refresh()
-            gamepads.startDiscovery()
-        }
-        .onDisappear { gamepads.stopDiscovery() }
-        #if os(macOS)
-        .frame(width: 380)
-        .fixedSize()
-        .onAppear {
-            outputDevices = AudioDevices.outputs()
-            inputDevices = AudioDevices.inputs()
-        }
-        #endif
-    }
-
     private func fillFromMainScreen() {
         #if os(macOS)
         guard let screen = NSScreen.main else { return }

clients/apple/Sources/PunktfunkClient/SpeedTestSheet.swift

@@ -23,10 +23,12 @@ private final class ProbeToken: @unchecked Sendable {
 /// What the host is asked to burst: the host's full probe ceiling (it clamps to ≤ 3 Gbps),
 /// so the measurement surfaces the link's real ceiling instead of an artificial cap —
 /// bursting ABOVE what the link can carry is how the probe finds where delivery falls off.
-/// Two seconds rides out scheduler jitter. File-scope so the detached probe task reads them
+/// Five seconds (was 2 s) averages out the scheduler/recv jitter that made a short probe swing
-/// without crossing into the view's main actor.
+/// wildly (50 vs 900 Mbps on the same link) — long enough for the host's steady-state send and
+/// the client's recv drain to settle. File-scope so the detached probe task reads them without
+/// crossing into the view's main actor.
 private let probeTargetKbps: UInt32 = 3_000_000
-private let probeDurationMs: UInt32 = 2_000
+private let probeDurationMs: UInt32 = 5_000
 
 struct SpeedTestSheet: View {
     @Environment(\.dismiss) private var dismiss

clients/apple/Sources/PunktfunkClient/StreamCommands.swift

@@ -0,0 +1,49 @@
+// The app's "Stream" menu (macOS menu bar + iPad hardware-keyboard shortcuts). These live at
+// the Scene level so they keep working when the HUD overlay is hidden — in particular ⌘D
+// disconnect, which used to be reachable only via the HUD's button. The toggle just flips the
+// shared `hudEnabled` setting; ContentView reads the same @AppStorage and reacts.
+//
+// tvOS has no menu bar / hardware-keyboard command surface (disconnect there is the Siri
+// Remote's Menu button, handled by ContentView's `.onExitCommand`), so this whole file is
+// non-tvOS only.
+
+#if !os(tvOS)
+import PunktfunkKit
+import SwiftUI
+
+/// The live session's menu-reachable actions, published by ContentView via
+/// `.focusedSceneValue` so the Scene-level commands can drive it.
+struct SessionFocus {
+    var isStreaming: Bool
+    var disconnect: () -> Void
+}
+
+private struct SessionFocusKey: FocusedValueKey {
+    typealias Value = SessionFocus
+}
+
+extension FocusedValues {
+    var sessionFocus: SessionFocus? {
+        get { self[SessionFocusKey.self] }
+        set { self[SessionFocusKey.self] = newValue }
+    }
+}
+
+struct StreamCommands: Commands {
+    @FocusedValue(\.sessionFocus) private var session
+    @AppStorage(DefaultsKey.hudEnabled) private var hudEnabled = true
+
+    var body: some Commands {
+        CommandMenu("Stream") {
+            Button(hudEnabled ? "Hide Statistics" : "Show Statistics") {
+                hudEnabled.toggle()
+            }
+            .keyboardShortcut("s", modifiers: [.command, .shift])
+            Divider()
+            Button("Disconnect") { session?.disconnect() }
+                .keyboardShortcut("d", modifiers: .command)
+                .disabled(session?.isStreaming != true)
+        }
+    }
+}
+#endif

clients/apple/Sources/PunktfunkClient/StreamHUDView.swift

@@ -4,12 +4,44 @@
 import PunktfunkKit
 import SwiftUI
 
+/// Which corner the HUD overlay occupies (persisted as `DefaultsKey.hudPlacement`). The raw
+/// values are stable on disk — rename the cases freely, never the strings.
+enum HUDPlacement: String, CaseIterable, Identifiable {
+    case topLeading, topTrailing, bottomLeading, bottomTrailing
+
+    var id: String { rawValue }
+
+    /// SwiftUI overlay alignment for `.overlay(alignment:)`.
+    var alignment: Alignment {
+        switch self {
+        case .topLeading: return .topLeading
+        case .topTrailing: return .topTrailing
+        case .bottomLeading: return .bottomLeading
+        case .bottomTrailing: return .bottomTrailing
+        }
+    }
+
+    /// The HUD's own stack hugs the screen edge it sits against, so its text aligns outward.
+    var isTrailing: Bool { self == .topTrailing || self == .bottomTrailing }
+
+    /// User-facing corner label.
+    var label: String {
+        switch self {
+        case .topLeading: return "Top Left"
+        case .topTrailing: return "Top Right"
+        case .bottomLeading: return "Bottom Left"
+        case .bottomTrailing: return "Bottom Right"
+        }
+    }
+}
+
 struct StreamHUDView: View {
     @ObservedObject var model: SessionModel
     let connection: PunktfunkConnection
+    var placement: HUDPlacement = .topTrailing
 
     var body: some View {
-        VStack(alignment: .trailing, spacing: 4) {
+        VStack(alignment: placement.isTrailing ? .trailing : .leading, spacing: 4) {
             HStack(spacing: 6) {
                 Circle()
                     .fill(Color.accentColor)
@@ -39,6 +71,11 @@ struct StreamHUDView: View {
                 : "Click the stream to capture input")
                 .font(.caption2)
                 .foregroundStyle(.secondary)
+            // The client-side cursor (⌘⇧C) draws the local cursor over the stream instead of
+            // capturing it — the only accurate cursor for gamescope, whose capture has none.
+            Text("⌘⇧C toggles the on-screen cursor")
+                .font(.caption2)
+                .foregroundStyle(.secondary)
             #elseif os(iOS)
             // Touch always plays directly; ⌘⎋ (hardware keyboard) toggles kb/mouse.
             Text(model.mouseCaptured
@@ -55,9 +92,10 @@ struct StreamHUDView: View {
                 .font(.caption)
                 .foregroundStyle(.secondary)
             #else
+            // ⌘D lives on the app's Stream menu (so it still works when the HUD is hidden);
+            // this button is the in-overlay, click-to-disconnect affordance.
             Button("Disconnect (⌘D)") { model.disconnect() }
                 .font(.caption)
-                .keyboardShortcut("d", modifiers: .command)
             #endif
         }
         .padding(10)

clients/apple/Sources/PunktfunkKit/ClientTLS.swift

@@ -0,0 +1,142 @@
+// mTLS for the management REST API. The host now serves the API over HTTPS and authorizes a
+// request whose client certificate is in its paired store (host commit b4a85a8) — the SAME
+// identity + trust the QUIC data plane uses — so a paired client needs no bearer token.
+//
+// To present that identity, URLSession needs a SecIdentity (cert + private key pair). The client
+// stores its identity as PEM (rcgen ECDSA P-256, PKCS#8 key). We rebuild a SecIdentity natively:
+// CryptoKit parses the key → its X9.63 form → a SecKey, the cert PEM → a SecCertificate, and
+// SecIdentityCreateWithCertificate pairs them via the Keychain. This is macOS-only
+// (SecIdentityCreateWithCertificate is unavailable on iOS — that path will need a PKCS#12); the
+// client library is macOS-first today.
+
+import CryptoKit
+import Foundation
+import Security
+import os
+
+private let tlsLog = Logger(subsystem: "io.unom.punktfunk", category: "library-tls")
+
+enum ClientTLS {
+    enum TLSError: LocalizedError {
+        case unsupportedPlatform
+        case badKey(String)
+        case badCert
+        case identity(String)
+
+        var errorDescription: String? {
+            switch self {
+            case .unsupportedPlatform:
+                return "Library mTLS is supported on macOS only right now."
+            case .badKey(let why): return "Couldn't load the client key: \(why)"
+            case .badCert: return "Couldn't load the client certificate."
+            case .identity(let why): return "Couldn't build the client identity: \(why)"
+            }
+        }
+    }
+
+    /// First PEM block of `type` ("CERTIFICATE" / "PRIVATE KEY") → its DER bytes.
+    private static func derFromPEM(_ pem: String, type: String) -> Data? {
+        guard let start = pem.range(of: "-----BEGIN \(type)-----"),
+              let end = pem.range(of: "-----END \(type)-----", range: start.upperBound..<pem.endIndex)
+        else { return nil }
+        let b64 = pem[start.upperBound..<end.lowerBound]
+            .components(separatedBy: .whitespacesAndNewlines).joined()
+        return Data(base64Encoded: b64)
+    }
+
+    /// Build a `SecIdentity` from the client's PEM cert + PKCS#8 P-256 key. Pairs them via the
+    /// Keychain (the key is stored once under a stable tag, so repeat calls reuse it).
+    static func makeIdentity(certPEM: String, keyPEM: String) throws -> SecIdentity {
+        #if os(macOS)
+        // Key: CryptoKit accepts the SEC1 or PKCS#8 PEM; its x963 form is what SecKey wants.
+        let priv: P256.Signing.PrivateKey
+        do {
+            priv = try P256.Signing.PrivateKey(pemRepresentation: keyPEM)
+        } catch {
+            throw TLSError.badKey(error.localizedDescription)
+        }
+        var keyError: Unmanaged<CFError>?
+        let attrs: [CFString: Any] = [
+            kSecAttrKeyType: kSecAttrKeyTypeECSECPrimeRandom,
+            kSecAttrKeyClass: kSecAttrKeyClassPrivate,
+            kSecAttrKeySizeInBits: 256,
+        ]
+        guard let secKey = SecKeyCreateWithData(
+            priv.x963Representation as CFData, attrs as CFDictionary, &keyError)
+        else {
+            throw TLSError.badKey((keyError?.takeRetainedValue()).map { "\($0)" } ?? "SecKeyCreateWithData")
+        }
+
+        guard let certDER = derFromPEM(certPEM, type: "CERTIFICATE"),
+              let cert = SecCertificateCreateWithData(nil, certDER as CFData)
+        else { throw TLSError.badCert }
+
+        // The key must live in a Keychain for SecIdentityCreateWithCertificate to pair it with the
+        // cert. Add it under a stable tag; a duplicate just means a previous fetch already did.
+        let tag = Data("io.unom.punktfunk.library-client-key".utf8)
+        let add: [CFString: Any] = [
+            kSecClass: kSecClassKey,
+            kSecAttrApplicationTag: tag,
+            kSecValueRef: secKey,
+        ]
+        let status = SecItemAdd(add as CFDictionary, nil)
+        guard status == errSecSuccess || status == errSecDuplicateItem else {
+            throw TLSError.identity("keychain add failed (OSStatus \(status))")
+        }
+
+        var identity: SecIdentity?
+        let idStatus = SecIdentityCreateWithCertificate(nil, cert, &identity)
+        guard idStatus == errSecSuccess, let identity else {
+            throw TLSError.identity("SecIdentityCreateWithCertificate (OSStatus \(idStatus))")
+        }
+        return identity
+        #else
+        throw TLSError.unsupportedPlatform
+        #endif
+    }
+}
+
+/// URLSession delegate that pins the host's self-signed cert (by the fingerprint the client
+/// already trusts) and presents the client identity for the mTLS client-cert challenge.
+final class LibraryTLSDelegate: NSObject, URLSessionDelegate {
+    private let identity: SecIdentity
+    private let pinnedHostFingerprint: Data? // SHA-256 of the host cert DER; nil = accept any (TOFU)
+
+    init(identity: SecIdentity, pinnedHostFingerprint: Data?) {
+        self.identity = identity
+        self.pinnedHostFingerprint = pinnedHostFingerprint
+    }
+
+    func urlSession(
+        _ session: URLSession,
+        didReceive challenge: URLAuthenticationChallenge,
+        completionHandler: @escaping (URLSession.AuthChallengeDisposition, URLCredential?) -> Void
+    ) {
+        switch challenge.protectionSpace.authenticationMethod {
+        case NSURLAuthenticationMethodServerTrust:
+            // Pin the host cert by fingerprint — the host is self-signed (the client trusts it the
+            // same way the QUIC session does). No pin yet (TOFU) → accept the presented leaf.
+            guard let trust = challenge.protectionSpace.serverTrust,
+                  let leaf = (SecTrustCopyCertificateChain(trust) as? [SecCertificate])?.first
+            else {
+                completionHandler(.cancelAuthenticationChallenge, nil)
+                return
+            }
+            let der = SecCertificateCopyData(leaf) as Data
+            let fp = Data(SHA256.hash(data: der))
+            if let pinned = pinnedHostFingerprint, pinned != fp {
+                tlsLog.warning("library: host cert fingerprint mismatch — refusing")
+                completionHandler(.cancelAuthenticationChallenge, nil)
+                return
+            }
+            completionHandler(.useCredential, URLCredential(trust: trust))
+
+        case NSURLAuthenticationMethodClientCertificate:
+            completionHandler(.useCredential,
+                URLCredential(identity: identity, certificates: nil, persistence: .forSession))
+
+        default:
+            completionHandler(.performDefaultHandling, nil)
+        }
+    }
+}

clients/apple/Sources/PunktfunkKit/DefaultsKeys.swift

@@ -20,4 +20,16 @@ public enum DefaultsKey {
     public static let micUID = "punktfunk.micUID"
     public static let presenter = "punktfunk.presenter"
     public static let hosts = "punktfunk.hosts"
+    /// Client-side cursor mode: "auto" (shown only in gamescope sessions), "always", "never".
+    public static let cursorMode = "punktfunk.cursorMode"
+    /// Experimental: show the host's game library (browsed over the management API). Off by default.
+    public static let libraryEnabled = "punktfunk.libraryEnabled"
+    /// macOS: take the window fullscreen while streaming and restore it on the host list. On by default.
+    public static let fullscreenWhileStreaming = "punktfunk.fullscreenWhileStreaming"
+    /// Show the streaming statistics overlay (mode/fps/throughput/latency). On by default; toggle
+    /// while streaming with ⌘⇧S (macOS / hardware keyboard).
+    public static let hudEnabled = "punktfunk.hudEnabled"
+    /// Which corner the statistics overlay sits in — a `HUDPlacement` raw value
+    /// ("topLeading"/"topTrailing"/"bottomLeading"/"bottomTrailing"). Default top-trailing.
+    public static let hudPlacement = "punktfunk.hudPlacement"
 }

clients/apple/Sources/PunktfunkKit/GamepadCapture.swift

@@ -169,6 +169,18 @@ public final class GamepadCapture {
         ext.valueChangedHandler = { [weak self] g, _ in
             MainActor.assumeIsolated { self?.sync(g) }
         }
+        // The Home/PS button (→ guide; the host maps it to the DualSense PS / Xbox guide bit). On
+        // macOS the SYSTEM grabs it by default (opens Launchpad's Games folder), so it never reached
+        // the app — `preferredSystemGestureState = .disabled` on the element is what hands it to us.
+        // We drive `guide` DIRECTLY from this handler's pressed value (not via buttonMask), because
+        // the legacy `extendedGamepad.buttonHome` is unreliable/often nil even when the physical
+        // element exists. On tvOS the element is absent (reserved) → nil, the whole block no-ops.
+        if let home = c.physicalInputProfile.buttons[GCInputButtonHome] {
+            home.preferredSystemGestureState = .disabled
+            home.pressedChangedHandler = { [weak self] _, _, pressed in
+                MainActor.assumeIsolated { self?.sendGuide(down: pressed) }
+            }
+        }
         // Wake the host pad immediately (pads are created lazily from the first event;
         // a DualSense's UHID handshake + initial lightbar write only start then).
         connection.send(.gamepadAxis(GamepadWire.axisLSX, value: 0, pad: 0))
@@ -215,6 +227,18 @@ public final class GamepadCapture {
         }
     }
 
+    /// Forward the guide (Home/PS) transition directly — it's kept out of `buttonMask` (the legacy
+    /// `buttonHome` element is unreliable). Folds into `buttons` so a held PS button is released by
+    /// `releaseAll` on focus loss just like the others.
+    private func sendGuide(down: Bool) {
+        guard !suspended else { return }
+        let bit = GamepadWire.guide
+        let now = down ? (buttons | bit) : (buttons & ~bit)
+        guard now != buttons else { return }
+        connection.send(.gamepadButton(bit, down: down, pad: 0))
+        buttons = now
+    }
+
     private static func buttonMask(_ g: GCExtendedGamepad) -> UInt32 {
         var b: UInt32 = 0
         if g.dpad.up.isPressed { b |= GamepadWire.dpadUp }
@@ -227,7 +251,8 @@ public final class GamepadCapture {
         if g.rightThumbstickButton?.isPressed == true { b |= GamepadWire.rightStickClick }
         if g.leftShoulder.isPressed { b |= GamepadWire.leftShoulder }
         if g.rightShoulder.isPressed { b |= GamepadWire.rightShoulder }
-        if g.buttonHome?.isPressed == true { b |= GamepadWire.guide }
+        // guide (Home/PS) is NOT read here — it's forwarded directly by the Home button's
+        // pressedChangedHandler (the legacy `buttonHome` element is unreliable). See `rebind`.
         if g.buttonA.isPressed { b |= GamepadWire.a }
         if g.buttonB.isPressed { b |= GamepadWire.b }
         if g.buttonX.isPressed { b |= GamepadWire.x }

clients/apple/Sources/PunktfunkKit/GamepadFeedback.swift

@@ -173,7 +173,10 @@ public final class GamepadFeedback {
 
     public init(connection: PunktfunkConnection, manager: GamepadManager) {
         self.connection = connection
-        Task { @MainActor in
+        // Capture self weakly in the hop too, so the inner sink's weak capture isn't shadowing
+        // an implicit strong one — and the subscription (stored on self) never retain-cycles.
+        Task { @MainActor [weak self] in
+            guard let self else { return }
             self.activeSub = manager.$active.sink { [weak self] dc in
                 MainActor.assumeIsolated { self?.retarget(dc?.controller) }
             }

clients/apple/Sources/PunktfunkKit/GamepadManager.swift

@@ -107,6 +107,11 @@ public final class GamepadManager: ObservableObject {
         setting: PunktfunkConnection.GamepadType
     ) -> PunktfunkConnection.GamepadType {
         guard setting == .auto else { return setting }
+        // Refresh from the LIVE controller list first. `active` is otherwise only populated by the
+        // async `.GCControllerDidConnect` notification, so at connect time it can still be nil even
+        // with a DualSense attached — which would send `.auto` and the host would create an Xbox 360
+        // pad. `rebuild()` re-reads `GCController.controllers()` synchronously, closing that race.
+        rebuild()
         guard let active else { return .auto }
         return active.isDualSense ? .dualSense : .xbox360
     }

clients/apple/Sources/PunktfunkKit/HostDiscovery.swift

@@ -27,6 +27,10 @@ public struct DiscoveredHost: Identifiable, Sendable, Equatable {
     public let fingerprintHex: String?
     /// The host advertised `pair=required` — a client must pair before it can stream.
     public let requiresPairing: Bool
+    /// The host EXPLICITLY advertised `pair=optional` — only then may the client offer the
+    /// reduced-security TOFU "Trust" path. A missing/unknown `pair` field is NOT optional:
+    /// pairing is mandatory unless this is true (the policy authority is the host's advert).
+    public let allowsTofu: Bool
 }
 
 @MainActor
@@ -124,7 +128,8 @@ public final class HostDiscovery: ObservableObject {
                         self.resolved[key] = DiscoveredHost(
                             id: (id?.isEmpty == false) ? id! : name,
                             name: name, host: address, port: port.rawValue,
-                            fingerprintHex: fp, requiresPairing: pair == "required")
+                            fingerprintHex: fp, requiresPairing: pair == "required",
+                            allowsTofu: pair == "optional")
                         self.publish()
                     }
                     conn.cancel()

clients/apple/Sources/PunktfunkKit/InputCapture.swift

@@ -111,6 +111,12 @@ public final class InputCapture {
     /// event itself is swallowed). Main queue.
     public var onToggleCapture: (() -> Void)?
 
+    /// Fired on ⌘⇧C (the client-side-cursor toggle — flips between the captured/disassociated
+    /// relative path and the visible-cursor absolute path; detected here, like ⌘⎋, so it works
+    /// regardless of the current capture state and the event itself is swallowed). macOS only;
+    /// the absolute-vs-relative forwarding lives entirely in StreamLayerView. Main queue.
+    public var onToggleCursor: (() -> Void)?
+
     /// Fired when a newer InputCapture takes the process-global GC handler slots (the
     /// singletons hold ONE handler each): the preempted owner must drop its capture
     /// state — its handlers are gone, so it would otherwise sit "captured" with dead
@@ -203,6 +209,15 @@ public final class InputCapture {
                 self.onToggleCapture?()
                 return nil
             }
+            // ⌘⇧C toggles the client-side cursor (visible-cursor absolute path vs the
+            // captured relative path). keyCode 8 = kVK_ANSI_C; layout-independent so it
+            // fires the same on any keyboard. Suppress the C (latched like ⌘⎋'s Esc) so it
+            // doesn't type into the host, and swallow the event so it doesn't beep.
+            if event.keyCode == 8 /* C */, flags == [.command, .shift] {
+                self.suppressedVK = 0x43 // VK_C — the same physical C is en route via GC
+                self.onToggleCursor?()
+                return nil
+            }
             return event
         }
         #endif

clients/apple/Sources/PunktfunkKit/LibraryClient.swift

@@ -0,0 +1,116 @@
+// Game library client (experimental, plan step 3). Fetches the host's unified game library
+// from the management REST API (`GET /api/v1/library`) — the same payload the web console's
+// /library page renders. Read-only on the client for now; launching a chosen title is a later
+// step. Gated behind `DefaultsKey.libraryEnabled` in the UI.
+//
+// The management API is HTTP on a port distinct from the punktfunk/1 data plane (default 47990),
+// binds loopback unless started with a token, and REQUIRES a bearer token for any non-loopback
+// bind. So to browse a host's library remotely the host must expose the mgmt API on the LAN with
+// `--mgmt-token`; the client carries that token per host. This mirrors the GameEntry/Artwork/
+// LaunchSpec schema in `crates/punktfunk-host/src/library.rs`.
+
+import Foundation
+
+/// Cover art URLs (the public Steam CDN for Steam titles, user-supplied for custom entries).
+public struct Artwork: Codable, Hashable, Sendable {
+    public var portrait: String?
+    public var hero: String?
+    public var logo: String?
+    public var header: String?
+
+    /// Preferred order for a poster grid: the 600×900 capsule, falling back to the header
+    /// (which is near-universal — many older titles lack a portrait capsule).
+    public var posterCandidates: [URL] {
+        [portrait, header, hero].compactMap { $0 }.compactMap { URL(string: $0) }
+    }
+}
+
+/// How the host would launch a title (carried for a later step; the client only displays it).
+public struct LaunchSpec: Codable, Hashable, Sendable {
+    public var kind: String // "steam_appid" | "command"
+    public var value: String
+}
+
+/// One title in the unified library. `id` is store-qualified: `steam:<appid>` / `custom:<id>`.
+public struct GameEntry: Codable, Hashable, Identifiable, Sendable {
+    public var id: String
+    public var store: String // "steam" | "custom"
+    public var title: String
+    public var art: Artwork
+    public var launch: LaunchSpec?
+
+    public var isCustom: Bool { store == "custom" }
+}
+
+/// Errors surfaced to the UI so it can guide setup (the common case is "not paired yet").
+public enum LibraryError: LocalizedError {
+    case unauthorized
+    case http(Int)
+    case unreachable(String)
+
+    public var errorDescription: String? {
+        switch self {
+        case .unauthorized:
+            return "The host didn't recognize this device. Pair with the host first — it "
+                + "authorizes paired clients by their certificate (no token needed)."
+        case .http(let code):
+            return "The management API returned HTTP \(code)."
+        case .unreachable(let why):
+            return "Couldn't reach the host's management API: \(why). The host must expose it on "
+                + "the LAN (serve --mgmt-bind 0.0.0.0)."
+        }
+    }
+}
+
+/// The management API's default port — adjacent to the GameStream block; matches
+/// `mgmt::DEFAULT_PORT` on the host.
+public let punktfunkDefaultMgmtPort: UInt16 = 47990
+
+/// Stateless fetcher for a host's library.
+public enum LibraryClient {
+    /// `GET https://<address>:<port>/api/v1/library`, authenticated by **mTLS**: the client
+    /// presents `identity` (its persistent cert/key PEM — the same identity the host paired over
+    /// QUIC), and the host's self-signed cert is pinned by `hostFingerprint` (SHA-256 of its DER,
+    /// the value the client already trusts). No bearer token — a paired client is authorized by
+    /// its certificate. `hostFingerprint == nil` ⇒ TOFU (accept the presented host cert).
+    public static func fetch(
+        address: String,
+        port: UInt16 = punktfunkDefaultMgmtPort,
+        certPEM: String,
+        keyPEM: String,
+        hostFingerprint: Data?
+    ) async throws -> [GameEntry] {
+        guard let url = URL(string: "https://\(address):\(port)/api/v1/library") else {
+            throw LibraryError.unreachable("invalid host address")
+        }
+        let identity: SecIdentity
+        do {
+            identity = try ClientTLS.makeIdentity(certPEM: certPEM, keyPEM: keyPEM)
+        } catch {
+            throw LibraryError.unreachable(
+                (error as? LocalizedError)?.errorDescription ?? error.localizedDescription)
+        }
+        let delegate = LibraryTLSDelegate(identity: identity, pinnedHostFingerprint: hostFingerprint)
+        let session = URLSession(configuration: .ephemeral, delegate: delegate, delegateQueue: nil)
+        defer { session.finishTasksAndInvalidate() }
+
+        let req = URLRequest(url: url, timeoutInterval: 10)
+        let (data, response): (Data, URLResponse)
+        do {
+            (data, response) = try await session.data(for: req)
+        } catch {
+            throw LibraryError.unreachable(error.localizedDescription)
+        }
+        guard let http = response as? HTTPURLResponse else {
+            throw LibraryError.unreachable("not an HTTP response")
+        }
+        switch http.statusCode {
+        case 200:
+            return try JSONDecoder().decode([GameEntry].self, from: data)
+        case 401:
+            throw LibraryError.unauthorized
+        default:
+            throw LibraryError.http(http.statusCode)
+        }
+    }
+}

clients/apple/Sources/PunktfunkKit/MetalVideoPresenter.swift

@@ -7,6 +7,7 @@
 // (which fires on the main runloop). The Metal objects + texture cache are touched only here.
 
 #if canImport(Metal) && canImport(QuartzCore)
+import CoreGraphics
 import CoreVideo
 import Metal
 import QuartzCore
@@ -44,6 +45,27 @@ fragment float4 pf_frag(VOut in [[stage_in]],
     float b = y + 1.8556 * u;
     return float4(saturate(float3(r, g, b)), 1.0);
 }
+
+// HDR: 10-bit P010 (BT.2020, limited range), Y'CbCr that is PQ-encoded. We apply the BT.2020
+// matrix to get PQ-encoded R'G'B' and output it as-is — the CAMetalLayer's itur_2100_PQ colour
+// space + EDR tells the compositor the samples are PQ, so it does the PQ→display mapping. No EOTF
+// here (matching the host, which emitted BT.2020 PQ). P010 stores the 10-bit code in the high bits
+// of each 16-bit sample, so an .r16Unorm sample reads ~code/1023 (the /1024 vs /1023 error is < 0.1%).
+fragment float4 pf_frag_hdr(VOut in [[stage_in]],
+                            texture2d<float> lumaTex [[texture(0)]],
+                            texture2d<float> chromaTex [[texture(1)]]) {
+    constexpr sampler s(filter::linear, address::clamp_to_edge);
+    float y = lumaTex.sample(s, in.uv).r;
+    float2 c = chromaTex.sample(s, in.uv).rg;
+    // BT.2020 10-bit limited (video) range → full-range PQ R'G'B'.
+    y = (y - 64.0/1023.0) * (1023.0/876.0);
+    float u = (c.x - 512.0/1023.0) * (1023.0/896.0);
+    float v = (c.y - 512.0/1023.0) * (1023.0/896.0);
+    float r = y + 1.4746 * v;
+    float g = y - 0.16455 * u - 0.57135 * v;
+    float b = y + 1.8814 * u;
+    return float4(saturate(float3(r, g, b)), 1.0);
+}
 """
 
 public final class MetalVideoPresenter {
@@ -52,8 +74,13 @@ public final class MetalVideoPresenter {
 
     private let device: MTLDevice
     private let queue: MTLCommandQueue
-    private let pipeline: MTLRenderPipelineState
+    /// SDR (BT.709 8-bit NV12 → bgra8) and HDR (BT.2020 PQ 10-bit P010 → rgba16Float) pipelines.
+    /// Selected per frame by `render`; the layer is reconfigured when the mode flips (HDR toggle).
+    private let pipelineSDR: MTLRenderPipelineState
+    private let pipelineHDR: MTLRenderPipelineState
     private var textureCache: CVMetalTextureCache?
+    /// Current layer configuration — switched lazily in `configure(hdr:)` when a frame's mode differs.
+    private var hdrActive = false
 
     /// nil if Metal is unavailable (no GPU / a headless CI) — the caller falls back to stage-1.
     public init?() {
@@ -64,11 +91,17 @@ public final class MetalVideoPresenter {
         self.queue = queue
         do {
             let library = try device.makeLibrary(source: shaderSource, options: nil)
-            let desc = MTLRenderPipelineDescriptor()
+            let vtx = library.makeFunction(name: "pf_vtx")
-            desc.vertexFunction = library.makeFunction(name: "pf_vtx")
+            let sdr = MTLRenderPipelineDescriptor()
-            desc.fragmentFunction = library.makeFunction(name: "pf_frag")
+            sdr.vertexFunction = vtx
-            desc.colorAttachments[0].pixelFormat = .bgra8Unorm
+            sdr.fragmentFunction = library.makeFunction(name: "pf_frag")
-            pipeline = try device.makeRenderPipelineState(descriptor: desc)
+            sdr.colorAttachments[0].pixelFormat = .bgra8Unorm
+            pipelineSDR = try device.makeRenderPipelineState(descriptor: sdr)
+            let hdr = MTLRenderPipelineDescriptor()
+            hdr.vertexFunction = vtx
+            hdr.fragmentFunction = library.makeFunction(name: "pf_frag_hdr")
+            hdr.colorAttachments[0].pixelFormat = .rgba16Float // EDR-capable
+            pipelineHDR = try device.makeRenderPipelineState(descriptor: hdr)
         } catch {
             return nil
         }
@@ -102,14 +135,40 @@ public final class MetalVideoPresenter {
         if layer.drawableSize != size { layer.drawableSize = size }
     }
 
-    /// Draw one decoded frame to the next drawable and present it. Returns true on success;
+    /// Reconfigure the layer for SDR or HDR when the stream mode flips (HDR toggle). HDR uses an
+    /// rgba16Float drawable + a BT.2020 PQ colour space + EDR, so the compositor PQ-maps to the
+    /// display; SDR uses the plain 8-bit sRGB path. Main-thread only (called from `render`).
+    private func configure(hdr: Bool) {
+        guard hdr != hdrActive else { return }
+        hdrActive = hdr
+        if hdr {
+            layer.pixelFormat = .rgba16Float
+            layer.colorspace = CGColorSpace(name: CGColorSpace.itur_2100_PQ)
+            #if os(macOS)
+            layer.wantsExtendedDynamicRangeContent = true
+            #endif
+        } else {
+            layer.pixelFormat = .bgra8Unorm
+            layer.colorspace = nil
+            #if os(macOS)
+            layer.wantsExtendedDynamicRangeContent = false
+            #endif
+        }
+    }
+
+    /// Draw one decoded frame to the next drawable and present it. `isHDR` selects the 10-bit
+    /// BT.2020 PQ path (P010 input) vs the 8-bit BT.709 path (NV12 input). Returns true on success;
     /// false when there's no drawable yet, a texture couldn't be made, or Metal errored — the
     /// caller then doesn't stamp a present for this frame.
     @discardableResult
-    public func render(_ pixelBuffer: CVPixelBuffer) -> Bool {
+    public func render(_ pixelBuffer: CVPixelBuffer, isHDR: Bool = false) -> Bool {
+        configure(hdr: isHDR)
+        // P010 stores 10-bit luma/chroma in 16-bit samples → R16/RG16; NV12 is 8-bit → R8/RG8.
+        let lumaFmt: MTLPixelFormat = isHDR ? .r16Unorm : .r8Unorm
+        let chromaFmt: MTLPixelFormat = isHDR ? .rg16Unorm : .rg8Unorm
         guard let textureCache,
-              let luma = makeTexture(pixelBuffer, plane: 0, format: .r8Unorm, cache: textureCache),
+              let luma = makeTexture(pixelBuffer, plane: 0, format: lumaFmt, cache: textureCache),
-              let chroma = makeTexture(pixelBuffer, plane: 1, format: .rg8Unorm, cache: textureCache)
+              let chroma = makeTexture(pixelBuffer, plane: 1, format: chromaFmt, cache: textureCache)
         else { return false }
 
         // The hosting view owns drawableSize (aspect-fit to its bounds); skip until it's laid
@@ -127,7 +186,7 @@ public final class MetalVideoPresenter {
         guard let encoder = commandBuffer.makeRenderCommandEncoder(descriptor: pass) else {
             return false
         }
-        encoder.setRenderPipelineState(pipeline)
+        encoder.setRenderPipelineState(isHDR ? pipelineHDR : pipelineSDR)
         encoder.setFragmentTexture(CVMetalTextureGetTexture(luma), index: 0)
         encoder.setFragmentTexture(CVMetalTextureGetTexture(chroma), index: 1)
         encoder.drawPrimitives(type: .triangle, vertexStart: 0, vertexCount: 3)

clients/apple/Sources/PunktfunkKit/PunktfunkConnection.swift

@@ -195,6 +195,13 @@ public final class PunktfunkConnection {
     /// DualSense feedback.
     public private(set) var resolvedGamepad: GamepadType = .auto
 
+    /// The compositor the host actually resolved for this session's virtual output (the
+    /// Welcome's echo of the requested `compositor`, with `.auto` resolved to a concrete
+    /// backend). `.auto` = an older host that didn't say. Clients use it to decide
+    /// client-side cursor behavior: `.gamescope`'s PipeWire capture carries no cursor, so
+    /// the client draws its own (a visible system cursor over the stream).
+    public private(set) var resolvedCompositor: Compositor = .auto
+
     /// Host clock minus client clock (nanoseconds), from the connect-time wall-clock skew handshake
     /// (`punktfunk_connection_clock_offset_ns`). Add it to a local `CLOCK_REALTIME` instant to
     /// express that instant in the host's capture clock — the clock each `AccessUnit.ptsNs` is
@@ -235,29 +242,34 @@ public final class PunktfunkConnection {
         compositor: Compositor = .auto,
         gamepad: GamepadType = .auto,
         bitrateKbps: UInt32 = 0,
+        launchID: String? = nil,
         timeoutMs: UInt32 = 10_000
     ) throws {
         if let pin = pinSHA256, pin.count != 32 { throw PunktfunkClientError.invalidPin }
         var observed = [UInt8](repeating: 0, count: 32)
+        // `launchID` (a host library id like "steam:570") asks the host to launch that title in
+        // the session; the host resolves it against its own library — nil = the host's default.
         handle = host.withCString { cs in
             withOptionalCString(identity?.certPEM) { cert in
                 withOptionalCString(identity?.keyPEM) { key in
+                    withOptionalCString(launchID) { launch in
                         if let pin = pinSHA256 {
                             return pin.withUnsafeBytes { p in
-                            punktfunk_connect_ex3(
+                                punktfunk_connect_ex4(
                                     cs, port, width, height, refreshHz, compositor.rawValue,
-                                gamepad.rawValue, bitrateKbps,
+                                    gamepad.rawValue, bitrateKbps, launch,
                                     p.bindMemory(to: UInt8.self).baseAddress, &observed,
                                     cert, key, timeoutMs)
                             }
                         }
-                    return punktfunk_connect_ex3(
+                        return punktfunk_connect_ex4(
                             cs, port, width, height, refreshHz, compositor.rawValue,
-                        gamepad.rawValue, bitrateKbps,
+                            gamepad.rawValue, bitrateKbps, launch,
                             nil, &observed, cert, key, timeoutMs)
                     }
                 }
             }
+        }
         guard handle != nil else { throw PunktfunkClientError.connectFailed }
         hostFingerprint = Data(observed)
         var w: UInt32 = 0, h: UInt32 = 0, hz: UInt32 = 0
@@ -268,6 +280,9 @@ public final class PunktfunkConnection {
         var gp: UInt32 = 0
         _ = punktfunk_connection_gamepad(handle, &gp)
         resolvedGamepad = GamepadType(rawValue: gp) ?? .auto
+        var comp: UInt32 = 0
+        _ = punktfunk_connection_compositor(handle, &comp)
+        resolvedCompositor = Compositor(rawValue: comp) ?? .auto
         var offset: Int64 = 0
         _ = punktfunk_connection_clock_offset_ns(handle, &offset)
         clockOffsetNs = offset

clients/apple/Sources/PunktfunkKit/Stage2Pipeline.swift

@@ -144,7 +144,7 @@ public final class Stage2Pipeline {
     /// converted to `CLOCK_REALTIME` (see `realtimeNs(forDisplayLinkTimestamp:)`).
     public func renderTick(targetPresentNs: Int64) {
         guard let frame = ring.take() else { return }
-        guard presenter.render(frame.pixelBuffer) else { return }
+        guard presenter.render(frame.pixelBuffer, isHDR: frame.isHDR) else { return }
         presentMeter.record(ptsNs: frame.ptsNs, atNs: targetPresentNs, offsetNs: offsetNs)
     }
 

clients/apple/Sources/PunktfunkKit/StreamPump.swift

@@ -37,6 +37,10 @@ final class StreamPump {
         onSessionEnd: (@Sendable () -> Void)?
     ) {
         let token = token
+        // The layer is non-Sendable but its enqueue/flush are documented thread-safe, and after
+        // this point only the pump thread drives it — assert that so the @Sendable Thread closure
+        // may capture it.
+        nonisolated(unsafe) let layer = layer
         layer.flush() // drop any frames a previous connection left queued
 
         let thread = Thread {

clients/apple/Sources/PunktfunkKit/StreamView.swift

@@ -35,15 +35,26 @@ private let streamInputDebug =
 /// (`CGAssociateMouseAndMouseCursorPosition(false)` — under which NSEvent mouseMoved/
 /// dragged deltas become the relative motion StreamLayerView forwards), and hide it.
 /// hide/unhide and associate are balanced via `captured`.
+///
+/// In CLIENT-SIDE-CURSOR mode (gamescope, whose capture carries no host cursor) this is a
+/// no-op: the local cursor stays visible and free, and StreamLayerView forwards ABSOLUTE
+/// positions instead — the visible system cursor IS the on-screen cursor. `disassociate`
+/// selects between the two; `release()` only undoes what `capture` actually did.
 private final class CursorCapture {
     private var captured = false
+    /// Whether the engaged capture actually disassociated+hid (false in cursor-visible mode),
+    /// so `release()` only restores when it must.
+    private var disassociated = false
 
     /// Returns whether capture actually engaged. It can fail mid app-activation — the click
     /// that reactivates the app delivers `mouseDown` before the app is frontmost, and
     /// `CGAssociateMouseAndMouseCursorPosition` is refused then — so the caller must stay
-    /// released and let the NEXT click retry, never latching a half-captured state.
+    /// released and let the NEXT click retry, never latching a half-captured state. With
-    func capture(in view: NSView) -> Bool {
+    /// `disassociate: false` (cursor-visible mode) it always engages — there is no grab to
+    /// be refused, the cursor stays free and visible.
+    func capture(in view: NSView, disassociate: Bool) -> Bool {
         guard !captured, let window = view.window, view.bounds.width > 0 else { return false }
+        if disassociate {
             // Park the cursor mid-view so a click can't land in (and activate) another app.
             let rectOnScreen = window.convertToScreen(view.convert(view.bounds, to: nil))
             let primaryHeight = NSScreen.screens.first?.frame.height ?? 0
@@ -51,15 +62,20 @@ private final class CursorCapture {
                 CGPoint(x: rectOnScreen.midX, y: primaryHeight - rectOnScreen.midY))
             guard CGAssociateMouseAndMouseCursorPosition(0) == .success else { return false }
             NSCursor.hide()
+        }
         captured = true
+        disassociated = disassociate
         return true
     }
 
     func release() {
         guard captured else { return }
+        if disassociated {
             CGAssociateMouseAndMouseCursorPosition(1)
             NSCursor.unhide()
+        }
         captured = false
+        disassociated = false
     }
 }
 
@@ -136,10 +152,22 @@ public final class StreamLayerView: NSView {
     /// captured (GCMouse's own delivery proved unreliable on macOS — see InputCapture).
     /// Installed on engage, removed on release; nil while not captured.
     private var mouseEventMonitor: Any?
+    /// The window's `acceptsMouseMovedEvents` value before client-side-cursor capture raised
+    /// it (nil = not raised by us); restored on release so we leave the window as we found it.
+    private var savedAcceptsMouseMoved: Bool?
 
     /// Whether input capture is currently engaged (cursor hidden+frozen, mouse/keyboard
     /// forwarded). Main-thread only.
     public private(set) var captured = false
+
+    /// Client-side-cursor mode: when true the local system cursor stays VISIBLE over the
+    /// stream and the mouse monitor forwards ABSOLUTE positions (the visible cursor is the
+    /// on-screen cursor — gamescope draws none, so no double cursor); when false the existing
+    /// captured/disassociated relative path runs unchanged. Initialized at session start from
+    /// the `cursorMode` setting + the host's resolved compositor, toggled live by ⌘⇧C. A live
+    /// flip re-engages capture in the new mode so disassociation + the abs/rel choice swap
+    /// atomically. Main-thread only.
+    private var cursorVisible = false
     /// One-shot auto-engage request (stream start, trust confirmed) — attempted as soon
     /// as the view is in a window with real bounds, then dropped, so it can never fire
     /// surprisingly later (e.g. on a resize).
@@ -333,7 +361,9 @@ public final class StreamLayerView: NSView {
         // If the cursor grab is refused (e.g. the reactivating click arrives before the app is
         // frontmost), stay released so the NEXT click retries — never latch captured=true over
         // a free cursor, which would make mouseDown's `!captured` guard reject every later click.
-        guard cursorCapture.capture(in: self) else { return }
+        // In client-side-cursor mode there is no grab (the cursor stays visible) — capture
+        // always engages and the monitor forwards absolute positions instead.
+        guard cursorCapture.capture(in: self, disassociate: !cursorVisible) else { return }
         inputCapture?.setForwarding(true, suppressClick: fromClick)
         // Install AFTER the warp + setForwarding: the engage warp generates no forwarded
         // delta (the monitor isn't up yet), and the engage click's suppression latch is
@@ -363,8 +393,16 @@ public final class StreamLayerView: NSView {
     /// host re-accelerates there's mild double-acceleration, acceptable and fixable later
     /// via IOHID. Events are returned (not swallowed): the cursor is frozen, so they're
     /// inert locally.
+    ///
+    /// In client-side-cursor mode the cursor is NOT frozen, so bare `.mouseMoved` events are
+    /// only generated while `window.acceptsMouseMovedEvents` is true — we enable it here and
+    /// restore it on removal so absolute hover-motion keeps flowing without a click held.
     private func installMouseMonitor() {
         guard mouseEventMonitor == nil else { return }
+        if cursorVisible {
+            savedAcceptsMouseMoved = window?.acceptsMouseMovedEvents
+            window?.acceptsMouseMovedEvents = true
+        }
         mouseEventMonitor = NSEvent.addLocalMonitorForEvents(matching: [
             .mouseMoved, .leftMouseDragged, .rightMouseDragged, .otherMouseDragged,
             .leftMouseDown, .leftMouseUp, .rightMouseDown, .rightMouseUp,
@@ -373,7 +411,16 @@ public final class StreamLayerView: NSView {
             guard let self, self.captured, let ic = self.inputCapture else { return event }
             switch event.type {
             case .mouseMoved, .leftMouseDragged, .rightMouseDragged, .otherMouseDragged:
+                if self.cursorVisible {
+                    // Client-side cursor: forward the ABSOLUTE position (mapped through the
+                    // aspect-fit letterbox into host pixels), the same path the iPad pointer
+                    // fallback uses. Events in the letterbox bars are dropped (nil host point).
+                    if let p = self.hostPoint(from: event) {
+                        ic.sendMouseAbs(x: p.x, y: p.y, surfaceWidth: p.w, surfaceHeight: p.h)
+                    }
+                } else {
                     ic.sendMotion(dx: Float(event.deltaX), dy: Float(event.deltaY)) // no y-negation
+                }
             case .leftMouseDown: ic.sendMouseButton(1, pressed: true)
             case .leftMouseUp: ic.sendMouseButton(1, pressed: false)
             case .rightMouseDown: ic.sendMouseButton(3, pressed: true)
@@ -393,6 +440,43 @@ public final class StreamLayerView: NSView {
             mouseEventMonitor = nil
             if streamInputDebug { streamInputLog.debug("mouse NSEvent monitor removed (capture released)") }
         }
+        // Restore the window's prior mouse-moved-events setting if we raised it (cursor mode).
+        if let saved = savedAcceptsMouseMoved {
+            window?.acceptsMouseMovedEvents = saved
+            savedAcceptsMouseMoved = nil
+        }
+    }
+
+    /// One host-pixel point on the negotiated output, with the surface dimensions the host
+    /// rescales against (surface == host mode, so the host applies no extra scaling).
+    private struct HostPoint { let x: Int32; let y: Int32; let w: UInt32; let h: UInt32 }
+
+    /// Map an NSEvent's cursor location into host-mode pixels for the client-side-cursor
+    /// (absolute) path. NSEvent.locationInWindow is window space, origin BOTTOM-left (+y up);
+    /// we convert to this view's space, FLIP y to the host's top-left (+y down) convention,
+    /// then aspect-fit-letterbox into the host mode exactly like the iOS touch/pointer path.
+    /// Returns nil for events in the letterbox bars (outside the video rect) so the host's
+    /// cursor isn't dragged onto a black edge, and until a mode is negotiated.
+    private func hostPoint(from event: NSEvent) -> HostPoint? {
+        guard let connection else { return nil }
+        let mode = connection.currentMode()
+        guard mode.width > 0, mode.height > 0 else { return nil }
+        // Window → view coords (non-flipped: origin bottom-left), then flip y into view-top-left.
+        let inView = convert(event.locationInWindow, from: nil)
+        let p = CGPoint(x: inView.x, y: bounds.height - inView.y)
+        // The video occupies the aspect-fit rect inside the (non-flipped) bounds; AVMakeRect's
+        // origin is bottom-left, so flip its minY too to match p's top-left space.
+        let fit = AVMakeRect(
+            aspectRatio: CGSize(width: Int(mode.width), height: Int(mode.height)),
+            insideRect: bounds)
+        guard fit.width > 0, fit.height > 0 else { return nil }
+        let videoMinYTop = bounds.height - fit.maxY
+        let u = (p.x - fit.minX) / fit.width
+        let v = (p.y - videoMinYTop) / fit.height
+        guard u >= 0, u <= 1, v >= 0, v <= 1 else { return nil } // letterbox bars
+        let hx = Int32((u * CGFloat(mode.width)).rounded().clamped(0, CGFloat(mode.width - 1)))
+        let hy = Int32((v * CGFloat(mode.height)).rounded().clamped(0, CGFloat(mode.height - 1)))
+        return HostPoint(x: hx, y: hy, w: mode.width, h: mode.height)
     }
 
     /// NSEvent `buttonNumber` → GameStream wire id for the "other" buttons: 2 = middle,
@@ -444,9 +528,27 @@ public final class StreamLayerView: NSView {
             // be a cursor trap with dead input.
             self?.releaseCapture()
         }
+        // ⌘⇧C flips the client-side cursor live. Only the key window's stream owns it (same
+        // guard as the ⌘⎋ capture toggle). Re-engage capture in the new mode so disassociation
+        // and the absolute/relative forwarding choice swap atomically — releaseCapture restores
+        // the old mode's grab (if any), engageCapture installs the new one.
+        // ⌘⇧C would flip the client-side cursor live — NEUTERED while the feature is disabled
+        // (see the cursorVisible resolution below): toggling it on under gamescope's relative-only
+        // input traps the pointer. Restore this body when absolute/synthetic-cursor support lands.
+        capture.onToggleCursor = {}
         capture.start()
         inputCapture = capture
 
+        // Client-side cursor is TEMPORARILY DISABLED. It positions the host cursor with ABSOLUTE
+        // events, but gamescope's input socket (EIS) grants only a relative pointer, so those are
+        // silently dropped — the pointer never moves and clicks/scroll land on the stuck position
+        // (looks like "all input dead"). gamescope is exactly the compositor Auto enabled it for.
+        // Forced off until per-compositor gating (KWin/GNOME/Sway have absolute) or a synthetic-
+        // cursor-over-relative path lands; the resolution logic below is kept for that. See the
+        // ⌘⇧C handler (also neutered) and the cursorMode setting (hidden).
+        cursorVisible = false
+        _ = connection.resolvedCompositor // (was: Auto → gamescope; kept to document intent)
+
         // Presenter choice — default stage-1 (the known-good AVSampleBufferDisplayLayer). Stage-2
         // (`punktfunk.presenter == "stage2"`) takes explicit VTDecompressionSession decode + a
         // CAMetalLayer/display-link present; it falls back here if Metal can't be set up.
@@ -547,4 +649,12 @@ public final class StreamLayerView: NSView {
         teardownStage2() // invalidate the display link + stop the pipeline if stop() was missed
     }
 }
+
+extension CGFloat {
+    /// Clamp into a [lo, hi] range — keeps the absolute-cursor mapping inside the host's
+    /// pixel bounds even if a stray event reports a point a hair past the video rect.
+    fileprivate func clamped(_ lo: CGFloat, _ hi: CGFloat) -> CGFloat {
+        Swift.min(Swift.max(self, lo), hi)
+    }
+}
 #endif

clients/apple/Sources/PunktfunkKit/VideoDecoder.swift

@@ -17,8 +17,11 @@ public struct ReadyFrame: @unchecked Sendable {
     public let ptsNs: UInt64
     /// Client `CLOCK_REALTIME` instant decode completed, in nanoseconds.
     public let decodedNs: Int64
-    /// The decoded image (NV12 biplanar, Metal-compatible).
+    /// The decoded image — 8-bit NV12 biplanar (SDR) or 10-bit P010 biplanar (HDR), Metal-compatible.
     public let pixelBuffer: CVPixelBuffer
+    /// True when the stream is HDR (BT.2020 PQ): the buffer is 10-bit P010 and the presenter must
+    /// configure EDR + BT.2020 PQ output. Derived from the decoded buffer's pixel format.
+    public let isHDR: Bool
 }
 
 /// The C output callback can't capture context, so VideoToolbox hands it the refcon we set at
@@ -116,8 +119,22 @@ public final class VideoDecoder: @unchecked Sendable {
         format = nil
     }
 
-    /// `lock` held. Replace the session with one for `newFormat`. NV12 video-range, Metal-
+    /// True when `newFormat` carries a PQ (SMPTE ST 2084) or HLG transfer function — i.e. the host
-    /// compatible output (10-bit/HDR is a later tie-in — see the plan).
+    /// is sending HDR (BT.2020). VideoToolbox populates the transfer-function extension from the
+    /// HEVC VUI, so this tracks the *stream*, switching dynamically when the user toggles HDR
+    /// (the host re-emits parameter sets with the new VUI → a new format desc → session rebuild).
+    static func isHDRFormat(_ format: CMVideoFormatDescription) -> Bool {
+        guard
+            let tf = CMFormatDescriptionGetExtension(
+                format, extensionKey: kCMFormatDescriptionExtension_TransferFunction)
+        else { return false }
+        let s = tf as? String
+        return s == (kCMFormatDescriptionTransferFunction_SMPTE_ST_2084_PQ as String)
+            || s == (kCMFormatDescriptionTransferFunction_ITU_R_2100_HLG as String)
+    }
+
+    /// `lock` held. Replace the session with one for `newFormat`. SDR streams decode to 8-bit NV12;
+    /// HDR streams (BT.2020 PQ) decode to 10-bit P010 so the presenter can drive EDR.
     private func createSessionLocked(format newFormat: CMVideoFormatDescription) -> Bool {
         if let session {
             VTDecompressionSessionWaitForAsynchronousFrames(session)
@@ -126,10 +143,14 @@ public final class VideoDecoder: @unchecked Sendable {
         session = nil
         format = nil
 
+        let hdr = Self.isHDRFormat(newFormat)
+        let pixelFormat =
+            hdr
+            ? kCVPixelFormatType_420YpCbCr10BiPlanarVideoRange // P010 (10-bit)
+            : kCVPixelFormatType_420YpCbCr8BiPlanarVideoRange // NV12 (8-bit)
         let imageAttrs: [CFString: Any] = [
             kCVPixelBufferMetalCompatibilityKey: true,
-            kCVPixelBufferPixelFormatTypeKey:
+            kCVPixelBufferPixelFormatTypeKey: pixelFormat,
-                kCVPixelFormatType_420YpCbCr8BiPlanarVideoRange,
         ]
         var callback = VTDecompressionOutputCallbackRecord(
             decompressionOutputCallback: decoderOutputCallback,
@@ -160,6 +181,11 @@ public final class VideoDecoder: @unchecked Sendable {
         // pts was stamped at timescale 1e9 (AnnexB.sampleBuffer); normalize defensively.
         let p = CMTimeConvertScale(pts, timescale: 1_000_000_000, method: .default)
         let ptsNs = p.value > 0 ? UInt64(p.value) : 0
-        onDecoded(ReadyFrame(ptsNs: ptsNs, decodedNs: decodedNs, pixelBuffer: imageBuffer))
+        // HDR iff the decoder produced a 10-bit P010 buffer (we only request P010 for PQ streams).
+        let isHDR =
+            CVPixelBufferGetPixelFormatType(imageBuffer)
+            == kCVPixelFormatType_420YpCbCr10BiPlanarVideoRange
+        onDecoded(
+            ReadyFrame(ptsNs: ptsNs, decodedNs: decodedNs, pixelBuffer: imageBuffer, isHDR: isHDR))
     }
 }

clients/apple/Tests/PunktfunkKitTests/LibraryClientTests.swift

@@ -0,0 +1,63 @@
+// Unit tests for the game-library models — decoding the management API's GET /api/v1/library
+// payload and the poster-art fallback order. (The network fetch itself isn't unit-tested; it's
+// exercised live against a host.)
+
+import XCTest
+@testable import PunktfunkKit
+
+final class LibraryClientTests: XCTestCase {
+    func testDecodesLibraryPayload() throws {
+        // A Steam entry (full art + launch) and a custom entry (sparse art, no launch) — the two
+        // shapes the host's `GameEntry` serializes (note the host omits null fields).
+        let json = """
+        [
+          {
+            "id": "steam:570",
+            "store": "steam",
+            "title": "Dota 2",
+            "art": {
+              "portrait": "https://cdn.cloudflare.steamstatic.com/steam/apps/570/library_600x900.jpg",
+              "hero": "https://cdn.cloudflare.steamstatic.com/steam/apps/570/library_hero.jpg",
+              "logo": "https://cdn.cloudflare.steamstatic.com/steam/apps/570/logo.png",
+              "header": "https://cdn.cloudflare.steamstatic.com/steam/apps/570/header.jpg"
+            },
+            "launch": { "kind": "steam_appid", "value": "570" }
+          },
+          {
+            "id": "custom:abc123",
+            "store": "custom",
+            "title": "Dolphin",
+            "art": { "header": "https://example.com/dolphin.jpg" }
+          }
+        ]
+        """.data(using: .utf8)!
+
+        let games = try JSONDecoder().decode([GameEntry].self, from: json)
+        XCTAssertEqual(games.count, 2)
+
+        let steam = games[0]
+        XCTAssertEqual(steam.id, "steam:570")
+        XCTAssertFalse(steam.isCustom)
+        XCTAssertEqual(steam.launch?.kind, "steam_appid")
+        XCTAssertEqual(steam.launch?.value, "570")
+
+        let custom = games[1]
+        XCTAssertTrue(custom.isCustom)
+        XCTAssertNil(custom.launch)
+        XCTAssertNil(custom.art.portrait)
+    }
+
+    func testPosterCandidatesPreferPortraitThenHeader() {
+        let full = Artwork(
+            portrait: "https://x/p.jpg", hero: "https://x/hero.jpg",
+            logo: "https://x/logo.png", header: "https://x/h.jpg")
+        XCTAssertEqual(full.posterCandidates.map(\.absoluteString),
+                       ["https://x/p.jpg", "https://x/h.jpg", "https://x/hero.jpg"])
+
+        // No portrait → header leads; absent fields are skipped, not nil-padded.
+        let sparse = Artwork(portrait: nil, hero: nil, logo: nil, header: "https://x/h.jpg")
+        XCTAssertEqual(sparse.posterCandidates.map(\.absoluteString), ["https://x/h.jpg"])
+
+        XCTAssertTrue(Artwork().posterCandidates.isEmpty)
+    }
+}

clients/decky/.gitignore

@@ -0,0 +1,30 @@
+# Dependency directory
+node_modules
+.pnpm-store
+
+# Built TS files
+dist/
+
+# Python
+__pycache__/
+*.pyc
+
+# Editors
+.idea
+*.iml
+.vscode/settings.json
+
+# OS metadata
+.DS_Store
+Thumbs.db
+
+# Logs / scratch
+*.log
+tmp
+
+# decky CLI build artifacts
+out
+out/*
+cli/
+.yalc
+yalc.lock

clients/decky/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 unom
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

clients/decky/README.md

@@ -0,0 +1,132 @@
+# punktfunk Decky plugin (SteamOS / Steam Deck)
+
+A **[Decky Loader](https://decky.xyz/)** plugin that adds a **punktfunk** panel to the Steam
+Deck's Quick Access Menu (the QAM, opened with the `…` button), so you can launch the
+punktfunk streaming client from **Gaming Mode** without dropping to the desktop.
+
+Because Decky plugins run inside Steam's CEF, the panel is built from real Steam UI
+primitives (`@decky/ui`: `PanelSection`, `PanelSectionRow`, `ButtonItem`, `Field`,
+`Spinner`) — so it looks and feels native to Gaming Mode.
+
+> **Spike / launcher only.** This is a minimal but functional first cut: discover hosts,
+> connect, disconnect. It launches the existing native GTK4 client
+> (`punktfunk-client`) over the top of Gaming Mode. An in-stream overlay (latency / bitrate
+> HUD, mid-session controls) and a fuller real-Steam-components UI are the next steps.
+> Runtime behavior on a real Deck is **untested** — only the build is verified here.
+
+## What it does
+
+1. **Refresh** — browses the LAN over mDNS for punktfunk/1 hosts (the `_punktfunk._udp`
+   service) via the backend `discover()`.
+2. **Lists discovered hosts** — name, `ip:port`, and a lock icon for whether pairing is
+   required (`pair=required` in the host's TXT record).
+3. **Connect** — selecting a host calls `connect(host, port)`, which launches
+   `punktfunk-client --connect host:port`; a toast and the status line reflect the result.
+4. **Disconnect** — `disconnect()` terminates the launched client.
+
+## Architecture
+
+| File | Role |
+| --- | --- |
+| `src/index.tsx` | Frontend QAM panel (`@decky/ui` + `@decky/api`). |
+| `main.py` | Backend `Plugin` class: `discover` / `connect` / `disconnect` / `status` exposed over the Decky bridge. |
+| `plugin.json` | Decky plugin manifest. |
+| `decky.pyi` | Type stub for the injected `decky` module (vendored from the template). |
+
+### Discovery (`discover()`)
+
+Shells out to **`avahi-browse -rpt _punktfunk._udp`** (SteamOS and Bazzite ship
+`avahi-daemon`; this avoids bundling python-zeroconf):
+
+- `-r` resolve services, `-p` parseable output, `-t` terminate after the cache dump.
+- Resolved records start with `=` and are semicolon-separated:
+  `=;iface;protocol;name;type;domain;hostname;address;port;txt`.
+- The `txt` column is space-separated, quoted `"key=value"` tokens. We read the keys the
+  host advertises (`crates/punktfunk-host/src/discovery.rs`): `proto`, `fp`, `pair`, `id`.
+- Records are deduped on the `id` TXT key (a host re-advertises per interface and across
+  IPv4/IPv6), preferring the IPv4 address for the user-facing host string.
+
+### Client launch (`connect()`)
+
+The client binary `punktfunk-client` is resolved in order: `PATH` → `/usr/bin` →
+`/usr/local/bin` → `~/.local/bin` → a `flatpak run io.unom.Punktfunk` fallback. The resolved
+argv and a clear `client-not-found` error surface to the UI. The child PID is tracked so
+`disconnect()` (and plugin `_unload`) can terminate it.
+
+> On the **Steam Deck** the client install is the flatpak `io.unom.Punktfunk`
+> (`packaging/flatpak/`) — SteamOS `/usr` is read-only and lacks `libadwaita`/`libSDL3`, so
+> the flatpak (which bundles them) is the canonical path; the resolver's flatpak fallback
+> launches exactly that.
+
+## Prerequisites
+
+- **Decky Loader** installed on the Deck (https://decky.xyz/).
+- **`punktfunk-client`** (the GTK4/libadwaita Linux client, crate `punktfunk-client-linux`)
+  installed and runnable on the Deck — via `.deb`/RPM/flatpak, or symlinked into
+  `~/.local/bin`.
+- **avahi** (`avahi-daemon` + `avahi-browse`) for discovery — present on SteamOS/Bazzite.
+- A punktfunk/1 host on the LAN (`punktfunk-host serve --native` or `m3-host`).
+
+## Build
+
+```sh
+pnpm install
+pnpm build      # rollup → dist/index.js
+```
+
+(`npm install && npm run build` also works.)
+
+## Install on the Deck
+
+### Option A — Decky "install from URL" (recommended; published by CI)
+
+CI (`.gitea/workflows/decky.yml`) builds the plugin into a store-layout zip and publishes it to
+Gitea's **generic package registry** on every push to `main` and on `v*` tags, exposing a stable
+URL. In Decky's settings → **Developer Mode** → **Install Plugin from URL**, paste:
+
+```
+https://git.unom.io/api/packages/unom/generic/punktfunk-decky/latest/punktfunk.zip
+```
+
+(or a pinned version: `.../punktfunk-decky/<version>/punktfunk.zip`). On tags the same zip is
+also attached to the Gitea release. The zip's layout is the store-required one — a single
+top-level `punktfunk/` dir holding `plugin.json`, `package.json`, `main.py`, `dist/index.js`,
+`README.md`, and `LICENSE`.
+
+### Option B — manual dev copy (sideload)
+
+Decky's `~/homebrew/plugins/` is **root-owned** (PluginLoader runs as root and manages it), so a
+plain `rsync` into it fails — stage to a writable temp dir, then `sudo`-install and restart the
+loader. The two helper scripts do exactly this:
+
+```sh
+cd clients/decky
+pnpm install
+pnpm run package                       # → out/punktfunk/ + out/punktfunk-v<ver>.zip
+DECK=deck@<deck-ip> pnpm run deploy    # rsync → /tmp, sudo cp into plugins/, chown root, restart
+```
+
+`deploy.sh` prompts for the Deck's sudo password interactively (via `ssh -t`); set `DECKPASS=…`
+to run it non-interactively. Equivalent by hand:
+
+```sh
+cd clients/decky && pnpm build && bash scripts/package.sh
+rsync -azp --delete out/punktfunk/ deck@<deck-ip>:/tmp/punktfunk/
+ssh -t deck@<deck-ip> 'sudo sh -c "rm -rf ~deck/homebrew/plugins/punktfunk && \
+  cp -r /tmp/punktfunk ~deck/homebrew/plugins/punktfunk && \
+  chown -R root:root ~deck/homebrew/plugins/punktfunk && systemctl restart plugin_loader"'
+```
+
+A loader restart is required for an out-of-band install to appear. The **punktfunk** panel then
+shows up in the Quick Access Menu.
+
+> The plugin launches the client via the flatpak `io.unom.Punktfunk` (see
+> [`../../packaging/flatpak/README.md`](../../packaging/flatpak/README.md)) — install that on
+> the Deck too, or the panel's Connect surfaces a `client-not-found` error.
+
+## Limitations / next steps
+
+- Launcher only — no in-stream overlay yet; the client owns the full session once launched.
+- mDNS discovery depends on `avahi-browse`; no manual "add host by IP" entry yet.
+- Pairing (PIN ceremony) is handled by the launched client, not the panel.
+- Not yet tested on real Deck hardware.

clients/decky/decky.pyi

@@ -0,0 +1,184 @@
+"""
+This module exposes various constants and helpers useful for decky plugins.
+
+* Plugin's settings and configurations should be stored under `DECKY_PLUGIN_SETTINGS_DIR`.
+* Plugin's runtime data should be stored under `DECKY_PLUGIN_RUNTIME_DIR`.
+* Plugin's persistent log files should be stored under `DECKY_PLUGIN_LOG_DIR`.
+
+Avoid writing outside of `DECKY_HOME`, storing under the suggested paths is strongly recommended.
+
+Some basic migration helpers are available: `migrate_any`, `migrate_settings`, `migrate_runtime`, `migrate_logs`.
+
+A logging facility `logger` is available which writes to the recommended location.
+"""
+
+__version__ = '1.0.0'
+
+import logging
+
+from typing import Any
+
+"""
+Constants
+"""
+
+HOME: str
+"""
+The home directory of the effective user running the process.
+Environment variable: `HOME`.
+If `root` was specified in the plugin's flags it will be `/root` otherwise the user whose home decky resides in.
+e.g.: `/home/deck`
+"""
+
+USER: str
+"""
+The effective username running the process.
+Environment variable: `USER`.
+It would be `root` if `root` was specified in the plugin's flags otherwise the user whose home decky resides in.
+e.g.: `deck`
+"""
+
+DECKY_VERSION: str
+"""
+The version of the decky loader.
+Environment variable: `DECKY_VERSION`.
+e.g.: `v2.5.0-pre1`
+"""
+
+DECKY_USER: str
+"""
+The user whose home decky resides in.
+Environment variable: `DECKY_USER`.
+e.g.: `deck`
+"""
+
+DECKY_USER_HOME: str
+"""
+The home of the user where decky resides in.
+Environment variable: `DECKY_USER_HOME`.
+e.g.: `/home/deck`
+"""
+
+DECKY_HOME: str
+"""
+The root of the decky folder.
+Environment variable: `DECKY_HOME`.
+e.g.: `/home/deck/homebrew`
+"""
+
+DECKY_PLUGIN_SETTINGS_DIR: str
+"""
+The recommended path in which to store configuration files (created automatically).
+Environment variable: `DECKY_PLUGIN_SETTINGS_DIR`.
+e.g.: `/home/deck/homebrew/settings/decky-plugin-template`
+"""
+
+DECKY_PLUGIN_RUNTIME_DIR: str
+"""
+The recommended path in which to store runtime data (created automatically).
+Environment variable: `DECKY_PLUGIN_RUNTIME_DIR`.
+e.g.: `/home/deck/homebrew/data/decky-plugin-template`
+"""
+
+DECKY_PLUGIN_LOG_DIR: str
+"""
+The recommended path in which to store persistent logs (created automatically).
+Environment variable: `DECKY_PLUGIN_LOG_DIR`.
+e.g.: `/home/deck/homebrew/logs/decky-plugin-template`
+"""
+
+DECKY_PLUGIN_DIR: str
+"""
+The root of the plugin's directory.
+Environment variable: `DECKY_PLUGIN_DIR`.
+e.g.: `/home/deck/homebrew/plugins/decky-plugin-template`
+"""
+
+DECKY_PLUGIN_NAME: str
+"""
+The name of the plugin as specified in the 'plugin.json'.
+Environment variable: `DECKY_PLUGIN_NAME`.
+e.g.: `Example Plugin`
+"""
+
+DECKY_PLUGIN_VERSION: str
+"""
+The version of the plugin as specified in the 'package.json'.
+Environment variable: `DECKY_PLUGIN_VERSION`.
+e.g.: `0.0.1`
+"""
+
+DECKY_PLUGIN_AUTHOR: str
+"""
+The author of the plugin as specified in the 'plugin.json'.
+Environment variable: `DECKY_PLUGIN_AUTHOR`.
+e.g.: `John Doe`
+"""
+
+DECKY_PLUGIN_LOG: str
+"""
+The path to the plugin's main logfile.
+Environment variable: `DECKY_PLUGIN_LOG`.
+e.g.: `/home/deck/homebrew/logs/decky-plugin-template/plugin.log`
+"""
+
+"""
+Migration helpers
+"""
+
+
+def migrate_any(target_dir: str, *files_or_directories: str) -> dict[str, str]:
+    """
+    Migrate files and directories to a new location and remove old locations.
+    Specified files will be migrated to `target_dir`.
+    Specified directories will have their contents recursively migrated to `target_dir`.
+
+    Returns the mapping of old -> new location.
+    """
+
+
+def migrate_settings(*files_or_directories: str) -> dict[str, str]:
+    """
+    Migrate files and directories relating to plugin settings to the recommended location and remove old locations.
+    Specified files will be migrated to `DECKY_PLUGIN_SETTINGS_DIR`.
+    Specified directories will have their contents recursively migrated to `DECKY_PLUGIN_SETTINGS_DIR`.
+
+    Returns the mapping of old -> new location.
+    """
+
+
+def migrate_runtime(*files_or_directories: str) -> dict[str, str]:
+    """
+    Migrate files and directories relating to plugin runtime data to the recommended location and remove old locations
+    Specified files will be migrated to `DECKY_PLUGIN_RUNTIME_DIR`.
+    Specified directories will have their contents recursively migrated to `DECKY_PLUGIN_RUNTIME_DIR`.
+
+    Returns the mapping of old -> new location.
+    """
+
+
+def migrate_logs(*files_or_directories: str) -> dict[str, str]:
+    """
+    Migrate files and directories relating to plugin logs to the recommended location and remove old locations.
+    Specified files will be migrated to `DECKY_PLUGIN_LOG_DIR`.
+    Specified directories will have their contents recursively migrated to `DECKY_PLUGIN_LOG_DIR`.
+
+    Returns the mapping of old -> new location.
+    """
+
+
+"""
+Logging
+"""
+
+logger: logging.Logger
+"""The main plugin logger writing to `DECKY_PLUGIN_LOG`."""
+
+"""
+Event handling
+"""
+# TODO better docstring im lazy
+async def emit(event: str, *args: Any) -> None:
+    """
+    Send an event to the frontend.
+    """

clients/decky/main.py

@@ -0,0 +1,274 @@
+"""
+punktfunk Decky plugin — backend.
+
+Bridges the Gaming-Mode Quick Access panel (``src/index.tsx``) to two host-side
+operations:
+
+* **discover()** — browse the LAN over mDNS for punktfunk/1 hosts advertising the
+  ``_punktfunk._udp`` service, returning name / ip:port / pairing-requirement / cert
+  fingerprint for each. Implemented by shelling out to ``avahi-browse`` (SteamOS, Bazzite
+  and most Linux distros ship ``avahi-daemon``); see :func:`Plugin.discover`.
+* **connect(host, port)** / **disconnect()** — launch / kill the native GTK4 client
+  (``punktfunk-client --connect host:port``). The child PID is tracked so a later
+  :func:`Plugin.disconnect` (or plugin unload) can terminate it.
+
+The TXT-record keys parsed here (``proto`` / ``fp`` / ``pair`` / ``id``) are defined by the
+host advert in ``crates/punktfunk-host/src/discovery.rs``.
+"""
+
+import asyncio
+import shutil
+from pathlib import Path
+
+import decky
+
+# The native punktfunk/1 client binary (the GTK4/libadwaita Linux client, crate
+# ``punktfunk-client-linux``). It is resolved at runtime from PATH and a handful of common
+# install locations (see :func:`_resolve_client`). If none exist we fall back to this bare
+# name and let the spawn fail loudly — install the client on the Deck (.deb / RPM / flatpak)
+# or symlink it into ~/.local/bin.
+#
+# On SteamOS (read-only /usr, image-based) the settled install path is the flatpak
+# ``io.unom.Punktfunk`` (packaging/flatpak/), launched via ``flatpak run`` — see the flatpak
+# fallback in :func:`_resolve_client`.
+CLIENT_BINARY = "punktfunk-client"
+
+# Service type advertised by punktfunk/1 hosts (matches NATIVE_SERVICE in the Rust host).
+SERVICE_TYPE = "_punktfunk._udp"
+
+# Candidate locations probed (in order) when the binary is not on PATH. ``$HOME`` is the
+# effective user's home as provided by decky.
+_CLIENT_CANDIDATES = [
+    "/usr/bin/punktfunk-client",
+    "/usr/local/bin/punktfunk-client",
+    str(Path(decky.HOME) / ".local" / "bin" / "punktfunk-client"),
+    # Flatpak: launched via `flatpak run` rather than a path — handled in _resolve_client.
+]
+
+
+def _resolve_client() -> list[str]:
+    """Return the argv prefix used to launch the native client.
+
+    Resolution order: PATH → well-known absolute paths → flatpak (if the app id is
+    installed) → bare binary name (so the eventual spawn fails with a clear error).
+    """
+    on_path = shutil.which(CLIENT_BINARY)
+    if on_path:
+        return [on_path]
+
+    for candidate in _CLIENT_CANDIDATES:
+        if Path(candidate).exists():
+            return [candidate]
+
+    # Flatpak fallback — the canonical install path on the Steam Deck (SteamOS /usr is
+    # read-only; the flatpak bundles the libadwaita + SDL3 the system lacks). The app id is
+    # the one the flatpak manifest publishes (packaging/flatpak/io.unom.Punktfunk.yml). If it
+    # is not installed, `flatpak run <id>` fails and surfaces as a spawn error the user can
+    # act on (install the bundle: `flatpak install --user punktfunk-client-*.flatpak`).
+    flatpak = shutil.which("flatpak")
+    if flatpak:
+        return [flatpak, "run", "io.unom.Punktfunk"]
+
+    decky.logger.warning(
+        "punktfunk-client not found on PATH or in %s; falling back to bare name",
+        _CLIENT_CANDIDATES,
+    )
+    return [CLIENT_BINARY]
+
+
+def _parse_avahi_browse(stdout: str) -> list[dict]:
+    """Parse ``avahi-browse -rpt`` output into a list of host dicts.
+
+    ``avahi-browse -r`` resolves services; ``-p`` makes the output parseable (one record
+    per line, semicolon-separated, fields escaped with ``\\``); ``-t`` terminates after the
+    initial cache dump instead of running forever.
+
+    Resolved records start with ``=`` and have the columns::
+
+        =;iface;protocol;name;type;domain;hostname;address;port;txt
+
+    where ``txt`` is a space-separated list of ``"key=value"`` tokens, each already wrapped
+    in double quotes by avahi, e.g. ``"proto=punktfunk/1" "fp=ab12..." "pair=required"``.
+
+    We dedup on the host advert ``id`` TXT key (a host re-advertises across interfaces /
+    IPv4+IPv6, producing several ``=`` lines for one logical host); when ``id`` is absent we
+    fall back to ``host:port``.
+    """
+    out: dict[str, dict] = {}
+    for raw in stdout.splitlines():
+        line = raw.strip()
+        if not line.startswith("="):
+            continue
+        # Split on unescaped ';'. avahi escapes literal ';' inside fields as '\;', so a
+        # simple replace-guard split is adequate for the fixed 10-column layout.
+        parts = line.replace("\\;", "\x00").split(";")
+        parts = [p.replace("\x00", ";") for p in parts]
+        if len(parts) < 9:
+            continue
+
+        name = parts[3]
+        # parts[4] is the service type, parts[5] the domain.
+        address = parts[7]
+        port_str = parts[8]
+        txt = parts[9] if len(parts) > 9 else ""
+
+        try:
+            port = int(port_str)
+        except ValueError:
+            port = 0
+
+        # Parse TXT tokens: each is a quoted "key=value".
+        props: dict[str, str] = {}
+        for token in _split_txt(txt):
+            if "=" in token:
+                k, v = token.split("=", 1)
+                props[k] = v
+
+        # Only surface actual punktfunk/1 adverts.
+        if props.get("proto") and not props["proto"].startswith("punktfunk/"):
+            continue
+
+        entry = {
+            "name": name,
+            "host": address,
+            "port": port,
+            "pair": props.get("pair", "optional"),
+            "fp": props.get("fp", ""),
+            "proto": props.get("proto", ""),
+        }
+        key = props.get("id") or f"{address}:{port}"
+        # Prefer an IPv4 record over IPv6 for the user-facing host string when both exist.
+        existing = out.get(key)
+        if existing is None or (":" in existing["host"] and ":" not in address):
+            out[key] = entry
+
+    return list(out.values())
+
+
+def _split_txt(txt: str) -> list[str]:
+    """Split an avahi TXT column into tokens, honouring the ``"key=value"`` quoting.
+
+    avahi prints each TXT item wrapped in double quotes and space-separated, e.g.::
+
+        "proto=punktfunk/1" "fp=ab12cd" "pair=required" "id=host-1"
+
+    A value can legitimately contain spaces, so we split on the quote boundaries rather
+    than on whitespace.
+    """
+    tokens: list[str] = []
+    cur: list[str] = []
+    in_quote = False
+    for ch in txt:
+        if ch == '"':
+            if in_quote:
+                tokens.append("".join(cur))
+                cur = []
+            in_quote = not in_quote
+        elif in_quote:
+            cur.append(ch)
+    if cur:
+        tokens.append("".join(cur))
+    return tokens
+
+
+class Plugin:
+    # Tracks the launched native client so disconnect()/_unload can terminate it.
+    _client: asyncio.subprocess.Process | None = None
+    _connected_host: str | None = None
+
+    async def discover(self) -> list[dict]:
+        """Browse the LAN for punktfunk/1 hosts. Returns ``[{name, host, port, pair, fp}]``."""
+        avahi = shutil.which("avahi-browse")
+        if not avahi:
+            decky.logger.error("avahi-browse not found; install avahi for host discovery")
+            return []
+
+        try:
+            proc = await asyncio.create_subprocess_exec(
+                avahi,
+                "-rpt",
+                SERVICE_TYPE,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+            )
+            try:
+                stdout, stderr = await asyncio.wait_for(proc.communicate(), timeout=8.0)
+            except asyncio.TimeoutError:
+                proc.kill()
+                decky.logger.warning("avahi-browse timed out")
+                return []
+        except Exception:  # noqa: BLE001 - surface any spawn failure as "no hosts"
+            decky.logger.exception("avahi-browse failed")
+            return []
+
+        if stderr:
+            decky.logger.debug("avahi-browse stderr: %s", stderr.decode(errors="replace"))
+
+        hosts = _parse_avahi_browse(stdout.decode(errors="replace"))
+        decky.logger.info("discovered %d punktfunk host(s)", len(hosts))
+        return hosts
+
+    async def connect(self, host: str, port: int) -> dict:
+        """Launch the native client against ``host:port``. Returns ``{ok, host, error?}``."""
+        # Tear down any prior session first.
+        await self.disconnect()
+
+        argv = _resolve_client() + ["--connect", f"{host}:{port}"]
+        decky.logger.info("launching client: %s", " ".join(argv))
+        try:
+            self._client = await asyncio.create_subprocess_exec(
+                *argv,
+                stdout=asyncio.subprocess.DEVNULL,
+                stderr=asyncio.subprocess.DEVNULL,
+            )
+        except FileNotFoundError:
+            decky.logger.error("client binary not found: %s", argv[0])
+            return {"ok": False, "host": f"{host}:{port}", "error": "client-not-found"}
+        except Exception as exc:  # noqa: BLE001
+            decky.logger.exception("failed to launch client")
+            return {"ok": False, "host": f"{host}:{port}", "error": str(exc)}
+
+        self._connected_host = f"{host}:{port}"
+        decky.logger.info("client launched (pid %s) -> %s", self._client.pid, self._connected_host)
+        return {"ok": True, "host": self._connected_host}
+
+    async def disconnect(self) -> dict:
+        """Terminate the launched native client, if any."""
+        proc = self._client
+        self._client = None
+        host = self._connected_host
+        self._connected_host = None
+        if proc is None or proc.returncode is not None:
+            return {"ok": True, "host": None}
+
+        decky.logger.info("disconnecting client (pid %s)", proc.pid)
+        try:
+            proc.terminate()
+            try:
+                await asyncio.wait_for(proc.wait(), timeout=5.0)
+            except asyncio.TimeoutError:
+                decky.logger.warning("client did not exit; killing (pid %s)", proc.pid)
+                proc.kill()
+                await proc.wait()
+        except ProcessLookupError:
+            pass
+        except Exception:  # noqa: BLE001
+            decky.logger.exception("error terminating client")
+        return {"ok": True, "host": host}
+
+    async def status(self) -> dict:
+        """Return the current connection status for UI refresh on panel open."""
+        connected = self._client is not None and self._client.returncode is None
+        return {"connected": connected, "host": self._connected_host if connected else None}
+
+    # ---- Decky lifecycle ----
+
+    async def _main(self):
+        decky.logger.info("punktfunk plugin loaded")
+
+    async def _unload(self):
+        decky.logger.info("punktfunk plugin unloading; tearing down client")
+        await self.disconnect()
+
+    async def _uninstall(self):
+        decky.logger.info("punktfunk plugin uninstalled")

clients/decky/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "punktfunk-decky",
+  "version": "0.0.1",
+  "description": "SteamOS / Steam Deck Gaming-Mode launcher for the punktfunk streaming client.",
+  "type": "module",
+  "scripts": {
+    "build": "rollup -c",
+    "watch": "rollup -c -w",
+    "package": "pnpm build && bash scripts/package.sh",
+    "deploy": "bash scripts/deploy.sh",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "decky",
+    "steam-deck",
+    "punktfunk",
+    "game-streaming"
+  ],
+  "author": "enrico",
+  "license": "Apache-2.0 OR MIT",
+  "dependencies": {
+    "@decky/api": "^1.1.3",
+    "react-icons": "^5.3.0",
+    "tslib": "^2.7.0"
+  },
+  "devDependencies": {
+    "@decky/rollup": "^1.0.2",
+    "@decky/ui": "^4.11.0",
+    "@rollup/rollup-linux-x64-musl": "^4.53.3",
+    "@types/react": "19.1.1",
+    "@types/react-dom": "19.1.1",
+    "@types/webpack": "^5.28.5",
+    "rollup": "^4.53.3",
+    "typescript": "^5.6.2"
+  },
+  "pnpm": {
+    "peerDependencyRules": {
+      "ignoreMissing": [
+        "react",
+        "react-dom"
+      ]
+    }
+  }
+}

clients/decky/plugin.json

@@ -0,0 +1,11 @@
+{
+  "name": "punktfunk",
+  "author": "enrico",
+  "flags": ["debug"],
+  "api_version": 1,
+  "publish": {
+    "tags": ["streaming", "game-streaming", "remote-play"],
+    "description": "Launch the punktfunk low-latency streaming client from Gaming Mode: discover hosts on the LAN over mDNS and connect to one.",
+    "image": "https://opengraph.githubassets.com/1/SteamDeckHomebrew/PluginLoader"
+  }
+}

clients/decky/rollup.config.js

@@ -0,0 +1,5 @@
+import deckyPlugin from "@decky/rollup";
+
+export default deckyPlugin({
+  // Add your extra Rollup options here
+});

clients/decky/scripts/deploy.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+# Deploy the staged plugin tree (out/<name>, produced by scripts/package.sh) into a Steam
+# Deck's ~/homebrew/plugins/, then restart Decky Loader.
+#
+# Decky's plugins dir is ROOT-OWNED (PluginLoader runs as root and manages it), so the install
+# step needs sudo on the Deck. We rsync to a deck-writable /tmp first (no privilege), then
+# sudo-copy into place. Out-of-band installs only appear after a loader restart.
+#
+# Usage:
+#   DECK=deck@192.168.1.235 bash scripts/deploy.sh             # interactive sudo (prompts on the Deck)
+#   DECK=deck@192.168.1.235 DECKPASS=... bash scripts/deploy.sh # non-interactive (scripted/CI)
+set -euo pipefail
+HERE="$(cd "$(dirname "$0")/.." && pwd)"
+DECK="${DECK:?set DECK=deck@<ip>}"
+NAME="$(python3 -c 'import json;print(json.load(open("'"$HERE"'/plugin.json"))["name"])')"
+STAGE_LOCAL="$HERE/out/$NAME"
+[ -d "$STAGE_LOCAL" ] || { echo "$STAGE_LOCAL missing — run scripts/package.sh first" >&2; exit 1; }
+
+# 1. push to a deck-writable temp dir (deck owns its $HOME)
+rsync -azp --delete -e ssh "$STAGE_LOCAL/" "$DECK:/tmp/$NAME/"
+
+# 2. sudo-install into the root-owned plugins dir, match Decky's root:root ownership, reload
+INSTALL="rm -rf /home/deck/homebrew/plugins/$NAME \
+  && cp -r /tmp/$NAME /home/deck/homebrew/plugins/$NAME \
+  && chown -R root:root /home/deck/homebrew/plugins/$NAME \
+  && rm -rf /tmp/$NAME \
+  && systemctl restart plugin_loader"
+
+if [ -n "${DECKPASS:-}" ]; then
+  ssh "$DECK" "echo '$DECKPASS' | sudo -S sh -c '$INSTALL'"
+else
+  echo "==> sudo on the Deck will prompt for ${DECK}'s password:"
+  ssh -t "$DECK" "sudo sh -c '$INSTALL'"
+fi
+echo "deployed $NAME → $DECK:~/homebrew/plugins/$NAME and restarted plugin_loader"

clients/decky/scripts/package.sh

@@ -0,0 +1,39 @@
+#!/usr/bin/env bash
+# Assemble the Decky plugin into the canonical store/sideload layout:
+#
+#   out/punktfunk-v<version>.zip   ->  punktfunk/{dist/index.js,main.py,plugin.json,
+#                                                  package.json,decky.pyi,LICENSE,README.md}
+#   out/punktfunk/                 (the same tree, unzipped — rsync this with scripts/deploy.sh)
+#
+# Decky extracts the zip with --strip-components=1, so the single top-level dir MUST equal
+# plugin.json "name". Run after `pnpm build` (or use `pnpm run package`). Host-agnostic: needs
+# only bash, python3 and zip.
+set -euo pipefail
+HERE="$(cd "$(dirname "$0")/.." && pwd)"
+cd "$HERE"
+
+[ -f dist/index.js ] || { echo "dist/index.js missing — run 'pnpm build' first" >&2; exit 1; }
+[ -f LICENSE ]       || { echo "LICENSE missing (required by the Decky store)" >&2; exit 1; }
+
+NAME="$(python3 -c 'import json;print(json.load(open("plugin.json"))["name"])')"
+VER="$(python3 -c 'import json;print(json.load(open("package.json"))["version"])')"
+
+STAGE="$(mktemp -d)"
+DEST="$STAGE/$NAME"
+mkdir -p "$DEST/dist"
+cp dist/index.js "$DEST/dist/index.js"          # ship the bundle only, not the sourcemap
+cp main.py plugin.json package.json LICENSE "$DEST/"
+[ -f decky.pyi ]  && cp decky.pyi  "$DEST/"
+[ -f README.md ]  && cp README.md  "$DEST/"
+
+OUT="$HERE/out"
+mkdir -p "$OUT"
+ZIP="$OUT/${NAME}-v${VER}.zip"
+rm -f "$ZIP"
+( cd "$STAGE" && zip -r -X "$ZIP" "$NAME" >/dev/null )
+# Leave an unzipped staging tree for the rsync/sudo deploy path (scripts/deploy.sh).
+rm -rf "$OUT/$NAME" && cp -r "$DEST" "$OUT/$NAME"
+rm -rf "$STAGE"
+
+echo "built  $ZIP"
+echo "staged $OUT/$NAME  (deploy with: DECK=deck@<ip> bash scripts/deploy.sh)"

clients/decky/src/index.tsx

@@ -0,0 +1,188 @@
+import {
+  ButtonItem,
+  Field,
+  PanelSection,
+  PanelSectionRow,
+  Spinner,
+} from "@decky/ui";
+import {
+  callable,
+  definePlugin,
+  toaster,
+} from "@decky/api";
+import { useEffect, useState } from "react";
+import { FaTv, FaSyncAlt, FaStop, FaLock, FaLockOpen } from "react-icons/fa";
+
+// ---- Backend bridge (see main.py) ----
+
+interface Host {
+  name: string;
+  host: string;
+  port: number;
+  pair: string; // "required" | "optional"
+  fp: string;
+}
+
+interface ConnectResult {
+  ok: boolean;
+  host: string | null;
+  error?: string;
+}
+
+interface Status {
+  connected: boolean;
+  host: string | null;
+}
+
+const discover = callable<[], Host[]>("discover");
+const connect = callable<[host: string, port: number], ConnectResult>("connect");
+const disconnect = callable<[], { ok: boolean; host: string | null }>("disconnect");
+const getStatus = callable<[], Status>("status");
+
+function Content() {
+  const [hosts, setHosts] = useState<Host[]>([]);
+  const [scanning, setScanning] = useState(false);
+  const [busyHost, setBusyHost] = useState<string | null>(null);
+  const [connectedHost, setConnectedHost] = useState<string | null>(null);
+
+  const refresh = async () => {
+    setScanning(true);
+    try {
+      const found = await discover();
+      setHosts(found);
+      toaster.toast({
+        title: "punktfunk",
+        body:
+          found.length === 0
+            ? "No hosts found on the LAN"
+            : `Found ${found.length} host${found.length === 1 ? "" : "s"}`,
+      });
+    } catch (e) {
+      toaster.toast({ title: "punktfunk", body: `Discovery failed: ${e}` });
+    } finally {
+      setScanning(false);
+    }
+  };
+
+  const onConnect = async (h: Host) => {
+    const target = `${h.host}:${h.port}`;
+    setBusyHost(target);
+    try {
+      const res = await connect(h.host, h.port);
+      if (res.ok) {
+        setConnectedHost(res.host);
+        toaster.toast({ title: "punktfunk", body: `Connecting to ${h.name}` });
+      } else {
+        toaster.toast({
+          title: "punktfunk",
+          body:
+            res.error === "client-not-found"
+              ? "punktfunk-client is not installed"
+              : `Connect failed: ${res.error ?? "unknown"}`,
+        });
+      }
+    } catch (e) {
+      toaster.toast({ title: "punktfunk", body: `Connect failed: ${e}` });
+    } finally {
+      setBusyHost(null);
+    }
+  };
+
+  const onDisconnect = async () => {
+    try {
+      await disconnect();
+      setConnectedHost(null);
+      toaster.toast({ title: "punktfunk", body: "Disconnected" });
+    } catch (e) {
+      toaster.toast({ title: "punktfunk", body: `Disconnect failed: ${e}` });
+    }
+  };
+
+  // On panel open: sync the current connection status and do an initial scan.
+  useEffect(() => {
+    getStatus()
+      .then((s) => setConnectedHost(s.connected ? s.host : null))
+      .catch(() => {});
+    void refresh();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  return (
+    <>
+      <PanelSection title="Status">
+        <PanelSectionRow>
+          <Field label="State" focusable={false}>
+            {connectedHost ? `Connected — ${connectedHost}` : "Idle"}
+          </Field>
+        </PanelSectionRow>
+        {connectedHost && (
+          <PanelSectionRow>
+            <ButtonItem layout="below" onClick={onDisconnect}>
+              <FaStop style={{ marginRight: "0.5em" }} />
+              Disconnect
+            </ButtonItem>
+          </PanelSectionRow>
+        )}
+      </PanelSection>
+
+      <PanelSection title="Hosts">
+        <PanelSectionRow>
+          <ButtonItem layout="below" onClick={refresh} disabled={scanning}>
+            {scanning ? (
+              <Spinner style={{ height: "1em", marginRight: "0.5em" }} />
+            ) : (
+              <FaSyncAlt style={{ marginRight: "0.5em" }} />
+            )}
+            {scanning ? "Scanning…" : "Refresh"}
+          </ButtonItem>
+        </PanelSectionRow>
+
+        {hosts.length === 0 && !scanning && (
+          <PanelSectionRow>
+            <Field focusable={false}>No hosts discovered yet.</Field>
+          </PanelSectionRow>
+        )}
+
+        {hosts.map((h) => {
+          const target = `${h.host}:${h.port}`;
+          const isBusy = busyHost === target;
+          const pairRequired = h.pair === "required";
+          return (
+            <PanelSectionRow key={h.fp || target}>
+              <ButtonItem
+                layout="below"
+                disabled={isBusy}
+                onClick={() => onConnect(h)}
+                label={
+                  <span>
+                    {pairRequired ? (
+                      <FaLock style={{ marginRight: "0.4em" }} />
+                    ) : (
+                      <FaLockOpen style={{ marginRight: "0.4em" }} />
+                    )}
+                    {h.name}
+                  </span>
+                }
+                description={`${target}${pairRequired ? " · pairing required" : ""}`}
+              >
+                {isBusy ? "Connecting…" : "Connect"}
+              </ButtonItem>
+            </PanelSectionRow>
+          );
+        })}
+      </PanelSection>
+    </>
+  );
+}
+
+export default definePlugin(() => {
+  return {
+    name: "punktfunk",
+    titleView: <div>punktfunk</div>,
+    content: <Content />,
+    icon: <FaTv />,
+    onDismount() {
+      // The backend tears the client down on _unload; nothing frontend-side to clean up.
+    },
+  };
+});

clients/decky/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "outDir": "dist",
+    "module": "ESNext",
+    "target": "ES2020",
+    "jsx": "react-jsx",
+    "declaration": false,
+    "moduleResolution": "node",
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "esModuleInterop": true,
+    "noImplicitReturns": true,
+    "noImplicitThis": true,
+    "noImplicitAny": true,
+    "strict": true,
+    "allowSyntheticDefaultImports": true
+  },
+  "include": ["src"],
+  "exclude": ["node_modules"]
+}

crates/punktfunk-android/Cargo.toml

@@ -0,0 +1,35 @@
+[package]
+name = "punktfunk-android"
+description = "punktfunk Android client — JNI bridge ('nativecore') over punktfunk-core (Rust-heavy client model)"
+version.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+license.workspace = true
+authors.workspace = true
+repository.workspace = true
+
+[lib]
+# `libpunktfunk_android.so` — loaded by Kotlin via `System.loadLibrary("punktfunk_android")`.
+name = "punktfunk_android"
+crate-type = ["cdylib"]
+
+[dependencies]
+# The whole protocol/transport/FEC/crypto + the embeddable NativeClient connector. `quic` pulls
+# the punktfunk/1 control plane (now ring-only — no aws-lc, see punktfunk-core/Cargo.toml).
+punktfunk-core = { path = "../punktfunk-core", features = ["quic"] }
+jni = "0.21"
+log = "0.4"
+
+# Android-only deps. Gated so `cargo build --workspace` on the Linux/macOS dev boxes + CI still
+# compiles this crate (as a host cdylib) — the Android-framework glue (logging now; AMediaCodec via
+# `ndk` and Oboe/Opus audio later) is only pulled in for the real `*-linux-android` targets.
+[target.'cfg(target_os = "android")'.dependencies]
+android_logger = "0.14"
+# NDK bindings. "media" = AMediaCodec/ANativeWindow (video); "audio" = AAudio (audio playback).
+# Pure-Rust FFI to libmediandk/libnativewindow/libaaudio — no C++/libc++_shared to bundle. Decode +
+# audio run entirely in Rust on native threads (the "no async on the hot path" invariant).
+ndk = { version = "0.9", features = ["media", "audio"] }
+# Opus decode for the host→client audio plane (0xC9: 48 kHz stereo, 5 ms frames). Same crate the
+# host + Linux client use. audiopus_sys vendors libopus (pure C) and builds it static via cmake —
+# the cargo-ndk build sets LIBOPUS_STATIC=1/LIBOPUS_NO_PKG=1 so it links the bundled lib, not the host's.
+opus = "0.3"

crates/punktfunk-android/src/audio.rs

@@ -0,0 +1,196 @@
+//! Android audio playback (android-only): pull Opus packets from the connector, decode to
+//! interleaved f32 stereo, and feed AAudio (LowLatency) via its realtime data callback through a
+//! jitter ring. Mirrors [`crate::decode`]: one thread we own (the Opus decode producer) plus a
+//! shutdown flag; the realtime callback thread is owned by AAudio. Ring logic ported from
+//! `punktfunk-client-linux/src/audio.rs` (prime ~3 quanta, drop-oldest cap, re-prime on drain).
+
+use ndk::audio::{
+    AudioCallbackResult, AudioDirection, AudioFormat, AudioPerformanceMode, AudioSharingMode,
+    AudioStream, AudioStreamBuilder,
+};
+use punktfunk_core::client::NativeClient;
+use punktfunk_core::error::PunktfunkError;
+use std::collections::VecDeque;
+use std::ffi::c_void;
+use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
+use std::sync::mpsc::{sync_channel, SyncSender, TrySendError};
+use std::sync::Arc;
+use std::time::Duration;
+
+const CHANNELS: usize = 2;
+const SAMPLE_RATE: i32 = 48_000;
+/// Decoded-chunk hand-off depth: 64 × 5 ms = 320 ms slack (matches the core's AUDIO_QUEUE).
+const RING_CHUNKS: usize = 64;
+/// Opus decode scratch: worst-case 120 ms stereo frame (5760 samples/ch × 2 ch).
+const PCM_SCRATCH: usize = 5760 * CHANNELS;
+
+/// Diagnostics — written by the decode thread + the realtime callback, logged periodically. The
+/// audio analogue of the video `fed`/`rendered` counters (we can't "screenshot" sound).
+#[derive(Default)]
+struct Counters {
+    opus_decoded: AtomicU64, // Opus packets decoded OK (~200/s at 5 ms frames)
+    pcm_written: AtomicU64,  // PCM frames copied out to AAudio (device clock is pulling)
+    underruns: AtomicU64,    // callbacks that emitted silence (ring not primed / drained)
+    ring_depth: AtomicU64,   // ring sample count at the last callback
+}
+
+/// Owned by [`crate::session::SessionHandle`]: the live AAudio stream + the decode thread.
+pub struct AudioPlayback {
+    _stream: AudioStream, // dropping it stops + closes the AAudio stream
+    shutdown: Arc<AtomicBool>,
+    join: Option<std::thread::JoinHandle<()>>,
+}
+
+impl AudioPlayback {
+    /// Open AAudio (LowLatency, 48 kHz/stereo/f32) with a realtime callback draining a jitter ring,
+    /// then spawn the Opus decode thread. `None` on failure (the caller leaves video streaming).
+    pub fn start(client: Arc<NativeClient>) -> Option<AudioPlayback> {
+        let counters = Arc::new(Counters::default());
+        let (tx, rx) = sync_channel::<Vec<f32>>(RING_CHUNKS);
+
+        // Realtime consumer state, owned by the callback (FnMut) — no lock: AAudio calls it from a
+        // single high-priority thread, and the decode thread only touches `tx`.
+        let cb_counters = counters.clone();
+        let mut ring: VecDeque<f32> = VecDeque::with_capacity(PCM_SCRATCH);
+        let mut primed = false;
+        let callback = move |_s: &AudioStream, data: *mut c_void, num_frames: i32| {
+            let want = num_frames as usize * CHANNELS;
+            // SAFETY: AAudio provides `num_frames * channel_count` F32 slots at `data`.
+            let out = unsafe { std::slice::from_raw_parts_mut(data as *mut f32, want) };
+            while let Ok(chunk) = rx.try_recv() {
+                ring.extend(chunk);
+            }
+            // Prime to ~3 quanta (15 ms; floor 15 ms / ceiling 200 ms); drop OLDEST above the cap.
+            let target = (3 * want).clamp(720 * CHANNELS, 9600 * CHANNELS);
+            while ring.len() > target.max(want) + want {
+                ring.pop_front();
+            }
+            if !primed && ring.len() >= target {
+                primed = true;
+            }
+            if primed {
+                for slot in out.iter_mut() {
+                    *slot = ring.pop_front().unwrap_or(0.0);
+                }
+                cb_counters
+                    .pcm_written
+                    .fetch_add(num_frames as u64, Ordering::Relaxed);
+            } else {
+                out.fill(0.0);
+                cb_counters.underruns.fetch_add(1, Ordering::Relaxed);
+            }
+            if ring.is_empty() {
+                primed = false; // re-prime after a genuine drain (avoids sustained crackle on loss)
+            }
+            cb_counters
+                .ring_depth
+                .store(ring.len() as u64, Ordering::Relaxed);
+            AudioCallbackResult::Continue
+        };
+
+        let stream = AudioStreamBuilder::new()
+            .map_err(|e| log::error!("audio: AudioStreamBuilder::new: {e}"))
+            .ok()?
+            .direction(AudioDirection::Output)
+            .sample_rate(SAMPLE_RATE)
+            .channel_count(CHANNELS as i32)
+            .format(AudioFormat::PCM_Float)
+            .performance_mode(AudioPerformanceMode::LowLatency)
+            .sharing_mode(AudioSharingMode::Shared)
+            .data_callback(Box::new(callback))
+            .error_callback(Box::new(|_s, e| {
+                log::warn!("audio: AAudio error (device reroute/disconnect?): {e:?}");
+            }))
+            .open_stream()
+            .map_err(|e| log::error!("audio: open_stream: {e}"))
+            .ok()?;
+
+        if let Err(e) = stream.request_start() {
+            log::error!("audio: request_start: {e}");
+            return None;
+        }
+        log::info!(
+            "audio: AAudio started rate={} ch={} fmt={:?} burst={}",
+            stream.sample_rate(),
+            stream.channel_count(),
+            stream.format(),
+            stream.frames_per_burst(),
+        );
+
+        let shutdown = Arc::new(AtomicBool::new(false));
+        let sd = shutdown.clone();
+        let join = std::thread::Builder::new()
+            .name("pf-audio".into())
+            .spawn(move || decode_loop(client, tx, sd, counters))
+            .ok();
+
+        Some(AudioPlayback {
+            _stream: stream,
+            shutdown,
+            join,
+        })
+    }
+}
+
+impl Drop for AudioPlayback {
+    fn drop(&mut self) {
+        self.shutdown.store(true, Ordering::SeqCst);
+        if let Some(j) = self.join.take() {
+            let _ = j.join();
+        }
+        // `_stream` drops here → AAudio request_stop + close.
+    }
+}
+
+/// Producer: `next_audio` → Opus `decode_float` → push interleaved f32 into the ring channel.
+fn decode_loop(
+    client: Arc<NativeClient>,
+    tx: SyncSender<Vec<f32>>,
+    shutdown: Arc<AtomicBool>,
+    counters: Arc<Counters>,
+) {
+    let mut dec = match opus::Decoder::new(SAMPLE_RATE as u32, opus::Channels::Stereo) {
+        Ok(d) => d,
+        Err(e) => {
+            log::error!("audio: opus decoder init: {e} — audio disabled");
+            return;
+        }
+    };
+    let mut pcm = vec![0f32; PCM_SCRATCH];
+    let mut window_peak = 0f32; // loudest |sample| since the last log — tells a tone from silence
+    while !shutdown.load(Ordering::Relaxed) {
+        match client.next_audio(Duration::from_millis(5)) {
+            Ok(pkt) => match dec.decode_float(&pkt.data, &mut pcm, false) {
+                Ok(samples) => {
+                    let n = samples * CHANNELS;
+                    for &s in &pcm[..n] {
+                        window_peak = window_peak.max(s.abs());
+                    }
+                    let count = counters.opus_decoded.fetch_add(1, Ordering::Relaxed) + 1;
+                    match tx.try_send(pcm[..n].to_vec()) {
+                        Ok(()) | Err(TrySendError::Full(_)) => {} // drop-newest under backpressure
+                        Err(TrySendError::Disconnected(_)) => break,
+                    }
+                    if count % 600 == 0 {
+                        log::info!(
+                            "audio: opus={count} pcm_frames={} underruns={} ring={} peak={window_peak:.3}",
+                            counters.pcm_written.load(Ordering::Relaxed),
+                            counters.underruns.load(Ordering::Relaxed),
+                            counters.ring_depth.load(Ordering::Relaxed),
+                        );
+                        window_peak = 0.0;
+                    }
+                }
+                Err(e) => log::debug!("audio: opus decode: {e}"),
+            },
+            Err(PunktfunkError::NoFrame) => {} // timeout
+            Err(_) => break,                   // session closed
+        }
+    }
+    log::info!(
+        "audio: stopped (opus={} pcm_frames={} underruns={})",
+        counters.opus_decoded.load(Ordering::Relaxed),
+        counters.pcm_written.load(Ordering::Relaxed),
+        counters.underruns.load(Ordering::Relaxed),
+    );
+}

crates/punktfunk-android/src/decode.rs

@@ -0,0 +1,138 @@
+//! Android video decode (android-only): pull HEVC access units from the connector and render them
+//! to the SurfaceView via NDK `AMediaCodec` — hardware decode, zero per-frame JNI.
+//!
+//! One-in/one-out: the host opens every stream with an IDR carrying VPS/SPS/PPS **in-band**, so the
+//! decoder needs no out-of-band codec-specific data — we configure with mime + the negotiated
+//! WxH (from [`NativeClient::mode`]) and feed each access unit as it arrives. The decode thread owns
+//! the codec + window for its whole life; [`crate::session`] signals it to stop via the shared flag.
+
+use ndk::media::media_codec::{
+    DequeuedInputBufferResult, DequeuedOutputBufferInfoResult, MediaCodec, MediaCodecDirection,
+};
+use ndk::media::media_format::MediaFormat;
+use ndk::native_window::NativeWindow;
+use punktfunk_core::client::NativeClient;
+use punktfunk_core::error::PunktfunkError;
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::Arc;
+use std::time::Duration;
+
+/// The decode loop. Runs on the `pf-decode` thread until `shutdown` is set or the session closes.
+pub fn run(client: Arc<NativeClient>, window: NativeWindow, shutdown: Arc<AtomicBool>) {
+    let mode = client.mode();
+    let codec = match MediaCodec::from_decoder_type("video/hevc") {
+        Some(c) => c,
+        None => {
+            log::error!("decode: no HEVC decoder on this device");
+            return;
+        }
+    };
+
+    let mut format = MediaFormat::new();
+    format.set_str("mime", "video/hevc");
+    format.set_i32("width", mode.width as i32);
+    format.set_i32("height", mode.height as i32);
+    // Generous input buffer so a large keyframe AU is never truncated.
+    format.set_i32(
+        "max-input-size",
+        (mode.width * mode.height).max(2_000_000) as i32,
+    );
+    // Ask for the low-latency decode path where the decoder supports it (no reordering buffer).
+    format.set_i32("low-latency", 1);
+
+    if let Err(e) = codec.configure(&format, Some(&window), MediaCodecDirection::Decoder) {
+        log::error!("decode: configure failed: {e}");
+        return;
+    }
+    if let Err(e) = codec.start() {
+        log::error!("decode: start failed: {e}");
+        return;
+    }
+    log::info!(
+        "decode: HEVC decoder started at {}x{}",
+        mode.width,
+        mode.height
+    );
+
+    let mut fed: u64 = 0;
+    let mut rendered: u64 = 0;
+    while !shutdown.load(Ordering::Relaxed) {
+        match client.next_frame(Duration::from_millis(5)) {
+            Ok(frame) => {
+                if fed == 0 {
+                    let p = &frame.data;
+                    log::info!(
+                        "decode: first AU {} bytes, head {:02x?}",
+                        p.len(),
+                        &p[..p.len().min(6)]
+                    );
+                }
+                fed += 1;
+                feed(&codec, &frame.data, frame.pts_ns / 1000);
+            }
+            Err(PunktfunkError::NoFrame) => {} // timeout — still drain output below
+            Err(_) => break,                   // session closed
+        }
+        rendered += drain(&codec);
+        if fed > 0 && fed % 300 == 0 {
+            log::info!("decode: fed={fed} rendered={rendered}");
+        }
+    }
+
+    let _ = codec.stop();
+    log::info!("decode: stopped (fed={fed} rendered={rendered})");
+}
+
+/// Copy one access unit into a codec input buffer and queue it.
+fn feed(codec: &MediaCodec, au: &[u8], pts_us: u64) {
+    match codec.dequeue_input_buffer(Duration::from_millis(10)) {
+        Ok(DequeuedInputBufferResult::Buffer(mut buf)) => {
+            let n = {
+                let dst = buf.buffer_mut();
+                let n = au.len().min(dst.len());
+                if n < au.len() {
+                    log::warn!(
+                        "decode: AU {} > input buffer {}, truncated",
+                        au.len(),
+                        dst.len()
+                    );
+                }
+                for (slot, &b) in dst.iter_mut().zip(&au[..n]) {
+                    slot.write(b);
+                }
+                n
+            };
+            if let Err(e) = codec.queue_input_buffer(buf, 0, n, pts_us, 0) {
+                log::warn!("decode: queue_input_buffer: {e}");
+            }
+        }
+        Ok(DequeuedInputBufferResult::TryAgainLater) => {
+            // No input buffer free right now; the AU is dropped (FEC/keyframes recover).
+        }
+        Err(e) => log::warn!("decode: dequeue_input_buffer: {e}"),
+    }
+}
+
+/// Release any ready output buffers to the surface (render = true), latency-first. Returns the
+/// number of frames presented.
+fn drain(codec: &MediaCodec) -> u64 {
+    let mut n = 0;
+    loop {
+        match codec.dequeue_output_buffer(Duration::from_millis(0)) {
+            Ok(DequeuedOutputBufferInfoResult::Buffer(buf)) => {
+                if let Err(e) = codec.release_output_buffer(buf, true) {
+                    log::warn!("decode: release_output_buffer: {e}");
+                    break;
+                }
+                n += 1;
+            }
+            // TryAgainLater / OutputFormatChanged / OutputBuffersChanged — nothing to render now.
+            Ok(_) => break,
+            Err(e) => {
+                log::warn!("decode: dequeue_output_buffer: {e}");
+                break;
+            }
+        }
+    }
+    n
+}

crates/punktfunk-android/src/feedback.rs

@@ -0,0 +1,114 @@
+//! Host→client gamepad feedback pulls (Option B): blocking JNI shims that forward to the connector's
+//! rumble (0xCA) / HID-output (0xCD) planes and return one decoded event. Kotlin owns the poll
+//! threads + the Android Vibrator/Lights rendering (see `GamepadFeedback.kt`) — no JNI upcalls, no
+//! `JavaVM` attach, no cached method ids. Mirrors the audio plane's one-thread-per-plane contract,
+//! except the thread lives in Kotlin and we just expose the blocking pull.
+//!
+//! Not android-gated: `next_rumble`/`next_hidout` are pure-Rust on the `quic` feature, so these
+//! compile on the host build too (parity with the input shims in [`crate::session`]).
+
+use crate::session::SessionHandle;
+use jni::objects::{JByteBuffer, JObject};
+use jni::sys::{jint, jlong};
+use jni::JNIEnv;
+use punktfunk_core::quic::HidOutput;
+use std::time::Duration;
+
+/// Short blocking timeout: long enough not to busy-spin, short enough that the Kotlin poll thread
+/// observes its `running=false` flag promptly on teardown.
+const PULL_TIMEOUT: Duration = Duration::from_millis(100);
+
+// HID-output kind tags written into the returned ByteBuffer (Kotlin reads them back).
+const TAG_LED: u8 = 0x01;
+const TAG_PLAYER_LEDS: u8 = 0x02;
+const TAG_TRIGGER: u8 = 0x03;
+
+/// `NativeBridge.nativeNextRumble(handle): Long` — block up to ~100 ms for the next rumble update.
+/// Returns `(low << 16) | high` (each 0..=0xFFFF; `0` = stop), or `-1` on timeout / session closed.
+/// Pad index is dropped (single-pad model). Run from a dedicated Kotlin poll thread.
+#[no_mangle]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeNextRumble(
+    _env: JNIEnv,
+    _this: JObject,
+    handle: jlong,
+) -> jlong {
+    if handle == 0 {
+        return -1;
+    }
+    // SAFETY: live handle per the nativeConnect/nativeClose contract; next_rumble is &self on the
+    // Sync connector — safe alongside the decode/audio/input threads. Kotlin stops these poll
+    // threads (and joins them) before nativeClose frees the handle.
+    let h = unsafe { &*(handle as *const SessionHandle) };
+    match h.client.next_rumble(PULL_TIMEOUT) {
+        Ok((_pad, low, high)) => (jlong::from(low) << 16) | jlong::from(high),
+        Err(_) => -1, // NoFrame (timeout) or Closed — Kotlin loops on its running flag
+    }
+}
+
+/// `NativeBridge.nativeNextHidout(handle, buf): Int` — block up to ~100 ms for the next DualSense
+/// HID-output event, written into the caller's direct ByteBuffer as `[kind][fields…]`:
+///   Led        → `[0x01][r][g][b]`         (len 4)
+///   PlayerLeds → `[0x02][bits]`            (len 2)
+///   Trigger    → `[0x03][which][effect…]`  (len 2 + effect.len())
+/// Returns the byte count written, or `-1` on timeout / session closed / buffer too small.
+#[no_mangle]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeNextHidout(
+    env: JNIEnv,
+    _this: JObject,
+    handle: jlong,
+    buf: JByteBuffer,
+) -> jint {
+    if handle == 0 {
+        return -1;
+    }
+    // SAFETY: live handle per the contract; next_hidout is &self on the Sync connector.
+    let h = unsafe { &*(handle as *const SessionHandle) };
+    let ev = match h.client.next_hidout(PULL_TIMEOUT) {
+        Ok(ev) => ev,
+        Err(_) => return -1, // timeout or closed — Kotlin loops
+    };
+
+    // The caller passes a direct ByteBuffer (allocateDirect) so we write its backing store directly.
+    let cap = match env.get_direct_buffer_capacity(&buf) {
+        Ok(c) => c,
+        Err(_) => return -1,
+    };
+    let ptr = match env.get_direct_buffer_address(&buf) {
+        Ok(p) if !p.is_null() => p,
+        _ => return -1,
+    };
+    // SAFETY: `ptr`/`cap` describe the direct ByteBuffer's backing store, valid for this call.
+    let out = unsafe { std::slice::from_raw_parts_mut(ptr, cap) };
+
+    let n = match ev {
+        HidOutput::Led { r, g, b, .. } => {
+            if cap < 4 {
+                return -1;
+            }
+            out[0] = TAG_LED;
+            out[1] = r;
+            out[2] = g;
+            out[3] = b;
+            4
+        }
+        HidOutput::PlayerLeds { bits, .. } => {
+            if cap < 2 {
+                return -1;
+            }
+            out[0] = TAG_PLAYER_LEDS;
+            out[1] = bits;
+            2
+        }
+        HidOutput::Trigger { which, effect, .. } => {
+            let n = 2 + effect.len();
+            if cap < n {
+                return -1; // the raw DS5 trigger block is ~11 bytes; Kotlin allocates 64
+            }
+            out[0] = TAG_TRIGGER;
+            out[1] = which;
+            out[2..n].copy_from_slice(&effect);
+            n
+        }
+    };
+    n as jint
+}

crates/punktfunk-android/src/lib.rs

@@ -0,0 +1,74 @@
+//! punktfunk Android client — the JNI bridge ("nativecore") over `punktfunk-core`.
+//!
+//! Architecture: the **Rust-heavy** client model (like `punktfunk-client-linux`, *not* the
+//! thin-native-over-C-ABI Apple model). This `cdylib` links `punktfunk-core` directly and drives
+//! the whole `punktfunk/1` protocol through [`punktfunk_core::client::NativeClient`]; Kotlin owns
+//! only the Android-framework surface (Compose UI, `SurfaceView` lifecycle, input capture,
+//! `NsdManager` discovery, Keystore). The JNI seam below is the one place the two languages meet.
+//!
+//! Why Rust-heavy: Kotlin cannot `import` the cbindgen C header the way Swift can, so a native
+//! bridge is unavoidable. Writing it in Rust lets the Android client reuse the Linux client's
+//! orchestration verbatim — audio jitter ring, the VK keymap inverse, latency/skew math, the
+//! input capture state machine, trust/pairing logic — instead of re-porting it into Kotlin.
+//!
+//! JNI symbols map to `io.unom.punktfunk.kit.NativeBridge` in the `:kit` Gradle module
+//! (`clients/android`). The current surface is the scaffold's native-link proof
+//! (`abiVersion`/`coreVersion`) plus the session handle lifecycle in [`session`]; the per-plane
+//! pumps (video → AMediaCodec, audio → Oboe), input, audio, pairing and mode renegotiation are
+//! the next milestone (see the TODOs in [`session`]).
+
+use jni::objects::JObject;
+use jni::sys::jint;
+use jni::JNIEnv;
+
+#[cfg(target_os = "android")]
+mod audio;
+#[cfg(target_os = "android")]
+mod decode;
+mod feedback;
+#[cfg(target_os = "android")]
+mod mic;
+mod session;
+
+/// Initialize `android_logger` once when the JVM loads the library. Logs land in logcat under the
+/// `punktfunk` tag. Android-only — there is no JVM (and no logcat) on the host build.
+#[cfg(target_os = "android")]
+#[no_mangle]
+pub extern "system" fn JNI_OnLoad(
+    _vm: *mut jni::sys::JavaVM,
+    _reserved: *mut std::ffi::c_void,
+) -> jint {
+    android_logger::init_once(
+        android_logger::Config::default()
+            .with_max_level(log::LevelFilter::Info)
+            .with_tag("punktfunk"),
+    );
+    log::info!(
+        "punktfunk_android loaded (core ABI v{})",
+        punktfunk_core::ABI_VERSION
+    );
+    jni::sys::JNI_VERSION_1_6
+}
+
+/// `NativeBridge.abiVersion(): Int` — the core's C-ABI version. A non-error return is the
+/// scaffold's proof that `System.loadLibrary` found the `.so`, the JNI symbol resolved, and the
+/// linked `punktfunk-core` is the one we expect.
+#[no_mangle]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_abiVersion(
+    _env: JNIEnv,
+    _this: JObject,
+) -> jint {
+    punktfunk_core::ABI_VERSION as jint
+}
+
+/// `NativeBridge.coreVersion(): String` — the crate version, proving JNI string marshaling works.
+#[no_mangle]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_coreVersion<'local>(
+    env: JNIEnv<'local>,
+    _this: JObject<'local>,
+) -> jni::sys::jstring {
+    match env.new_string(env!("CARGO_PKG_VERSION")) {
+        Ok(s) => s.into_raw(),
+        Err(_) => JObject::null().into_raw(),
+    }
+}

crates/punktfunk-android/src/mic.rs

@@ -0,0 +1,174 @@
+//! Android microphone uplink (android-only): capture mic PCM via AAudio (LowLatency **input**),
+//! Opus-encode 20 ms stereo frames, and push them to the host over the connector's mic plane
+//! (`send_mic` → 0xCB datagram). The mirror of [`crate::audio`] in reverse: AAudio's realtime input
+//! callback hands captured interleaved f32 to a channel; a worker thread we own does the Opus encode
+//! + send (encoding is too heavy for the realtime callback, exactly as decode is on the playback
+//! side). Format matches the host decoder + the Linux client: 48 kHz **stereo**, 20 ms, Opus VOIP.
+
+use ndk::audio::{
+    AudioCallbackResult, AudioDirection, AudioFormat, AudioPerformanceMode, AudioSharingMode,
+    AudioStream, AudioStreamBuilder,
+};
+use punktfunk_core::client::NativeClient;
+use std::collections::VecDeque;
+use std::ffi::c_void;
+use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
+use std::sync::mpsc::{sync_channel, Receiver, RecvTimeoutError, TrySendError};
+use std::sync::Arc;
+use std::time::{Duration, SystemTime, UNIX_EPOCH};
+
+const CHANNELS: usize = 2;
+const SAMPLE_RATE: i32 = 48_000;
+/// 20 ms per channel @ 48 kHz — the Linux client's frame; the host accepts ≤ 120 ms.
+const FRAME_SAMPLES: usize = 960;
+/// Captured-chunk hand-off depth (each ~ one burst); drops on overflow (best-effort uplink).
+const RING_CHUNKS: usize = 64;
+/// Opus VOIP target bitrate (speech; tunable).
+const MIC_BITRATE: i32 = 64_000;
+
+/// Owned by [`crate::session::SessionHandle`]: the live AAudio input stream + the encode thread.
+pub struct MicCapture {
+    _stream: AudioStream, // dropping it stops + closes the AAudio input stream
+    shutdown: Arc<AtomicBool>,
+    join: Option<std::thread::JoinHandle<()>>,
+}
+
+impl MicCapture {
+    /// Open AAudio (LowLatency, 48 kHz/stereo/f32) for **input** with a realtime callback that
+    /// forwards captured PCM to a channel, then spawn the Opus encode + uplink thread. `None` on
+    /// failure (the caller leaves the rest of the session streaming).
+    pub fn start(client: Arc<NativeClient>) -> Option<MicCapture> {
+        let (tx, rx) = sync_channel::<Vec<f32>>(RING_CHUNKS);
+        let captured = Arc::new(AtomicU64::new(0));
+        let cb_captured = captured.clone();
+
+        let callback = move |_s: &AudioStream, data: *mut c_void, num_frames: i32| {
+            let n = num_frames as usize * CHANNELS;
+            // SAFETY: for an input stream AAudio provides `num_frames * channel_count` captured F32
+            // samples at `data` (read-only for us).
+            let inp = unsafe { std::slice::from_raw_parts(data as *const f32, n) };
+            match tx.try_send(inp.to_vec()) {
+                Ok(()) | Err(TrySendError::Full(_)) => {} // drop-newest if the encoder lags
+                Err(TrySendError::Disconnected(_)) => return AudioCallbackResult::Stop,
+            }
+            cb_captured.fetch_add(num_frames as u64, Ordering::Relaxed);
+            AudioCallbackResult::Continue
+        };
+
+        let stream = AudioStreamBuilder::new()
+            .map_err(|e| log::error!("mic: AudioStreamBuilder::new: {e}"))
+            .ok()?
+            .direction(AudioDirection::Input)
+            .sample_rate(SAMPLE_RATE)
+            .channel_count(CHANNELS as i32)
+            .format(AudioFormat::PCM_Float)
+            .performance_mode(AudioPerformanceMode::LowLatency)
+            .sharing_mode(AudioSharingMode::Shared)
+            .data_callback(Box::new(callback))
+            .error_callback(Box::new(|_s, e| {
+                log::warn!("mic: AAudio error (device reroute/disconnect?): {e:?}");
+            }))
+            .open_stream()
+            .map_err(|e| log::error!("mic: open_stream (RECORD_AUDIO granted?): {e}"))
+            .ok()?;
+
+        if let Err(e) = stream.request_start() {
+            log::error!("mic: request_start: {e}");
+            return None;
+        }
+        log::info!(
+            "mic: AAudio input started rate={} ch={} fmt={:?}",
+            stream.sample_rate(),
+            stream.channel_count(),
+            stream.format(),
+        );
+
+        let shutdown = Arc::new(AtomicBool::new(false));
+        let sd = shutdown.clone();
+        let join = std::thread::Builder::new()
+            .name("pf-mic".into())
+            .spawn(move || encode_loop(client, rx, sd, captured))
+            .ok();
+
+        Some(MicCapture {
+            _stream: stream,
+            shutdown,
+            join,
+        })
+    }
+}
+
+impl Drop for MicCapture {
+    fn drop(&mut self) {
+        self.shutdown.store(true, Ordering::SeqCst);
+        if let Some(j) = self.join.take() {
+            let _ = j.join();
+        }
+        // `_stream` drops here → AAudio request_stop + close.
+    }
+}
+
+/// Consumer: drain captured f32 → accumulate → Opus `encode_float` 20 ms stereo frames → `send_mic`.
+fn encode_loop(
+    client: Arc<NativeClient>,
+    rx: Receiver<Vec<f32>>,
+    shutdown: Arc<AtomicBool>,
+    captured: Arc<AtomicU64>,
+) {
+    let mut enc = match opus::Encoder::new(
+        SAMPLE_RATE as u32,
+        opus::Channels::Stereo,
+        opus::Application::Voip,
+    ) {
+        Ok(e) => e,
+        Err(e) => {
+            log::error!("mic: opus encoder init: {e} — mic disabled");
+            return;
+        }
+    };
+    let _ = enc.set_bitrate(opus::Bitrate::Bits(MIC_BITRATE));
+
+    let frame = FRAME_SAMPLES * CHANNELS;
+    let mut ring: VecDeque<f32> = VecDeque::with_capacity(frame * 4);
+    let mut out = vec![0u8; 4000]; // max Opus packet for a 20 ms frame fits easily
+    let mut seq: u32 = 0;
+    let mut sent: u64 = 0;
+    let mut peak = 0f32; // loudest |sample| since the last log — tells speech from silence
+
+    while !shutdown.load(Ordering::Relaxed) {
+        match rx.recv_timeout(Duration::from_millis(100)) {
+            Ok(chunk) => ring.extend(chunk),
+            Err(RecvTimeoutError::Timeout) => continue, // wake to re-check shutdown
+            Err(RecvTimeoutError::Disconnected) => break,
+        }
+        while ring.len() >= frame {
+            let pcm: Vec<f32> = ring.drain(..frame).collect();
+            for &s in &pcm {
+                peak = peak.max(s.abs());
+            }
+            match enc.encode_float(&pcm, &mut out) {
+                Ok(len) => {
+                    let pts = SystemTime::now()
+                        .duration_since(UNIX_EPOCH)
+                        .map(|d| d.as_nanos() as u64)
+                        .unwrap_or(0);
+                    let _ = client.send_mic(seq, pts, out[..len].to_vec());
+                    seq = seq.wrapping_add(1);
+                    sent += 1;
+                    if sent % 250 == 0 {
+                        log::info!(
+                            "mic: sent={sent} captured_frames={} peak={peak:.3}",
+                            captured.load(Ordering::Relaxed),
+                        );
+                        peak = 0.0;
+                    }
+                }
+                Err(e) => log::debug!("mic: opus encode: {e}"),
+            }
+        }
+    }
+    log::info!(
+        "mic: stopped (sent={sent} captured_frames={})",
+        captured.load(Ordering::Relaxed),
+    );
+}

crates/punktfunk-android/src/session.rs

@@ -0,0 +1,609 @@
+//! Session lifecycle + plane wiring over JNI.
+//!
+//! A connected session is a [`SessionHandle`] — an `Arc<NativeClient>` plus the decode thread it
+//! feeds — boxed and handed to Kotlin as an opaque `jlong`. The connector is `Sync`, so the decode
+//! thread pulls the video plane (`next_frame`) directly while Kotlin still holds the handle.
+//!
+//! Wired: connect/close, the video plane (HEVC `next_frame` → NDK AMediaCodec → the SurfaceView's
+//! `ANativeWindow`, see [`crate::decode`]), host→client audio ([`crate::audio`]), input
+//! (`send_input` — mouse/keyboard/gamepad), rumble/DualSense HID feedback ([`crate::feedback`]),
+//! and the trust surface: `nativeGenerateIdentity` (persistent identity, Keystore-wrapped on the
+//! Kotlin side), `nativeConnect` with identity + pin (TOFU / pinned), and `nativePair` (SPAKE2 PIN).
+//!
+//! TODO(M4 Android stage 1): client→host DualSense rich input (`send_rich_input`), mode
+//! renegotiation. Port the remaining orchestration from `crates/punktfunk-client-linux`.
+
+use jni::objects::{JObject, JString};
+use jni::sys::{jboolean, jint, jlong};
+use jni::JNIEnv;
+use punktfunk_core::client::NativeClient;
+use punktfunk_core::config::{CompositorPref, GamepadPref, Mode};
+use punktfunk_core::input::{InputEvent, InputKind};
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::{Arc, Mutex};
+use std::thread::JoinHandle;
+use std::time::Duration;
+
+/// A live session behind the `jlong` handle: the connector + the decode thread it feeds.
+pub(crate) struct SessionHandle {
+    // Read only by the android decode path (`nativeStartVideo` → `crate::decode`); on the host
+    // build (CI's workspace clippy/build) those readers are cfg'd out, so it's intentionally unused.
+    #[cfg_attr(not(target_os = "android"), allow(dead_code))]
+    pub client: Arc<NativeClient>,
+    video: Mutex<Option<VideoThread>>,
+    #[cfg(target_os = "android")]
+    audio: Mutex<Option<crate::audio::AudioPlayback>>,
+    #[cfg(target_os = "android")]
+    mic: Mutex<Option<crate::mic::MicCapture>>,
+}
+
+struct VideoThread {
+    shutdown: Arc<AtomicBool>,
+    join: Option<JoinHandle<()>>,
+}
+
+impl SessionHandle {
+    /// Signal the decode thread to stop and join it. Idempotent.
+    fn stop_video(&self) {
+        if let Some(mut vt) = self.video.lock().unwrap().take() {
+            vt.shutdown.store(true, Ordering::SeqCst);
+            if let Some(j) = vt.join.take() {
+                let _ = j.join();
+            }
+        }
+    }
+
+    /// Stop + close audio playback. Dropping the [`crate::audio::AudioPlayback`] joins its decode
+    /// thread and closes the AAudio stream. Idempotent.
+    #[cfg(target_os = "android")]
+    fn stop_audio(&self) {
+        let _ = self.audio.lock().unwrap().take();
+    }
+
+    /// Stop mic uplink. Dropping the [`crate::mic::MicCapture`] joins its encode thread and closes
+    /// the AAudio input stream. Idempotent.
+    #[cfg(target_os = "android")]
+    fn stop_mic(&self) {
+        let _ = self.mic.lock().unwrap().take();
+    }
+}
+
+impl Drop for SessionHandle {
+    fn drop(&mut self) {
+        self.stop_video();
+        #[cfg(target_os = "android")]
+        self.stop_audio();
+        #[cfg(target_os = "android")]
+        self.stop_mic();
+    }
+}
+
+/// SHA-256 fingerprint → 64 lowercase hex chars (matches the host log + client-rs).
+fn hex32(fp: &[u8; 32]) -> String {
+    use std::fmt::Write;
+    fp.iter().fold(String::with_capacity(64), |mut s, b| {
+        let _ = write!(s, "{b:02x}");
+        s
+    })
+}
+
+/// 64-hex → [u8; 32]; `None` on bad length/char.
+fn parse_hex32(s: &str) -> Option<[u8; 32]> {
+    if s.len() != 64 {
+        return None;
+    }
+    let mut out = [0u8; 32];
+    for (i, b) in out.iter_mut().enumerate() {
+        *b = u8::from_str_radix(&s[2 * i..2 * i + 2], 16).ok()?;
+    }
+    Some(out)
+}
+
+/// `NativeBridge.nativeGenerateIdentity(): String` — mint a fresh persistent self-signed identity.
+/// Returns `"<certPem>\n-----PUNKTFUNK-KEY-----\n<keyPem>"`, or `""` on failure (logged). Kotlin
+/// persists it (Keystore-wrapped) and only calls this again when the store is genuinely empty.
+#[no_mangle]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeGenerateIdentity<'local>(
+    env: JNIEnv<'local>,
+    _this: JObject<'local>,
+) -> jni::sys::jstring {
+    let out = match punktfunk_core::quic::endpoint::generate_identity() {
+        Ok((cert, key)) => format!("{cert}\n-----PUNKTFUNK-KEY-----\n{key}"),
+        Err(e) => {
+            log::error!("nativeGenerateIdentity failed: {e}");
+            String::new()
+        }
+    };
+    match env.new_string(out) {
+        Ok(s) => s.into_raw(),
+        Err(_) => JObject::null().into_raw(),
+    }
+}
+
+/// `NativeBridge.nativeConnect(host, port, w, h, hz, certPem, keyPem, pinHex, bitrateKbps,
+/// compositorPref, gamepadPref): Long`. `certPem`/`keyPem` empty = anonymous, else presented as the
+/// persistent identity. `pinHex` empty = TOFU (read `nativeHostFingerprint` after), else 64-hex
+/// SHA-256 to pin the host (mismatch → 0). `bitrateKbps` 0 = host default. `compositorPref`/
+/// `gamepadPref` are `CompositorPref`/`GamepadPref` wire bytes (0 = Auto; unknown → Auto).
+/// Returns an opaque handle, or 0 on failure (logged).
+#[no_mangle]
+#[allow(clippy::too_many_arguments)]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeConnect<'local>(
+    mut env: JNIEnv<'local>,
+    _this: JObject<'local>,
+    host: JString<'local>,
+    port: jint,
+    width: jint,
+    height: jint,
+    refresh_hz: jint,
+    cert_pem: JString<'local>,
+    key_pem: JString<'local>,
+    pin_hex: JString<'local>,
+    bitrate_kbps: jint,
+    compositor_pref: jint,
+    gamepad_pref: jint,
+) -> jlong {
+    let host: String = match env.get_string(&host) {
+        Ok(s) => s.into(),
+        Err(_) => return 0,
+    };
+    let cert: String = env
+        .get_string(&cert_pem)
+        .map(Into::into)
+        .unwrap_or_default();
+    let key: String = env.get_string(&key_pem).map(Into::into).unwrap_or_default();
+    let pin_hex: String = env.get_string(&pin_hex).map(Into::into).unwrap_or_default();
+
+    let identity: Option<(String, String)> = if cert.is_empty() || key.is_empty() {
+        None
+    } else {
+        Some((cert, key))
+    };
+    let pin: Option<[u8; 32]> = if pin_hex.is_empty() {
+        None
+    } else {
+        match parse_hex32(&pin_hex) {
+            Some(fp) => Some(fp),
+            None => {
+                log::error!("nativeConnect: bad pin hex (len {})", pin_hex.len());
+                return 0;
+            }
+        }
+    };
+    let mode = Mode {
+        width: width as u32,
+        height: height as u32,
+        refresh_hz: refresh_hz as u32,
+    };
+    match NativeClient::connect(
+        &host,
+        port as u16,
+        mode,
+        CompositorPref::from_u8(compositor_pref.clamp(0, u8::MAX as jint) as u8),
+        GamepadPref::from_u8(gamepad_pref.clamp(0, u8::MAX as jint) as u8),
+        bitrate_kbps.max(0) as u32, // 0 = host default
+        None,                       // launch: default app
+        pin,                        // Some → Crypto on host-fp mismatch
+        identity,                   // owned (cert, key) PEM, or None (anonymous)
+        Duration::from_secs(10),
+    ) {
+        Ok(client) => {
+            let handle = SessionHandle {
+                client: Arc::new(client),
+                video: Mutex::new(None),
+                #[cfg(target_os = "android")]
+                audio: Mutex::new(None),
+                #[cfg(target_os = "android")]
+                mic: Mutex::new(None),
+            };
+            Box::into_raw(Box::new(handle)) as jlong
+        }
+        Err(e) => {
+            log::error!("nativeConnect to {host}:{port} failed: {e}");
+            0
+        }
+    }
+}
+
+/// `NativeBridge.nativeClose(handle)` — drop the session (stops the decode thread, then RAII-tears
+/// down the connector). No-op on `0`.
+///
+/// # Safety contract
+/// `handle` must be `0` or a live handle from [`Java_io_unom_punktfunk_kit_NativeBridge_nativeConnect`],
+/// closed exactly once and not concurrently with other calls on the same handle (Kotlin owns this).
+#[no_mangle]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeClose(
+    _env: JNIEnv,
+    _this: JObject,
+    handle: jlong,
+) {
+    if handle != 0 {
+        // SAFETY: per the contract, `handle` is a live `Box<SessionHandle>` pointer.
+        unsafe { drop(Box::from_raw(handle as *mut SessionHandle)) };
+    }
+}
+
+/// `NativeBridge.nativeHostFingerprint(handle): String` — the SHA-256 (64-hex) of the cert the host
+/// presented on this connection. Valid after a successful `nativeConnect`; Kotlin pins it on a TOFU
+/// connect. `""` on a `0` handle.
+#[no_mangle]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeHostFingerprint<'local>(
+    env: JNIEnv<'local>,
+    _this: JObject<'local>,
+    handle: jlong,
+) -> jni::sys::jstring {
+    let out = if handle == 0 {
+        String::new()
+    } else {
+        // SAFETY: live handle per the nativeConnect/nativeClose contract.
+        let h = unsafe { &*(handle as *const SessionHandle) };
+        hex32(&h.client.host_fingerprint)
+    };
+    match env.new_string(out) {
+        Ok(s) => s.into_raw(),
+        Err(_) => JObject::null().into_raw(),
+    }
+}
+
+/// `NativeBridge.nativePair(host, port, certPem, keyPem, pin, name): String` — run the SPAKE2 PIN
+/// ceremony, presenting our persistent identity. On success returns the host's verified fingerprint
+/// (64-hex) to persist + pin; on any failure (wrong PIN / MITM / host reject / unreachable) returns
+/// `""` (logged). Blocking — Kotlin calls it off the UI thread.
+#[no_mangle]
+#[allow(clippy::too_many_arguments)]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativePair<'local>(
+    mut env: JNIEnv<'local>,
+    _this: JObject<'local>,
+    host: JString<'local>,
+    port: jint,
+    cert_pem: JString<'local>,
+    key_pem: JString<'local>,
+    pin: JString<'local>,
+    name: JString<'local>,
+) -> jni::sys::jstring {
+    let g = |e: &mut JNIEnv<'local>, j: &JString<'local>| -> String {
+        e.get_string(j).map(Into::into).unwrap_or_default()
+    };
+    let host = g(&mut env, &host);
+    let cert = g(&mut env, &cert_pem);
+    let key = g(&mut env, &key_pem);
+    let pin = g(&mut env, &pin);
+    let name = g(&mut env, &name);
+
+    let out = if host.is_empty() || cert.is_empty() || key.is_empty() {
+        log::error!("nativePair: missing host/identity");
+        String::new()
+    } else {
+        match NativeClient::pair(
+            &host,
+            port as u16,
+            (&cert, &key), // borrowed identity
+            &pin,
+            &name,
+            Duration::from_secs(60),
+        ) {
+            Ok(host_fp) => hex32(&host_fp),
+            Err(e) => {
+                // Crypto error == wrong PIN / MITM; anything else == transport/host reject.
+                log::error!("nativePair to {host}:{port} failed: {e}");
+                String::new()
+            }
+        }
+    };
+    match env.new_string(out) {
+        Ok(s) => s.into_raw(),
+        Err(_) => JObject::null().into_raw(),
+    }
+}
+
+/// `NativeBridge.nativeStartVideo(handle, surface)` — wrap the SurfaceView's `Surface` as an
+/// `ANativeWindow` and start the HEVC decode thread rendering onto it. No-op if already started.
+#[cfg(target_os = "android")]
+#[no_mangle]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeStartVideo(
+    env: JNIEnv,
+    _this: JObject,
+    handle: jlong,
+    surface: JObject,
+) {
+    if handle == 0 {
+        return;
+    }
+    // SAFETY: live handle per the nativeConnect/nativeClose contract.
+    let h = unsafe { &*(handle as *const SessionHandle) };
+    let mut guard = h.video.lock().unwrap();
+    if guard.is_some() {
+        return; // already streaming
+    }
+    // SAFETY: `env`/`surface` are valid JNI pointers for this call. `as *mut _` bridges any
+    // jni-sys version skew between the `jni` and `ndk` crates (both are raw `*mut _` pointers).
+    let window = match unsafe {
+        ndk::native_window::NativeWindow::from_surface(
+            env.get_native_interface() as *mut _,
+            surface.as_raw() as *mut _,
+        )
+    } {
+        Some(w) => w,
+        None => {
+            log::error!("nativeStartVideo: no ANativeWindow from Surface");
+            return;
+        }
+    };
+    let shutdown = Arc::new(AtomicBool::new(false));
+    let client = h.client.clone();
+    let sd = shutdown.clone();
+    let join = std::thread::Builder::new()
+        .name("pf-decode".into())
+        .spawn(move || crate::decode::run(client, window, sd))
+        .ok();
+    *guard = Some(VideoThread { shutdown, join });
+}
+
+/// `NativeBridge.nativeStopVideo(handle)` — stop + join the decode thread (without closing the
+/// session). No-op on `0`.
+#[no_mangle]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeStopVideo(
+    _env: JNIEnv,
+    _this: JObject,
+    handle: jlong,
+) {
+    if handle != 0 {
+        // SAFETY: live handle per the contract.
+        let h = unsafe { &*(handle as *const SessionHandle) };
+        h.stop_video();
+    }
+}
+
+/// `NativeBridge.nativeStartAudio(handle)` — start the Opus→AAudio playback thread. No-op if already
+/// started or on a `0` handle. Best-effort: a failure leaves video streaming.
+#[cfg(target_os = "android")]
+#[no_mangle]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeStartAudio(
+    _env: JNIEnv,
+    _this: JObject,
+    handle: jlong,
+) {
+    if handle == 0 {
+        return;
+    }
+    // SAFETY: live handle per the nativeConnect/nativeClose contract.
+    let h = unsafe { &*(handle as *const SessionHandle) };
+    let mut guard = h.audio.lock().unwrap();
+    if guard.is_some() {
+        return; // already playing
+    }
+    match crate::audio::AudioPlayback::start(h.client.clone()) {
+        Some(p) => *guard = Some(p),
+        None => log::error!("nativeStartAudio: playback init failed (video unaffected)"),
+    }
+}
+
+/// `NativeBridge.nativeStopAudio(handle)` — stop + join the audio thread and close AAudio (without
+/// closing the session). No-op on `0`.
+#[cfg(target_os = "android")]
+#[no_mangle]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeStopAudio(
+    _env: JNIEnv,
+    _this: JObject,
+    handle: jlong,
+) {
+    if handle != 0 {
+        // SAFETY: live handle per the contract.
+        let h = unsafe { &*(handle as *const SessionHandle) };
+        h.stop_audio();
+    }
+}
+
+/// `NativeBridge.nativeStartMic(handle)` — start mic capture (AAudio input → Opus → host `send_mic`).
+/// No-op if already running or on a `0` handle. Caller MUST hold RECORD_AUDIO; a failure (e.g. no
+/// permission) leaves the rest of the session streaming.
+#[cfg(target_os = "android")]
+#[no_mangle]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeStartMic(
+    _env: JNIEnv,
+    _this: JObject,
+    handle: jlong,
+) {
+    if handle == 0 {
+        return;
+    }
+    // SAFETY: live handle per the nativeConnect/nativeClose contract.
+    let h = unsafe { &*(handle as *const SessionHandle) };
+    let mut guard = h.mic.lock().unwrap();
+    if guard.is_some() {
+        return; // already capturing
+    }
+    match crate::mic::MicCapture::start(h.client.clone()) {
+        Some(m) => *guard = Some(m),
+        None => log::error!("nativeStartMic: mic init failed (RECORD_AUDIO? — session unaffected)"),
+    }
+}
+
+/// `NativeBridge.nativeStopMic(handle)` — stop + join the mic thread and close the AAudio input
+/// stream (without closing the session). No-op on `0`.
+#[cfg(target_os = "android")]
+#[no_mangle]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeStopMic(
+    _env: JNIEnv,
+    _this: JObject,
+    handle: jlong,
+) {
+    if handle != 0 {
+        // SAFETY: live handle per the contract.
+        let h = unsafe { &*(handle as *const SessionHandle) };
+        h.stop_mic();
+    }
+}
+
+// ---- Input plane: Kotlin capture → NativeClient::send_input ----------------------------------
+// All four are `&self` on the `Sync` connector (send_input is a non-blocking datagram push), safe
+// from the Kotlin UI thread. NOT android-gated — send_input exists on the host build too, so these
+// compile everywhere (parity with nativeConnect/nativeClose). The wire codes are the GameStream
+// conventions: buttons 1=left/2=middle/3=right/4=X1/5=X2; scroll axis 0=vertical/1=horizontal,
+// signed 120-unit delta, +=up/right; keys are Windows VK (mapped from KEYCODE_* on the Kotlin side).
+
+/// `NativeBridge.nativeSendPointerMove(handle, dx, dy)` — relative mouse motion (screen +y down).
+#[no_mangle]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSendPointerMove(
+    _env: JNIEnv,
+    _this: JObject,
+    handle: jlong,
+    dx: jint,
+    dy: jint,
+) {
+    if handle == 0 {
+        return;
+    }
+    // SAFETY: live handle per the nativeConnect/nativeClose contract; send_input is &self.
+    let h = unsafe { &*(handle as *const SessionHandle) };
+    let _ = h.client.send_input(&InputEvent {
+        kind: InputKind::MouseMove,
+        _pad: [0; 3],
+        code: 0,
+        x: dx,
+        y: dy,
+        flags: 0,
+    });
+}
+
+/// `NativeBridge.nativeSendPointerButton(handle, button, down)` — one button transition.
+/// `button`: GameStream id (1=left, 2=middle, 3=right, 4=X1, 5=X2). `down`: 1=press, 0=release.
+#[no_mangle]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSendPointerButton(
+    _env: JNIEnv,
+    _this: JObject,
+    handle: jlong,
+    button: jint,
+    down: jboolean,
+) {
+    if handle == 0 {
+        return;
+    }
+    // SAFETY: live handle per the contract.
+    let h = unsafe { &*(handle as *const SessionHandle) };
+    let _ = h.client.send_input(&InputEvent {
+        kind: if down != 0 {
+            InputKind::MouseButtonDown
+        } else {
+            InputKind::MouseButtonUp
+        },
+        _pad: [0; 3],
+        code: button as u32,
+        x: 0,
+        y: 0,
+        flags: 0,
+    });
+}
+
+/// `NativeBridge.nativeSendScroll(handle, axis, delta)` — one scroll step. `axis`: 0=vertical,
+/// 1=horizontal. `delta`: signed, WHEEL_DELTA(120)-scaled, +=up/right.
+#[no_mangle]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSendScroll(
+    _env: JNIEnv,
+    _this: JObject,
+    handle: jlong,
+    axis: jint,
+    delta: jint,
+) {
+    if handle == 0 {
+        return;
+    }
+    // SAFETY: live handle per the contract.
+    let h = unsafe { &*(handle as *const SessionHandle) };
+    let _ = h.client.send_input(&InputEvent {
+        kind: InputKind::MouseScroll,
+        _pad: [0; 3],
+        code: axis as u32,
+        x: delta,
+        y: 0,
+        flags: 0,
+    });
+}
+
+/// `NativeBridge.nativeSendKey(handle, vk, down, mods)` — one key transition. `vk`: Windows
+/// Virtual-Key code (0 = unmapped → dropped). `down`: 1=press, 0=release. `mods`: VK modifier
+/// bitmask (0 for now — the host folds modifiers from the L/R modifier key events themselves).
+#[no_mangle]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSendKey(
+    _env: JNIEnv,
+    _this: JObject,
+    handle: jlong,
+    vk: jint,
+    down: jboolean,
+    mods: jint,
+) {
+    if handle == 0 || vk == 0 {
+        return;
+    }
+    // SAFETY: live handle per the contract.
+    let h = unsafe { &*(handle as *const SessionHandle) };
+    let _ = h.client.send_input(&InputEvent {
+        kind: if down != 0 {
+            InputKind::KeyDown
+        } else {
+            InputKind::KeyUp
+        },
+        _pad: [0; 3],
+        code: vk as u32,
+        x: 0,
+        y: 0,
+        flags: mods as u32,
+    });
+}
+
+// ---- Gamepad: Kotlin captures (KeyEvent/MotionEvent) → NativeClient::send_input ---------------
+// Single-pad model: exactly one controller, forwarded as pad 0 (flags = 0). Buttons carry the
+// gamepad::BTN_* bit in `code` and pressed/released in `x` (1/0); axes carry the gamepad::AXIS_* id
+// in `code` and the value in `x` (sticks i16 −32768..32767, +y = up; triggers 0..255). The host
+// accumulates the incremental events into its virtual xpad. Wire contract: input.rs::gamepad.
+
+/// `NativeBridge.nativeSendGamepadButton(handle, bit, down)` — one gamepad button transition.
+/// `bit`: a `gamepad::BTN_*` bit (e.g. BTN_A = 0x1000). `down`: 1=press, 0=release.
+#[no_mangle]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSendGamepadButton(
+    _env: JNIEnv,
+    _this: JObject,
+    handle: jlong,
+    bit: jint,
+    down: jboolean,
+) {
+    if handle == 0 {
+        return;
+    }
+    // SAFETY: live handle per the contract.
+    let h = unsafe { &*(handle as *const SessionHandle) };
+    let _ = h.client.send_input(&InputEvent {
+        kind: InputKind::GamepadButton,
+        _pad: [0; 3],
+        code: bit as u32,
+        x: i32::from(down != 0),
+        y: 0,
+        flags: 0, // pad index 0 — single-pad model
+    });
+}
+
+/// `NativeBridge.nativeSendGamepadAxis(handle, axisId, value)` — one gamepad axis update.
+/// `axisId`: a `gamepad::AXIS_*` id (LS_X=0..RT=5). `value`: stick i16 (−32768..32767, +y=up) or
+/// trigger 0..255.
+#[no_mangle]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSendGamepadAxis(
+    _env: JNIEnv,
+    _this: JObject,
+    handle: jlong,
+    axis_id: jint,
+    value: jint,
+) {
+    if handle == 0 {
+        return;
+    }
+    // SAFETY: live handle per the contract.
+    let h = unsafe { &*(handle as *const SessionHandle) };
+    let _ = h.client.send_input(&InputEvent {
+        kind: InputKind::GamepadAxis,
+        _pad: [0; 3],
+        code: axis_id as u32,
+        x: value,
+        y: 0,
+        flags: 0, // pad index 0 — single-pad model
+    });
+}

crates/punktfunk-client-linux/src/app.rs

@@ -44,7 +44,10 @@ pub fn run() -> glib::ExitCode {
 }
 
 /// `--connect host[:port]` — skip the hosts page and start a session immediately
-/// (scripting + headless testing; trust follows the same known-hosts/TOFU rules).
+/// (scripting + headless testing). Trust follows the same rules as a manual entry: a host
+/// already pinned at this address connects silently on its stored pin; an unknown host is
+/// routed to the PIN ceremony (never a silent TOFU connect — `fp_hex`/`pair_optional` are
+/// unset, so `initiate_connect`'s manual arm mandates pairing).
 fn cli_connect_request() -> Option<ConnectRequest> {
     let args: Vec<String> = std::env::args().collect();
     let target = args
@@ -61,7 +64,7 @@ fn cli_connect_request() -> Option<ConnectRequest> {
         addr,
         port,
         fp_hex: None,
-        pair_required: false,
+        pair_optional: false,
     })
 }
 
@@ -119,10 +122,18 @@ fn build_ui(gtk_app: &adw::Application) {
     }
 }
 
-/// The trust gate in front of every connect. Discovered hosts carry their fingerprint in
+/// The trust gate in front of every connect. The host is the policy authority (it
-/// the mDNS advert, so trust is decided *before* any traffic: known → pinned connect;
+/// advertises `pair=optional` only when it accepts unpaired clients); the client renders
-/// unknown → TOFU prompt (or straight to pairing when the host requires it). Manual
+/// its trust UI from that:
-/// entries have no advance fingerprint: trust on first use, pin from then on.
+///   1. PINNED RECONNECT — a host already pinned to this exact fingerprint connects silently.
+///   2. FINGERPRINT CHANGED — a host we know at this address but whose fingerprint no longer
+///      matches is the impostor signal: force re-pairing via the PIN ceremony, regardless of
+///      the advertised policy.
+///   3. NEW host — TOFU is offered only when the host advertised `pair=optional` (rule 3a);
+///      otherwise (pair=required, unknown/empty policy, or a manual entry) PIN pairing is
+///      mandatory (rule 3b).
+///
+/// A new host is never auto-connected without a stored pin or an explicit trust decision.
 fn initiate_connect(app: Rc<App>, req: ConnectRequest) {
     if app.busy.get() {
         return;
@@ -131,19 +142,31 @@ fn initiate_connect(app: Rc<App>, req: ConnectRequest) {
     match &req.fp_hex {
         Some(fp_hex) => {
             if known.find_by_fp(fp_hex).is_some() {
+                // Rule 1: pinned fingerprint matches — silent connect.
                 start_session(app, req.clone(), crate::trust::parse_hex32(fp_hex));
-            } else if req.pair_required {
+            } else if known.find_by_addr(&req.addr, req.port).is_some() {
-                // TOFU alone won't pass the host's gate — go straight to the ceremony.
+                // Rule 2: we trust a host at this address but the fingerprint changed —
+                // the impostor signal. Re-pair via the PIN ceremony (no TOFU shortcut).
+                app.toast("Host fingerprint changed — re-pair with a PIN to continue");
                 pin_dialog(app, req);
-            } else {
+            } else if req.pair_optional {
+                // Rule 3a: the host opted into reduced-security TOFU; offer it alongside PIN.
                 tofu_dialog(app, req);
+            } else {
+                // Rule 3b: pair=required or unknown policy — PIN pairing is mandatory.
+                pin_dialog(app, req);
             }
         }
         None => {
-            let pin = known
+            // Manual entry (no advertised fingerprint). A known address connects silently
+            // on its stored pin (rule 1); an unknown one must pair — never silent TOFU.
+            match known
                 .find_by_addr(&req.addr, req.port)
-                .and_then(|k| crate::trust::parse_hex32(&k.fp_hex));
+                .and_then(|k| crate::trust::parse_hex32(&k.fp_hex))
-            start_session(app, req, pin);
+            {
+                Some(pin) => start_session(app, req, Some(pin)),
+                None => pin_dialog(app, req), // rule 3b
+            }
         }
     }
 }
@@ -286,6 +309,7 @@ fn speed_test(app: Rc<App>, req: ConnectRequest) {
                 CompositorPref::Auto,
                 GamepadPref::Auto,
                 0,
+                None, // launch: speed-test probe connect, no game
                 pin,
                 Some(identity),
                 std::time::Duration::from_secs(15),
@@ -456,10 +480,21 @@ fn start_session(app: Rc<App>, req: ConnectRequest, pin: Option<[u8; 32]>) {
                         p.update_stats(s);
                     }
                 }
-                SessionEvent::Failed(msg) => {
+                SessionEvent::Failed {
-                    tracing::warn!(%msg, "connect failed");
+                    msg,
-                    app.toast(&msg);
+                    trust_rejected,
+                } => {
+                    tracing::warn!(%msg, trust_rejected, "connect failed");
                     app.busy.set(false);
+                    // A pinned connect rejected on trust grounds means the host's cert no
+                    // longer matches the stored pin (rotated cert or impostor) — route to
+                    // the PIN ceremony to re-establish trust rather than dead-ending.
+                    if trust_rejected && !tofu {
+                        app.toast("Host fingerprint changed — re-pair with a PIN to continue");
+                        pin_dialog(app.clone(), req.clone());
+                    } else {
+                        app.toast(&msg);
+                    }
                     break;
                 }
                 SessionEvent::Ended(err) => {