feat(windows-drivers): STEP 8 (3/n) — re-vendor the installer driver from the new wdk-sys tree

The installer's vendored driver binary (packaging/windows/pf-vdisplay/) was STALE — built from the OLD oracle tree (packaging/windows/vdisplay-driver/, wdf-umdf, SudoVDA-compat GUID), so it was ABI-mismatched with the host (which opens the owned proto GUID 70667664). Re-vendor it from the NEW drivers/ tree so the rewrite's ACTUAL driver is what the installer ships. Built RELEASE on the RTX box from the new tree + the new .inx: cargo build --release -p pf-vdisplay -> FORCE_INTEGRITY clear -> stampinf (DriverVer 06/25/2026,9.5.0625.1614, > the old 06/22) -> Inf2Cat /os:10_X64 -> signtool sign the .cat with punktfunk-ds-test (.cat sig Valid). Replaces the stale .dll/.inf/.cat; the .cer is unchanged (same cert). ON-GLASS VALIDATED (install-test): pnputil /add-driver /install the release package -> clean WUDFHost reload -> Status=OK, init_adapter -> IddCxAdapterInitAsync -> 0x0 (FP16 accepted), IddCxMonitorCreate(id=1) -> 0x0. The shipping installer now installs + loads the real wdk-sys proto-GUID driver, FP16/HDR-capable, monitor-create working. Remaining STEP 8 (recorded in memory, deferred): re-point the stale "built from vdisplay-driver/" comments in stage-pf-vdisplay.ps1 / pack-host-installer.ps1 / packaging README; selector default -> pf-vdisplay unconditional; CI build-sign-or-stale-vendored drift guard; then DELETE the oracle tree. KEEP sudovda.rs (runtime fallback + the backend-neutral CCD helpers pf_vdisplay.rs reuses) and the WGC-relay/DDA secure path (the secure-desktop lock/UAC gate is not yet proven on glass for IDD-push). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
feat(windows-drivers): STEP 8 (2/n) — give the new pf-vdisplay tree its own .inx
2026-06-25 12:18:48 +00:00 · 2026-06-25 12:03:26 +00:00 · 2026-06-25 12:00:55 +00:00 · 2026-06-25 11:31:28 +00:00 · 2026-06-25 10:28:47 +00:00 · 2026-06-25 09:32:12 +00:00
682 changed files with 149259 additions and 1 deletions
@@ -0,0 +1,20 @@
+# cargo-audit configuration — consumed by `.gitea/workflows/audit.yml` (`cargo audit`).
+#
+# Silence only advisories that are KNOWN-UNFIXABLE and either not applicable to how we use the crate
+# or an accepted, documented risk. Keep this list TIGHT and justify every entry — an ignore here
+# means the audit job stops flagging it, so the reasoning must hold up.
+#
+# NOTE: `cargo audit` (no `--deny warnings`) fails only on *vulnerabilities*, not on the
+# `unmaintained` warnings (audiopus_sys / paste / rustls-pemfile). Those are left visible on purpose
+# so we keep getting the maintenance signal — they do not fail CI.
+
+[advisories]
+ignore = [
+    # rsa "Marvin Attack" — a timing sidechannel in RSA *decryption* (PKCS#1 v1.5 padding oracle).
+    # There is NO fixed rsa release (the constant-time rewrite is still unreleased upstream), and rsa
+    # is required for GameStream/Moonlight pairing. Crucially, the host uses rsa ONLY for PKCS#1 v1.5
+    # SIGNING / VERIFYING (gamestream/cert.rs + gamestream/pairing.rs: SigningKey / VerifyingKey /
+    # Signer / Verifier) — it never performs RSA decryption, which is the operation Marvin targets.
+    # So the vulnerable code path is not exercised. Revisit if a fixed rsa ships or we add RSA decrypt.
+    "RUSTSEC-2023-0071",
+]
@@ -0,0 +1,11 @@
+# Root build context is used only by web/Dockerfile, which needs web/ and
+# docs/api/openapi.json. Allowlist those; keep everything else (target/, .git, crates)
+# out of the context upload.
+*
+!web
+!docs/api/openapi.json
+web/node_modules
+web/.output
+web/dist
+web/src/api/gen
+web/src/paraglide
@@ -0,0 +1,153 @@
+# Android client CI (Gitea Actions). Builds the Rust JNI core (clients/android/native) 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]
+    # Single project version: a `vX.Y.Z` tag is THE release (uploads to Play's `alpha` closed
+    # track for manual promotion + attaches the .aab/.apk to the unified Gitea Release). A main
+    # push is canary (Play `internal`).
+    tags: ['v*']
+  pull_request:
+  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 r30 + platform 36 + build-tools + CMake (libopus cross-build)
+        # cmake;3.22.1 installs cmake + ninja under $ANDROID_SDK/cmake/3.22.1/bin — the exact path
+        # kit/build.gradle.kts prepends to PATH for cargo-ndk's audiopus_sys (libopus) CMake build.
+        # Note: platforms;android-37 is sometimes missing from standard channels; AGP will 
+        # auto-download it if needed during the build.
+        run: sdkmanager "platform-tools" "platforms;android-36" "build-tools;37.0.0" "ndk;30.0.14904198" "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
+        env:
+          VERSION_CODE: ${{ github.run_number }}
+        run: ./gradlew :app:assembleDebug --stacktrace
+
+      # Single source of the version name + the Play track for the release steps below. versionCode
+      # stays github.run_number (monotonic across both tracks; Play rejects a regressed code).
+      - name: Version + channel
+        if: github.event_name == 'push' && (github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/v'))
+        run: |
+          case "$GITHUB_REF" in
+            refs/tags/v*) VN="${GITHUB_REF_NAME#v}"; TRACK="alpha" ;;   # alpha = built-in closed testing
+            *)            VN="0.3.0-ci${GITHUB_RUN_NUMBER}"; TRACK="internal" ;;
+          esac
+          echo "VERSION_NAME=$VN" >> "$GITHUB_ENV"
+          echo "PLAY_TRACK=$TRACK" >> "$GITHUB_ENV"
+          echo "android version $VN -> Play track '$TRACK'"
+
+      - name: Build Release (signed AAB + universal APK)
+        if: github.event_name == 'push' && (github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/v'))
+        working-directory: clients/android
+        env:
+          VERSION_CODE: ${{ github.run_number }}   # VERSION_NAME comes from the Version+channel step (GITHUB_ENV)
+          RELEASE_KEYSTORE_FILE: "../release.jks"
+          RELEASE_KEYSTORE_PASSWORD: ${{ secrets.RELEASE_KEYSTORE_PASSWORD }}
+          RELEASE_KEY_ALIAS: ${{ secrets.RELEASE_KEY_ALIAS }}
+          RELEASE_KEY_PASSWORD: ${{ secrets.RELEASE_KEY_PASSWORD }}
+        run: |
+          echo "${{ secrets.RELEASE_KEYSTORE_BASE64 }}" | base64 -d > release.jks
+          # AAB for Play; a universal APK (both ABIs) for direct sideload/testing — same upload key.
+          ./gradlew :app:bundleRelease :app:assembleRelease --stacktrace
+
+      # Publish BEFORE the Play upload so artifacts land even while the Play step is still failing.
+      # Generic registry is public for reads — matches windows-msix.yml / deb.yml (REGISTRY_TOKEN, user enricobuehler).
+      # main = canary store + `canary/` sideload alias; a `vX.Y.Z` tag = `latest/` alias + attached
+      # to the unified Gitea Release.
+      - name: Publish to generic registry + attach to Gitea release
+        if: github.event_name == 'push' && (github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/v'))
+        env:
+          REGISTRY: git.unom.io
+          OWNER: unom
+          PKG: punktfunk-android
+          VERSION: ${{ github.run_number }}
+          REGISTRY_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
+          GITEA_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
+        run: |
+          AAB=clients/android/app/build/outputs/bundle/release/app-release.aab
+          APK=clients/android/app/build/outputs/apk/release/app-release.apk
+          base="https://$REGISTRY/api/packages/$OWNER/generic/$PKG"
+          # 1) immutable, run-number-versioned store (sideload + provenance)
+          curl -fsS --user "enricobuehler:$REGISTRY_TOKEN" --upload-file "$AAB" "$base/$VERSION/punktfunk-android-r$VERSION.aab"
+          curl -fsS --user "enricobuehler:$REGISTRY_TOKEN" --upload-file "$APK" "$base/$VERSION/punktfunk-android-r$VERSION.apk"
+          echo "published store version $VERSION (versionCode)"
+          # 2) channel alias for a predictable sideload URL: stable -> latest/, canary -> canary/
+          case "$GITHUB_REF" in refs/tags/v*) ALIAS=latest ;; *) ALIAS=canary ;; esac
+          curl -fsS -o /dev/null --user "enricobuehler:$REGISTRY_TOKEN" -X DELETE "$base/$ALIAS/punktfunk-android.apk" || true
+          curl -fsS --user "enricobuehler:$REGISTRY_TOKEN" --upload-file "$APK" "$base/$ALIAS/punktfunk-android.apk"
+          echo "sideload alias: $base/$ALIAS/punktfunk-android.apk"
+          # 3) on a real release, attach the .aab + .apk to the unified Gitea Release (X.Y.Z names)
+          case "$GITHUB_REF" in
+            refs/tags/v*)
+              . scripts/ci/gitea-release.sh
+              RID=$(ensure_release "$GITHUB_REF_NAME" "$GITHUB_REF_NAME" auto)
+              upsert_asset "$RID" "$AAB" "punktfunk-${VERSION_NAME}.aab"
+              upsert_asset "$RID" "$APK" "punktfunk-${VERSION_NAME}.apk"
+              ;;
+          esac
+
+      # Direct Publishing-API upload instead of r0adkll/upload-google-play — that action hides the
+      # real API error behind "Unknown error occurred."; this prints it. stdlib + openssl only (no
+      # pip), reuses SERVICE_ACCOUNT_JSON (raw JSON or base64), auto-handles changesNotSentForReview.
+      # Track: canary main -> `internal`; a vX.Y.Z release -> `alpha` (closed testing) for manual
+      # promotion to production in the Play console.
+      - name: Upload to Google Play
+        if: github.event_name == 'push' && (github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/v'))
+        env:
+          SERVICE_ACCOUNT_JSON: ${{ secrets.SERVICE_ACCOUNT_JSON }}
+        run: |
+          echo "uploading to Play track '$PLAY_TRACK'"
+          python3 clients/android/ci/play-upload.py \
+            --package io.unom.punktfunk \
+            --aab clients/android/app/build/outputs/bundle/release/app-release.aab \
+            --track "$PLAY_TRACK" --status completed
@@ -0,0 +1,96 @@
+# Apple client CI — runs on the self-hosted macOS runner (home-mac-mini-1, host mode;
+# see scripts/ci/setup-macos-runner.sh). Builds the Rust core into
+# PunktfunkCore.xcframework, then builds + tests the Swift package. Network-dependent
+# tests (RemoteFirstLightTests) self-skip without PUNKTFUNK_REMOTE_HOST.
+#
+# A second job (`screenshots`) captures the App Store Connect screenshots of the REAL UI
+# (mac window + iOS/iPad/tvOS Simulators, see clients/apple/tools/screenshots.sh) and attaches
+# them to the run as a single zip artifact (`punktfunk-appstore-screenshots`). It is isolated
+# from the build/test job and best-effort, so a capture gap never reds the core signal.
+name: apple
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  swift:
+    runs-on: macos-arm64
+    timeout-minutes: 60
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Rust toolchain (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-apple-darwin x86_64-apple-darwin
+
+      - name: Build PunktfunkCore.xcframework
+        run: bash scripts/build-xcframework.sh
+
+      - name: Build (PunktfunkKit + PunktfunkClient app shell)
+        working-directory: clients/apple
+        run: swift build
+
+      - name: Test (unit + real-codec round trip; remote tests self-skip)
+        working-directory: clients/apple
+        run: swift test
+
+  # App Store screenshots of the real UI, zipped and attached to the run as a build artifact.
+  # Skipped on PRs (cost); runs on main pushes + manual dispatch. Needs the build/test job green
+  # first, and is a separate job so a capture hiccup can never red the core signal.
+  #
+  # Scope = the two REQUIRED iOS sizes (iPhone 6.9" + iPad 13"), captured on the Simulator
+  # (`simctl io screenshot`, no Screen Recording grant needed). macOS and tvOS are deliberately
+  # NOT in CI: the self-hosted runner is headless (no window-server session), so the mac window
+  # capture can't run there; tvOS needs the Tier-3 build-std slice. Generate those two locally on
+  # a GUI Mac with `clients/apple/tools/screenshots.sh macos tvos`.
+  screenshots:
+    needs: swift
+    if: gitea.event_name != 'pull_request'
+    runs-on: macos-arm64
+    timeout-minutes: 75
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Rust toolchain + iOS Simulator targets
+        run: |
+          if ! command -v rustup >/dev/null && [ ! -x "$HOME/.cargo/bin/rustup" ]; then
+            curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs \
+              | sh -s -- -y --no-modify-path --profile minimal
+          fi
+          RUSTUP="$(command -v rustup || echo "$HOME/.cargo/bin/rustup")"
+          dirname "$RUSTUP" >> "$GITHUB_PATH"
+          "$RUSTUP" target add aarch64-apple-darwin x86_64-apple-darwin \
+            aarch64-apple-ios aarch64-apple-ios-sim x86_64-apple-ios
+
+      - name: Build PunktfunkCore.xcframework (mac + iOS slices)
+        run: BUILD_IOS=1 bash scripts/build-xcframework.sh
+
+      - name: Capture screenshots (iPhone 6.9" + iPad 13"; auto-creates the Simulators)
+        working-directory: clients/apple
+        env:
+          SETTLE: "8" # Simulators settle slower than a local run
+        run: |
+          # Independent invocations: one platform failing skips it, not the other.
+          bash tools/screenshots.sh ios  || echo "::warning::iOS (iPhone 6.9\") screenshots skipped"
+          bash tools/screenshots.sh ipad || echo "::warning::iPad 13\" screenshots skipped"
+          echo "Produced:"; ls -la screenshots || true
+
+      - name: Upload screenshots (zip artifact)
+        if: always()
+        # v3, not v4: Gitea's artifact backend identifies as GHES, which @actions/artifact v2+
+        # (upload-artifact@v4) refuses. v3 uses the older API Gitea supports; download is still a zip.
+        uses: actions/upload-artifact@v3
+        with:
+          name: punktfunk-appstore-screenshots
+          path: clients/apple/screenshots
+          if-no-files-found: warn
+          retention-days: 30
@@ -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
@@ -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
@@ -0,0 +1,143 @@
+# CI for punktfunk (Gitea Actions). Linux jobs run on the `ubuntu-latest` runner; the Rust
+# job runs inside the prebuilt builder image (ci/rust-ci.Dockerfile — system FFmpeg 8,
+# PipeWire, GL/GBM, libcuda link stub, pinned-channel rustup) so the workspace links the
+# same libs as the dev boxes. Apple client CI lives in apple.yml (macOS runner).
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  rust:
+    runs-on: ubuntu-24.04
+    container:
+      image: git.unom.io/unom/punktfunk-rust-ci:latest
+    timeout-minutes: 90
+    steps:
+      - uses: actions/checkout@v4
+
+      # punktfunk-client-linux link deps. Also baked into rust-ci.Dockerfile — but ci.yml
+      # runs against the image from the PREVIOUS push (docker.yml bootstrap note), so this
+      # keeps the job green across image-content changes; a no-op once the image has them.
+      - name: GTK4/libadwaita/SDL3 dev packages
+        run: |
+          apt-get update
+          apt-get install -y --no-install-recommends libgtk-4-dev libadwaita-1-dev libsdl3-dev
+
+      # Best-effort caches (act_runner's built-in cache server). Keyed on Cargo.lock:
+      # registry/git are download caches, target/ the incremental build. The target key
+      # carries the rustc version — rust-toolchain.toml pins the floating "stable"
+      # channel, so the file alone wouldn't invalidate stale incremental state.
+      - name: Cache keys
+        run: echo "rustc=$(rustc --version | cut -d' ' -f2)" >> "$GITHUB_ENV"
+      - uses: actions/cache@v4
+        with:
+          path: |
+            /usr/local/cargo/registry
+            /usr/local/cargo/git
+          key: cargo-home-${{ hashFiles('Cargo.lock') }}
+          restore-keys: cargo-home-
+      - uses: actions/cache@v4
+        with:
+          path: target
+          # -v3-: the prior `cargo-target-<rustc>-*` cache was poisoned when the runner ran
+          # 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
+
+      - name: Clippy (deny warnings)
+        run: cargo clippy --workspace --all-targets --locked -- -D warnings
+
+      - name: Build
+        run: cargo build --workspace --locked
+
+      - name: Test (unit + loopback + proptest + C ABI harness)
+        run: cargo test --workspace --locked
+
+      - name: C ABI harness (standalone link proof)
+        run: bash crates/punktfunk-core/tests/c/run.sh
+
+      - name: Verify generated header is committed & up to date
+        run: |
+          cargo build -p punktfunk-core --locked
+          git config --global --add safe.directory "$PWD"
+          git diff --exit-code include/punktfunk_core.h \
+            || (echo "include/punktfunk_core.h is stale — commit the regenerated header" && exit 1)
+
+  web:
+    runs-on: ubuntu-24.04
+    container:
+      image: oven/bun:1
+    timeout-minutes: 30
+    defaults:
+      run:
+        working-directory: web
+    steps:
+      # oven/bun ships neither git nor a real node (only a bun shim) — actions/checkout
+      # needs both. The slim Debian base also lacks ca-certificates, so without it git's
+      # HTTPS fetch of the repo dies with "Problem with the SSL CA cert (path? access
+      # rights?)" — no CA bundle to validate git.unom.io's (public) Let's Encrypt cert.
+      - name: Install git + node + CA certs
+        working-directory: /
+        run: apt-get update && apt-get install -y --no-install-recommends ca-certificates git nodejs
+      - uses: actions/checkout@v4
+      - name: Install dependencies
+        run: bun install --frozen-lockfile --ignore-scripts
+      # Build first: it generates the orval API client + paraglide messages that
+      # typechecking imports.
+      - name: Build
+        run: bun run build
+      - name: Typecheck
+        run: bun run lint
+
+  docs-site:
+    runs-on: ubuntu-24.04
+    container:
+      image: oven/bun:1
+    timeout-minutes: 30
+    defaults:
+      run:
+        working-directory: docs-site
+    steps:
+      # ca-certificates: the slim Debian base lacks a CA bundle, so actions/checkout's
+      # HTTPS fetch otherwise fails with "Problem with the SSL CA cert" (see web job).
+      - name: Install git + CA certs
+        working-directory: /
+        run: apt-get update && apt-get install -y --no-install-recommends ca-certificates git
+      - uses: actions/checkout@v4
+      - name: Install dependencies
+        run: bun install --frozen-lockfile --ignore-scripts
+      # Build first: fumadocs-mdx emits the .source typegen the typecheck imports.
+      - name: Build
+        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
@@ -0,0 +1,144 @@
+# Build the punktfunk-host and punktfunk-client .debs and publish them to Gitea's Debian
+# package registry, so Ubuntu boxes get new builds via `apt update && apt upgrade`. Runs
+# inside the same Ubuntu 26.04 rust-ci builder image as ci.yml, so dpkg-shlibdeps pins the
+# runtime lib package names (libavcodec62, libpipewire-0.3-0t64, …) to exactly what the
+# target boxes run.
+#
+# Registry (public, unom org): https://git.unom.io/unom/-/packages
+# Box setup (once):  see packaging/debian/README.md
+#
+# REGISTRY_TOKEN: repo Actions secret, a PAT with write:package scope (shared with docker.yml).
+name: deb
+
+on:
+  push:
+    branches: [main]
+    # Single project version: a `vX.Y.Z` tag is THE release for every platform (see
+    # docs-site channels.md). The old version-shadow (a client tag shipping a host package
+    # that outranked rolling builds) is now structurally impossible — main publishes to the
+    # `canary` apt distribution, tags to `stable`, so the two never share a version line.
+    tags: ['v*']
+  workflow_dispatch:
+
+env:
+  REGISTRY: git.unom.io
+  OWNER: unom
+  COMPONENT: main
+
+jobs:
+  build-publish:
+    runs-on: ubuntu-24.04
+    container:
+      image: git.unom.io/unom/punktfunk-rust-ci:latest
+    timeout-minutes: 90
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Version + channel
+        # vX.Y.Z tag -> X.Y.Z, published to the `stable` apt distribution (a real release).
+        # A main push -> 0.3.0~ciN.g<sha>, published to the `canary` distribution: the '~' sorts
+        # below the eventual 0.3.0 tag, it climbs monotonically by run number, and the canary base
+        # stays one minor AHEAD of the latest stable so a stable->canary box re-point still moves
+        # forward (see channels.md). Computed BEFORE the build so it's stamped into the binary
+        # (PUNKTFUNK_BUILD_VERSION -> build.rs -> --version).
+        run: |
+          SHORT=$(echo "$GITHUB_SHA" | cut -c1-8)
+          case "$GITHUB_REF" in
+            refs/tags/v*) V="${GITHUB_REF_NAME#v}"; DIST=stable ;;
+            *)            V="0.3.0~ci${GITHUB_RUN_NUMBER}.g${SHORT}"; DIST=canary ;;
+          esac
+          echo "VERSION=$V" >> "$GITHUB_ENV"
+          echo "DISTRIBUTION=$DIST" >> "$GITHUB_ENV"
+          echo "package version $V -> apt distribution '$DIST'"
+
+      # 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
+      # changes; a no-op once the image has them.
+      - name: dpkg-dev + client link deps
+        run: |
+          apt-get update
+          # python3 is used by scripts/ci/gitea-release.sh for the stable-tag release attach.
+          apt-get install -y --no-install-recommends dpkg-dev python3 \
+            libgtk-4-dev libadwaita-1-dev libsdl3-dev
+
+      # Share ci.yml's cache keys so the release build reuses its registry + target artifacts.
+      - name: Cache keys
+        run: echo "rustc=$(rustc --version | cut -d' ' -f2)" >> "$GITHUB_ENV"
+      - uses: actions/cache@v4
+        with:
+          path: |
+            /usr/local/cargo/registry
+            /usr/local/cargo/git
+          key: cargo-home-${{ hashFiles('Cargo.lock') }}
+          restore-keys: cargo-home-
+      - uses: actions/cache@v4
+        with:
+          path: target
+          # -v3-: bypass a target cache poisoned by a disk-full build (see ci.yml). Shares the
+          # 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: Build + smoke-boot web console (node-server preset)
+        # Gate the .deb on a real node boot: the punktfunk-web .deb runs `node .output/server`,
+        # so prove the node-server build exists, isn't a bun bundle, and actually serves /login.
+        run: |
+          # bun builds the console. It's baked into the rust-ci image, but bootstrap it here too so
+          # the job stays green against the PREVIOUS image (docker.yml bootstrap lag).
+          command -v bun >/dev/null || {
+            apt-get install -y --no-install-recommends unzip
+            curl -fsSL https://bun.sh/install | bash
+          }
+          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:
+          TOKEN: ${{ secrets.REGISTRY_TOKEN }}
+        run: |
+          for DEB in dist/*.deb; do
+            echo "uploading $DEB"
+            # PAT owner (enricobuehler), not the push actor — matches docker.yml's registry login.
+            curl -fsS --user "enricobuehler:$TOKEN" --upload-file "$DEB" \
+              "https://$REGISTRY/api/packages/$OWNER/debian/pool/$DISTRIBUTION/$COMPONENT/upload"
+          done
+          echo "published to $OWNER/debian $DISTRIBUTION/$COMPONENT"
+
+      # On a real release, also attach the .debs to the unified Gitea Release so they're on the
+      # downloads page next to every other platform's artifact (canary builds live in the apt
+      # `canary` distribution above — no release page for those).
+      - name: Attach .debs to the Gitea release (stable tags only)
+        if: startsWith(gitea.ref, 'refs/tags/v')
+        env:
+          GITEA_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
+        run: |
+          . scripts/ci/gitea-release.sh
+          RID=$(ensure_release "$GITHUB_REF_NAME" "$GITHUB_REF_NAME" auto)
+          for DEB in dist/*.deb; do
+            upsert_asset "$RID" "$DEB"
+          done
@@ -0,0 +1,123 @@
+# 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 + channel
+        # Tag vX.Y.Z -> X.Y.Z (stable `latest/` alias + Gitea Release); main push -> 0.3.0-ciN.g<sha>
+        # (`canary/` alias). Used for the registry version path + the zip name (the plugin.json
+        # version is the source of truth Decky reads after install — bump it in the release commit).
+        working-directory: ${{ gitea.workspace }}
+        run: |
+          SHORT=$(echo "$GITHUB_SHA" | cut -c1-8)
+          case "$GITHUB_REF" in
+            refs/tags/v*) V="${GITHUB_REF_NAME#v}"; ALIAS=latest ;;
+            *)            V="0.3.0-ci${GITHUB_RUN_NUMBER}.g${SHORT}"; ALIAS=canary ;;
+          esac
+          echo "VERSION=$V" >> "$GITHUB_ENV"
+          echo "ALIAS=$ALIAS" >> "$GITHUB_ENV"
+          echo "decky version $V -> alias '$ALIAS'"
+
+      - 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" "$DEST/bin"
+          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/"
+          # The stream-launch wrapper (target of the Steam shortcut); keep it executable
+          # (runner_info() also re-chmods at runtime in case the zip/extract drops the bit).
+          cp clients/decky/bin/punktfunkrun.sh "$DEST/bin/"
+          chmod 0755 "$DEST/bin/punktfunkrun.sh"
+          # Store requires a LICENSE in the plugin root; the project is MIT OR Apache-2.0.
+          cp LICENSE-MIT                 "$DEST/LICENSE"
+          ( 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) Channel alias (stable release -> latest/, canary main build -> canary/) — the link
+          #    to paste into Decky's "install from URL". The generic registry rejects re-uploading
+          #    an existing version/file (409), so delete the prior alias first (ignore 404 on run #1).
+          curl -fsS -o /dev/null --user "enricobuehler:$TOKEN" -X DELETE \
+            "$BASE/$ALIAS/punktfunk.zip" || true
+          curl -fsS --user "enricobuehler:$TOKEN" --upload-file "$RUNNER_TEMP/punktfunk.zip" \
+            "$BASE/$ALIAS/punktfunk.zip"
+          echo "install-from-URL link: $BASE/$ALIAS/punktfunk.zip"
+
+      - name: Attach zip to the Gitea release (stable tags only)
+        if: startsWith(gitea.ref, 'refs/tags/v')
+        working-directory: ${{ gitea.workspace }}
+        env:
+          GITEA_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
+        run: |
+          . scripts/ci/gitea-release.sh
+          RID=$(ensure_release "$GITHUB_REF_NAME" "$GITHUB_REF_NAME" auto)
+          upsert_asset "$RID" "$RUNNER_TEMP/punktfunk.zip" "punktfunk-${VERSION}.zip"
@@ -0,0 +1,115 @@
+# Build + push the dockerized pieces to the Gitea container registry:
+#   punktfunk-web      — management console (web/Dockerfile, repo-root context)
+#   punktfunk-docs     — documentation site (docs-site/Dockerfile)
+#   punktfunk-rust-ci  — Rust CI builder image consumed by ci.yml
+#   punktfunk-fedora-rpm — Fedora 43 builder image consumed by rpm.yml (Bazzite RPM)
+# Host and clients are intentionally NOT containerized (see CLAUDE.md "What's left").
+#
+# REGISTRY_TOKEN: repo Actions secret, a PAT with write:package scope.
+#
+# Bootstrap note: ci.yml's rust job pulls punktfunk-rust-ci:latest from the registry, so
+# this workflow (or a manual push) must have succeeded once before that job can run; on
+# the same push, ci.yml builds against the PREVIOUS image. All three were seeded manually
+# on 2026-06-12.
+name: docker
+
+on:
+  push:
+    branches: [main]
+    tags: ['v*']
+  workflow_dispatch:
+
+env:
+  REGISTRY: git.unom.io
+  OWNER: unom
+
+jobs:
+  build-push:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 45
+    strategy:
+      matrix:
+        include:
+          - image: punktfunk-web
+            dockerfile: web/Dockerfile
+            context: .
+          - image: punktfunk-docs
+            dockerfile: docs-site/Dockerfile
+            context: docs-site
+          - image: punktfunk-rust-ci
+            dockerfile: ci/rust-ci.Dockerfile
+            context: ci
+          - image: punktfunk-fedora-rpm
+            dockerfile: ci/fedora-rpm.Dockerfile
+            context: ci
+          # Fedora 44 builder (Fedora KDE spin): same Dockerfile, newer base → libavcodec.so.62.
+          - image: punktfunk-fedora44-rpm
+            dockerfile: ci/fedora-rpm.Dockerfile
+            context: ci
+            buildargs: --build-arg FEDORA_VERSION=44
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Login to registry
+        # Username must be the owner of the REGISTRY_TOKEN PAT, not the push actor.
+        run: |
+          echo "${{ secrets.REGISTRY_TOKEN }}" \
+            | docker login "$REGISTRY" -u enricobuehler --password-stdin
+
+      - name: Build
+        run: |
+          # On a release tag, also tag the image vX.Y.Z so a release pins reproducible web/docs images.
+          EXTRA=""
+          case "$GITHUB_REF" in refs/tags/v*) EXTRA="-t $REGISTRY/$OWNER/${{ matrix.image }}:${GITHUB_REF_NAME}" ;; esac
+          docker build --pull ${{ matrix.buildargs }} \
+            -f "${{ matrix.dockerfile }}" \
+            -t "$REGISTRY/$OWNER/${{ matrix.image }}:latest" \
+            -t "$REGISTRY/$OWNER/${{ matrix.image }}:sha-${GITHUB_SHA::8}" \
+            $EXTRA \
+            "${{ matrix.context }}"
+
+      - name: Push
+        run: |
+          docker push "$REGISTRY/$OWNER/${{ matrix.image }}:sha-${GITHUB_SHA::8}"
+          docker push "$REGISTRY/$OWNER/${{ matrix.image }}:latest"
+          case "$GITHUB_REF" in refs/tags/v*) docker push "$REGISTRY/$OWNER/${{ matrix.image }}:${GITHUB_REF_NAME}" ;; esac
+
+  # Deploy the docs site to unom-1, the DMZ services VM website/cms also deploy to
+  # (docs.punktfunk.unom.io via Caddy on home-reverse-proxy-1 -> :3220). Same secret set
+  # as unom/website's deploy: DEPLOY_HOST/DEPLOY_USER/DEPLOY_PORT/DEPLOY_SSH_KEY (the
+  # unom-ci-deploy key).
+  deploy-docs:
+    runs-on: ubuntu-24.04
+    needs: build-push
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Sync compose file
+        uses: appleboy/scp-action@v0.1.7
+        with:
+          host: ${{ secrets.DEPLOY_HOST }}
+          username: ${{ secrets.DEPLOY_USER }}
+          port: ${{ secrets.DEPLOY_PORT }}
+          key: ${{ secrets.DEPLOY_SSH_KEY }}
+          source: "compose.production.yml"
+          target: "~/punktfunk-docs"
+          overwrite: true
+
+      - name: Pull and start docs
+        uses: appleboy/ssh-action@v1.2.5
+        env:
+          REGISTRY_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
+        with:
+          host: ${{ secrets.DEPLOY_HOST }}
+          username: ${{ secrets.DEPLOY_USER }}
+          port: ${{ secrets.DEPLOY_PORT }}
+          key: ${{ secrets.DEPLOY_SSH_KEY }}
+          # Token enters via env, never the script text (keeps it out of run logs).
+          envs: REGISTRY_TOKEN
+          script: |
+            set -euo pipefail
+            printf '%s' "$REGISTRY_TOKEN" | docker login git.unom.io -u enricobuehler --password-stdin
+            cd ~/punktfunk-docs
+            docker compose -f compose.production.yml pull docs
+            docker compose -f compose.production.yml up -d --no-build docs
@@ -0,0 +1,237 @@
+# 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:
+      - 'clients/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
+  REPO_URL: https://flatpak.unom.io   # shared unom OSTree repo (reusable across unom apps)
+  DEPLOY_DIR: unom-flatpak             # ~/<dir> on unom-1 (compose + ./site tree)
+
+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`).
+          # gnupg2/rsync/openssh-clients: sign the OSTree repo + rsync it to unom-1 (see the deploy step).
+          dnf -y install flatpak flatpak-builder git python3 python3-aiohttp python3-tomlkit curl jq \
+            gnupg2 rsync openssh-clients
+          # 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 + channel
+        # Tag vX.Y.Z -> X.Y.Z on the OSTree `stable` branch (a real release); a main push ->
+        # 0.3.0-ciN.g<sha> on the `canary` branch. The two branches live side-by-side in one repo
+        # (rsync runs without --delete), each tracked by its own .flatpakref, so `flatpak update`
+        # on a stable box never jumps to a canary build. The generic-registry version string allows
+        # letters/dots/hyphens.
+        run: |
+          SHORT=$(echo "$GITHUB_SHA" | cut -c1-8)
+          case "$GITHUB_REF" in
+            refs/tags/v*) V="${GITHUB_REF_NAME#v}"; BRANCH=stable; ALIAS=latest ;;
+            *)            V="0.3.0-ci${GITHUB_RUN_NUMBER}.g${SHORT}"; BRANCH=canary; ALIAS=canary ;;
+          esac
+          echo "VERSION=$V" >> "$GITHUB_ENV"
+          echo "BUNDLE=punktfunk-client-${V}.flatpak" >> "$GITHUB_ENV"
+          echo "FLATPAK_BRANCH=$BRANCH" >> "$GITHUB_ENV"
+          echo "ALIAS=$ALIAS" >> "$GITHUB_ENV"
+          echo "flatpak version $V -> branch '$BRANCH' alias '$ALIAS'"
+
+      - 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).
+        #
+        # Prune the microsoft/windows-rs git crates first: they belong to
+        # punktfunk-client-windows, which the flatpak never builds, and leaving them in makes
+        # flatpak-builder full-clone that multi-GB repo at build time → "No space left on
+        # device" (see packaging/flatpak/prune-windows-lock.py). The committed Cargo.lock is
+        # untouched; cargo --offline only needs sources for the crates it compiles.
+        run: |
+          curl -fsSL -o /tmp/flatpak-cargo-generator.py \
+            https://raw.githubusercontent.com/flatpak/flatpak-builder-tools/master/cargo/flatpak-cargo-generator.py
+          python3 packaging/flatpak/prune-windows-lock.py Cargo.lock /tmp/Cargo.flatpak.lock
+          python3 /tmp/flatpak-cargo-generator.py /tmp/Cargo.flatpak.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).
+          # --default-branch=$FLATPAK_BRANCH pins the ref to app/io.unom.Punktfunk/x86_64/<branch>
+          # (canary or stable) so the matching hosted .flatpakref resolves deterministically
+          # (manifest sets no branch).
+          flatpak-builder --user --force-clean --disable-rofiles-fuse \
+            --default-branch="$FLATPAK_BRANCH" \
+            --install-deps-from=flathub \
+            --repo="$PWD/repo" \
+            "$PWD/build-dir" "$MANIFEST"
+
+      - name: Export single-file bundle
+        run: |
+          # Branch must be passed explicitly (matches --default-branch above); build-bundle
+          # otherwise defaults to `master` and errors "Refspec … not found".
+          flatpak build-bundle "$PWD/repo" "$BUNDLE" "$APP_ID" "$FLATPAK_BRANCH"
+          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) Channel alias (stable release -> latest/, canary main build -> canary/) for the
+          #    Decky fallback + scripts. The generic registry rejects re-uploading an existing
+          #    version/file (409), so delete the prior alias file first (ignore 404 on run #1).
+          curl -fsS -o /dev/null --user "enricobuehler:$TOKEN" -X DELETE \
+            "$BASE/$ALIAS/punktfunk-client.flatpak" || true
+          curl -fsS --user "enricobuehler:$TOKEN" --upload-file "$BUNDLE" \
+            "$BASE/$ALIAS/punktfunk-client.flatpak"
+          echo "published $BASE/$ALIAS/punktfunk-client.flatpak"
+
+      # Sign the OSTree repo flatpak-builder already produced and publish it to flatpak.unom.io on
+      # unom-1, so users get `flatpak update` (the single-file bundle above has no remote). Mirrors
+      # docker.yml's deploy-docs (DEPLOY_* = the unom-ci-deploy key). No-ops cleanly until the GPG
+      # secret + DEPLOY_* exist, so the bundle build stays green during setup.
+      - name: Sign + deploy the OSTree repo to unom-1 (flatpak.unom.io)
+        env:
+          FLATPAK_GPG_PRIVATE_KEY: ${{ secrets.FLATPAK_GPG_PRIVATE_KEY }}
+          DEPLOY_HOST: ${{ secrets.DEPLOY_HOST }}
+          DEPLOY_USER: ${{ secrets.DEPLOY_USER }}
+          DEPLOY_PORT: ${{ secrets.DEPLOY_PORT }}
+          DEPLOY_SSH_KEY: ${{ secrets.DEPLOY_SSH_KEY }}
+        run: |
+          set -euo pipefail
+          if [ -z "${FLATPAK_GPG_PRIVATE_KEY:-}" ] || [ -z "${DEPLOY_HOST:-}" ]; then
+            echo "::warning::FLATPAK_GPG_PRIVATE_KEY/DEPLOY_* not set — skipping repo deploy (bundle still published)."
+            exit 0
+          fi
+          # 1) Import the signing key into a throwaway keyring; sign the repo.
+          export GNUPGHOME="$(mktemp -d)"; chmod 700 "$GNUPGHOME"
+          echo "$FLATPAK_GPG_PRIVATE_KEY" | base64 -d | gpg --batch --import
+          KEYID="$(gpg --list-keys --with-colons | awk -F: '/^fpr:/{print $10; exit}')"
+          # build-sign signs the COMMIT objects; build-update-repo signs the SUMMARY. Both are
+          # required — clients with gpg-verify=true verify the commit, so summary-only signing
+          # fails the pull with "GPG verification enabled, but no signatures found".
+          flatpak build-sign "$PWD/repo" "$APP_ID" "$FLATPAK_BRANCH" \
+            --gpg-sign="$KEYID" --gpg-homedir="$GNUPGHOME"
+          flatpak build-update-repo --generate-static-deltas \
+            --gpg-sign="$KEYID" --gpg-homedir="$GNUPGHOME" "$PWD/repo"
+          # 2) Build the install descriptors (GPGKey = the committed public key, base64).
+          GPGKEY="$(base64 -w0 packaging/flatpak/unom-flatpak.gpg)"
+          rm -rf site && mkdir -p site
+          cat > site/unom.flatpakrepo <<EOF
+          [Flatpak Repo]
+          Title=unom
+          Url=$REPO_URL/repo/
+          Homepage=https://punktfunk.unom.io
+          Comment=unom Flatpak applications
+          GPGKey=$GPGKEY
+          EOF
+          # Two refs, one per channel — both regenerated every run and rsync'd without --delete, so
+          # the server always offers both (the stable ref only resolves once a release has built the
+          # `stable` branch). A box installs ONE; `flatpak update` then tracks that channel's branch.
+          write_ref() {  # <filename> <branch> <title>
+            cat > "site/$1" <<EOF
+          [Flatpak Ref]
+          Name=$APP_ID
+          Branch=$2
+          Url=$REPO_URL/repo/
+          Title=$3
+          Homepage=https://punktfunk.unom.io
+          IsRuntime=false
+          GPGKey=$GPGKEY
+          RuntimeRepo=https://dl.flathub.org/repo/flathub.flatpakrepo
+          EOF
+          }
+          write_ref "${APP_ID}.flatpakref"        stable "Punktfunk"
+          write_ref "${APP_ID}.Canary.flatpakref" canary "Punktfunk (Canary)"
+          cat > site/index.html <<EOF
+          <!doctype html><meta charset=utf-8><title>unom flatpak repo</title>
+          <h1>unom Flatpak repository</h1>
+          <p>Install the Punktfunk Linux client (auto-adds Flathub for the GNOME runtime, then tracks updates).</p>
+          <p><b>Stable</b> (recommended — only moves on releases):</p>
+          <pre>flatpak install --user $REPO_URL/${APP_ID}.flatpakref
+          flatpak run $APP_ID</pre>
+          <p><b>Canary</b> (latest main build, unstable):</p>
+          <pre>flatpak install --user $REPO_URL/${APP_ID}.Canary.flatpakref</pre>
+          <p>Or add the whole remote: <code>flatpak remote-add --user --if-not-exists unom $REPO_URL/unom.flatpakrepo</code></p>
+          EOF
+          # 3) Ship to unom-1 and (re)start the static server. rsync WITHOUT --delete keeps old
+          #    objects so clients mid-update aren't broken; the fresh signed summary advertises latest.
+          install -d -m700 ~/.ssh
+          printf '%s\n' "$DEPLOY_SSH_KEY" > ~/.ssh/deploy; chmod 600 ~/.ssh/deploy
+          SSH="ssh -i $HOME/.ssh/deploy -p ${DEPLOY_PORT:-22} -o StrictHostKeyChecking=accept-new"
+          DEST="${DEPLOY_USER}@${DEPLOY_HOST}"
+          $SSH "$DEST" "mkdir -p ~/$DEPLOY_DIR/site/repo"
+          rsync -az --info=stats1 -e "$SSH" repo/ "$DEST:$DEPLOY_DIR/site/repo/"
+          rsync -az -e "$SSH" site/unom.flatpakrepo "site/${APP_ID}.flatpakref" "site/${APP_ID}.Canary.flatpakref" site/index.html "$DEST:$DEPLOY_DIR/site/"
+          rsync -az -e "$SSH" packaging/flatpak/server/compose.production.yml packaging/flatpak/server/Caddyfile "$DEST:$DEPLOY_DIR/"
+          $SSH "$DEST" "cd ~/$DEPLOY_DIR && docker compose -f compose.production.yml up -d"
+          echo "deployed → $REPO_URL/${APP_ID}.flatpakref"
+
+      - name: Attach bundle to the Gitea release (stable tags only)
+        if: startsWith(gitea.ref, 'refs/tags/v')
+        env:
+          GITEA_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
+        run: |
+          . scripts/ci/gitea-release.sh
+          RID=$(ensure_release "$GITHUB_REF_NAME" "$GITHUB_REF_NAME" auto)
+          upsert_asset "$RID" "$BUNDLE"
@@ -0,0 +1,346 @@
+# Production Apple client builds — runs on the macos-arm64 runner (home-mac-mini-1).
+#
+#   Tag v* (or workflow_dispatch):
+#     macOS (Developer ID) -> sandboxed, signed, notarized + stapled .dmg, attached to a
+#               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   -> archive + upload to TestFlight (Rust core built from tier-3 targets,
+#               nightly -Zbuild-std, in build-xcframework.sh)
+#
+# One App Store listing for all platforms (universal purchase): every target shares the
+# bundle ID io.unom.punktfunk.
+#
+# The macOS app is App-SANDBOXED for both channels (Config/Punktfunk-macOS.entitlements —
+# app-sandbox + network client/server + audio-input + bluetooth/usb device access; the
+# shared Config/Punktfunk.entitlements stays iOS/tvOS-only, where app-sandbox is invalid).
+# The Developer ID DMG is codesigned with the SAME macOS entitlements, so what we test
+# locally equals what App Store users get.
+#
+# 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
+# loud warning.
+name: release
+
+on:
+  push:
+    # Canary: a relevant main push uploads the iOS + macOS + tvOS builds to TestFlight (Apple's
+    # own canary channel) — no notarized DMG (that's stable-only; see the per-step gates).
+    # Heavy on the shared mac-mini runner, so paths-filtered; the TestFlight steps are
+    # continue-on-error until the App Store Connect record exists, so this no-ops until then.
+    branches: [main]
+    paths:
+      - 'clients/apple/**'
+      - 'crates/punktfunk-core/**'
+      - 'scripts/build-xcframework.sh'
+      - 'Cargo.lock'
+      - '.gitea/workflows/release.yml'
+    # Stable: a `vX.Y.Z` tag is THE release — notarized DMG attached to the unified Gitea Release
+    # + macOS/iOS/tvOS to TestFlight for manual promotion to the App Store.
+    tags: ['v*']
+  workflow_dispatch:
+    inputs:
+      testflight:
+        description: "Upload the iOS build to TestFlight (true/false)"
+        required: false
+        default: "true"
+
+jobs:
+  apple:
+    runs-on: macos-arm64
+    timeout-minutes: 120
+    env:
+      TEAM_ID: F4H37KF6WC
+      PROJECT: clients/apple/Punktfunk.xcodeproj
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Select release Xcode
+        run: |
+          DEV_DIR=""
+          for app in /Applications/Xcode.app /Applications/Xcode_*.app /Applications/Xcode-*.app; do
+            case "$app" in *beta*|*Beta*) continue;; esac
+            [ -x "$app/Contents/Developer/usr/bin/xcodebuild" ] && DEV_DIR="$app/Contents/Developer" && break
+          done
+          if [ -z "$DEV_DIR" ]; then
+            for app in /Applications/Xcode*.app; do
+              [ -x "$app/Contents/Developer/usr/bin/xcodebuild" ] && DEV_DIR="$app/Contents/Developer" && break
+            done
+            echo "::warning::No release Xcode found — using $DEV_DIR. TestFlight/App Store REJECTS beta-SDK builds."
+          fi
+          [ -n "$DEV_DIR" ] || { echo "no usable Xcode found" >&2; exit 1; }
+          # Scoped to xcodebuild steps only (XCODE_DEV_DIR, not DEVELOPER_DIR): cargo must
+          # keep the system-default linker — a newer-than-OS Xcode's ld produces dylibs the
+          # running dyld rejects, killing proc-macro loads (see build-xcframework.sh).
+          echo "XCODE_DEV_DIR=$DEV_DIR" >> "$GITHUB_ENV"
+          DEVELOPER_DIR="$DEV_DIR" xcodebuild -version
+
+      - name: Version from tag
+        run: |
+          case "$GITHUB_REF" in
+            refs/tags/v*) V="${GITHUB_REF_NAME#v}"; V="${V%%-*}" ;;  # App Store marketing version is numeric X.Y.Z (drop -rc)
+            *)            V="0.3.0" ;;                                # canary marketing version; the build number disambiguates
+          esac
+          echo "VERSION=$V" >> "$GITHUB_ENV"
+          echo "BUILD_NUM=$GITHUB_RUN_NUMBER" >> "$GITHUB_ENV"
+          echo "version $V build $GITHUB_RUN_NUMBER"
+
+      - 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 + tvOS)
+        # tvOS is a tier-3 target (nightly -Zbuild-std): slow on the first build, then cached on
+        # the self-hosted runner. Built on canary too so the tvOS archive/upload below runs on the
+        # same track as iOS/macOS (the nightly toolchain is installed unconditionally above).
+        run: BUILD_IOS=1 BUILD_TVOS=1 bash scripts/build-xcframework.sh
+
+      - name: Stage App Store Connect API key
+        env:
+          ASC_P8: ${{ secrets.ASC_API_KEY_P8 }}
+        run: |
+          printf '%s' "$ASC_P8" > "$RUNNER_TEMP/asc.p8"
+          chmod 600 "$RUNNER_TEMP/asc.p8"
+
+      - name: macOS — archive, codesign Developer ID, notarize, DMG
+        # Stable releases only — the notarized DMG is a Gatekeeper/direct-download artifact, not
+        # relevant to TestFlight testers (the canary channel). Skipped on canary main pushes.
+        if: startsWith(gitea.ref, 'refs/tags/v')
+        run: |
+          # Archive UNSIGNED, then codesign with the Developer ID Application identity from the
+          # login keychain. Unsigned archive sidesteps Xcode's keychain-access-groups
+          # provisioning-profile gate; codesign just needs the (now valid) identity + the
+          # team-prefixed entitlements, no profile (App Sandbox + the network/device
+          # capabilities are self-asserted for Developer ID — no profile entry needed).
+          # Bundle is a single static binary.
+          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
+          APP="$RUNNER_TEMP/Punktfunk-macos.xcarchive/Products/Applications/Punktfunk.app"
+          # Sandboxed Developer ID: sign with the SAME macOS entitlements the App Store build
+          # uses. codesign won't expand $(AppIdentifierPrefix) — resolve it to the team prefix.
+          RESOLVED="$RUNNER_TEMP/macos.entitlements"
+          sed "s/\$(AppIdentifierPrefix)/${TEAM_ID}./g" \
+            clients/apple/Config/Punktfunk-macOS.entitlements > "$RESOLVED"
+          codesign --force --options runtime --timestamp \
+            --entitlements "$RESOLVED" \
+            --sign "Developer ID Application" "$APP"
+          codesign --verify --strict --verbose=2 "$APP"
+          # Notarized DMG.
+          STAGE="$RUNNER_TEMP/dmg-stage"
+          mkdir -p "$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"
+          DEVELOPER_DIR="$XCODE_DEV_DIR" xcrun notarytool submit "$DMG" --wait \
+            --key "$RUNNER_TEMP/asc.p8" \
+            --key-id "${{ secrets.ASC_API_KEY_ID }}" \
+            --issuer "${{ secrets.ASC_API_ISSUER_ID }}"
+          DEVELOPER_DIR="$XCODE_DEV_DIR" xcrun stapler staple "$DMG"
+          echo "DMG=$DMG" >> "$GITHUB_ENV"
+
+      - name: Attach DMG to the Gitea release (stable tags only)
+        if: startsWith(gitea.ref, 'refs/tags/v')
+        env:
+          GITEA_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
+        run: |
+          . scripts/ci/gitea-release.sh
+          RID=$(ensure_release "$GITHUB_REF_NAME" "$GITHUB_REF_NAME" auto)
+          upsert_asset "$RID" "$DMG" "Punktfunk-$VERSION.dmg"
+
+      - name: macOS App Store — archive + upload to TestFlight
+        if: gitea.event_name != 'workflow_dispatch' || inputs.testflight == 'true'
+        # Best-effort until the App Store Connect record has the macOS platform + the
+        # "Punktfunk macOS App Store Distribution" profile and the "3rd Party Mac Developer
+        # 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: |
+          # Separate archive from the Developer ID one above: App Store needs a profile-signed
+          # archive (manual signing), not the unsigned-then-codesign DMG path. Same App-Manager
+          # ASC-key constraint as iOS/tvOS — MANUAL signing, NOT -allowProvisioningUpdates
+          # (cloud signing the key can't do). Quit Xcode so it can't prune the dropped profile.
+          osascript -e 'tell application "Xcode" to quit' >/dev/null 2>&1 || true
+          pkill -x Xcode 2>/dev/null || true
+          PROFILE="Punktfunk macOS App Store Distribution"
+          DEVELOPER_DIR="$XCODE_DEV_DIR" xcodebuild archive \
+            -project "$PROJECT" -scheme Punktfunk \
+            -destination 'generic/platform=macOS' \
+            -archivePath "$RUNNER_TEMP/Punktfunk-macos-appstore.xcarchive" \
+            MARKETING_VERSION="$VERSION" CURRENT_PROJECT_VERSION="$BUILD_NUM" \
+            CODE_SIGN_STYLE=Manual \
+            CODE_SIGN_IDENTITY="Apple Distribution" \
+            DEVELOPMENT_TEAM="$TEAM_ID" \
+            PROVISIONING_PROFILE_SPECIFIER="$PROFILE"
+          cat > "$RUNNER_TEMP/export-macos-appstore.plist" <<EOF
+          <?xml version="1.0" encoding="UTF-8"?>
+          <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+          <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" \
+            -skipMacroValidation -skipPackagePluginValidation \
+            -xcconfig "$SIGN_XCCONFIG" \
+            MARKETING_VERSION="$VERSION" CURRENT_PROJECT_VERSION="$BUILD_NUM"
+          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">
+          <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-ios.xcarchive" \
+            -exportOptionsPlist "$RUNNER_TEMP/export-appstore.plist" \
+            -exportPath "$RUNNER_TEMP/export-appstore" \
+            -authenticationKeyPath "$RUNNER_TEMP/asc.p8" \
+            -authenticationKeyID "${{ secrets.ASC_API_KEY_ID }}" \
+            -authenticationKeyIssuerID "${{ secrets.ASC_API_ISSUER_ID }}"
+
+      - name: tvOS — archive + upload to TestFlight
+        # Canary + stable, the same track as iOS/macOS — the tvOS xcframework slice is now built
+        # on every apple push (above), so this matches the iOS step's gate exactly.
+        if: gitea.event_name != 'workflow_dispatch' || inputs.testflight == 'true'
+        # Needs tvOS added to the App Store Connect app record + the tvOS platform installed
+        # on the runner (xcodebuild -downloadPlatform tvOS).
+        continue-on-error: true
+        run: |
+          # Same manual App Store signing as iOS (the App-Manager ASC key can't cloud-sign).
+          osascript -e 'tell application "Xcode" to quit' >/dev/null 2>&1 || true
+          pkill -x Xcode 2>/dev/null || true
+          PROFILE="Punktfunk tvOS App Store Distribution"
+          # Scope signing to the tvOS device SDK via an xcconfig. A global (CLI) profile specifier
+          # hits EVERY target, including the shared SwiftPM macro plugins (OnceMacro/SwizzlingMacro/
+          # AssociationMacro) which build for the macOS host and reject a provisioning profile
+          # ("<macro> does not support provisioning profiles"), failing the archive. Conditionals
+          # work only in an xcconfig (xcodebuild mis-parses a CLI "SETTING[sdk=..]=val"), and a
+          # command-line -xcconfig outranks target settings, so [sdk=appletvos*] puts the profile on
+          # the app/framework slices only — the macosx-host macros get nothing. (The macOS archive
+          # above is immune: its host-SDK macros are CODE_SIGNING_ALLOWED=NO, so a global specifier
+          # is ignored there.)
+          SIGN_XCCONFIG="$RUNNER_TEMP/sign-tvos.xcconfig"
+          cat > "$SIGN_XCCONFIG" <<XCCONF
+          CODE_SIGN_STYLE = Manual
+          DEVELOPMENT_TEAM = $TEAM_ID
+          CODE_SIGN_IDENTITY[sdk=appletvos*] = Apple Distribution
+          PROVISIONING_PROFILE_SPECIFIER[sdk=appletvos*] = $PROFILE
+          XCCONF
+          DEVELOPER_DIR="$XCODE_DEV_DIR" xcodebuild archive \
+            -project "$PROJECT" -scheme Punktfunk-tvOS \
+            -destination 'generic/platform=tvOS' \
+            -archivePath "$RUNNER_TEMP/Punktfunk-tvos.xcarchive" \
+            -skipMacroValidation -skipPackagePluginValidation \
+            -xcconfig "$SIGN_XCCONFIG" \
+            MARKETING_VERSION="$VERSION" CURRENT_PROJECT_VERSION="$BUILD_NUM"
+          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 }}"
@@ -0,0 +1,125 @@
+# Build the punktfunk-host RPM and publish it to Gitea's RPM package registry, so Bazzite /
+# Fedora Atomic hosts layer + update it with rpm-ostree. Counterpart to deb.yml (apt). Runs in
+# the Fedora 43 builder image (ci/fedora-rpm.Dockerfile) so the RPM's auto library Requires
+# (libavcodec.so.NN, …) match the target's sonames.
+#
+# Registry (public, unom org), group "bazzite":
+#   repo file  https://git.unom.io/api/packages/unom/rpm/bazzite.repo
+# Box setup (once): see packaging/rpm/README.md
+#
+# REGISTRY_TOKEN: repo Actions secret, a PAT with write:package scope (shared with docker.yml).
+name: rpm
+
+on:
+  push:
+    branches: [main]
+    # Single project version: a `vX.Y.Z` tag is THE release. main publishes to the `*-canary` rpm
+    # groups, tags to the base groups (`bazzite`/`fedora-44`) — separate repos, so the old
+    # version-shadow (a release outranking rolling builds in one group) is structurally gone.
+    tags: ['v*']
+  workflow_dispatch:
+
+env:
+  REGISTRY: git.unom.io
+  OWNER: unom
+
+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/${{ matrix.image }}:latest
+    timeout-minutes: 90
+    env:
+      CARGO_HOME: /usr/local/cargo
+    steps:
+      - uses: actions/checkout@v4
+
+      # rpmbuild + git archive need the checkout trusted; cache the crates download.
+      # The client link deps are also baked into the fedora-rpm image, but this job runs
+      # against the image from the PREVIOUS push (docker.yml bootstrap note) — keep it
+      # green across image changes; a no-op once the image has them.
+      - name: Prep
+        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
+          key: cargo-home-${{ hashFiles('Cargo.lock') }}
+          restore-keys: cargo-home-
+
+      - name: Version + channel
+        # vX.Y.Z tag -> X.Y.Z-1 in the base group (a real release); main push -> 0.3.0-0.ciN.g<sha>
+        # in the `<base>-canary` group, whose "0." release sorts below the eventual 0.3.0-1 yet
+        # climbs by run number. The canary base stays one minor ahead of the latest stable so a
+        # stable->canary box re-point still moves forward. The spec %build stamps
+        # 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"; GROUP="${{ matrix.group }}" ;;
+            *)            V="0.3.0"; R="0.ci${GITHUB_RUN_NUMBER}.g${SHORT}"; GROUP="${{ matrix.group }}-canary" ;;
+          esac
+          echo "PF_VERSION=$V" >> "$GITHUB_ENV"
+          echo "PF_RELEASE=$R" >> "$GITHUB_ENV"
+          echo "GROUP=$GROUP" >> "$GITHUB_ENV"
+          echo "rpm $V-$R -> group '$GROUP'"
+
+      - name: Build RPM
+        # 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:
+          TOKEN: ${{ secrets.REGISTRY_TOKEN }}
+        run: |
+          # Publish only the main package (skip -debuginfo/-debugsource subpackages).
+          for rpm in dist/*.rpm; do
+            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/$GROUP/upload"
+          done
+          echo "published to $OWNER/rpm/$GROUP"
+
+      # On a real release, also attach the .rpms to the unified Gitea Release. Both Fedora bases
+      # (bazzite=F43, fedora-44) build the SAME filename, so suffix the asset with the base to keep
+      # both on the release; canary builds live in the `*-canary` rpm groups (no release page).
+      - name: Attach .rpms to the Gitea release (stable tags only)
+        if: startsWith(gitea.ref, 'refs/tags/v')
+        env:
+          GITEA_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
+        run: |
+          . scripts/ci/gitea-release.sh
+          RID=$(ensure_release "$GITHUB_REF_NAME" "$GITHUB_REF_NAME" auto)
+          for rpm in dist/*.rpm; do
+            case "$rpm" in *debuginfo*|*debugsource*) continue;; esac
+            base="$(basename "$rpm" .rpm)"
+            upsert_asset "$RID" "$rpm" "${base}.${{ matrix.group }}.rpm"
+          done
@@ -0,0 +1,27 @@
+# One-shot provisioning of the WDK + cargo-wdk onto the persistent self-hosted windows-amd64 runner, so
+# the all-Rust UMDF drivers can build there (docs/windows-host-rewrite.md, M0). The runner has the base
+# Windows SDK + MSVC + LLVM + Rust but NOT the WDK (no km/wdf/iddcx headers) or cargo-wdk.
+#
+# Dispatch manually (workflow_dispatch). Idempotent: re-running is a near no-op once provisioned. The
+# install persists on the runner (real box, not an ephemeral container), so this runs once, not per build.
+name: windows-drivers-provision
+
+on:
+  workflow_dispatch:
+  push:
+    branches: [main]
+    paths:
+      - 'scripts/ci/provision-windows-wdk.ps1'
+      - '.gitea/workflows/windows-drivers-provision.yml'
+
+jobs:
+  provision:
+    runs-on: windows-amd64
+    timeout-minutes: 60
+    defaults:
+      run:
+        shell: pwsh
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install WDK + cargo-wdk on the runner
+        run: ./scripts/ci/provision-windows-wdk.ps1
@@ -0,0 +1,150 @@
+# Windows driver workspace CI — runs on the self-hosted Windows runner (home-windows-1, host mode;
+# label windows-amd64). Part of the Windows-host rewrite (docs/windows-host-rewrite.md, M0).
+#
+# Stage 1 (this file): PROBE the runner's driver toolchain (WDK / EWDK / cargo-make / LLVM / the
+# inf2cat/stampinf/devgen/signtool tools) so we know what's provisioned BEFORE writing driver code,
+# and build+test the owned ABI crate (pf-vdisplay-proto) on MSVC to prove it compiles cross-OS and the
+# CI wiring works. The runner has no RTX GPU — that's fine: builds, the IddCx bindgen/link, the
+# /INTEGRITYCHECK self-sign-load, and (later) IDD-push frame flow on the basic display do not need one;
+# only live NVENC encode does, which defers to the RTX box.
+#
+# shell: pwsh deliberately (PowerShell 5.1's Out-File -Encoding utf8 prepends a BOM that corrupts the
+# first GITHUB_ENV line — see windows.yml).
+name: windows-drivers
+
+on:
+  workflow_dispatch:
+  push:
+    branches: [main]
+    paths:
+      - '.gitea/workflows/windows-drivers.yml'
+      - 'crates/pf-vdisplay-proto/**'
+      - 'packaging/windows/drivers/**'
+  pull_request:
+    paths:
+      - '.gitea/workflows/windows-drivers.yml'
+      - 'crates/pf-vdisplay-proto/**'
+      - 'packaging/windows/drivers/**'
+
+# Driver builds need the WDK on the runner (provision once via windows-drivers-provision.yml).
+
+jobs:
+  probe-and-proto:
+    runs-on: windows-amd64
+    timeout-minutes: 30
+    defaults:
+      run:
+        shell: pwsh
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Probe driver toolchain (informational — never fails the job)
+        continue-on-error: true
+        run: |
+          $ErrorActionPreference = 'Continue'
+          function head($t) { Write-Host ""; Write-Host "===== $t =====" }
+
+          head "Windows Kits roots"
+          $kits = @('C:\Program Files (x86)\Windows Kits\10', 'C:\Program Files\Windows Kits\10')
+          foreach ($k in $kits) { if (Test-Path $k) { Write-Host "found: $k" } }
+
+          head "SDK Include versions (um vs km — km => WDK present)"
+          foreach ($k in $kits) {
+            $inc = Join-Path $k 'Include'
+            if (Test-Path $inc) {
+              Get-ChildItem $inc -Directory | ForEach-Object {
+                $hasUm = Test-Path (Join-Path $_.FullName 'um')
+                $hasKm = Test-Path (Join-Path $_.FullName 'km')
+                $wdf   = Test-Path (Join-Path $_.FullName 'km\wdf\umdf\2.31')
+                $iddcx = (Get-ChildItem (Join-Path $_.FullName 'um\iddcx') -Directory -ErrorAction SilentlyContinue | ForEach-Object { $_.Name }) -join ','
+                Write-Host ("{0,-16} um={1,-5} km={2,-5} wdf2.31={3,-5} iddcx=[{4}]" -f $_.Name, $hasUm, $hasKm, $wdf, $iddcx)
+              }
+            }
+          }
+
+          head "Driver tooling (inf2cat / stampinf / signtool / devgen / InfVerif)"
+          foreach ($tool in 'inf2cat.exe','stampinf.exe','signtool.exe','devgen.exe','InfVerif.exe','makecat.exe') {
+            $hits = @()
+            foreach ($k in $kits) {
+              $hits += Get-ChildItem -Path $k -Filter $tool -Recurse -ErrorAction SilentlyContinue |
+                       Where-Object { $_.FullName -match '\\x64\\' } | Select-Object -First 1 -ExpandProperty FullName
+            }
+            $hits = $hits | Where-Object { $_ } | Select-Object -First 1
+            Write-Host ("{0,-14} -> {1}" -f $tool, ($(if ($hits) { $hits } else { 'NOT FOUND' })))
+          }
+
+          head "EWDK"
+          Write-Host ("EWDKROOT = " + ($env:EWDKROOT ?? '<unset>'))
+
+          head "LLVM / clang (README pins 21.1.2 for wdk-sys bindgen)"
+          Write-Host ("LIBCLANG_PATH = " + ($env:LIBCLANG_PATH ?? '<unset>'))
+          $clang = Get-Command clang -ErrorAction SilentlyContinue
+          if ($clang) { & clang --version } else { Write-Host "clang: NOT on PATH" }
+
+          head "cargo-make (the gamepad drivers' build driver)"
+          $cm = & cargo make --version 2>&1; Write-Host $cm
+
+          head "Rust + targets"
+          & rustc -V; & cargo -V
+          Write-Host "installed targets:"; & rustup target list --installed
+
+          head "Env knobs the WDK build cares about"
+          Write-Host ("Version_Number = " + ($env:Version_Number ?? '<unset>'))
+          Write-Host ("CARGO_HOME     = " + ($env:CARGO_HOME ?? '<unset>'))
+          Write-Host ("CARGO_TARGET_DIR (daemon) = " + ($env:CARGO_TARGET_DIR ?? '<unset>'))
+
+      - name: Build + test pf-vdisplay-proto (MSVC)
+        run: |
+          # Short target dir to dodge MAX_PATH inside the deep act host workdir (see windows.yml).
+          $env:CARGO_TARGET_DIR = "C:\t\drv"
+          cargo build -p pf-vdisplay-proto
+          cargo test  -p pf-vdisplay-proto
+          cargo clippy -p pf-vdisplay-proto --all-targets -- -D warnings
+          cargo fmt -p pf-vdisplay-proto -- --check
+
+  # Build the UMDF driver workspace (wdk-probe) on windows-drivers-rs: proves wdk-sys bindgen/link works
+  # on the runner's WDK + LLVM, that pf-vdisplay-proto path-deps into a driver, and exposes the produced
+  # DLL's FORCE_INTEGRITY (/INTEGRITYCHECK) bit — the M0 self-signed-load question.
+  driver-build:
+    runs-on: windows-amd64
+    timeout-minutes: 45
+    defaults:
+      run:
+        shell: pwsh
+        # In-tree target dir on purpose: wdk-build's find_top_level_cargo_manifest() walks UP from OUT_DIR
+        # to the first ancestor with a Cargo.lock, so a relocated CARGO_TARGET_DIR (C:\t\…) hides the
+        # workspace lock and it panics. The driver deps have no deep CMake-from-source crates, so the
+        # default in-tree target stays well under MAX_PATH (unlike the SDL3/audiopus client build).
+        working-directory: packaging/windows/drivers
+    env:
+      # wdk-build otherwise picks 10.0.28000.0 (no km/crt) and bindgen fails — pin the WDK SDK version.
+      Version_Number: '10.0.26100.0'
+      # wdk-sys bindgen layout tests overflow (E0080) on the runner's default LLVM (ToT/22-dev); point at
+      # the pinned LLVM 21.1.2 that windows-drivers-rs builds clean against (provisioned to C:\llvm-21).
+      LIBCLANG_PATH: 'C:\llvm-21\bin'
+    steps:
+      - uses: actions/checkout@v4
+      - name: Ensure WDK + cargo-wdk + LLVM 21.1.2 (idempotent self-provision)
+        # Run the provisioning script here too so driver-build is self-sufficient and never races a
+        # separate provision run on the single runner. Path is relative to the job working-directory
+        # (packaging/windows/drivers). Near-noop once the toolchain is present.
+        run: ../../../scripts/ci/provision-windows-wdk.ps1
+      - name: cargo build the driver workspace (wdk-probe + wdk-iddcx + pf-vdisplay)
+        # Whole workspace: wdk-probe (toolchain/surface-assert probe) + wdk-iddcx (DDI wrappers) +
+        # pf-vdisplay (the real IddCx driver). pf-vdisplay linking proves the IddCx call sites resolve
+        # against IddCxStub end-to-end (M1 step 2 gate).
+        run: cargo build -v
+      - name: Inspect /INTEGRITYCHECK (before) — expect FORCE_INTEGRITY set by wdk-build
+        run: |
+          # explicit --target (.cargo/config.toml) -> output under the triple subdir.
+          $dll = "target\x86_64-pc-windows-msvc\debug\pf_vdisplay.dll"
+          if (-not (Test-Path $dll)) { throw "pf_vdisplay.dll not produced at $dll" }
+          $b = [IO.File]::ReadAllBytes($dll)
+          $pe = [BitConverter]::ToInt32($b, 0x3c)
+          $dllchar = [BitConverter]::ToUInt16($b, $pe + 0x5e)   # OptionalHeader.DllCharacteristics
+          Write-Host ("pf_vdisplay.dll built OK ({0:N0} bytes)" -f (Get-Item $dll).Length)
+          Write-Host ("BEFORE: DllCharacteristics = 0x{0:X4}; FORCE_INTEGRITY = {1}" -f $dllchar, (($dllchar -band 0x0080) -ne 0))
+      - name: Clear FORCE_INTEGRITY (self-signed-load fix) + verify
+        # wdk-build sets /INTEGRITYCHECK unconditionally -> a self-signed driver won't load. Clear the PE
+        # bit deterministically (the reusable packaging step; signing/.cat happen later for real drivers).
+        run: ../clear-force-integrity.ps1 -Path target\x86_64-pc-windows-msvc\debug\pf_vdisplay.dll
@@ -0,0 +1,206 @@
+# Build the punktfunk Windows HOST as a signed Inno Setup installer and publish it to Gitea's generic
+# package registry, so a Windows GPU box can install the streaming host (SYSTEM service + bundled
+# pf-vdisplay virtual-display driver + the web management console, run by a scheduled task on a bundled
+# bun) from one signed setup.exe. Runs on the self-hosted Windows runner
+# (host mode; scripts/ci/setup-windows-runner.ps1) — same MSVC/Windows-SDK/LLVM env as windows.yml.
+#
+# Why an installer and not MSIX (like the client): the host installs a LocalSystem SCM service that
+# CreateProcessAsUserW's into the interactive session for secure-desktop capture, and bundles a
+# kernel/IDD driver — neither is expressible in MSIX's sandbox. The real install logic already lives
+# in `punktfunk-host service install` (crates/punktfunk-host/src/service.rs); the installer just lays
+# the exe down and calls it elevated. Packaging internals: packaging/windows/README.md.
+#
+# Registry (public reads, unom org): https://git.unom.io/unom/-/packages  (generic group)
+#
+# Versioning (free-form; not MSIX's 4-part rule) — single project version:
+#   vX.Y.Z tag -> X.Y.Z   (THE release; published + stable `latest/` alias + attached to the
+#                          unified Gitea Release).
+#   main push / dispatch -> 0.3.<run_number>  (canary; `canary/` alias; climbs by run number).
+#
+# Signing reuses the client's MSIX_CERT_PFX_B64 / MSIX_CERT_PASSWORD secrets (CN=unom). Without them
+# an ephemeral self-signed cert is generated and its public .cer published next to the installer
+# (import once to LocalMachine\TrustedPublisher). See packaging/windows/pack-host-installer.ps1.
+#
+# GPU backends: the host builds with --features nvenc,amf-qsv = all three vendors in one installer.
+#  - NVENC (NVIDIA, direct SDK): the only link need is nvencodeapi.lib, synthesised from a 2-export
+#    .def with llvm-dlltool (no GPU/SDK at build time).
+#  - AMF/QSV (AMD/Intel, libavcodec): link-imports the FFmpeg libs from FFMPEG_DIR (the BtbN gpl-shared
+#    tree the client uses; includes the *_amf/*_qsv encoders) and bundles its DLLs into the installer.
+# CI never launches the exe, so no GPU is needed here — this is build + Windows clippy coverage only.
+name: windows-host
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'crates/punktfunk-host/**'
+      - 'crates/punktfunk-core/**'
+      - 'packaging/windows/**'
+      - 'scripts/windows/**'
+      - 'web/**'
+      - 'Cargo.lock'
+      - 'Cargo.toml'
+      - '.gitea/workflows/windows-host.yml'
+    tags: ['v*']
+  workflow_dispatch:
+
+env:
+  REGISTRY: git.unom.io
+  OWNER: unom
+  PKG: punktfunk-host-windows
+
+jobs:
+  package:
+    runs-on: windows-amd64
+    timeout-minutes: 90
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Configure + version
+        shell: pwsh
+        run: |
+          # CARGO_TARGET_DIR=C:\t dodges the MAX_PATH wall in the CMake-from-source crates (aws-lc,
+          # opus) the host pulls; CARGO_WORKSPACE_DIR mirrors the client workflows. Both via GITHUB_ENV
+          # (pwsh Out-File utf8 = no BOM, unlike Windows PowerShell 5.1 — keeps the first line clean).
+          "CARGO_TARGET_DIR=C:\t" | Out-File -FilePath $env:GITHUB_ENV -Append -Encoding utf8
+          "CARGO_WORKSPACE_DIR=$env:GITHUB_WORKSPACE" | Out-File -FilePath $env:GITHUB_ENV -Append -Encoding utf8
+          # FFMPEG_DIR: the same BtbN gpl-shared x64 tree the Windows CLIENT links against (provisioned
+          # by scripts/ci/setup-windows-runner.ps1). The host's AMD/Intel AMF/QSV encode backend
+          # (--features amf-qsv) link-imports avcodec/avutil/swscale from it; pack-host-installer.ps1
+          # then bundles its bin\*.dll into the installer. LIBCLANG_PATH is in the runner daemon env.
+          if (-not $env:FFMPEG_DIR) {
+            "FFMPEG_DIR=C:\Users\Public\ffmpeg" | Out-File -FilePath $env:GITHUB_ENV -Append -Encoding utf8
+          }
+          $v = if ($env:GITHUB_REF -like 'refs/tags/v*') {
+            $env:GITHUB_REF_NAME -replace '^v', ''
+          } else {
+            "0.3.$($env:GITHUB_RUN_NUMBER)"
+          }
+          "HOST_VERSION=$v" | Out-File -FilePath $env:GITHUB_ENV -Append -Encoding utf8
+          "PUNKTFUNK_BUILD_VERSION=$v" | Out-File -FilePath $env:GITHUB_ENV -Append -Encoding utf8
+          Write-Output "host version $v"
+
+      - name: Generate NVENC import lib
+        shell: pwsh
+        run: |
+          & packaging/windows/nvenc/gen-nvenc-importlib.ps1 -OutDir C:\t\nvenc
+          "PUNKTFUNK_NVENC_LIB_DIR=C:\t\nvenc" | Out-File -FilePath $env:GITHUB_ENV -Append -Encoding utf8
+
+      - name: Build (release, nvenc + amf-qsv)
+        shell: pwsh
+        # All-vendor host: NVENC (NVIDIA, direct SDK) + AMF/QSV (AMD/Intel, libavcodec via FFMPEG_DIR).
+        run: cargo build --release -p punktfunk-host --features nvenc,amf-qsv
+
+      - name: Clippy (host, Windows)
+        shell: pwsh
+        # First-ever Windows lint coverage for the host (Linux CI never lints the windows-cfg code).
+        run: cargo clippy -p punktfunk-host --features nvenc,amf-qsv -- -D warnings
+
+      - name: Ensure Inno Setup
+        shell: pwsh
+        run: |
+          if (-not (Test-Path 'C:\Program Files (x86)\Inno Setup 6\ISCC.exe') -and -not (Get-Command iscc -ErrorAction SilentlyContinue)) {
+            Write-Output "installing Inno Setup via choco"
+            choco install innosetup -y --no-progress
+          }
+
+      - name: Fetch portable bun runtime (build tool + bundled to run the console)
+        shell: pwsh
+        run: |
+          # ONE pinned bun, used both to BUILD the console and shipped in the installer to RUN it. The
+          # .output is self-contained (Nitro noExternals — deps bundled + tree-shaken, no node_modules),
+          # so the installer ships just bun + a ~75-file .output instead of node + a node_modules forest.
+          $ver = 'bun-v1.3.14'
+          $url = "https://github.com/oven-sh/bun/releases/download/$ver/bun-windows-x64.zip"
+          New-Item -ItemType Directory -Force -Path C:\t | Out-Null
+          $zip = 'C:\t\bun.zip'; $dst = 'C:\t\bundist'
+          Invoke-WebRequest -Uri $url -OutFile $zip
+          if (Test-Path $dst) { Remove-Item $dst -Recurse -Force }
+          Expand-Archive -Path $zip -DestinationPath $dst -Force
+          $bun = (Get-ChildItem -Path $dst -Recurse -Filter bun.exe | Select-Object -First 1).FullName
+          if (-not $bun) { throw "bun.exe not found in $url" }
+          "BUN_EXE=$bun" | Out-File -FilePath $env:GITHUB_ENV -Append -Encoding utf8
+          & $bun --version
+
+      - name: Build + smoke-boot web console (bun)
+        shell: pwsh
+        env:
+          # PAT with read access to the unom org packages — the @unom npm registry needs auth to BUILD.
+          REGISTRY_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
+        # The bun fetched above builds the Nitro server AND runs it. noExternals (vite.config) makes the
+        # output self-contained, so there's no .output/server install — the installer ships bun + the
+        # ~75-file .output. The runner is SYSTEM with no ~/.npmrc, so supply the private @unom token in
+        # the SYSTEM home .npmrc to BUILD (kept OUT of the shipped bundle — web\.npmrc has only the
+        # registry mapping, and nothing copies it into .output).
+        run: |
+          $bun = $env:BUN_EXE
+          if ($env:REGISTRY_TOKEN) {
+            $rc = Join-Path $env:USERPROFILE '.npmrc'
+            Add-Content -Path $rc -Value '@unom:registry=https://git.unom.io/api/packages/unom/npm/'
+            Add-Content -Path $rc -Value "//git.unom.io/api/packages/unom/npm/:_authToken=$env:REGISTRY_TOKEN"
+          }
+          Push-Location web
+          & $bun install --frozen-lockfile; if ($LASTEXITCODE) { throw "bun install failed ($LASTEXITCODE)" }
+          & $bun run build; if ($LASTEXITCODE) { throw "web build failed ($LASTEXITCODE)" }
+          if (Select-String -Path .output\server\index.mjs -Pattern 'Bun\.serve' -Quiet) {
+            throw "web build is a bun bundle (Bun.serve) - need the node-server preset"
+          }
+          Pop-Location
+          # Gate the installer on a real boot under the BUNDLED bun (the runtime it ships), serving /login.
+          $env:PORT = '3009'; $env:HOST = '127.0.0.1'; $env:PUNKTFUNK_UI_PASSWORD = 'ci'
+          $server = (Resolve-Path 'web\.output\server\index.mjs').Path
+          $p = Start-Process -FilePath $bun -ArgumentList $server -PassThru -WindowStyle Hidden
+          Start-Sleep -Seconds 4
+          try { $code = (Invoke-WebRequest -Uri 'http://127.0.0.1:3009/login' -UseBasicParsing -TimeoutSec 10).StatusCode } catch { $code = 0 }
+          Stop-Process -Id $p.Id -Force -ErrorAction SilentlyContinue
+          Write-Output "web console smoke (bun): /login -> $code"
+          if ($code -ne 200) { throw "web console failed to boot under bun" }
+          "WEB_OUTPUT_DIR=$((Resolve-Path 'web\.output').Path)" | Out-File -FilePath $env:GITHUB_ENV -Append -Encoding utf8
+
+      - name: Pack + sign installer
+        shell: pwsh
+        env:
+          MSIX_CERT_PFX_B64: ${{ secrets.MSIX_CERT_PFX_B64 }}
+          MSIX_CERT_PASSWORD: ${{ secrets.MSIX_CERT_PASSWORD }}
+        run: |
+          & packaging/windows/pack-host-installer.ps1 `
+            -Version $env:HOST_VERSION -TargetDir C:\t\release -OutDir C:\t\out
+
+      - name: Publish to Gitea generic registry
+        shell: pwsh
+        env:
+          REGISTRY_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
+        run: |
+          # Check curl's exit code ourselves — a best-effort DELETE (404 on first run) must not abort.
+          $PSNativeCommandUseErrorActionPreference = $false
+          function Publish-File($f, $url) {
+            curl.exe -fsS --user "enricobuehler:$($env:REGISTRY_TOKEN)" --upload-file "$f" "$url"
+            if ($LASTEXITCODE -ne 0) { throw "upload failed ($LASTEXITCODE): $url" }
+            Write-Output "published $url"
+          }
+          $files = @($env:HOST_SETUP_PATH, $env:HOST_CER_PATH) | Where-Object { $_ -and (Test-Path $_) }
+          if (-not $files) { throw "pack produced no artifacts to publish" }
+          $base = "https://$($env:REGISTRY)/api/packages/$($env:OWNER)/generic/$($env:PKG)"
+          foreach ($f in $files) { Publish-File $f "$base/$($env:HOST_VERSION)/$(Split-Path $f -Leaf)" }
+          # Refresh the channel alias (delete-then-reupload, like flatpak.yml/decky.yml) for a
+          # predictable download URL: stable release -> `latest/`, canary main build -> `canary/`.
+          $alias = if ($env:GITHUB_REF -like 'refs/tags/v*') { 'latest' } else { 'canary' }
+          $aliasNames = @{ $env:HOST_SETUP_PATH = 'punktfunk-host-setup.exe'; $env:HOST_CER_PATH = 'punktfunk-host-windows.cer' }
+          foreach ($f in $files) {
+            $an = $aliasNames[$f]; if (-not $an) { continue }
+            curl.exe -fsS -o NUL --user "enricobuehler:$($env:REGISTRY_TOKEN)" -X DELETE "$base/$alias/$an" 2>$null
+            Publish-File $f "$base/$alias/$an"
+          }
+
+      # On a real release, also attach the signed installer (+ its .cer) to the unified Gitea Release.
+      - name: Attach host installer to the Gitea release (stable tags only)
+        if: startsWith(gitea.ref, 'refs/tags/v')
+        shell: pwsh
+        env:
+          GITEA_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
+        run: |
+          . scripts/ci/gitea-release.ps1
+          $rid = Ensure-GiteaRelease -Tag $env:GITHUB_REF_NAME -Name $env:GITHUB_REF_NAME -Prerelease 'auto'
+          foreach ($f in @($env:HOST_SETUP_PATH, $env:HOST_CER_PATH)) {
+            if ($f -and (Test-Path $f)) { Upsert-GiteaAsset -ReleaseId $rid -File $f }
+          }
@@ -0,0 +1,145 @@
+# Build the punktfunk Windows client as signed MSIX packages (x64 + ARM64) and publish them to
+# Gitea's generic package registry, so Windows boxes can download + install a real package (Start
+# tile, clean install/uninstall) instead of a loose exe. Runs on the self-hosted Windows runner
+# (host mode; scripts/ci/setup-windows-runner.ps1) — the MSVC/WinUI/FFmpeg toolchain + the Windows
+# SDK's makeappx/signtool are baked into the runner's daemon env, same as windows.yml.
+#
+# Both arches come off the ONE x64 runner: x86_64 natively, aarch64 cross-compiled (the x64 MSVC
+# toolset has the ARM64 cross compiler; the matrix points FFMPEG_DIR at the ARM64 FFmpeg tree). See
+# windows.yml for the cross-build rationale + the BOM/MAX_PATH runner gotchas.
+#
+# Registry (public, unom org): https://git.unom.io/unom/-/packages  (generic group)
+# Packaging internals: clients/windows/packaging/README.md.
+#
+# Versioning — single project version; MSIX requires a strictly 4-part numeric version, so:
+#   vX.Y.Z tag -> X.Y.Z.0  (THE release; any -rc/+meta pre-release suffix is dropped for MSIX).
+#                Published to the generic registry + the stable `latest/` alias + attached to the
+#                unified Gitea Release alongside every other platform's artifact.
+#   main push / dispatch -> 0.3.<run_number>.0  (canary; climbs monotonically by run number).
+#                Published to the generic registry + the `canary/` alias.
+# Both arches share the version; artifacts are arch-suffixed (..._x64.msix / ..._arm64.msix).
+#
+# Signing (packaging/pack-msix.ps1): if the MSIX_CERT_PFX_B64 / MSIX_CERT_PASSWORD Actions secrets
+# are set (a real or shared code-signing .pfx whose subject DN == Publisher), the package is signed
+# with them. Otherwise an ephemeral self-signed cert is generated and its public .cer is published
+# next to the .msix (users import it to Trusted People before install). Drop in a real cert later
+# with no workflow change — just add the secrets (+ pass -Publisher if its subject differs).
+name: windows-msix
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'clients/windows/**'
+      - 'crates/punktfunk-core/**'
+      - 'Cargo.lock'
+      - 'Cargo.toml'
+      - '.gitea/workflows/windows-msix.yml'
+    tags: ['v*']
+  workflow_dispatch:
+
+env:
+  REGISTRY: git.unom.io
+  OWNER: unom
+  PKG: punktfunk-client-windows
+
+jobs:
+  package:
+    runs-on: windows-amd64
+    timeout-minutes: 90
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - arch: x64
+            target: x86_64-pc-windows-msvc
+            ffmpeg: C:\Users\Public\ffmpeg
+            td: C:\t
+          - arch: arm64
+            target: aarch64-pc-windows-msvc
+            ffmpeg: C:\Users\Public\ffmpeg-arm64
+            td: C:\t-a64
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Configure + version
+        shell: pwsh
+        run: |
+          # windows-reactor's build.rs unwraps CARGO_WORKSPACE_DIR; CARGO_TARGET_DIR (per-arch, short)
+          # dodges the MAX_PATH wall in the CMake-from-source crates (see windows.yml). FFMPEG_DIR
+          # selects the arch's import libs + is read by pack-msix.ps1 for the runtime DLLs. All via
+          # GITHUB_ENV.
+          "CARGO_WORKSPACE_DIR=$env:GITHUB_WORKSPACE" | Out-File -FilePath $env:GITHUB_ENV -Append -Encoding utf8
+          "CARGO_TARGET_DIR=${{ matrix.td }}" | Out-File -FilePath $env:GITHUB_ENV -Append -Encoding utf8
+          "FFMPEG_DIR=${{ matrix.ffmpeg }}" | Out-File -FilePath $env:GITHUB_ENV -Append -Encoding utf8
+          rustup target add ${{ matrix.target }}
+          $parts = if ($env:GITHUB_REF -like 'refs/tags/v*') {
+            # MSIX needs a purely-numeric 4-part version: drop any -rc/+meta pre-release suffix.
+            (($env:GITHUB_REF_NAME -replace '^v', '') -replace '[-+].*$', '').Split('.')
+          } else {
+            @('0', '3', $env:GITHUB_RUN_NUMBER)
+          }
+          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  arch ${{ matrix.arch }}  target ${{ matrix.target }}"
+
+      - name: Build (release)
+        shell: pwsh
+        run: cargo build --release -p punktfunk-client-windows --target ${{ matrix.target }}
+
+      - name: Pack + sign MSIX
+        shell: pwsh
+        env:
+          MSIX_CERT_PFX_B64: ${{ secrets.MSIX_CERT_PFX_B64 }}
+          MSIX_CERT_PASSWORD: ${{ secrets.MSIX_CERT_PASSWORD }}
+        run: |
+          & clients/windows/packaging/pack-msix.ps1 `
+            -Version $env:MSIX_VERSION -Arch ${{ matrix.arch }} `
+            -TargetDir ${{ matrix.td }}\${{ matrix.target }}\release -OutDir ${{ matrix.td }}\msix
+
+      - name: Publish to Gitea generic registry
+        shell: pwsh
+        env:
+          REGISTRY_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
+        run: |
+          $PSNativeCommandUseErrorActionPreference = $false
+          $base = "https://$($env:REGISTRY)/api/packages/$($env:OWNER)/generic/$($env:PKG)"
+          # stable release -> `latest/` alias; canary main build -> `canary/` alias.
+          $alias = if ($env:GITHUB_REF -like 'refs/tags/v*') { 'latest' } else { 'canary' }
+          # version-less, arch-suffixed alias names so each channel keeps one predictable URL.
+          $aliasNames = @{
+            "$($env:MSIX_PATH)"     = "$($env:PKG)_${{ matrix.arch }}.msix"
+            "$($env:MSIX_CER_PATH)" = "$($env:PKG)_${{ matrix.arch }}.cer"
+          }
+          $files = @($env:MSIX_PATH, $env:MSIX_CER_PATH) | Where-Object { $_ -and (Test-Path $_) }
+          if (-not $files) { throw "pack produced no artifacts to publish" }
+          function Put($f, $url) {
+            curl.exe -fsS --user "enricobuehler:$($env:REGISTRY_TOKEN)" --upload-file "$f" "$url"
+            if ($LASTEXITCODE -ne 0) { throw "upload failed ($LASTEXITCODE): $url" }
+            Write-Output "published $url"
+          }
+          foreach ($f in $files) {
+            $name = Split-Path $f -Leaf
+            # 1) immutable, versioned path
+            Put $f "$base/$($env:MSIX_VERSION)/$name"
+            # 2) channel alias (delete-then-reupload; the generic registry 409s on an existing file)
+            $an = $aliasNames["$f"]
+            curl.exe -fsS -o NUL --user "enricobuehler:$($env:REGISTRY_TOKEN)" -X DELETE "$base/$alias/$an" 2>$null
+            Put $f "$base/$alias/$an"
+          }
+
+      # On a real release, also attach the MSIX (+ its .cer) to the unified Gitea Release. Both
+      # arch legs attach to the same release concurrently — the helper's create-or-fetch handles
+      # the race, and x64/arm64 filenames differ so the assets don't collide.
+      - name: Attach MSIX to the Gitea release (stable tags only)
+        if: startsWith(gitea.ref, 'refs/tags/v')
+        shell: pwsh
+        env:
+          GITEA_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
+        run: |
+          . scripts/ci/gitea-release.ps1
+          $rid = Ensure-GiteaRelease -Tag $env:GITHUB_REF_NAME -Name $env:GITHUB_REF_NAME -Prerelease 'auto'
+          foreach ($f in @($env:MSIX_PATH, $env:MSIX_CER_PATH)) {
+            if ($f -and (Test-Path $f)) { Upsert-GiteaAsset -ReleaseId $rid -File $f }
+          }
@@ -0,0 +1,95 @@
+# 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).
+#
+# Two architectures from ONE x64 runner: x86_64-pc-windows-msvc natively and
+# aarch64-pc-windows-msvc by cross-compiling. The x64 MSVC toolset ships an ARM64 cross compiler
+# (VC\Tools\MSVC\<ver>\bin\Hostx64\arm64\cl.exe) and aarch64-pc-windows-msvc is a tier-2 Rust
+# target with host tools, so no ARM64 runner is needed — the cc/cmake crates pick the ARM64
+# compiler from the target triple (SDL3 + libopus build-from-source cross-compile fine). The one
+# arch-specific external dep is FFmpeg's import libs: the runner keeps an x64 tree at
+# C:\Users\Public\ffmpeg and an ARM64 tree at C:\Users\Public\ffmpeg-arm64 (both FFmpeg 7.x /
+# avcodec-61); the matrix points FFMPEG_DIR at the right one. aarch64 can't *run* on the x64 host,
+# so fmt + test run only for x64.
+#
+# The MSVC/WinUI/FFmpeg toolchain (cargo/rustup on ASCII paths, NASM, CMake, LLVM, the x64 FFmpeg,
+# CARGO_HOME, CMAKE_POLICY_VERSION_MINIMUM, …) is baked into the runner's daemon env. Per-checkout
+# / per-arch vars are set in a step:
+#   - CARGO_WORKSPACE_DIR  windows-reactor's build.rs unwraps it + stages the Win App SDK
+#                          NuGets/winmd under it (from GITHUB_WORKSPACE).
+#   - CARGO_TARGET_DIR=C:\t…  the runner's host workdir is buried deep under
+#                          C:\Windows\System32\config\systemprofile\.cache\act\<hash>\hostexecutor\,
+#                          so the default target\ path blows past Windows' MAX_PATH (260) inside the
+#                          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 (per-arch so the two
+#                          matrix legs don't share a target dir).
+#   - FFMPEG_DIR           per-arch FFmpeg import libs (x64 vs arm64 tree).
+#
+# Steps use `shell: pwsh` (PowerShell 7) deliberately: Windows PowerShell 5.1's
+# `Out-File -Encoding utf8` prepends a UTF-8 BOM that corrupts the first GITHUB_ENV line (the
+# CARGO_WORKSPACE_DIR var silently never gets set -> reactor build.rs panics). pwsh writes no BOM.
+# 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:
+      - 'clients/windows/**'
+      - 'crates/punktfunk-core/**'
+      - 'Cargo.lock'
+      - 'Cargo.toml'
+      - '.gitea/workflows/windows.yml'
+  pull_request:
+    paths:
+      - 'clients/windows/**'
+      - 'crates/punktfunk-core/**'
+      - 'Cargo.lock'
+      - 'Cargo.toml'
+      - '.gitea/workflows/windows.yml'
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: windows-amd64
+    timeout-minutes: 90
+    strategy:
+      fail-fast: false
+      matrix:
+        target: [x86_64-pc-windows-msvc, aarch64-pc-windows-msvc]
+    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
+          # Per-arch short target root (dodges MAX_PATH; keeps the two legs from sharing target\).
+          $td = if ('${{ matrix.target }}' -eq 'aarch64-pc-windows-msvc') { 'C:\t-a64' } else { 'C:\t' }
+          "CARGO_TARGET_DIR=$td" | Out-File -FilePath $env:GITHUB_ENV -Append -Encoding utf8
+          # Per-arch FFmpeg import libs (the runner provisions both — setup-windows-runner.ps1).
+          $ff = if ('${{ matrix.target }}' -eq 'aarch64-pc-windows-msvc') { 'C:\Users\Public\ffmpeg-arm64' } else { 'C:\Users\Public\ffmpeg' }
+          "FFMPEG_DIR=$ff" | Out-File -FilePath $env:GITHUB_ENV -Append -Encoding utf8
+          rustup target add ${{ matrix.target }}
+          rustc --version
+          cargo --version
+          Write-Output "target ${{ matrix.target }}  target-dir $td  ffmpeg $ff"
+
+      - name: Build
+        shell: pwsh
+        run: cargo build -p punktfunk-client-windows --target ${{ matrix.target }}
+
+      - name: Clippy (-D warnings)
+        shell: pwsh
+        run: cargo clippy -p punktfunk-client-windows --all-targets --target ${{ matrix.target }} -- -D warnings
+
+      - name: Rustfmt check
+        if: matrix.target == 'x86_64-pc-windows-msvc'
+        shell: pwsh
+        run: cargo fmt -p punktfunk-client-windows -- --check
+
+      - name: Test
+        if: matrix.target == 'x86_64-pc-windows-msvc'
+        shell: pwsh
+        run: cargo test -p punktfunk-client-windows --target ${{ matrix.target }}
@@ -0,0 +1,32 @@
+/target
+**/*.rs.bk
+*.pdb
+.DS_Store
+# generated C header is checked in (see include/), build artifacts are not
+/crates/*/target
+/tools/*/target
+node_modules/
+dist/
+# Swift package build artifacts + the locally-built xcframework (rebuild via scripts/build-xcframework.sh)
+clients/apple/.build/
+clients/apple/PunktfunkCore.xcframework/
+clients/apple/.swiftpm/
+# Generated App Store screenshots (tools/screenshots.sh output; uploaded as a CI artifact)
+clients/apple/screenshots/
+# Xcode per-user state
+xcuserdata/
+
+# Debian package build output
+/dist/
+
+# Windows App SDK staging by windows-reactor build.rs
+/temp/
+/winmd/
+
+# Client crate build artifacts (clients moved out of crates/ -> clients/ 2026-06-18)
+/clients/*/target
+/clients/*/*/target
+
+# Python bytecode (e.g. clients/android/ci tooling)
+__pycache__/
+*.pyc
@@ -0,0 +1,24 @@
+{
+    "configurations": [
+        {
+            "type": "swift",
+            "request": "launch",
+            "args": [],
+            "cwd": "${workspaceFolder:punktfunk}/clients/apple",
+            "name": "Debug PunktfunkClient (clients/apple)",
+            "target": "PunktfunkClient",
+            "configuration": "debug",
+            "preLaunchTask": "swift: Build Debug PunktfunkClient (clients/apple)"
+        },
+        {
+            "type": "swift",
+            "request": "launch",
+            "args": [],
+            "cwd": "${workspaceFolder:punktfunk}/clients/apple",
+            "name": "Release PunktfunkClient (clients/apple)",
+            "target": "PunktfunkClient",
+            "configuration": "release",
+            "preLaunchTask": "swift: Build Release PunktfunkClient (clients/apple)"
+        }
+    ]
+}
@@ -0,0 +1,342 @@
+# CLAUDE.md — punktfunk
+
+Low-latency desktop/game streaming stack, Linux-first, with a shared Rust protocol core
+(`punktfunk-core`) exposed over a C ABI and native clients per platform. Full design:
+[`docs/implementation-plan.md`](docs/implementation-plan.md). Status table: `README.md`.
+
+## Where the work stands
+
+- **Core (`punktfunk-core` + C ABI): complete and hardened.** FEC recovery, loopback-under-loss,
+  proptests, C ABI harness all green; 13 adversarial-review findings fixed +
+  regression-tested (`a913042`).
+- **GameStream host: working end-to-end with a stock Moonlight client.** Validated live
+  on this box: pairing (persists across restarts), serverinfo/applist (app catalog from
+  `~/.config/punktfunk/apps.json` → each entry picks a compositor + nested command), RTSP, ENet
+  control, audio, and video at the **client's native resolution and refresh** — the host
+  creates a per-session virtual output via per-compositor `VirtualDisplay` backends:
+  **KWin** (`zkde_screencast stream_virtual_output`, needs KWin ≥ 6.5.6 headless; >60 Hz via
+  custom modes), **gamescope** (spawned headless at WxH@Hz, its PipeWire node captured, needs
+  gamescope ≥ 3.16.22 — older deadlocks on PipeWire ≥ 1.6), **Mutter** (D-Bus
+  `RecordVirtual` virtual monitor; validated live on headless GNOME Shell 50, zero-copy),
+  **Sway/wlroots** (`swaymsg create_output` + custom mode, xdpw portal capture with a
+  managed chooser config; validated live on sway 1.11, zero-copy).
+  Performance work landed and measured: GPU **zero-copy** on all paths (tiled dmabuf →
+  EGL/GL → CUDA; LINEAR dmabuf → **Vulkan bridge** → CUDA → NVENC), auto 2-way NVENC
+  split-encode above ~1 Gpix/s (5K@240), infinite GOP + RFI keyframes (killed the periodic
+  freeze), encode|send thread split with `sendmmsg` batching. Stable 240 fps at 5120×1440.
+  Input: mouse/keyboard (libei via RemoteDesktop portal on KWin/GNOME, gamescope's own EIS
+  socket, wlr protocols on Sway) and **gamepads** (uinput X-Box-360 pads + rumble
+  back-channel; validated live — pad created/destroyed with the session). Management REST API +
+  checked-in OpenAPI doc (`mgmt.rs`).
+- **Native protocol (`punktfunk/1`): full session planes, validated live.** QUIC
+  control plane (`punktfunk-core` `quic` feature: Hello{mode}/Welcome{full Config}/Start), data
+  plane = the hardened core `Session` over raw UDP with **GF(2¹⁶) Leopard FEC + AES-GCM**
+  (inexpressible in GameStream), host creates the native virtual output at the client's
+  requested mode. `punktfunk1-host` is a **persistent listener** (sessions back to back;
+  `--max-sessions`). QUIC datagrams carry the side planes, demuxed by first byte: input
+  0xC8 (incl. **gamepads** — incremental events accumulated into the uinput xpad), **Opus
+  audio** 0xC9 (48 kHz stereo, 5 ms, host→client), **rumble** 0xCA (host→client). **Trust:**
+  host serves its persistent identity (`~/.config/punktfunk/cert.pem`, shared with GameStream
+  pairing) and logs the SHA-256 fingerprint; clients pin it, established by a **SPAKE2 PIN pairing
+  ceremony** (host arms pairing and displays a 4-digit PIN; a PAKE binds both cert fingerprints so an
+  attacker gets one online guess, no offline dictionary attack) — PIN pairing is the default for new
+  hosts. **TOFU on first connect** (`endpoint::client_pinned`) stays as an explicit host opt-in
+  (`punktfunk1-host --allow-tofu` / `serve --open`, advertised as `pair=optional`) for fully trusted LANs;
+  clients only offer the TOFU "Trust" path for a host that advertised `pair=optional`, route every
+  other new host straight to the PIN ceremony, and on a pinned-fingerprint change force re-pairing
+  (no re-TOFU shortcut). Clients present persistent identities via QUIC client auth, the host stores
+  paired fingerprints (`punktfunk1-paired.json`) and gates sessions with `--require-pairing` (the
+  default; `--allow-tofu`/`--open` accept unpaired clients).
+  **LAN auto-discovery**: both `serve` and `punktfunk1-host` advertise the native service over
+  mDNS (`_punktfunk._udp`, `crate::discovery`) with TXT `proto`/`fp`(cert fingerprint to
+  pin)/`pair`(required|optional)/`id`; `punktfunk-probe --discover` lists hosts, Apple clients
+  browse the same service via NWBrowser (validated cross-LAN 2026-06-12).
+  **Mid-stream mode renegotiation**: `Reconfigure` on the still-open control stream — the
+  host rebuilds output+encoder at the new mode in ~90 ms while the data plane runs on
+  (validated live: one .h265 with 720p and 1080p segments). Measured on-box at 720p120: 1680/1680 frames, **p50 0.83 ms**
+  capture→…→reassembled; audio measured live (~200 pkts/s). A **wall-clock skew handshake**
+  (`ClockProbe`/`ClockEcho`, 8 NTP rounds after `Start`, `clock_offset_ns`) aligns the client to the
+  host clock, so that latency is now valid **cross-machine** (`skew_corrected=true`) — measured GNOME
+  box → dev box over the LAN: **p50 1.30 ms** (the −1.57 ms inter-box clock offset removed).
+  `punktfunk-probe` is the
+  working reference client (`--pin`, datagram counters, `--input-test` incl. gamepad).
+  The embeddable connector (`NativeClient`) exposes it all over the C ABI: `punktfunk_connect`
+  (pin/TOFU) + `next_au`/`next_audio`/`next_rumble`/`next_hidout`/`send_input`/
+  `send_rich_input`. **Client-negotiated virtual pad type**: the Hello carries a gamepad
+  preference byte (same trailing-byte back-compat pattern as the compositor), the Welcome
+  echoes the resolved backend — precedence: explicit client choice > `PUNKTFUNK_GAMEPAD`
+  env > uinput Xbox 360. Backends: **Xbox 360** (uinput / ViGEm), **Xbox One/Series** (the same
+  XInput backend with the One/Series USB identity for matching glyphs — no extra game-visible
+  capability; impulse-trigger rumble is unreachable through a virtual pad), and the UHID
+  `hid-playstation` pads — **DualSense** (adaptive triggers, lightbar, touchpad, motion) and
+  **DualShock 4** (lightbar, touchpad, motion, rumble; DualSense minus adaptive triggers / player
+  LEDs / mute). DualSense and DualShock 4 each have a Linux (UHID `hid-playstation`) **and a Windows
+  (UMDF minidriver)** backend — `inject/dualsense_windows.rs` + `inject/dualshock4_windows.rs`, one
+  driver serving either identity per a `device_type` byte the host stamps into shared memory (the DS4
+  reuses the same SwDeviceCreate game-detection identity fix as the DualSense). One/Series stays
+  Linux-only and folds into Xbox 360 off it. Clients auto-resolve the type from the physical controller
+  (DS5→DualSense, DS4→DualShock 4, Xbox One→Xbox One). **Windows uses ZERO external gamepad
+  dependencies — ViGEmBus is gone.** Xbox 360 (XInput) runs on a UMDF2 **XUSB companion** driver
+  (`packaging/windows/xusb-driver/`, `inject/gamepad_windows.rs`) that registers `GUID_DEVINTERFACE_XUSB`
+  and answers the buffered XInput IOCTLs from a shared section, so classic `XInputGetState`/`SetState`
+  work with no kernel bus driver (validated live: slot connected, state + rumble round-trip; Xbox One
+  folds to this 360 path). All three UMDF drivers (DualSense/DS4 + XUSB) are bundled + pnputil-installed
+  by the Inno Setup installer (`packaging/windows/gamepad-drivers/` + `install-gamepad-drivers.ps1`).
+  **Multi-pad ready**: the host stamps each pad's index into the device Location (`pszDeviceLocation`),
+  the driver reads it (`WdfDeviceAllocAndQueryProperty`) to map its own `*-shm-<index>`, and
+  `UmdfHostProcessSharing=ProcessSharingDisabled` gives each pad its own host (per-pad statics) —
+  validated live with 2 distinct XInput slots + 2 DualSense pads. (Client-side multi-pad forwarding is
+  the remaining piece.)
+- **Windows host: implemented and shipping (all-vendor, x64-only).** `#[cfg(windows)]` backends
+  behind the same traits as Linux — DXGI Desktop Duplication capture (`capture/dxgi.rs`), **SudoVDA**
+  virtual display per session (`vdisplay/sudovda.rs`), GPU encode (NVENC `--features nvenc`; AMD/Intel
+  `--features amf-qsv`), SendInput + **ViGEm** gamepads (`inject/gamepad_windows.rs`), WASAPI loopback
+  + virtual mic (`audio/wasapi_*`). Ships as a **signed Inno Setup installer** that registers a
+  `LocalSystem` SCM service launching into the interactive session for secure-desktop (UAC/lock-screen)
+  capture (`service.rs`), bundles the SudoVDA driver + the FFmpeg DLLs, and is published by
+  `windows-host.yml`. **Encoder is GPU-aware** (`encode.rs` `open_video` + `windows_resolved_backend`):
+  `PUNKTFUNK_ENCODER=auto` (the host.env default) detects the DXGI adapter vendor → **NVENC** (NVIDIA,
+  direct SDK, `encode/nvenc.rs`), **AMF** (AMD) / **QSV** (Intel) via libavcodec
+  (`encode/ffmpeg_win.rs`, the Windows analogue of the Linux VAAPI backend — `WinVendor{Amf,Qsv}`,
+  system-memory NV12/P010 readback default + opt-in zero-copy D3D11 behind `PUNKTFUNK_ZEROCOPY` with a
+  system fallback), or software H.264 (`encode/sw.rs`, GPU-less). GameStream codec advertisement is
+  probed per-GPU on AMF/QSV (`windows_codec_support` → `serverinfo`, AV1 gated). **HDR (10-bit)**: WGC
+  captures the HDR desktop as FP16/Rgb10a2 (DDA FP16 for the secure desktop), the encoder forces HEVC
+  Main10 + BT.2020 PQ (NVENC ABGR10/P010; AMF/QSV P010 + a swscale Rgb10a2→P010 fallback), the client
+  auto-detects PQ from the HEVC VUI — gated by `PUNKTFUNK_10BIT` + client `VIDEO_CAP_10BIT`; **Windows
+  host only** (the Linux host stays 8-bit, blocked upstream). **AMF/QSV is CI-green but not yet
+  on-glass validated** (no AMD/Intel Windows box in the lab); NVENC is live-validated. Newer/less
+  battle-tested than the Linux host. Packaging: `packaging/windows/`.
+
+## What's left
+
+1. **Native clients — decode + present: macOS stage 1 done, first light achieved
+   (2026-06-10).** PunktfunkKit compiles and is tested on macOS (AnnexB → VideoToolbox →
+   `AVSampleBufferDisplayLayer`, GCMouse/GCKeyboard capture, `PunktfunkClient` app shell);
+   validated live Mac ↔ this box at 720p60 — vkcube on glass, input injected via gamescope
+   EIS. The app speaks the full ABI v2 trust surface: Keychain-persisted client identity
+   presented on every connect, SPAKE2 PIN pairing UI (host-card context menu + the trust
+   prompt's "Pair with PIN instead…"), TOFU fingerprint prompt. **Gamepads (2026-06-11):**
+   controller discovery + selection in Settings (`GamepadManager` — exactly one pad
+   forwarded as pad 0, auto or pinned; pad TYPE auto-resolves from the physical
+   controller, user-overridable), capture incl. DualSense touchpad/motion
+   (`GamepadCapture`/`GamepadWire`), feedback rendering (rumble → CoreHaptics; lightbar /
+   player LEDs / adaptive triggers → `GCDeviceLight`/`playerIndex`/
+   `GCDualSenseAdaptiveTrigger` via the table-driven `DualSenseTriggerEffect` parser).
+   Loopback-tested end to end (`PUNKTFUNK_TEST_FEEDBACK=1` scripted burst); DualSense
+   motion sign/scale derived, not yet live-verified. Tests: `swift test` in
+   `clients/apple` (unit + real-codec round trip),
+   `test-loopback.sh` (Swift client vs synthetic punktfunk1-hosts on loopback — runs on macOS;
+   includes the pairing ceremony + `--require-pairing` gate),
+   `RemoteFirstLightTests` (full pipeline over the LAN). See
+   [`clients/apple/README.md`](clients/apple/README.md). **Stage 2 presenter**
+   (`VTDecompressionSession` + `CAMetalLayer`) is built and live-validated on glass behind the opt-in
+   `punktfunk.presenter` flag (~11 ms p50 capture→present), to become the default after a few
+   resolution/HDR checks. Next: make stage 2 the default, glass-to-glass numbers via
+   `tools/latency-probe`, iOS/iPadOS/tvOS variants.
+   **Linux stage 1 done, first light 2026-06-12** (`clients/linux`, binary
+   `punktfunk-client`): GTK4/libadwaita shell linking `punktfunk-core` directly (no C ABI;
+   `NativeClient` is now `Sync` — mutexed plane receivers), mDNS host list, TOFU + SPAKE2
+   PIN dialogs (identity shared with client-rs), FFmpeg software HEVC decode (LOW_DELAY,
+   slice threads) → `GtkGraphicsOffload`-wrapped picture, PipeWire playback (mic-player
+   jitter ring inverted), SDL3 gamepad capture + rumble/lightbar feedback, keyboard via
+   exact inverse of the host VK table, absolute mouse + 120-unit scroll. Validated live
+   against `serve` on this box: 1080p60, steady 60 fps, capture→decoded p50
+   ≈6.4 ms (debug build). `--connect host[:port]` for scripting. **Swift-parity batch +
+   stage 1.5 (2026-06-12 evening)**: capture state machine (click-to-capture,
+   Ctrl+Alt+Shift+Q / focus-loss release, held-state flush), app-lifetime SDL gamepad
+   service (pad pin UI, auto type from the physical pad, DualSense touchpad/motion 0xCC +
+   raw-DS5-effects trigger/player-LED replay — needs a physical pad to live-verify), mic
+   uplink (validated live), per-host speed test, compositor pref, native-display mode
+   default, saved-hosts list, .deb + RPM-subpackage CI (deb.yml/rpm.yml). **VAAPI decode
+   → DRM-PRIME dmabuf → `GdkDmabufTexture`** (BT.709 color state; Tier-1 zero-copy on
+   Intel/AMD, `PUNKTFUNK_DECODER=software|vaapi` override) with a proven fallback ladder —
+   no VAAPI device (NVIDIA) or mid-session VAAPI error → software decode. **First AMD test
+   (Steam Deck) hit a green-screen bug, fixed:** FFmpeg's VAAPI export uses
+   `SEPARATE_LAYERS`, so NV12 arrives as two single-plane layers (R8 luma + GR88 chroma,
+   one shared fd); the mapper took `layers[0]` only → GTK got a luma-only R8 texture, chroma
+   read as 0 → green field / red whites. Fix derives the combined fourcc from the decoder
+   `sw_format` (→ `DRM_FORMAT_NV12`) and flattens all planes across all layers (mpv's
+   pattern); a first-frame descriptor dump logs the real layout. Awaiting Steam Deck
+   reconfirm. Next: the stage-2 raw-Wayland
+   presenter (wp_presentation feedback, tearing-control, Vulkan Video on NVIDIA) —
+   **wgpu/winit rejected** (no dmabuf import / presentation feedback / shortcuts-inhibit).
+   **Windows stage 1 done 2026-06-15** (`clients/windows`, binary
+   `punktfunk-client`): pure-Rust **WinUI 3** UI via **windows-reactor** (a declarative React-like
+   framework backed by WinUI; PR #4499 added the `SwapChainPanel` widget + `set_swap_chain`). The
+   video is a **`SwapChainPanel`** bound to a **D3D11 composition swapchain** (WARP fallback for
+   the GPU-less dev box; runtime-compiled fullscreen-triangle shaders, Contain-fit letterbox),
+   driven by reactor's per-frame `on_rendering`. **FFmpeg HEVC decode with a D3D11VA
+   zero-copy hardware path** (`gpu.rs` shares one D3D11 device — hardware+`VIDEO_SUPPORT`, WARP
+   fallback, multithread-protected — between the decoder and presenter; the decoder outputs
+   NV12/P010 `ID3D11Texture2D` array slices with `BIND_SHADER_RESOURCE` and the presenter samples
+   them via per-plane SRVs + YUV→RGB shaders — NV12/BT.709, P010/BT.2020-PQ; **software CPU decode
+   stays as the robust fallback**, auto-selected with a `DecoderPref` override). **HDR10**: the
+   client advertises 10-bit/HDR (Settings toggle), detects PQ in-band (`transfer == SMPTE2084`),
+   and flips the swapchain to `R10G10B10A2` + ST.2084 with HDR10 metadata. **WASAPI** render + mic
+   capture, **SDL3** gamepads (rumble/lightbar/DualSense), `mdns-sd` discovery, and the full trust
+   surface — all **in-app**: a polished WinUI shell (host cards w/ monogram + status pills,
+   `InfoBar` errors/hints, `ToggleSwitch` settings, status-chip stream HUD showing GPU/CPU decode +
+   HDR), host list (live mDNS + saved + manual), settings (resolution/refresh/decoder/bitrate/HDR/
+   mic), SPAKE2 PIN pairing screen, TOFU, pinned-fp-mismatch re-pair. **(D3D11VA + HDR present + the
+   GUI polish are written against the windows-rs/reactor APIs but not yet on-glass validated — the
+   dev VM is headless/WARP; needs the RTX box.)** **Stream input** is Win32 low-level hooks (`WH_KEYBOARD_LL`/`WH_MOUSE_LL`) — reactor
+   exposes no raw key/pointer events; native Windows VK + absolute mouse (client-rect Contain-fit) +
+   wheel, Ctrl+Alt+Shift+Q capture toggle. `--headless`/`--discover` keep CLI paths. Builds + clippy
+   + fmt green on **`x86_64-pc-windows-msvc` and `aarch64-pc-windows-msvc`** — the latter
+   **cross-compiled off the one x64 runner** (no ARM64 runner; the x64 MSVC toolset's ARM64 cross
+   compiler + a per-arch `FFMPEG_DIR` ARM64 tree, SDL3/libopus build-from-source cross-compile
+   cleanly), and both ship as signed MSIX (`windows-msix.yml` matrix → `..._x64.msix`/`..._arm64.msix`,
+   verified: ARM64 binaries + manifest arch). **windows-reactor is unpublished** (git
+   dep pinned to commit `b4129fcc`; `windows` pinned to the SAME commit so `IDXGISwapChain1` unifies
+   with `set_swap_chain`); its `build.rs` downloads the Win App SDK NuGets + needs `CARGO_WORKSPACE_DIR`
+   set (in the VM build env; `/temp`+`/winmd` gitignored). Gotcha: `CARGO_HOME` must be an ASCII path
+   — the `ü` in the dev box's username breaks SDL3's MSVC precompiled-header build. Next: **on-glass
+   validation** of the D3D11VA decode + HDR present + GUI on the RTX box (the dev VM is
+   headless/Session-0/WARP → the WinUI window + hardware decode need a real display+GPU: RDP or the
+   RTX box), then RAWINPUT relative-mouse pointer-lock and a per-host speed test in the UI.
+   **Android stage 1 done** (`clients/android`, Kotlin app + `native/` Rust JNI core linking
+   `punktfunk-core`; phone + Android TV): NDK `AMediaCodec` hardware HEVC decode → `SurfaceView` incl.
+   **HDR10** (Main10/BT.2020 PQ) with low-latency tuning + a live stats HUD (`decode.rs`/`stats.rs`),
+   Opus/Oboe audio + mic uplink (`audio.rs`/`mic.rs`), gamepad input with rumble/HID feedback
+   (`feedback.rs`), **native `mdns-sd` mDNS discovery** (`discovery.rs`, polled over JNI — the same
+   browse the Linux/Windows clients use, replacing the flaky per-OEM `NsdManager`; Kotlin keeps only
+   the `MulticastLock` + permission UX), SPAKE2 PIN pairing + TOFU (Keystore identity +
+   known-host store), Compose UI (Connect/Settings/Stream) with D-pad/controller focus nav. Built for
+   `arm64-v8a` + `x86_64`; published to Google Play (Internal Testing) via `android.yml`
+   (`ci/play-upload.py`). Next: real-device gamepad/HDR live-verify, presenter/latency polish.
+2. **Sub-frame pipelining**: overlap encode and transmit within a frame. Requires a direct
+   NVENC SDK wrapper (libavcodec only emits whole AUs) — the next big latency lever (~2–4 ms
+   at high res).
+3. **punktfunk/1 protocol growth.** **Done:** unified host (`serve --gamestream` runs GameStream + the
+   punktfunk/1 QUIC host in one process; bare `serve` is the secure native-only default — GameStream is
+   opt-in, trusted-LAN only, security-review #5/#9) with native pairing driven over the mgmt API /
+   web console (`mod native_pairing`: arm-on-demand → display PIN, paired-device list).
+   **Done:** PIN pairing is the default, host-gated — the host requires pairing and advertises
+   `pair=required` unless opted out with `--allow-tofu`/`--open` (then `pair=optional`, accepts
+   unpaired clients); clients render TOFU only for a `pair=optional` host and force re-pairing on a
+   fingerprint change. **Done:** concurrent sessions — the accept loop spawns each session
+   (`--max-concurrent`, default 4, an NVENC bound), each with its own virtual output + encoder, sharing
+   the host-lifetime input/audio/mic services (shared-desktop multi-view on kwin/mutter/wlroots).
+   **Done:** delegated pairing approval (§8b-1) — an unpaired device shows up as a pending request in
+   the web console, one click approves + pins it. Next (see roadmap): gamescope multi-user isolation
+   (per-session input/audio = independent desktops); §8b-2 peer-push approval from a paired device's
+   own app.
+4. **GameStream host polish**: HDR/10-bit (needs HDR capture + metadata plumbing; `av1_nvenc
+   -highbitdepth 1` already encodes Main10 from 8-bit input on this box),
+   reconnect-at-new-mode robustness. AV1 negotiation and surround audio are implemented
+   and unit/live-capture tested — both still need a live Moonlight confirmation (select
+   AV1 in a stock client; a real 5.1/7.1 listen incl. FEC under loss).
+
+Box one-time setup is complete: udev rule + `input` group (gamepads validated live),
+gamescope 3.16.22 installed system-wide (no PATH override), gnome-shell installed (Mutter
+backend validated live). All three compositor backends are live-validated.
+
+## Build / test / run
+
+```sh
+cargo build --workspace          # green on Linux and macOS
+cargo test  --workspace          # unit + loopback + proptest + C ABI harness (~100 tests)
+cargo clippy --workspace --all-targets -- -D warnings
+cargo fmt --all --check
+
+cargo run -p loss-harness        # FEC loss-resilience sweep (no network needed)
+bash crates/punktfunk-core/tests/c/run.sh   # standalone C-ABI link + round-trip proof
+```
+
+Generated artifacts are **checked in** and CI fails on drift: `include/punktfunk_core.h`
+(cbindgen from `punktfunk-core/src/abi.rs`) and `docs/api/openapi.json` (regenerate with
+`cargo run -p punktfunk-host -- openapi > docs/api/openapi.json`; spec lives in `mgmt.rs`).
+
+CI is Gitea Actions (`.gitea/workflows/`, guide: docs-site `ci.md`): `ci.yml` runs the
+workspace checks inside the `git.unom.io/unom/punktfunk-rust-ci` image plus web/docs-site
+build+typecheck; `docker.yml` builds+pushes the web/docs/rust-ci images (host and native
+clients are deliberately NOT containerized); `apple.yml` builds the xcframework and runs
+`swift build`/`swift test` on the `macos-arm64` host-mode runner (home-mac-mini-1,
+provisioned by `scripts/ci/setup-macos-runner.sh`). Per-client/host release workflows:
+`deb.yml`/`rpm.yml`/`flatpak.yml` (Linux client), `android.yml` (Google Play), `windows-msix.yml`
+(Windows client), `windows-host.yml` (Windows host installer), `release.yml` (Apple notarized DMG +
+TestFlight), `decky.yml` (Steam Deck plugin); Windows builds run on a self-hosted Windows runner.
+
+## Layout
+
+```
+crates/punktfunk-core/        protocol · FEC · crypto · quic (punktfunk/1 control plane, feature-gated)
+crates/punktfunk-host/
+  gamestream/             Moonlight compat: nvhttp · pairing · rtsp · control · stream · gamepad · apps
+  vdisplay/{kwin,gamescope,mutter,wlroots}.rs   per-compositor client-sized virtual outputs
+  zerocopy/{egl,cuda,vulkan}.rs         dmabuf → CUDA → NVENC (tiled via EGL/GL, LINEAR via Vulkan)
+  inject/{libei,wlr,gamepad,dualsense}.rs   input backends (uinput xpad + UHID DualSense)
+  encode/{nvenc,linux,vaapi,ffmpeg_win,sw}.rs   per-GPU encoders (NVENC · Linux NVENC/CUDA · VAAPI · AMF/QSV · openh264)
+  capture.rs · encode.rs · audio.rs · spike.rs · punktfunk1.rs · mgmt.rs · native_pairing.rs
+clients/probe/    punktfunk/1 reference/probe client (headless test/measurement tool)
+clients/linux/    native Linux client (GTK4/libadwaita · FFmpeg · PipeWire · SDL3)
+clients/windows/  native Windows client (WinUI 3 via windows-reactor · D3D11 · WASAPI · SDL3)
+clients/apple/    native macOS/iOS/tvOS client (Swift · VideoToolbox · GameController)
+clients/android/  native Android client (Kotlin app + native/ Rust JNI core over punktfunk-core)
+clients/decky/    Steam Deck Decky plugin
+crates/punktfunk-host/src/{capture/dxgi,vdisplay/sudovda,encode/ffmpeg_win,inject/gamepad_windows,audio/wasapi_*,service}.rs   Windows host backends
+web/                          TanStack web console over the mgmt API (status · devices · pairing)
+packaging/                    apt(deb) · RPM/COPR · Arch/sysext · Flatpak · Bazzite bootc · Windows host installer (per-dir READMEs)
+tools/{loss-harness,latency-probe}/     measurement (plan §10)
+scripts/                  60-punktfunk.rules · punktfunk-host.service · host.env.example · headless/
+include/punktfunk_core.h      generated C header
+```
+
+## Design invariants — do not regress
+
+- **One core, linked everywhere.** Protocol/FEC/crypto live only in `punktfunk-core`, behind a
+  stable, versioned C ABI. `tokio`/`quinn` exist only behind the `quic` feature (control
+  plane); **no async on the per-frame path** — native threads only.
+- **Native client resolution, no scaling.** A session gets a virtual output at exactly the
+  client's WxH@Hz via the `VirtualDisplay` trait (`create(mode) → VirtualOutput { node_id,
+  remote_fd, preferred_mode, keepalive }`, RAII teardown). There is no cross-compositor
+  protocol for this — each compositor keeps its own backend.
+- **FEC is the wall-breaker.** GF(2⁸) (≤255 shards/block, Moonlight-compatible) and GF(2¹⁶)
+  Leopard (≤65535 shards/block) — punktfunk/1 negotiates the latter, removing the ~1 Gbps
+  ceiling.
+- **Core security hardening stays intact**: reassembler bounds attacker-controlled fields
+  before allocating (`ReassemblerLimits`); AES-GCM per-direction nonce salts + seq-as-AAD;
+  ABI `struct_size` checks. Regression tests exist — keep them green.
+- **PipeWire consumer discipline**: our capture streams set `node.dont-reconnect` and tear
+  down promptly on negotiation timeout — one wedged link head-blocks the daemon's shared
+  work queue system-wide.
+
+## Running on this box
+
+Headless QEMU VM (Ubuntu 26.04, kernel 7.0), passthrough RTX 5070 Ti (driver 595 **open**
+module — a kernel update silently drops it; reinstall `nvidia-driver-595-open`), no KMS
+scanout → KWin `--drm` impossible; everything renders offscreen via `renderD128`.
+
+```sh
+# compositor session (shell 1, or the systemd unit in scripts/): full headless Plasma.
+# The script sets XDG_MENU_PREFIX=plasma- & co. — without it plasmashell runs but the
+# launcher menu is EMPTY (no apps, no System Settings).
+bash scripts/headless/run-headless-kde.sh 1920x1080
+
+# host (shell 2): bare `serve` is native-only (secure default); add --gamestream for Moonlight compat.
+WAYLAND_DISPLAY=wayland-kde XDG_CURRENT_DESKTOP=KDE PUNKTFUNK_VIDEO_SOURCE=virtual \
+PUNKTFUNK_ZEROCOPY=1 cargo run -rp punktfunk-host -- serve --gamestream
+
+# punktfunk/1 native loopback test (no Moonlight needed; same env as serve, listener persists
+# across sessions — bound it with --max-sessions):
+cargo run -rp punktfunk-host -- punktfunk1-host --source virtual --seconds 10 --max-sessions 1
+cargo run -rp punktfunk-probe -- --mode 1280x720x120 --out /tmp/a.h265 --input-test  # + --pin HEX
+```
+
+Pinned crate facts: `ashpd` 0.13 + `pipewire` 0.9 (must match ashpd's) + `ffmpeg-next` 8.x
+(`ffmpeg-sys-next` auto-detects the system FFmpeg, so it builds against **FFmpeg 7.x/libavcodec 61
+or 8.x/libavcodec 62** — validated live on Ubuntu 26.04 (8) and Bazzite F43 (7.1); the zero-copy
+FFI also link-needs `libGL`/`libgbm`/`libcuda` at build time). Env knobs: `PUNKTFUNK_VIDEO_SOURCE=virtual|portal`,
+`PUNKTFUNK_COMPOSITOR=kwin|gamescope|mutter`, `PUNKTFUNK_ZEROCOPY=1`, `PUNKTFUNK_GAMESCOPE_APP=...`,
+`PUNKTFUNK_INPUT_BACKEND=...`, `PUNKTFUNK_PERF=1` (per-stage timing), `PUNKTFUNK_VIDEO_DROP=N` (FEC
+test), `PUNKTFUNK_FEC_PCT=N`, `PUNKTFUNK_DSCP=1` (opt-in DSCP/SO_PRIORITY media QoS on the data +
+GameStream video/audio sockets; no-op on the wire on Windows without a qWAVE policy).
+
+## Conventions
+
+- Rust 2021, `rustfmt` + `clippy -D warnings` clean before commit.
+- Match the surrounding code's comment density and naming.
+- Commit messages end with the Co-Authored-By trailer (see `git log`).
+- `pkill` caution on this box: match exact comm names (`pkill -x gamescope-wl`,
+  `pkill -x punktfunk-host`) — `pkill -f` self-matches the invoking shell.
@@ -0,0 +1,35 @@
+[workspace]
+resolver = "2"
+members = [
+    "crates/punktfunk-core",
+    "crates/punktfunk-host",
+    "crates/pf-vdisplay-proto",
+    "clients/probe",
+    "clients/linux",
+    "clients/windows",
+    "clients/android/native",
+    "tools/latency-probe",
+    "tools/loss-harness",
+]
+
+[workspace.package]
+version = "0.0.1"
+edition = "2021"
+rust-version = "1.82"
+license = "MIT OR Apache-2.0"
+authors = ["unom"]
+repository = "https://git.unom.io/unom/punktfunk"
+
+[profile.release]
+opt-level = 3
+lto = "thin"
+codegen-units = 1
+# NOTE: deliberately NOT `panic = "abort"`. punktfunk-core ships as a cdylib/staticlib into
+# third-party apps (Swift/Kotlin/C) and its C ABI catches panics at the boundary
+# (`catch_unwind` → `PunktfunkStatus::Panic`). `panic = "abort"` would make that guard a
+# no-op and let a stray panic abort the embedding application. Unwinding keeps the
+# documented isolation guarantee real.
+
+# The per-frame hot path must stay fast even in dev builds.
+[profile.dev.package."*"]
+opt-level = 2
@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative
+          Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 unom
+
+   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
+
+       http://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.
@@ -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.
@@ -1,2 +1,146 @@
-# lumen
+# punktfunk

+**Low-latency desktop and game streaming, Linux-first.** Run the host on a Linux machine — or a
+Windows PC — with an NVIDIA GPU, connect from a Mac, PC, phone, tablet, or TV, and stream your desktop
+or games — each device at its **own native resolution and refresh rate**, over your local network.
+
+📖 **Documentation: [docs.punktfunk.unom.io](https://docs.punktfunk.unom.io)** — start with
+[How It Works](https://docs.punktfunk.unom.io/docs/how-it-works) or the
+[Quick Start](https://docs.punktfunk.unom.io/docs/quickstart).
+
+punktfunk pairs a **virtual-display streaming host** with native clients on every platform. It speaks
+the existing **GameStream** protocol, so any [Moonlight](https://moonlight-stream.org/) client works
+day one — and adds its own faster **`punktfunk/1`** protocol that breaks the ~1 Gbps FEC wall with a
+**GF(2¹⁶) Leopard-RS** transport. A single shared **Rust core** (`punktfunk-core`) holds the
+protocol, FEC, and crypto, linked into the host and every client over a stable C ABI.
+
+## What makes it different
+
+- **Your device's exact mode.** For each client that connects, the host spins up a virtual display
+  sized to that device — 1080p60 to a laptop, 1440p120 to a desktop, 4K to a TV, all at once. No
+  letterboxing, no scaling, no rearranging your real monitors.
+- **Low latency, GPU end to end.** Frames go straight from the compositor to the NVENC encoder with
+  zero CPU copies (dmabuf → CUDA/Vulkan → NVENC), over a transport tuned for responsiveness rather
+  than throughput. Stable 240 fps at 5120×1440; sub-millisecond capture-to-reassembly on a LAN.
+- **Works with what you already have.** Any Moonlight/Artemis client connects over GameStream — and
+  native apps for macOS, Linux, Windows, and Android use the lower-latency `punktfunk/1` protocol.
+- **Secure by default.** Hosts require a one-time SPAKE2 **PIN pairing**; after that, devices
+  reconnect on a pinned identity. No accounts, no cloud. Hosts auto-advertise over mDNS, so clients
+  find them on the network without typing an IP.
+
+## Status
+
+| Component | State |
+|-----------|-------|
+| **Core** — `punktfunk-core` + C ABI (protocol · FEC · crypto · QUIC) | ✅ Complete & hardened |
+| **GameStream host** → stock Moonlight | ✅ Live end-to-end: pairing, RTSP, audio, per-client virtual output at native resolution, GPU zero-copy NVENC, gamepads |
+| **Native protocol** — `punktfunk/1` | ✅ Validated live: QUIC control + GF(2¹⁶) FEC/AES-GCM data plane, PIN pairing, mDNS discovery, mid-stream mode renegotiation |
+| **Windows host** (NVIDIA, x64) | 🟡 Implemented & shipping as a signed installer (DXGI capture · SudoVDA virtual display · NVENC · WASAPI · ViGEm); NVIDIA-only, newer than the Linux host |
+| **macOS / iOS / tvOS client** (`clients/apple`) | ✅ Streaming live: VideoToolbox decode, controllers incl. DualSense, discovery, pairing, speed test |
+| **Linux client** (`clients/linux`, GTK4) | ✅ Streaming live: FFmpeg + VAAPI zero-copy decode, PipeWire audio, SDL3 controllers; ships as Flatpak/apt/rpm/Arch |
+| **Android client** (`clients/android`, phone + TV) | ✅ Streaming live: AMediaCodec decode + HDR10, Oboe audio, controllers, discovery, pairing |
+| **Windows client** (`clients/windows`, WinUI 3) | 🟡 Stage 1 complete, ships as signed MSIX (x64 + ARM64); D3D11VA decode + HDR present pending on-glass validation |
+| **Web console + management API** (`web/`) | ✅ TanStack console over the OpenAPI mgmt API: host status, paired devices, on-demand PIN pairing |
+
+The **GameStream host works with a stock Moonlight client** — validated live on NVIDIA hardware
+(RTX 5070 Ti, RTX 4090): PIN pairing that persists across restarts, an app catalog, RTSP/ENet/audio,
+and **video at the client's exact resolution and refresh** via a per-session virtual output (KWin,
+gamescope, Mutter, and Sway/wlroots backends), encoded with GPU **zero-copy** (dmabuf → CUDA/Vulkan →
+NVENC) up to 5120×1440@240. The native **`punktfunk/1`** protocol adds a QUIC control plane and a
+GF(2¹⁶) Leopard-FEC + AES-GCM data plane (p50 ~0.8 ms capture→reassembled at 720p120), with
+mid-stream mode renegotiation and a wall-clock skew handshake so latency stays valid across machines.
+Both run from **one process**: bare `punktfunk-host serve` is the **secure native-only default**
+(`punktfunk/1` + the management API/web console), and `serve --gamestream` additionally enables the
+GameStream/Moonlight-compat planes (opt-in, trusted-LAN only — GameStream has inherent on-path
+weaknesses). The host is managed through a REST API and web console. Builds against FFmpeg 7 or 8.
+
+Full milestone status: **[docs.punktfunk.unom.io/docs/status](https://docs.punktfunk.unom.io/docs/status)** ·
+roadmap: **[/docs/roadmap](https://docs.punktfunk.unom.io/docs/roadmap)**.
+
+## Install the host
+
+Pick your platform and install from its package registry — the per-platform guide covers adding the
+repo, first run, and the web console. The Linux host is the primary, most battle-tested path; a
+Windows host (NVIDIA-only) also ships as a signed installer.
+
+| Platform | Install | Guide |
+|--------|---------|-------|
+| **Ubuntu / Debian** (apt) | `sudo apt install punktfunk-host` *(after adding the repo)* | [Ubuntu — GNOME](https://docs.punktfunk.unom.io/docs/ubuntu-gnome) · [KDE](https://docs.punktfunk.unom.io/docs/ubuntu-kde) |
+| **Fedora / Bazzite** (rpm-ostree) | `rpm-ostree install punktfunk punktfunk-web` *(or the bootc image)* | [Fedora — KDE](https://docs.punktfunk.unom.io/docs/fedora-kde) · [Bazzite](https://docs.punktfunk.unom.io/docs/bazzite) |
+| **Arch / Steam Deck** (PKGBUILD / sysext) | `makepkg -si` *(Arch)* · sysext `.raw` *(SteamOS)* | [packaging/arch](packaging/arch/README.md) |
+| **Windows** (NVIDIA, x64) | signed `setup.exe` from the package registry | [Windows Host](https://docs.punktfunk.unom.io/docs/windows-host) |
+
+`punktfunk-host` is the streaming host; `punktfunk-web` is the browser console (pairing + status).
+After install, run `punktfunk-host serve` inside your desktop session (the secure native default;
+add `--gamestream` on a trusted LAN if you also want stock Moonlight clients), then pair from the web
+console. Full instructions: **[docs.punktfunk.unom.io/docs/install](https://docs.punktfunk.unom.io/docs/install)**.
+
+## Connect a client
+
+| Streaming to… | Use |
+|---|---|
+| Mac, iPhone, iPad, Apple TV | The **Apple app** (`clients/apple`) — also on TestFlight |
+| Linux desktop / laptop, Steam Deck | **`punktfunk-client`** (Flatpak / apt / rpm / Arch) |
+| Android phone or TV | The **Android app** (`clients/android`) |
+| Windows | Native **`punktfunk-client`** (signed MSIX) or **Moonlight** |
+| Anything else (browser, old phone, smart TV) | **Moonlight** over GameStream |
+
+Each client discovers hosts on the network automatically and does a one-time
+[PIN pairing](https://docs.punktfunk.unom.io/docs/pairing). Per-device install steps:
+**[/docs/install-client](https://docs.punktfunk.unom.io/docs/install-client)**.
+
+## Build & test (from source)
+
+For development, or as an install fallback where no package is available:
+
+```sh
+cargo build --workspace          # the Rust core, host, Linux client, and probe (Linux & macOS)
+cargo test  --workspace          # unit + loopback + proptest + C ABI harness
+cargo clippy --workspace --all-targets -- -D warnings
+cargo fmt --all --check
+
+cargo run -p loss-harness        # FEC loss-resilience sweep (no network needed)
+bash crates/punktfunk-core/tests/c/run.sh   # standalone C-ABI link + round-trip proof
+```
+
+The C header regenerates from `crates/punktfunk-core/src/abi.rs` on every build (cbindgen via
+`build.rs`) into `include/punktfunk_core.h`. The Apple, Android, and Windows clients have their own
+toolchains (Xcode/`swift build`, Gradle, and `cargo` on the MSVC target) — see each client's README
+and the [docs site](https://docs.punktfunk.unom.io).
+
+## Layout
+
+```
+crates/
+  punktfunk-core/   protocol · FEC · pacing · crypto · QUIC control plane — the C ABI (lib + cdylib + staticlib)
+  punktfunk-host/   Linux host: virtual displays · capture · encode · input · GameStream · punktfunk/1 · mgmt
+clients/
+  apple/    macOS / iOS / tvOS app (Swift · VideoToolbox · Metal · GameController)
+  linux/    Linux desktop app (Rust · GTK4/libadwaita · FFmpeg/VAAPI · PipeWire · SDL3)
+  windows/  Windows desktop app (Rust · WinUI 3 · D3D11 · WASAPI · SDL3)
+  android/  Android phone + TV app (Kotlin · Rust JNI core · AMediaCodec · Oboe)
+  probe/    headless reference / measurement client for punktfunk/1
+  decky/    Steam Deck Decky plugin
+web/                         web console (TanStack) over the management API — status · devices · pairing
+packaging/                   apt · rpm / COPR · Arch · Flatpak · Bazzite bootc image
+docs-site/                   public documentation site (Fumadocs) — https://docs.punktfunk.unom.io
+docs/                        design notes & deep-dive plans
+include/punktfunk_core.h     cbindgen-generated C header (checked in)
+tools/                       latency-probe · loss-harness (measurement)
+```
+
+## Design invariants
+
+- **One core, linked everywhere.** Protocol, FEC, and crypto live in `punktfunk-core` exactly once,
+  exposed over a stable, versioned C ABI (`punktfunk_abi_version()`, `PunktfunkConfig` carries its own
+  `struct_size`). Every native client links the same core.
+- **No async on the hot path.** The per-frame pipeline uses native threads only; `tokio`/`quinn` are
+  gated behind the off-by-default `quic` feature (control plane only).
+- **Native client resolution, no scaling.** Each session gets a virtual output at exactly the
+  client's WxH@Hz; each compositor keeps its own backend behind a shared `VirtualDisplay` trait.
+- **FEC is the wall-breaker.** GF(2⁸) (≤255 shards/block) for Moonlight compatibility; GF(2¹⁶)
+  (≤65535 shards/block, SIMD, O(n log n)) for `punktfunk/1` to push past ~1 Gbps.
+
+## License
+
+MIT OR Apache-2.0.
@@ -0,0 +1,64 @@
+# CI builder for the punktfunk RPM. The Fedora version is parameterized so one Dockerfile
+# serves every target whose ffmpeg soname must match: Fedora 43 == Bazzite's base (group
+# "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 --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.
+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 \
+      "https://mirrors.rpmfusion.org/free/fedora/rpmfusion-free-release-$(rpm -E %fedora).noarch.rpm" \
+      "https://mirrors.rpmfusion.org/nonfree/fedora/rpmfusion-nonfree-release-$(rpm -E %fedora).noarch.rpm" \
+  && dnf -y install \
+      # rpmbuild + source-tarball tooling; nodejs runs the Gitea Actions JS (checkout/cache)
+      # AND the punktfunk-web .output at runtime; unzip is for the bun installer below.
+      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
+      ffmpeg-devel pipewire-devel wayland-devel libxkbcommon-devel opus-devel \
+      mesa-libGL-devel mesa-libgbm-devel \
+      # punktfunk-client link deps (GTK4 shell + SDL3 gamepads)
+      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
+# real driver lib, minus the driver). On Bazzite the real driver provides libcuda.so.1 at runtime.
+# The symbol list is `nm -D --undefined-only` of the built host binary; a new cu* call would fail
+# the link with a clear "undefined reference", flagging this list to update.
+RUN set -eux; : > /tmp/cuda_stub.c; \
+    for s in cuCtxCreate_v2 cuCtxSetCurrent cuCtxSynchronize cuDestroyExternalMemory \
+             cuDeviceGet cuExternalMemoryGetMappedBuffer cuGraphicsGLRegisterImage \
+             cuGraphicsMapResources cuGraphicsSubResourceGetMappedArray cuGraphicsUnmapResources \
+             cuGraphicsUnregisterResource cuImportExternalMemory cuInit cuMemAllocPitch_v2 \
+             cuMemcpy2D_v2 cuMemFree_v2; do \
+      echo "int $s(void){return 0;}" >> /tmp/cuda_stub.c; \
+    done; \
+    gcc -shared -fPIC -Wl,-soname,libcuda.so.1 -o /usr/lib64/libcuda.so.1 /tmp/cuda_stub.c; \
+    ln -sf libcuda.so.1 /usr/lib64/libcuda.so; \
+    rm -f /tmp/cuda_stub.c; ldconfig; test -e /usr/lib64/libcuda.so
+
+# Rustup (not Fedora's packaged rust) so rust-toolchain.toml's pinned channel resolves, matching
+# the Ubuntu builder. Shared location so jobs running as any uid can use it.
+ENV RUSTUP_HOME=/usr/local/rustup \
+    CARGO_HOME=/usr/local/cargo \
+    PATH=/usr/local/cargo/bin:$PATH
+RUN curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs \
+    | sh -s -- -y --no-modify-path --profile minimal \
+    && chmod -R a+w "$RUSTUP_HOME" "$CARGO_HOME" \
+    && rustc --version && cargo --version
@@ -0,0 +1,50 @@
+# CI builder for the Rust workspace — Ubuntu 26.04 to match the dev/host boxes
+# (FFmpeg 8 / libavcodec 62, PipeWire 1.6). Used by .gitea/workflows/ci.yml as the job
+# container; rebuilt+pushed by .gitea/workflows/docker.yml.
+#
+#   docker build -f ci/rust-ci.Dockerfile -t punktfunk-rust-ci ci
+#
+# The workspace links real system libs at build time (CLAUDE.md "Pinned crate facts"):
+# FFmpeg, PipeWire, Opus, GL/EGL/GBM — and libcuda, which has no real driver here; the
+# zerocopy path only needs the symbols at link time, so a driver userspace package plus a
+# libcuda.so -> libcuda.so.1 symlink stands in for it (CI never executes the CUDA path).
+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); unzip is for the bun installer
+    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 \
+    # capture / audio / display stacks (+xkbcommon for the wlr input backend)
+    libpipewire-0.3-dev libopus-dev libwayland-dev libxkbcommon-dev \
+    # zerocopy link deps (GL via libglvnd, EGL, GBM)
+    libgl-dev libegl-dev libgbm-dev \
+    # punktfunk-client-linux (GTK4/libadwaita shell, SDL3 gamepads)
+    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.
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends libnvidia-compute-580-server \
+    && rm -rf /var/lib/apt/lists/* \
+    && ln -sf libcuda.so.1 /usr/lib/x86_64-linux-gnu/libcuda.so \
+    && test -e /usr/lib/x86_64-linux-gnu/libcuda.so.1
+
+# Toolchain shared across CI users (jobs may run as different uids).
+ENV RUSTUP_HOME=/usr/local/rustup \
+    CARGO_HOME=/usr/local/cargo \
+    PATH=/usr/local/cargo/bin:$PATH
+RUN curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs \
+    | sh -s -- -y --no-modify-path --profile minimal \
+        --component rustfmt,clippy \
+    && chmod -R a+w "$RUSTUP_HOME" "$CARGO_HOME" \
+    && rustc --version && cargo clippy --version && cargo fmt --version
@@ -0,0 +1,9 @@
+# Punktfunk Android Release Secrets
+# Copy this file to .env and fill in the values.
+# DO NOT COMMIT THE .env FILE!
+
+RELEASE_KEYSTORE_FILE=../punktfunk-release.jks
+RELEASE_KEYSTORE_PASSWORD=
+RELEASE_KEY_ALIAS=punktfunk-key
+RELEASE_KEY_PASSWORD=
+VERSION_CODE=1
@@ -0,0 +1,15 @@
+# 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/
+
+# Secrets
+.env
+*.jks
@@ -0,0 +1,83 @@
+# punktfunk Android client
+
+Native Android client for **punktfunk/1**, targeting **phone + TV** (Compose, D-pad + touch).
+
+## 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** (`clients/android/native` → `libpunktfunk_android.so`) | the JNI seam, `NativeClient` (QUIC control + UDP data plane), AnnexB→`AMediaCodec` decode, Opus+Oboe audio, VK keymap, latency math, trust/pairing, **mDNS discovery** (`mdns-sd`, the same browse the Linux/Windows clients use) |
+| **Kotlin** (`clients/android`) | Compose UI (host grid / settings / stream), `SurfaceView` lifecycle, input capture, the Wi-Fi `MulticastLock` + permission UX, Keystore identity, permissions |
+
+The single seam is `io.unom.punktfunk.kit.NativeBridge` ⇄ `Java_io_unom_punktfunk_kit_NativeBridge_*`.
+
+## Layout
+
+```
+clients/android/native/          Rust cdylib (workspace member) — links punktfunk-core directly
+  src/lib.rs                       JNI seam (connect/pair, input, plane getters, abi/core version)
+  src/session.rs                   session lifecycle + plane pumps
+  src/decode.rs                    AnnexB → AMediaCodec HEVC hardware decode → SurfaceView (incl. HDR10)
+  src/audio.rs · src/mic.rs        Opus + Oboe playback / mic uplink (jitter ring)
+  src/feedback.rs                  rumble + HID output (lightbar / adaptive triggers)
+  src/stats.rs                     live video stats
+
+clients/android/                   Gradle project (this dir)
+  settings.gradle.kts · build.gradle.kts · gradle.properties · gradlew
+  app/                             :app — Compose UI: Connect / Settings / Stream screens (phone + TV)
+  kit/                             :kit — NativeBridge · discovery (native mdns-sd, polled) · Gamepad · Keymap ·
+                                         security (Keystore identity + known-host store) · cargo-ndk build
+```
+
+## Prerequisites
+
+- Android SDK + **NDK r30** (`30.0.14904198`), `platforms;android-37.0`, `build-tools;37.0.0`,
+  **`cmake;3.22.1`** (`sdkmanager "cmake;3.22.1"` — the `cmake` crate builds libopus with it)
+- **JDK 21** for Gradle/AGP (AGP 9.2 runs on JDK 17–21, *not* a newer default JDK like 25)
+- Rust + `rustup target add aarch64-linux-android x86_64-linux-android` + `cargo install cargo-ndk`
+
+Toolchain pinned: AGP 9.2.0 · Gradle 9.4.1 · Kotlin 2.3.21 · Compose BOM 2026.05.01 ·
+compileSdk 37 · targetSdk 36 · minSdk 31 · ABIs arm64-v8a + x86_64.
+
+## Build & run
+
+**Android Studio:** open `clients/android` — it uses its bundled JBR 21 automatically. The
+`cargoNdk*` task builds the `.so` as part of the normal build.
+
+**CLI** (point Gradle at a JDK 21 if your machine default is newer, e.g. JDK 25):
+
+```sh
+# Adoptium/Temurin 21 (installed by the Android Studio setup, or `brew install temurin@21`):
+export JAVA_HOME="$(/usr/libexec/java_home -v 21)"
+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/`. Launch it, pick a host from the list, pair,
+and stream.
+
+## Status
+
+A working native client (phone + Android TV), at parity with the Linux and Apple apps for the core
+streaming experience:
+
+- **Video** — `AMediaCodec` hardware HEVC decode → `SurfaceView`, including **HDR10** (Main10 /
+  BT.2020 PQ), with low-latency decode tuning and a live stats HUD.
+- **Audio** — Opus + Oboe playback with a jitter ring, plus mic uplink to the host.
+- **Input** — game controllers (buttons + axes) with rumble and HID feedback; D-pad /
+  game-controller focus navigation for the couch (TV + phone).
+- **Discovery & trust** — native `mdns-sd` mDNS host list (polled over JNI; the same browse the
+  Linux/Windows clients use, not `NsdManager`), SPAKE2 PIN pairing and TOFU, with a
+  Keystore-wrapped client identity and a known-host store.
+- **UI** — Compose host list / settings / stream screens, Material You theming.
+- **Shipping** — built for `arm64-v8a` + `x86_64`; published to Google Play (Internal Testing).
+
+`crates/punktfunk-core` uses the `ring` `rcgen` backend so the client `.so` is aws-lc-free.
@@ -0,0 +1,102 @@
+import org.jetbrains.kotlin.gradle.dsl.JvmTarget
+
+import java.util.Properties
+
+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 {
+        // Load from .env if it exists (local dev), otherwise from System.getenv (CI)
+        val envFile = project.rootProject.file(".env")
+        val props = Properties()
+        if (envFile.exists()) {
+            envFile.inputStream().use { props.load(it) }
+        }
+
+        applicationId = "io.unom.punktfunk"
+        minSdk = 31
+        targetSdk = 36
+        val vCode = (props.getProperty("VERSION_CODE") ?: System.getenv("VERSION_CODE"))
+        versionCode = vCode?.toInt() ?: 1
+        // versionName is the single project version, threaded from CI (a vX.Y.Z release or a
+        // canary string). versionCode stays the monotonic run number (Play rejects regressions).
+        versionName = (props.getProperty("VERSION_NAME") ?: System.getenv("VERSION_NAME")) ?: "0.0.2"
+        ndk { abiFilters += listOf("arm64-v8a", "x86_64") }
+    }
+
+    signingConfigs {
+        create("release") {
+            // Load from .env if it exists (local dev), otherwise from System.getenv (CI)
+            val envFile = project.rootProject.file(".env")
+            val props = Properties()
+            if (envFile.exists()) {
+                envFile.inputStream().use { props.load(it) }
+            }
+
+            val ksFile = props.getProperty("RELEASE_KEYSTORE_FILE") ?: System.getenv("RELEASE_KEYSTORE_FILE")
+            if (ksFile != null) {
+                storeFile = file(ksFile)
+                storePassword = props.getProperty("RELEASE_KEYSTORE_PASSWORD") ?: System.getenv("RELEASE_KEYSTORE_PASSWORD")
+                keyAlias = props.getProperty("RELEASE_KEY_ALIAS") ?: System.getenv("RELEASE_KEY_ALIAS")
+                keyPassword = props.getProperty("RELEASE_KEY_PASSWORD") ?: System.getenv("RELEASE_KEY_PASSWORD")
+            }
+        }
+    }
+
+    buildTypes {
+        release {
+            isMinifyEnabled = true
+            isShrinkResources = true
+            proguardFiles(getDefaultProguardFile("proguard-android-optimize.txt"), "proguard-rules.pro")
+            signingConfig = signingConfigs.getByName("release")
+        }
+    }
+
+    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.
+}
@@ -0,0 +1,17 @@
+# Punktfunk ProGuard Rules
+
+# Keep the Native Bridge and its methods for JNI
+-keep class io.unom.punktfunk.kit.NativeBridge { *; }
+-keepclasseswithmembernames class * {
+    native <methods>;
+}
+
+# Keep the models that might be serialized or accessed via JNI
+-keep class io.unom.punktfunk.models.** { *; }
+-keep class io.unom.punktfunk.kit.discovery.** { *; }
+-keep class io.unom.punktfunk.kit.security.** { *; }
+
+# Compose rules are usually handled by the plugin, but we can add more if needed
+-keepclassmembers class **.R$* {
+    public static <fields>;
+}
@@ -0,0 +1,51 @@
+<?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 (native mdns-sd browse). Requested
+         opportunistically — raw multicast reception needs only the MulticastLock, not this. -->
+    <uses-permission
+        android:name="android.permission.NEARBY_WIFI_DEVICES"
+        android:usesPermissionFlags="neverForLocation" />
+    <!-- HostDiscovery holds a MulticastLock while the native mDNS browse runs — raw multicast
+         reception needs it (also an OEM Wi-Fi power-save hedge). -->
+    <uses-permission android:name="android.permission.CHANGE_WIFI_MULTICAST_STATE" />
+    <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
+    <!-- Enforced from Android 17 (SDK 37) for ALL local-network traffic incl. the QUIC socket.
+         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>
@@ -0,0 +1,91 @@
+package io.unom.punktfunk
+
+import androidx.compose.animation.AnimatedContent
+import androidx.compose.animation.AnimatedVisibility
+import androidx.compose.animation.ExperimentalAnimationApi
+import androidx.compose.animation.fadeIn
+import androidx.compose.animation.fadeOut
+import androidx.compose.animation.scaleIn
+import androidx.compose.animation.scaleOut
+import androidx.compose.animation.slideInHorizontally
+import androidx.compose.animation.slideOutHorizontally
+import androidx.compose.animation.togetherWith
+import androidx.compose.foundation.layout.Box
+import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.foundation.layout.padding
+import androidx.compose.material3.Icon
+import androidx.compose.material3.NavigationBar
+import androidx.compose.material3.NavigationBarItem
+import androidx.compose.material3.Scaffold
+import androidx.compose.material3.Text
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.getValue
+import androidx.compose.runtime.mutableLongStateOf
+import androidx.compose.runtime.mutableStateOf
+import androidx.compose.runtime.remember
+import androidx.compose.runtime.setValue
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.platform.LocalContext
+import io.unom.punktfunk.models.Tab
+
+@Composable
+fun App() {
+    val context = LocalContext.current
+    val settingsStore = remember { SettingsStore(context) }
+    var settings by remember { mutableStateOf(settingsStore.load()) }
+    var streamHandle by remember { mutableLongStateOf(0L) } // 0 = not streaming
+    var tab by remember { mutableStateOf(Tab.Connect) }
+
+    AnimatedContent(
+        targetState = streamHandle != 0L,
+        transitionSpec = {
+            fadeIn() togetherWith fadeOut()
+        },
+        label = "StreamTransition"
+    ) { isStreaming ->
+        if (isStreaming) {
+            // 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)) {
+                    AnimatedContent(
+                        targetState = tab,
+                        transitionSpec = {
+                            if (targetState.ordinal > initialState.ordinal) {
+                                slideInHorizontally { it } + fadeIn() togetherWith
+                                        slideOutHorizontally { -it } + fadeOut()
+                            } else {
+                                slideInHorizontally { -it } + fadeIn() togetherWith
+                                        slideOutHorizontally { it } + fadeOut()
+                            }
+                        },
+                        label = "TabTransition"
+                    ) { targetTab ->
+                        when (targetTab) {
+                            Tab.Connect -> ConnectScreen(settings = settings, onConnected = { streamHandle = it })
+                            Tab.Settings -> SettingsScreen(
+                                initial = settings,
+                                onChange = { settings = it; settingsStore.save(it) },
+                                onBack = { tab = Tab.Connect },
+                            )
+                        }
+                    }
+                }
+            }
+        }
+    }
+}
@@ -0,0 +1,592 @@
+package io.unom.punktfunk
+
+import android.Manifest
+import android.content.Context
+import android.content.pm.PackageManager
+import android.os.Build
+import androidx.activity.compose.rememberLauncherForActivityResult
+import androidx.activity.result.contract.ActivityResultContracts
+import androidx.compose.animation.AnimatedVisibility
+import androidx.compose.animation.fadeIn
+import androidx.compose.animation.fadeOut
+import androidx.compose.animation.scaleIn
+import androidx.compose.animation.scaleOut
+import androidx.compose.foundation.layout.Arrangement
+import androidx.compose.foundation.layout.Box
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.PaddingValues
+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.lazy.grid.GridCells
+import androidx.compose.foundation.lazy.grid.GridItemSpan
+import androidx.compose.foundation.lazy.grid.LazyVerticalGrid
+import androidx.compose.foundation.lazy.grid.items
+import androidx.compose.foundation.rememberScrollState
+import androidx.compose.foundation.text.KeyboardOptions
+import androidx.compose.foundation.verticalScroll
+import androidx.compose.material.icons.Icons
+import androidx.compose.material.icons.filled.Add
+import androidx.compose.material3.AlertDialog
+import androidx.compose.material3.Button
+import androidx.compose.material3.CircularProgressIndicator
+import androidx.compose.material3.ExperimentalMaterial3Api
+import androidx.compose.material3.ExtendedFloatingActionButton
+import androidx.compose.material3.Icon
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.ModalBottomSheet
+import androidx.compose.material3.OutlinedTextField
+import androidx.compose.material3.Surface
+import androidx.compose.material3.Text
+import androidx.compose.material3.TextButton
+import androidx.compose.material3.rememberModalBottomSheetState
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.DisposableEffect
+import androidx.compose.runtime.LaunchedEffect
+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.platform.LocalContext
+import androidx.compose.ui.text.input.KeyboardType
+import androidx.compose.ui.text.style.TextAlign
+import androidx.compose.ui.unit.dp
+import androidx.core.content.ContextCompat
+import io.unom.punktfunk.components.EmptyHostsState
+import io.unom.punktfunk.components.HostCard
+import io.unom.punktfunk.components.SectionLabel
+import io.unom.punktfunk.kit.Gamepad
+import io.unom.punktfunk.kit.NativeBridge
+import io.unom.punktfunk.kit.discovery.DiscoveredHost
+import io.unom.punktfunk.kit.discovery.HostDiscovery
+import io.unom.punktfunk.kit.security.ClientIdentity
+import io.unom.punktfunk.kit.security.IdentityStore
+import io.unom.punktfunk.kit.security.KnownHost
+import io.unom.punktfunk.kit.security.KnownHostStore
+import io.unom.punktfunk.kit.security.obtainIdentity
+import io.unom.punktfunk.models.HostStatus
+import io.unom.punktfunk.models.PendingTrust
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.launch
+import kotlinx.coroutines.withContext
+
+@OptIn(ExperimentalMaterial3Api::class)
+@Composable
+fun ConnectScreen(settings: Settings, onConnected: (Long) -> Unit) {
+    val scope = rememberCoroutineScope()
+    val context = LocalContext.current
+    var host by remember { mutableStateOf("") }
+    var hostName by remember { mutableStateOf("") }
+    var port by remember { mutableStateOf("9777") }
+    var connecting by remember { mutableStateOf(false) }
+    var status by remember { mutableStateOf<String?>(null) }
+    // The host streams at exactly this mode; "Native" settings resolve from the device display.
+    val (w, h, hz) = settings.effectiveMode(context)
+
+    // mDNS discovery scoped to this screen, via the native mdns-sd browse (HostDiscovery) — its
+    // onChange fires on the main thread, so it can set Compose state directly. (Emulator SLIRP drops
+    // multicast → empty; that's the network, not the API.) Raw multicast reception only needs the
+    // Wi-Fi MulticastLock (HostDiscovery holds it), NOT NEARBY_WIFI_DEVICES — that gated the old
+    // NsdManager path. We still request NEARBY_WIFI_DEVICES opportunistically (some OEMs filter
+    // multicast without it; harmless where it isn't), but never block discovery on the grant — a
+    // denial used to leave discovery dead forever.
+    val discovery = remember { HostDiscovery(context) }
+    var discovered by remember { mutableStateOf<List<DiscoveredHost>>(emptyList()) }
+    val nearbyLauncher = rememberLauncherForActivityResult(
+        ActivityResultContracts.RequestPermission(),
+    ) { _ -> /* best-effort hint; discovery runs regardless of the result */ }
+    LaunchedEffect(Unit) {
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU && !hasNearbyPermission(context)) {
+            nearbyLauncher.launch(Manifest.permission.NEARBY_WIFI_DEVICES)
+        }
+    }
+    DisposableEffect(Unit) {
+        discovery.onChange = { discovered = it }
+        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) }
+    // A saved host whose label is being edited (the Rename dialog).
+    var renameTarget by remember { mutableStateOf<KnownHost?>(null) }
+
+    // Discovered hosts not already saved — a saved host (paired or TOFU) belongs in "Saved hosts",
+    // not also in "Discovered", so we hide the overlap (matched by fingerprint when both carry it, so
+    // it survives a DHCP address change; else by address:port). Mirrors the Apple client.
+    val discoveredUnsaved = discovered.filter { dh -> savedHosts.none { it.matches(dh) } }
+
+    // Issue the actual connect with identity + (optional) pin. On a TOFU connect (pinHex null),
+    // pin the fingerprint the host presented (as an unpaired known host) so the next connect goes
+    // 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 {
+            // Advertise HDR only when this device's display can present it (else the host sends a
+            // proper SDR stream rather than PQ the panel would mis-tone-map).
+            val hdrEnabled = displaySupportsHdr(context)
+            // "Automatic" resolves to a concrete pad type from the connected controller's VID/PID
+            // (Android exposes no controller-type enum) — parity with the Linux/Apple clients. An
+            // explicit choice is passed through unchanged.
+            val gamepadPref = Gamepad.resolvePref(settings.gamepad)
+            val handle = withContext(Dispatchers.IO) {
+                NativeBridge.nativeConnect(
+                    targetHost, targetPort, w, h, hz,
+                    id.certPem, id.privateKeyPem, pinHex ?: "",
+                    settings.bitrateKbps, settings.compositor, gamepadPref,
+                    hdrEnabled,
+                )
+            }
+            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,
+        manualName: String? = null,
+    ) {
+        val known = knownHostStore.get(targetHost, targetPort)
+        val adv = dh?.fingerprint?.lowercase()
+        // Label precedence: a saved host keeps its (possibly user-renamed) name; else the discovered
+        // mDNS name; else the name typed in the Add-host sheet; else the bare address.
+        val name = known?.name ?: dh?.name ?: manualName?.trim()?.takeIf { it.isNotEmpty() } ?: targetHost
+        when {
+            // Known host whose advertised fp still matches the pin → silent pinned reconnect.
+            known != null && (adv == null || adv == known.fpHex) ->
+                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()) {
+        LazyVerticalGrid(
+            columns = GridCells.Adaptive(minSize = 160.dp),
+            modifier = Modifier.fillMaxSize(),
+            contentPadding = PaddingValues(horizontal = 16.dp, vertical = 16.dp),
+            horizontalArrangement = Arrangement.spacedBy(8.dp),
+            verticalArrangement = Arrangement.spacedBy(8.dp),
+        ) {
+            item(span = { GridItemSpan(maxLineSpan) }) {
+                Column(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 {
+                        // While connecting it's progress (spinner, neutral); otherwise it's a
+                        // result/error (red). Previously every status showed in error-red, so a
+                        // normal "Connecting…" looked like a failure.
+                        if (connecting) {
+                            Row(
+                                verticalAlignment = Alignment.CenterVertically,
+                                horizontalArrangement = Arrangement.spacedBy(8.dp),
+                            ) {
+                                CircularProgressIndicator(
+                                    modifier = Modifier.size(16.dp),
+                                    strokeWidth = 2.dp,
+                                )
+                                Text(
+                                    it,
+                                    style = MaterialTheme.typography.bodyMedium,
+                                    color = MaterialTheme.colorScheme.onSurfaceVariant,
+                                )
+                            }
+                        } else {
+                            // Result/error: a filled error container reads as a real failure banner,
+                            // not just red text lost in the layout.
+                            Surface(
+                                color = MaterialTheme.colorScheme.errorContainer,
+                                shape = MaterialTheme.shapes.medium,
+                                modifier = Modifier.fillMaxWidth(),
+                            ) {
+                                Text(
+                                    it,
+                                    style = MaterialTheme.typography.bodyMedium,
+                                    color = MaterialTheme.colorScheme.onErrorContainer,
+                                    textAlign = TextAlign.Center,
+                                    modifier = Modifier.padding(horizontal = 16.dp, vertical = 12.dp),
+                                )
+                            }
+                        }
+                        Spacer(Modifier.height(16.dp))
+                    }
+                }
+            }
+
+            if (savedHosts.isEmpty() && discoveredUnsaved.isEmpty()) {
+                item(span = { GridItemSpan(maxLineSpan) }) {
+                    EmptyHostsState()
+                }
+            }
+
+            if (savedHosts.isNotEmpty()) {
+                item(span = { GridItemSpan(maxLineSpan) }) {
+                    SectionLabel("Saved hosts")
+                }
+                items(savedHosts, key = { "saved-${it.address}-${it.port}" }) { 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()
+                        },
+                        onRename = { renameTarget = kh },
+                    )
+                }
+            }
+
+            if (discoveredUnsaved.isNotEmpty()) {
+                item(span = { GridItemSpan(maxLineSpan) }) {
+                    Spacer(Modifier.height(12.dp))
+                    SectionLabel("Discovered on the network")
+                }
+                items(discoveredUnsaved, key = { "disc-${it.host}-${it.port}" }) { 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,
+                    )
+                }
+            }
+
+            // Active-discovery hint: discovery runs whenever this screen is up, so while it's
+            // scanning but nothing's turned up yet (and we're not mid-connect), show it's working
+            // rather than looking idle/empty.
+            if (!connecting && discovered.isEmpty()) {
+                item(span = { GridItemSpan(maxLineSpan) }) {
+                    Row(
+                        modifier = Modifier.fillMaxWidth().padding(vertical = 12.dp),
+                        horizontalArrangement = Arrangement.Center,
+                        verticalAlignment = Alignment.CenterVertically,
+                    ) {
+                        CircularProgressIndicator(modifier = Modifier.size(16.dp), strokeWidth = 2.dp)
+                        Spacer(Modifier.width(8.dp))
+                        Text(
+                            "Searching the local network…",
+                            style = MaterialTheme.typography.bodyMedium,
+                            color = MaterialTheme.colorScheme.onSurfaceVariant,
+                        )
+                    }
+                }
+            }
+
+            item(span = { GridItemSpan(maxLineSpan) }) {
+                Spacer(Modifier.height(96.dp))
+            }
+        }
+
+        AnimatedVisibility(
+            visible = true, // Static for now, could be based on scroll if needed
+            enter = scaleIn() + fadeIn(),
+            exit = scaleOut() + fadeOut(),
+            modifier = Modifier
+                .align(Alignment.BottomEnd)
+                .padding(20.dp)
+        ) {
+            ExtendedFloatingActionButton(
+                onClick = { showManualSheet = true },
+                icon = { Icon(Icons.Filled.Add, contentDescription = null) },
+                text = { Text("Add host") },
+                expanded = !connecting,
+            )
+        }
+    }
+
+    if (showManualSheet) {
+        ModalBottomSheet(
+            onDismissRequest = { showManualSheet = false },
+            sheetState = sheetState,
+        ) {
+            Column(
+                modifier = Modifier
+                    .fillMaxWidth()
+                    .padding(horizontal = 24.dp)
+                    .padding(bottom = 32.dp),
+            ) {
+                Text("Add a host", style = MaterialTheme.typography.titleLarge)
+                Spacer(Modifier.height(4.dp))
+                Text(
+                    "Enter its address. You'll pair with the host's PIN on first connect.",
+                    style = MaterialTheme.typography.bodyMedium,
+                    color = MaterialTheme.colorScheme.onSurfaceVariant,
+                )
+                Spacer(Modifier.height(20.dp))
+                OutlinedTextField(
+                    value = hostName,
+                    onValueChange = { hostName = it },
+                    label = { Text("Name (optional)") },
+                    placeholder = { Text("e.g. Living Room") },
+                    singleLine = true,
+                    modifier = Modifier.fillMaxWidth(),
+                )
+                Spacer(Modifier.height(16.dp))
+                OutlinedTextField(
+                    value = host,
+                    onValueChange = { host = it },
+                    label = { Text("Host") },
+                    singleLine = true,
+                    modifier = Modifier.fillMaxWidth(),
+                )
+                Spacer(Modifier.height(16.dp))
+                OutlinedTextField(
+                    value = port,
+                    onValueChange = { v -> port = v.filter { it.isDigit() }.take(5) },
+                    label = { Text("Port") },
+                    singleLine = true,
+                    keyboardOptions = KeyboardOptions(keyboardType = KeyboardType.Number),
+                    modifier = Modifier.fillMaxWidth(),
+                )
+                Spacer(Modifier.height(20.dp))
+                Button(
+                    enabled = !connecting && host.isNotBlank() && port.isNotBlank(),
+                    onClick = {
+                        val h = host.trim()
+                        val p = port.toIntOrNull() ?: 9777
+                        val n = hostName
+                        scope.launch { sheetState.hide() }.invokeOnCompletion {
+                            showManualSheet = false
+                            connect(h, p, manualName = n)
+                        }
+                    },
+                    modifier = Modifier.fillMaxWidth(),
+                ) { Text("Connect  ($w×$h@$hz)") }
+            }
+        }
+    }
+
+    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") }
+                    },
+                )
+            }
+        }
+    }
+
+    // Rename a saved host's label (discovered hosts are named by mDNS; this is how you give one a
+    // friendly name like "Living Room" after pairing). Keyed by the host so reopening resets the field.
+    renameTarget?.let { kh ->
+        var newName by remember(kh) { mutableStateOf(kh.name) }
+        AlertDialog(
+            onDismissRequest = { renameTarget = null },
+            title = { Text("Rename host") },
+            text = {
+                OutlinedTextField(
+                    value = newName,
+                    onValueChange = { newName = it },
+                    label = { Text("Name") },
+                    placeholder = { Text(kh.address) },
+                    singleLine = true,
+                )
+            },
+            confirmButton = {
+                TextButton(
+                    enabled = newName.isNotBlank(),
+                    onClick = {
+                        knownHostStore.rename(kh.address, kh.port, newName.trim())
+                        savedHosts = knownHostStore.all()
+                        renameTarget = null
+                    },
+                ) { Text("Save") }
+            },
+            dismissButton = {
+                TextButton(onClick = { renameTarget = null }) { Text("Cancel") }
+            },
+        )
+    }
+}
+
+/**
+ * Whether NEARBY_WIFI_DEVICES is held (API 33+; not applicable below). We request it opportunistically
+ * as a multicast-reception hedge on OEMs that filter multicast without it, but discovery (raw mDNS via
+ * the native core + MulticastLock) does not depend on it.
+ */
+fun hasNearbyPermission(context: Context): Boolean =
+    Build.VERSION.SDK_INT < Build.VERSION_CODES.TIRAMISU ||
+        ContextCompat.checkSelfPermission(context, Manifest.permission.NEARBY_WIFI_DEVICES) ==
+        PackageManager.PERMISSION_GRANTED
+
+/**
+ * True when a saved host and a discovered advert are the same machine — matched by certificate
+ * fingerprint when both carry it (so it survives a DHCP address change), else by address:port.
+ * Mirrors the Apple client's `StoredHost.matches`; de-dupes "Discovered" against "Saved hosts".
+ */
+private fun KnownHost.matches(dh: DiscoveredHost): Boolean {
+    val advFp = dh.fingerprint?.lowercase()
+    if (!advFp.isNullOrEmpty() && fpHex.isNotEmpty() && fpHex.lowercase() == advFp) return true
+    return address == dh.host && port == dh.port
+}
@@ -0,0 +1,134 @@
+package io.unom.punktfunk
+
+import android.os.Bundle
+import android.view.InputDevice
+import android.view.KeyEvent
+import android.view.MotionEvent
+import androidx.activity.ComponentActivity
+import androidx.activity.SystemBarStyle
+import androidx.activity.compose.setContent
+import androidx.activity.enableEdgeToEdge
+import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.material3.Surface
+import androidx.compose.ui.Modifier
+import io.unom.punktfunk.kit.Gamepad
+import io.unom.punktfunk.kit.Keymap
+import io.unom.punktfunk.kit.NativeBridge
+
+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 {
+            PunktfunkTheme {
+                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
+                    }
+                }
+            }
+        } else if (event.isFromSource(InputDevice.SOURCE_GAMEPAD)) {
+            // Not streaming: a game controller drives the Compose UI (TV + phone). Map the face
+            // buttons to the navigation keys the focus system understands; D-pad *keys* already move
+            // focus on their own, so they fall through to super untouched.
+            val mapped = when (event.keyCode) {
+                KeyEvent.KEYCODE_BUTTON_A -> KeyEvent.KEYCODE_DPAD_CENTER // activate focused element
+                KeyEvent.KEYCODE_BUTTON_B -> KeyEvent.KEYCODE_BACK // back / dismiss
+                else -> 0
+            }
+            if (mapped != 0) return super.dispatchKeyEvent(KeyEvent(event.action, mapped))
+        }
+        return super.dispatchKeyEvent(event)
+    }
+
+    /** Last D-pad direction synthesised from a stick/HAT — edge detection (one focus move per push). */
+    private var lastNavDir = 0
+
+    override fun dispatchGenericMotionEvent(event: MotionEvent): Boolean {
+        if (streamHandle != 0L) {
+            if (axisMapper?.onMotion(event) == true) return true
+            return super.dispatchGenericMotionEvent(event)
+        }
+        // Not streaming: turn the gamepad HAT / left stick into discrete D-pad focus moves, so a
+        // controller navigates the menus even when its D-pad reports as axes (not key events) and
+        // for stick-based navigation. Edge-detected so a held direction moves focus exactly once.
+        if (event.isFromSource(InputDevice.SOURCE_JOYSTICK) ||
+            event.isFromSource(InputDevice.SOURCE_GAMEPAD)
+        ) {
+            val x = event.getAxisValue(MotionEvent.AXIS_HAT_X)
+                .let { if (it != 0f) it else event.getAxisValue(MotionEvent.AXIS_X) }
+            val y = event.getAxisValue(MotionEvent.AXIS_HAT_Y)
+                .let { if (it != 0f) it else event.getAxisValue(MotionEvent.AXIS_Y) }
+            val dir = when {
+                x <= -0.5f -> KeyEvent.KEYCODE_DPAD_LEFT
+                x >= 0.5f -> KeyEvent.KEYCODE_DPAD_RIGHT
+                y <= -0.5f -> KeyEvent.KEYCODE_DPAD_UP
+                y >= 0.5f -> KeyEvent.KEYCODE_DPAD_DOWN
+                else -> 0
+            }
+            if (dir != lastNavDir) {
+                lastNavDir = dir
+                if (dir != 0) {
+                    super.dispatchKeyEvent(KeyEvent(KeyEvent.ACTION_DOWN, dir))
+                    super.dispatchKeyEvent(KeyEvent(KeyEvent.ACTION_UP, dir))
+                    return true
+                }
+            } else if (dir != 0) {
+                return true // already moved for this push; swallow until the stick returns to centre
+            }
+        }
+        return super.dispatchGenericMotionEvent(event)
+    }
+}
@@ -0,0 +1,152 @@
+package io.unom.punktfunk
+
+import android.content.Context
+import android.view.Display
+
+/**
+ * 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,
+    /** Show the live stats overlay (FPS / throughput / latency) during a stream. */
+    val statsHudEnabled: Boolean = true,
+)
+
+/** 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),
+        statsHudEnabled = prefs.getBoolean(K_HUD, true),
+    )
+
+    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)
+            .putBoolean(K_HUD, s.statsHudEnabled)
+            .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"
+        const val K_HUD = "stats_hud_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)
+}
+
+/**
+ * True when this device's display can actually present HDR10, so we should advertise HDR to the
+ * host. On an SDR panel we advertise `0` instead — the host then sends a proper 8-bit BT.709 stream
+ * rather than BT.2020 PQ the panel would mis-tone-map (the washed-out/dark failure). Mirrors the
+ * capability gate the Apple/Windows clients apply.
+ */
+fun displaySupportsHdr(context: Context): Boolean {
+    val display = runCatching { context.display }.getOrNull() ?: return false
+    @Suppress("DEPRECATION") // hdrCapabilities is the supported query on minSdk 31
+    val caps = display.hdrCapabilities ?: return false
+    return caps.supportedHdrTypes.any {
+        it == Display.HdrCapabilities.HDR_TYPE_HDR10 || it == Display.HdrCapabilities.HDR_TYPE_HDR10_PLUS
+    }
+}
+
+/** 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 (0=Auto 1=Xbox360 2=DualSense 3=XboxOne 4=DualShock4). */
+val GAMEPAD_OPTIONS = listOf(
+    "Automatic",
+    "Xbox 360",
+    "DualSense",
+    "Xbox One",
+    "DualShock 4",
+)
@@ -0,0 +1,209 @@
+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.ColumnScope
+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.OutlinedCard
+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, grouped into Display / Host / Audio / Overlay cards. 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)
+
+    // 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)) }
+
+    Column(
+        modifier = Modifier
+            .fillMaxSize()
+            .verticalScroll(rememberScrollState())
+            .padding(horizontal = 20.dp, vertical = 24.dp),
+        verticalArrangement = Arrangement.spacedBy(24.dp),
+    ) {
+        Text("Settings", style = MaterialTheme.typography.headlineMedium)
+
+        val (nw, nh, nhz) = nativeDisplayMode(context)
+
+        SettingsGroup("Display") {
+            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)) }
+        }
+
+        SettingsGroup("Host") {
+            SettingDropdown(
+                label = "Compositor",
+                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)) }
+        }
+
+        SettingsGroup("Audio") {
+            ToggleRow(
+                title = "Microphone",
+                subtitle = "Send your mic to the host's virtual microphone",
+                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)
+                    }
+                },
+            )
+        }
+
+        SettingsGroup("Overlay") {
+            ToggleRow(
+                title = "Stats overlay",
+                subtitle = "Show FPS, throughput and latency while streaming (3-finger tap toggles it live)",
+                checked = s.statsHudEnabled,
+                onCheckedChange = { on -> update(s.copy(statsHudEnabled = on)) },
+            )
+        }
+    }
+}
+
+/** A titled group of settings rendered inside an outlined card. */
+@Composable
+private fun SettingsGroup(title: String, content: @Composable ColumnScope.() -> Unit) {
+    Column(verticalArrangement = Arrangement.spacedBy(10.dp)) {
+        Text(
+            title,
+            style = MaterialTheme.typography.titleSmall,
+            color = MaterialTheme.colorScheme.primary,
+            modifier = Modifier.padding(start = 4.dp),
+        )
+        OutlinedCard(modifier = Modifier.fillMaxWidth()) {
+            Column(
+                modifier = Modifier.padding(16.dp),
+                verticalArrangement = Arrangement.spacedBy(16.dp),
+                content = content,
+            )
+        }
+    }
+}
+
+/** A title + subtitle on the left, a Switch on the right. */
+@Composable
+private fun ToggleRow(
+    title: String,
+    subtitle: String,
+    checked: Boolean,
+    onCheckedChange: (Boolean) -> Unit,
+) {
+    Row(modifier = Modifier.fillMaxWidth(), verticalAlignment = Alignment.CenterVertically) {
+        Column(Modifier.weight(1f)) {
+            Text(title, style = MaterialTheme.typography.bodyLarge)
+            Text(
+                subtitle,
+                style = MaterialTheme.typography.bodySmall,
+                color = MaterialTheme.colorScheme.onSurfaceVariant,
+            )
+        }
+        Switch(checked = checked, onCheckedChange = onCheckedChange)
+    }
+}
+
+/** 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
+                    },
+                )
+            }
+        }
+    }
+}
@@ -0,0 +1,300 @@
+package io.unom.punktfunk
+
+import android.Manifest
+import android.content.pm.PackageManager
+import android.view.SurfaceHolder
+import android.view.SurfaceView
+import android.view.WindowManager
+import androidx.activity.compose.BackHandler
+import androidx.compose.foundation.background
+import androidx.compose.foundation.gestures.awaitEachGesture
+import androidx.compose.foundation.gestures.awaitFirstDown
+import androidx.compose.foundation.layout.Box
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.shape.RoundedCornerShape
+import androidx.compose.material3.Text
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.DisposableEffect
+import androidx.compose.runtime.LaunchedEffect
+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.graphics.Color
+import androidx.compose.ui.input.pointer.pointerInput
+import androidx.compose.ui.platform.LocalContext
+import androidx.compose.ui.text.font.FontFamily
+import androidx.compose.ui.unit.dp
+import androidx.compose.ui.unit.sp
+import androidx.compose.ui.viewinterop.AndroidView
+import androidx.core.content.ContextCompat
+import androidx.core.view.WindowCompat
+import androidx.core.view.WindowInsetsCompat
+import androidx.core.view.WindowInsetsControllerCompat
+import io.unom.punktfunk.kit.Gamepad
+import io.unom.punktfunk.kit.GamepadFeedback
+import io.unom.punktfunk.kit.NativeBridge
+import java.util.concurrent.atomic.AtomicBoolean
+import kotlinx.coroutines.delay
+import kotlin.math.abs
+import kotlin.math.roundToInt
+
+// Touch-gesture tuning (px / ms). TAP_SLOP: movement under this still counts as a tap, not a drag.
+// TAP_DRAG_MS: a new touch within this long after a tap starts a left-button drag. SCROLL_DIV: px of
+// two-finger pan per wheel notch (smaller = faster scroll).
+private const val TAP_SLOP = 12f
+private const val TAP_DRAG_MS = 250L
+private const val SCROLL_DIV = 4f
+
+@Composable
+fun StreamScreen(handle: Long, micEnabled: Boolean, onDisconnect: () -> Unit) {
+    val context = LocalContext.current
+    val activity = context as? MainActivity
+    val window = activity?.window
+    val controller = remember(window) {
+        window?.let { WindowCompat.getInsetsController(it, it.decorView) }
+    }
+
+    // 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
+
+    // Live decode stats for the HUD. Poll once a second for the whole stream (cheap, and each call
+    // drains+resets the native window so it never grows unbounded even while the overlay is hidden);
+    // `showStats` only gates rendering. A 3-finger tap toggles it live; the default comes from Settings.
+    var stats by remember { mutableStateOf<DoubleArray?>(null) }
+    var showStats by remember { mutableStateOf(SettingsStore(context).load().statsHudEnabled) }
+    LaunchedEffect(handle) {
+        while (true) {
+            delay(1000)
+            stats = NativeBridge.nativeVideoStats(handle)
+        }
+    }
+
+    // One-shot teardown guard. Both the SurfaceView callback and DisposableEffect tear down on the
+    // way out, but `nativeClose` frees the handle — so once it's closed, NO path may touch the handle
+    // again (use-after-free → SIGSEGV: the consistent back-while-streaming crash). Both run on the
+    // main thread, so a plain flag is race-free; AtomicBoolean just makes the intent explicit.
+    val closed = remember { AtomicBoolean(false) }
+
+    DisposableEffect(handle) {
+        window?.addFlags(WindowManager.LayoutParams.FLAG_KEEP_SCREEN_ON)
+        controller?.let {
+            it.systemBarsBehavior = WindowInsetsControllerCompat.BEHAVIOR_SHOW_TRANSIENT_BARS_BY_SWIPE
+            it.hide(WindowInsetsCompat.Type.systemBars())
+        }
+        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 {
+            closed.set(true) // from here the handle gets freed; surfaceDestroyed must not touch it
+            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
+            controller?.show(WindowInsetsCompat.Type.systemBars())
+            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) {
+                            // Surface gone (backgrounding, or on the way out). Stop the threads that
+                            // render to it — but only while the session is still open. Once
+                            // DisposableEffect has closed it, the handle is freed; dereferencing it
+                            // here is the use-after-free that crashed on back-navigation.
+                            if (!closed.get()) {
+                                NativeBridge.nativeStopMic(handle)
+                                NativeBridge.nativeStopAudio(handle)
+                                NativeBridge.nativeStopVideo(handle)
+                            }
+                        }
+                    })
+                }
+            },
+        )
+        // Live stats HUD (FPS / throughput / capture→client latency), drawn over the video but
+        // BEFORE the transparent gesture layer below, so it shows through and never eats touches.
+        if (showStats) {
+            stats?.let { StatsOverlay(it, Modifier.align(Alignment.TopStart).padding(12.dp)) }
+        }
+        // Touch → mouse, absolute "direct pointing" like the Apple client: the host cursor follows
+        // your finger (MouseMoveAbs, host-normalized against the overlay size — which fills the video,
+        // so finger position maps straight onto the remote screen). Gestures: tap = left click;
+        // two-finger tap = right click; two-finger drag = scroll; tap-then-press-and-drag = left-drag
+        // (text selection / moving windows); three-finger tap = toggle the stats HUD.
+        Box(
+            Modifier.fillMaxSize().pointerInput(handle) {
+                var lastTapUp = 0L
+                var lastTapX = 0f
+                var lastTapY = 0f
+                fun moveAbs(x: Float, y: Float) {
+                    val sw = size.width
+                    val sh = size.height
+                    if (sw <= 0 || sh <= 0) return
+                    NativeBridge.nativeSendPointerAbs(
+                        handle,
+                        x.coerceIn(0f, (sw - 1).toFloat()).roundToInt(),
+                        y.coerceIn(0f, (sh - 1).toFloat()).roundToInt(),
+                        sw,
+                        sh,
+                    )
+                }
+                awaitEachGesture {
+                    val down = awaitFirstDown(requireUnconsumed = false)
+                    val startX = down.position.x
+                    val startY = down.position.y
+                    // A touch landing just after a quick tap nearby = tap-and-drag: hold the left
+                    // button for this whole gesture (laptop-trackpad convention).
+                    val isDrag = down.uptimeMillis - lastTapUp < TAP_DRAG_MS &&
+                        abs(startX - lastTapX) < TAP_SLOP && abs(startY - lastTapY) < TAP_SLOP
+                    lastTapUp = 0L // consume the arming either way
+                    moveAbs(startX, startY) // cursor jumps to the finger immediately
+                    if (isDrag) NativeBridge.nativeSendPointerButton(handle, 1, true)
+
+                    var moved = false
+                    var maxFingers = 1
+                    var scrolling = false
+                    var prevCx = startX
+                    var prevCy = startY
+                    var upTime = down.uptimeMillis
+
+                    while (true) {
+                        val ev = awaitPointerEvent()
+                        val pressed = ev.changes.filter { it.pressed }
+                        if (pressed.isEmpty()) {
+                            upTime = ev.changes.firstOrNull()?.uptimeMillis ?: upTime
+                            break
+                        }
+                        if (pressed.size > maxFingers) maxFingers = pressed.size
+
+                        if (pressed.size >= 2) {
+                            // Two fingers → scroll by the centroid delta; never move the cursor.
+                            val cx = (pressed.sumOf { it.position.x.toDouble() } / pressed.size).toFloat()
+                            val cy = (pressed.sumOf { it.position.y.toDouble() } / pressed.size).toFloat()
+                            if (!scrolling) {
+                                scrolling = true
+                                prevCx = cx
+                                prevCy = cy
+                            }
+                            val sy = ((prevCy - cy) / SCROLL_DIV).toInt() // finger up → wheel up
+                            val sx = ((cx - prevCx) / SCROLL_DIV).toInt()
+                            if (sy != 0) {
+                                NativeBridge.nativeSendScroll(handle, 0, sy * 120)
+                                prevCy = cy
+                                moved = true
+                            }
+                            if (sx != 0) {
+                                NativeBridge.nativeSendScroll(handle, 1, sx * 120)
+                                prevCx = cx
+                                moved = true
+                            }
+                        } else if (!scrolling) {
+                            // One finger → the cursor follows it (skipped once a gesture turned into
+                            // a scroll, so dropping back to one finger doesn't jerk the cursor).
+                            val p = pressed.firstOrNull { it.id == down.id } ?: pressed.first()
+                            if (abs(p.position.x - startX) > TAP_SLOP ||
+                                abs(p.position.y - startY) > TAP_SLOP
+                            ) {
+                                moved = true
+                            }
+                            moveAbs(p.position.x, p.position.y)
+                        }
+                        ev.changes.forEach { it.consume() }
+                    }
+
+                    if (isDrag) {
+                        NativeBridge.nativeSendPointerButton(handle, 1, false) // end the drag
+                    } else if (!moved) {
+                        when {
+                            maxFingers >= 3 -> showStats = !showStats // in-stream HUD toggle
+                            maxFingers == 2 -> { // two-finger tap → right click
+                                NativeBridge.nativeSendPointerButton(handle, 3, true)
+                                NativeBridge.nativeSendPointerButton(handle, 3, false)
+                            }
+                            else -> { // tap → left click, and arm tap-and-drag
+                                NativeBridge.nativeSendPointerButton(handle, 1, true)
+                                NativeBridge.nativeSendPointerButton(handle, 1, false)
+                                lastTapUp = upTime
+                                lastTapX = startX
+                                lastTapY = startY
+                            }
+                        }
+                    }
+                }
+            },
+        )
+    }
+}
+
+/**
+ * The live stats overlay — mirrors the Apple client's HUD. Reads the 10-double layout from
+ * [NativeBridge.nativeVideoStats]:
+ * `[fps, mbps, latP50Ms, latP95Ms, latValid, skew, w, h, hz, dropped]`.
+ */
+@Composable
+private fun StatsOverlay(s: DoubleArray, modifier: Modifier = Modifier) {
+    if (s.size < 10) return
+    val w = s[6].toInt()
+    val h = s[7].toInt()
+    val hz = s[8].toInt()
+    val latValid = s[4] != 0.0
+    val skew = s[5] != 0.0
+    val dropped = s[9].toLong()
+    Column(
+        modifier = modifier
+            .background(Color.Black.copy(alpha = 0.45f), RoundedCornerShape(6.dp))
+            .padding(horizontal = 8.dp, vertical = 4.dp),
+    ) {
+        Text(
+            "$w×$h@$hz   ${s[0].roundToInt()} fps   ${"%.1f".format(s[1])} Mb/s",
+            color = Color.White,
+            fontFamily = FontFamily.Monospace,
+            fontSize = 12.sp,
+        )
+        if (latValid) {
+            val tag = if (skew) "" else " (same-host)"
+            Text(
+                "capture→client ${"%.1f".format(s[2])}/${"%.1f".format(s[3])} ms p50/p95$tag",
+                color = Color.White,
+                fontFamily = FontFamily.Monospace,
+                fontSize = 12.sp,
+            )
+        }
+        if (dropped > 0) {
+            Text(
+                "dropped $dropped",
+                color = Color(0xFFFFB0B0),
+                fontFamily = FontFamily.Monospace,
+                fontSize = 12.sp,
+            )
+        }
+    }
+}
@@ -0,0 +1,43 @@
+package io.unom.punktfunk
+
+import android.os.Build
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.darkColorScheme
+import androidx.compose.material3.dynamicDarkColorScheme
+import androidx.compose.runtime.Composable
+import androidx.compose.ui.graphics.Color
+import androidx.compose.ui.platform.LocalContext
+
+// punktfunk brand violets (from the app icon: #6C5BF3 / #A79FF8 / #D2C9FB on a #16132A indigo).
+// Used as the fallback dark scheme on pre-Android-12 devices; on 12+ we defer to Material You.
+private val BrandDark = darkColorScheme(
+    primary = Color(0xFFA79FF8),
+    onPrimary = Color(0xFF1B1442),
+    primaryContainer = Color(0xFF4C3FB3),
+    onPrimaryContainer = Color(0xFFE5E0FF),
+    secondary = Color(0xFFC8C2EC),
+    onSecondary = Color(0xFF2E2A4D),
+    tertiary = Color(0xFF8FD0E8),
+    onTertiary = Color(0xFF053543),
+    background = Color(0xFF131129),
+    onBackground = Color(0xFFE5E1F2),
+    surface = Color(0xFF1A1733),
+    onSurface = Color(0xFFE5E1F2),
+    surfaceVariant = Color(0xFF2A2647),
+    onSurfaceVariant = Color(0xFFC7C2DE),
+)
+
+/**
+ * App theme — always dark (a streaming client reads best on a dark canvas, and the immersive
+ * stream view assumes it), but uses **Material You** dynamic colour on Android 12+ so the UI
+ * harmonises with the user's wallpaper, falling back to the punktfunk brand violets below that.
+ */
+@Composable
+fun PunktfunkTheme(content: @Composable () -> Unit) {
+    val scheme = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
+        dynamicDarkColorScheme(LocalContext.current)
+    } else {
+        BrandDark
+    }
+    MaterialTheme(colorScheme = scheme, content = content)
+}
@@ -0,0 +1,197 @@
+package io.unom.punktfunk.components
+
+import androidx.compose.foundation.background
+import androidx.compose.foundation.border
+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.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.shape.CircleShape
+import androidx.compose.material.icons.Icons
+import androidx.compose.material.icons.filled.MoreVert
+import androidx.compose.material3.CardDefaults
+import androidx.compose.material3.DropdownMenu
+import androidx.compose.material3.DropdownMenuItem
+import androidx.compose.material3.ElevatedCard
+import androidx.compose.material3.Icon
+import androidx.compose.material3.IconButton
+import androidx.compose.material3.MaterialTheme
+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.draw.clip
+import androidx.compose.ui.focus.onFocusChanged
+import androidx.compose.ui.text.style.TextAlign
+import androidx.compose.ui.text.style.TextOverflow
+import androidx.compose.ui.unit.dp
+import io.unom.punktfunk.models.HostStatus
+
+/** Left-aligned section header above each block of the connect screen. */
+@Composable
+fun SectionLabel(text: String) {
+    Text(
+        text,
+        style = MaterialTheme.typography.titleSmall,
+        color = MaterialTheme.colorScheme.primary,
+        modifier = Modifier.fillMaxWidth().padding(bottom = 8.dp),
+    )
+}
+
+/**
+ * A host as an Apple-style card: a colored letter-avatar, name + address, a trust pill, and (for
+ * saved hosts) an overflow menu with Rename / Forget. Tapping the card connects.
+ */
+@Composable
+fun HostCard(
+    name: String,
+    address: String,
+    status: HostStatus,
+    enabled: Boolean,
+    onConnect: () -> Unit,
+    onForget: (() -> Unit)?,
+    onRename: (() -> Unit)? = null,
+) {
+    // D-pad / controller focus highlight: a clickable card is focusable, but the default state
+    // layer is too subtle on a TV across a room — draw a clear primary-colour border when focused.
+    var focused by remember { mutableStateOf(false) }
+    ElevatedCard(
+        onClick = onConnect,
+        enabled = enabled,
+        modifier = Modifier
+            .fillMaxWidth()
+            .padding(4.dp)
+            .onFocusChanged { focused = it.isFocused }
+            .then(
+                if (focused) {
+                    Modifier.border(2.dp, MaterialTheme.colorScheme.primary, CardDefaults.elevatedShape)
+                } else {
+                    Modifier
+                },
+            ),
+    ) {
+        Box(modifier = Modifier.fillMaxWidth()) {
+            Column(
+                modifier = Modifier
+                    .fillMaxWidth()
+                    .padding(16.dp),
+                horizontalAlignment = Alignment.CenterHorizontally,
+            ) {
+                HostAvatar(name)
+                Spacer(Modifier.height(12.dp))
+                Text(
+                    name,
+                    style = MaterialTheme.typography.titleMedium,
+                    maxLines = 1,
+                    overflow = TextOverflow.Ellipsis,
+                    textAlign = TextAlign.Center,
+                )
+                Text(
+                    address,
+                    style = MaterialTheme.typography.bodySmall,
+                    color = MaterialTheme.colorScheme.onSurfaceVariant,
+                    maxLines = 1,
+                    overflow = TextOverflow.Ellipsis,
+                    textAlign = TextAlign.Center,
+                )
+                Spacer(Modifier.height(12.dp))
+                StatusPill(status)
+            }
+
+            if (onForget != null || onRename != null) {
+                var menu by remember { mutableStateOf(false) }
+                Box(modifier = Modifier.align(Alignment.TopEnd)) {
+                    IconButton(enabled = enabled, onClick = { menu = true }) {
+                        Icon(
+                            Icons.Filled.MoreVert,
+                            contentDescription = "More",
+                            modifier = Modifier.size(20.dp),
+                            tint = MaterialTheme.colorScheme.onSurfaceVariant.copy(alpha = 0.6f)
+                        )
+                    }
+                    DropdownMenu(expanded = menu, onDismissRequest = { menu = false }) {
+                        if (onRename != null) {
+                            DropdownMenuItem(
+                                text = { Text("Rename") },
+                                onClick = {
+                                    menu = false
+                                    onRename()
+                                },
+                            )
+                        }
+                        if (onForget != null) {
+                            DropdownMenuItem(
+                                text = { Text("Forget") },
+                                onClick = {
+                                    menu = false
+                                    onForget()
+                                },
+                            )
+                        }
+                    }
+                }
+            }
+        }
+    }
+}
+
+/** A circular avatar with the host's first letter (Apple-contact style). */
+@Composable
+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
+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
+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,
+        )
+    }
+}
@@ -0,0 +1,35 @@
+package io.unom.punktfunk.models
+
+import androidx.compose.material.icons.Icons
+import androidx.compose.material.icons.filled.Home
+import androidx.compose.material.icons.filled.Settings
+import androidx.compose.ui.graphics.vector.ImageVector
+
+/** Bottom-bar destinations (the immersive stream view is shown full-screen, outside the bar). */
+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.
+ */
+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 }
+}
+
+/** Trust state of a host, shown as a colored pill on its card. */
+enum class HostStatus(val label: String) {
+    PAIRED("Paired"),
+    PAIRING("PIN pairing"),
+    TOFU("Trust on first use"),
+}
@@ -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>
@@ -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>
@@ -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>
@@ -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>
@@ -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>
@@ -0,0 +1,4 @@
+<?xml version="1.0" encoding="utf-8"?>
+<resources>
+    <string name="app_name">Punktfunk</string>
+</resources>
@@ -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>
@@ -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.1" apply false
+    id("com.android.library") version "9.2.1" apply false
+    id("org.jetbrains.kotlin.plugin.compose") version "2.3.21" apply false
+}
@@ -0,0 +1,142 @@
+#!/usr/bin/env python3
+"""Upload a signed AAB to Google Play via the Publishing API — a direct replacement for
+r0adkll/upload-google-play, which swallows real API errors into "Unknown error occurred."
+
+Why hand-rolled: stdlib + `openssl` only (no pip on the runner), and it prints Google's actual
+error at the stage it fails instead of a catch-all. Reuses the SERVICE_ACCOUNT_JSON secret and
+tolerates it being raw JSON *or* base64-encoded JSON.
+
+Usage:
+  SERVICE_ACCOUNT_JSON='<raw-or-base64 SA key>' \
+    python3 play-upload.py --package io.unom.punktfunk \
+      --aab path/to/app-release.aab --track internal --status completed [--no-commit]
+
+--no-commit: do insert -> upload -> track-update -> validate, then delete the edit (publishes
+nothing). Use it to dry-run the credentials/AAB without touching the live track.
+"""
+import argparse, base64, json, os, subprocess, sys, tempfile, time
+import urllib.request, urllib.parse, urllib.error
+
+API = "https://androidpublisher.googleapis.com/androidpublisher/v3/applications"
+UPLOAD = "https://androidpublisher.googleapis.com/upload/androidpublisher/v3/applications"
+
+
+class ApiError(Exception):
+    def __init__(self, code, method, url, body):
+        super().__init__(f"HTTP {code} from {method} {url}\n{body}")
+        self.code, self.body = code, body
+
+
+def _b64url(raw: bytes) -> str:
+    return base64.urlsafe_b64encode(raw).rstrip(b"=").decode()
+
+
+def call(method, url, token=None, data=None, content_type=None, want_json=True):
+    headers = {}
+    if token:
+        headers["Authorization"] = f"Bearer {token}"
+    if content_type:
+        headers["Content-Type"] = content_type
+    req = urllib.request.Request(url, data=data, method=method, headers=headers)
+    try:
+        with urllib.request.urlopen(req, timeout=300) as r:
+            body = r.read()
+    except urllib.error.HTTPError as e:
+        raise ApiError(e.code, method, url, e.read().decode("utf-8", "replace"))
+    return json.loads(body) if (want_json and body) else body
+
+
+def load_sa():
+    raw = os.environ.get("SERVICE_ACCOUNT_JSON", "")
+    if not raw.strip():
+        sys.exit("ERROR: SERVICE_ACCOUNT_JSON env is empty")
+    try:                                        # raw JSON (what r0adkll expects)
+        return json.loads(raw)
+    except json.JSONDecodeError:
+        try:                                    # or base64-encoded JSON (common mistake)
+            sa = json.loads(base64.b64decode(raw))
+            print("note: SERVICE_ACCOUNT_JSON was base64-encoded; decoded it.")
+            return sa
+        except Exception:
+            sys.exit("ERROR: SERVICE_ACCOUNT_JSON is neither valid JSON nor base64-encoded JSON")
+
+
+def access_token(sa) -> str:
+    now = int(time.time())
+    header = _b64url(json.dumps({"alg": "RS256", "typ": "JWT"}).encode())
+    claims = _b64url(json.dumps({
+        "iss": sa["client_email"],
+        "scope": "https://www.googleapis.com/auth/androidpublisher",
+        "aud": sa["token_uri"], "iat": now, "exp": now + 3600,
+    }).encode())
+    signing_input = f"{header}.{claims}".encode()
+    with tempfile.NamedTemporaryFile("w", suffix=".pem", delete=False) as f:
+        f.write(sa["private_key"])
+        keyfile = f.name
+    try:
+        sig = subprocess.run(["openssl", "dgst", "-sha256", "-sign", keyfile],
+                             input=signing_input, capture_output=True, check=True).stdout
+    finally:
+        os.unlink(keyfile)
+    jwt = f"{header}.{claims}.{_b64url(sig)}"
+    tok = call("POST", sa["token_uri"],
+               data=urllib.parse.urlencode({
+                   "grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer",
+                   "assertion": jwt}).encode(),
+               content_type="application/x-www-form-urlencoded")
+    return tok["access_token"]
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--package", required=True)
+    ap.add_argument("--aab", required=True)
+    ap.add_argument("--track", default="internal")
+    ap.add_argument("--status", default="completed")
+    ap.add_argument("--no-commit", action="store_true")
+    a = ap.parse_args()
+
+    if not os.path.isfile(a.aab):
+        sys.exit(f"ERROR: AAB not found: {a.aab}")
+
+    sa = load_sa()
+    tok = access_token(sa)
+    print(f"authenticated as {sa['client_email']} (project {sa.get('project_id')})")
+    app = f"{API}/{a.package}"
+
+    try:
+        edit = call("POST", f"{app}/edits", token=tok)["id"]
+        with open(a.aab, "rb") as f:
+            blob = f.read()
+        print(f"uploading {a.aab} ({len(blob)} bytes) ...")
+        vc = call("POST", f"{UPLOAD}/{a.package}/edits/{edit}/bundles?uploadType=media",
+                  token=tok, data=blob, content_type="application/octet-stream")["versionCode"]
+        print(f"uploaded versionCode={vc}")
+        call("PUT", f"{app}/edits/{edit}/tracks/{a.track}", token=tok,
+             data=json.dumps({"track": a.track,
+                              "releases": [{"status": a.status, "versionCodes": [str(vc)]}]}).encode(),
+             content_type="application/json")
+        print(f"assigned versionCode={vc} -> track={a.track} status={a.status}")
+
+        if a.no_commit:
+            call("POST", f"{app}/edits/{edit}:validate", token=tok)
+            print("validated (dry-run) OK — deleting edit, nothing published")
+            call("DELETE", f"{app}/edits/{edit}", token=tok, want_json=False)
+            return
+
+        try:
+            call("POST", f"{app}/edits/{edit}:commit", token=tok)
+        except ApiError as e:
+            if "changesNotSentForReview" in e.body:
+                print("commit needs changesNotSentForReview=true — retrying")
+                call("POST", f"{app}/edits/{edit}:commit?changesNotSentForReview=true", token=tok)
+            else:
+                raise
+        print(f"COMMITTED: versionCode={vc} live on track '{a.track}' ({a.status})")
+    except ApiError as e:
+        print(f"\nPLAY API ERROR:\n{e}", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()
@@ -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.
@@ -0,0 +1,12 @@
+#This file is generated by updateDaemonJvm
+toolchainUrl.FREE_BSD.AARCH64=https\://api.foojay.io/disco/v3.0/ids/ec7520a1e057cd116f9544c42142a16b/redirect
+toolchainUrl.FREE_BSD.X86_64=https\://api.foojay.io/disco/v3.0/ids/4c4f879899012ff0a8b2e2117df03b0e/redirect
+toolchainUrl.LINUX.AARCH64=https\://api.foojay.io/disco/v3.0/ids/ec7520a1e057cd116f9544c42142a16b/redirect
+toolchainUrl.LINUX.X86_64=https\://api.foojay.io/disco/v3.0/ids/4c4f879899012ff0a8b2e2117df03b0e/redirect
+toolchainUrl.MAC_OS.AARCH64=https\://api.foojay.io/disco/v3.0/ids/73bcfb608d1fde9fb62e462f834a3299/redirect
+toolchainUrl.MAC_OS.X86_64=https\://api.foojay.io/disco/v3.0/ids/846ee0d876d26a26f37aa1ce8de73224/redirect
+toolchainUrl.UNIX.AARCH64=https\://api.foojay.io/disco/v3.0/ids/ec7520a1e057cd116f9544c42142a16b/redirect
+toolchainUrl.UNIX.X86_64=https\://api.foojay.io/disco/v3.0/ids/4c4f879899012ff0a8b2e2117df03b0e/redirect
+toolchainUrl.WINDOWS.AARCH64=https\://api.foojay.io/disco/v3.0/ids/9482ddec596298c84656d31d16652665/redirect
+toolchainUrl.WINDOWS.X86_64=https\://api.foojay.io/disco/v3.0/ids/39701d92e1756bb2f141eb67cd4c660e/redirect
+toolchainVersion=21
@@ -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
@@ -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" "$@"
@@ -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%
@@ -0,0 +1,104 @@
+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 = "30.0.14904198" // r30-beta1 — 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 clients/android/native (punktfunk-client-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-client-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")
+        // Resolve cargo by ABSOLUTE path: Gradle's Exec resolves command[0] via the JVM's
+        // inherited PATH, NOT the environment("PATH", …) set above (that only reaches the spawned
+        // child). A GUI Android Studio launch (and any daemon it started) has no ~/.cargo/bin on
+        // its PATH, so a bare "cargo" fails to start. The env PATH above still lets cargo/cargo-ndk
+        // find their subtools.
+        val cmd = mutableListOf(
+            "$cargoBin/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-client-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) }
+}
@@ -0,0 +1,3 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Library module manifest. The namespace lives in build.gradle.kts (AGP 9). -->
+<manifest />
@@ -0,0 +1,211 @@
+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
+
+    // GamepadPref wire bytes — must equal punktfunk-core `config.rs::GamepadPref::to_u8`.
+    const val PREF_AUTO = 0
+    const val PREF_XBOX360 = 1
+    const val PREF_DUALSENSE = 2
+    const val PREF_XBOXONE = 3
+    const val PREF_DUALSHOCK4 = 4
+
+    // USB vendor ids of the controllers we can identify by VID/PID.
+    private const val VID_SONY = 0x054C
+    private const val VID_MICROSOFT = 0x045E
+
+    // Sony product ids. DualSense (PS5) and DualShock 4 (PS4) map to distinct host pad types.
+    private val PID_DUALSENSE = setOf(0x0CE6, 0x0DF2)
+    private val PID_DUALSHOCK4 = setOf(0x05C4, 0x09CC)
+
+    // Microsoft Xbox One / Series product ids (wired + the common Bluetooth/dongle revisions). All
+    // behave like Xbox 360 on the host minus the glyph identity, so they share one pref byte.
+    private val PID_XBOXONE = setOf(
+        0x02D1, 0x02DD, 0x02E3, 0x02EA, 0x0B00, 0x0B12, 0x0B13, 0x0B20,
+    )
+
+    /**
+     * Resolve a connected controller's [GamepadPref] wire byte from its USB VID/PID, mirroring the
+     * Linux client's `pref_for_type` (SDL3 `GamepadType`) and the Apple client's GameController type
+     * auto-resolution. Android exposes no controller-type enum, so we match `getVendorId()` /
+     * `getProductId()`. Used only when the user picked "Automatic" — an explicit choice is honored as
+     * is. An unrecognized pad (or none) falls back to [PREF_XBOX360], the safe XInput default the
+     * host always supports. Never returns [PREF_AUTO] (the host would then decide) — once we have a
+     * physical pad we resolve it concretely, matching the other native clients.
+     */
+    fun prefFor(dev: InputDevice?): Int {
+        if (dev == null) return PREF_XBOX360
+        val vid = dev.vendorId
+        val pid = dev.productId
+        return when {
+            vid == VID_SONY && pid in PID_DUALSENSE -> PREF_DUALSENSE
+            vid == VID_SONY && pid in PID_DUALSHOCK4 -> PREF_DUALSHOCK4
+            vid == VID_MICROSOFT && pid in PID_XBOXONE -> PREF_XBOXONE
+            else -> PREF_XBOX360
+        }
+    }
+
+    /** First connected gamepad/joystick [InputDevice], or null when none is attached. */
+    fun firstPad(): InputDevice? {
+        for (id in InputDevice.getDeviceIds()) {
+            val d = InputDevice.getDevice(id) ?: continue
+            val s = d.sources
+            if (s and InputDevice.SOURCE_GAMEPAD == InputDevice.SOURCE_GAMEPAD ||
+                s and InputDevice.SOURCE_JOYSTICK == InputDevice.SOURCE_JOYSTICK
+            ) {
+                return d
+            }
+        }
+        return null
+    }
+
+    /**
+     * The [GamepadPref] wire byte to send for the user's [setting] (the persisted gamepad index). A
+     * non-Auto setting is passed through unchanged; "Automatic" ([PREF_AUTO]) resolves to a concrete
+     * type from the first connected controller via [prefFor] (so the host gets the right pad even
+     * though Android can't tell it the controller type any other way).
+     */
+    fun resolvePref(setting: Int): Int =
+        if (setting == PREF_AUTO) prefFor(firstPad()) else setting
+
+    /**
+     * 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)
+        }
+    }
+}
@@ -0,0 +1,233 @@
+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
+        rumbleThread?.interrupt()
+        hidoutThread?.interrupt()
+        runCatching { vm?.cancel() } // drop any held rumble immediately
+        // Join WITHOUT a timeout. These poll threads dereference the native session handle on every
+        // pull (nativeNextRumble/nativeNextHidout), so they MUST be dead before StreamScreen's
+        // onDispose reaches nativeClose, which frees that handle. A *bounded* join that times out
+        // would let a thread survive into the freed handle → use-after-free SIGSEGV (the
+        // back-while-streaming crash, on the one path the main-thread `closed` guard can't cover).
+        // Safe to block unbounded: the native pulls are internally time-bounded (PULL_TIMEOUT ~100 ms)
+        // and rendering is a quick best-effort binder call, so each thread observes running=false and
+        // exits within ~one timeout — the join returns promptly (well under any ANR threshold).
+        runCatching { rumbleThread?.join() }
+        runCatching { hidoutThread?.join() }
+        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? = Gamepad.firstPad()
+
+    // ---- 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())
+        }
+    }
+}
@@ -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
+    }
+}
@@ -0,0 +1,170 @@
+package io.unom.punktfunk.kit
+
+/**
+ * The single JNI seam to `libpunktfunk_android.so` (the Rust-heavy client core).
+ *
+ * Symbols are implemented in `clients/android/native`. 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,
+        hdrEnabled: Boolean,
+    ): 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)
+
+    // ---- LAN discovery: mDNS browse of `_punktfunk._udp` in Rust (mdns-sd), polled by Kotlin ----
+    // Replaces NsdManager. The caller holds the Wi-Fi MulticastLock for the browse lifetime; raw
+    // multicast *reception* needs it. See io.unom.punktfunk.kit.discovery.HostDiscovery.
+
+    /**
+     * Start browsing `_punktfunk._udp` on the LAN. Returns an opaque discovery handle, or `0` on
+     * failure. Pair with exactly one [nativeDiscoveryStop]. Cheap + non-blocking (spawns the mDNS
+     * daemon + a fold thread).
+     */
+    external fun nativeDiscoveryStart(): Long
+
+    /**
+     * The current resolved-host snapshot for [handle]: newline-joined records, each
+     * `key␟name␟addr␟port␟fp␟pair` (`␟` = U+001F). Empty string = no hosts / `0` handle. Poll ~1 Hz;
+     * cheap (a lock + string build), safe to call on the main thread.
+     */
+    external fun nativeDiscoveryPoll(handle: Long): String
+
+    /** Stop the browse, shut the mDNS daemon down and join its thread. No-op on `0`. */
+    external fun nativeDiscoveryStop(handle: Long)
+
+    /**
+     * Start the HEVC decode thread rendering onto [surface] (a SurfaceView's surface). Decode runs
+     * entirely in Rust (NDK AMediaCodec → ANativeWindow) — no per-frame JNI. No-op if already started.
+     */
+    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)
+
+    /**
+     * Drain ~1 s of live decode stats for the on-stream HUD, or `null` when no decode thread runs.
+     * Returns 10 doubles:
+     * `[fps, mbps, latP50Ms, latP95Ms, latValid, skewCorrected, width, height, refreshHz, framesDropped]`
+     * (the two flags are 1.0/0.0). Poll ~1 Hz; each call resets the measurement window.
+     */
+    external fun nativeVideoStats(handle: Long): DoubleArray?
+
+    /**
+     * 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)
+
+    /**
+     * Absolute mouse position — the host moves the cursor to (x, y) in a [surfaceWidth]×[surfaceHeight]
+     * pixel space (it normalizes against that size and maps into the output region). Touch
+     * "direct pointing": the cursor jumps to the finger. Parity with the Apple client's absolute touch.
+     */
+    external fun nativeSendPointerAbs(handle: Long, x: Int, y: Int, surfaceWidth: Int, surfaceHeight: Int)
+
+    /** One mouse-button transition. button: 1=left 2=middle 3=right 4=X1 5=X2. */
+    external fun nativeSendPointerButton(handle: Long, button: Int, down: Boolean)
+
+    /** 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
+}
@@ -0,0 +1,144 @@
+package io.unom.punktfunk.kit.discovery
+
+import android.content.Context
+import android.net.wifi.WifiManager
+import android.os.Handler
+import android.os.Looper
+import android.util.Log
+import io.unom.punktfunk.kit.NativeBridge
+
+private const val TAG = "PunktfunkMdns"
+
+/** 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,
+)
+
+/** Field separator the native browse uses inside one record (ASCII Unit Separator). */
+private const val FIELD_SEP = '\u001F'
+
+/**
+ * Parse one record from [NativeBridge.nativeDiscoveryPoll] (`key␟name␟addr␟port␟fp␟pair`), or null
+ * if it's malformed. Pure — unit-tested without Android (see ParseRecordTest). The native side
+ * already applied the protocol gate and address selection, so this is just field marshaling.
+ */
+fun parseHostRecord(record: String): DiscoveredHost? {
+    val f = record.split(FIELD_SEP)
+    if (f.size < 6) return null
+    val addr = f[2]
+    val port = f[3].toIntOrNull() ?: return null
+    if (addr.isBlank() || port !in 1..65535) return null
+    return DiscoveredHost(
+        key = f[0].ifBlank { "$addr:$port" },
+        name = f[1].ifBlank { addr },
+        host = addr,
+        port = port,
+        fingerprint = f[4].ifBlank { null },
+        pairingRequired = f[5] == "required",
+    )
+}
+
+/**
+ * Browses `_punktfunk._udp` for punktfunk/1 hosts via the native `mdns-sd` core (the same browse the
+ * Linux/Windows clients use), exposed over JNI — *not* `NsdManager`, whose per-OEM system daemon
+ * made discovery "mostly broken". [start] spins up the native browse and polls it ~1 Hz on the main
+ * thread, pushing the live host set to [onChange] (also on the main thread, only when it changes);
+ * [stop] tears it down.
+ *
+ * We hold a Wi-Fi [WifiManager.MulticastLock] for the browse lifetime — raw multicast *reception*
+ * needs it. (The Android emulator's SLIRP NAT drops multicast, so on the emulator discovery starts
+ * but never finds a LAN host — same as before; that's the network, not the API.)
+ */
+class HostDiscovery(context: Context) {
+    private val appCtx = context.applicationContext
+
+    /** Invoked on the main thread whenever the resolved host set changes. */
+    var onChange: ((List<DiscoveredHost>) -> Unit)? = null
+
+    private val handler = Handler(Looper.getMainLooper())
+    private var multicastLock: WifiManager.MulticastLock? = null
+    private var nativeHandle = 0L
+    private var running = false
+    private var last: List<DiscoveredHost> = emptyList()
+
+    private val poll = object : Runnable {
+        override fun run() {
+            if (!running) return
+            val hosts = snapshot()
+            if (hosts != last) {
+                last = hosts
+                onChange?.invoke(hosts)
+            }
+            handler.postDelayed(this, POLL_MS)
+        }
+    }
+
+    fun start() {
+        if (running) return
+        acquireMulticastLock()
+        val h = runCatching { NativeBridge.nativeDiscoveryStart() }
+            .onFailure { Log.e(TAG, "nativeDiscoveryStart threw", it) }
+            .getOrDefault(0L)
+        if (h == 0L) {
+            Log.e(TAG, "native mDNS discovery failed to start")
+            releaseMulticastLock()
+            return
+        }
+        nativeHandle = h
+        running = true
+        last = emptyList()
+        handler.post(poll)
+    }
+
+    fun stop() {
+        if (!running && nativeHandle == 0L) return
+        running = false
+        handler.removeCallbacks(poll)
+        val h = nativeHandle
+        nativeHandle = 0L
+        if (h != 0L) runCatching { NativeBridge.nativeDiscoveryStop(h) }
+            .onFailure { Log.e(TAG, "nativeDiscoveryStop threw", it) }
+        releaseMulticastLock()
+        last = emptyList()
+        onChange?.invoke(emptyList())
+    }
+
+    private fun snapshot(): List<DiscoveredHost> {
+        val h = nativeHandle
+        if (h == 0L) return emptyList()
+        // getOrNull (not getOrDefault): the JNI returns a platform String!, so a (near-impossible)
+        // native null is a *success* value here — coalesce it so the main-thread poll can't NPE.
+        val blob = runCatching { NativeBridge.nativeDiscoveryPoll(h) }
+            .onFailure { Log.e(TAG, "nativeDiscoveryPoll threw", it) }
+            .getOrNull() ?: ""
+        if (blob.isEmpty()) return emptyList()
+        return blob.split('\n')
+            .filter { it.isNotBlank() }
+            .mapNotNull { parseHostRecord(it) }
+            .associateBy { it.key } // dedup by stable key (id, or addr:port)
+            .values
+            .sortedBy { it.name.lowercase() }
+    }
+
+    private fun acquireMulticastLock() {
+        val wifi = appCtx.getSystemService(Context.WIFI_SERVICE) as WifiManager
+        multicastLock = wifi.createMulticastLock("punktfunk-mdns").apply {
+            setReferenceCounted(true)
+            runCatching { acquire() }
+        }
+    }
+
+    private fun releaseMulticastLock() {
+        multicastLock?.takeIf { it.isHeld }?.let { runCatching { it.release() } }
+        multicastLock = null
+    }
+
+    private companion object {
+        const val POLL_MS = 1000L
+    }
+}
@@ -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
+    }
+}
@@ -0,0 +1,73 @@
+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()
+    }
+
+    /** Set a saved host's display name, keeping its pin + paired flag. No-op if not saved. */
+    fun rename(address: String, port: Int, newName: String) {
+        val h = get(address, port) ?: return
+        save(h.copy(name = newName))
+    }
+
+    /** All trusted hosts, name-sorted — backs the saved-hosts list. */
+    fun all(): List<KnownHost> =
+        prefs.all.values.mapNotNull { (it as? String)?.let(::parse) }.sortedBy { it.name.lowercase() }
+
+    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()
+}
@@ -0,0 +1,62 @@
+package io.unom.punktfunk.kit.discovery
+
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertNull
+import org.junit.Assert.assertTrue
+import org.junit.Test
+
+/**
+ * Pure JVM test of the native-record parser (`key␟name␟addr␟port␟fp␟pair`), the Kotlin half of the
+ * discovery JNI seam. No Android types. Run: `./gradlew :kit:testDebugUnitTest`.
+ */
+class ParseRecordTest {
+    private val s = '\u001F' // field separator (must match the Rust side, discovery.rs FIELD_SEP)
+
+    private fun rec(vararg f: String) = f.joinToString(s.toString())
+
+    @Test
+    fun parsesFullRecord() {
+        val fp = "a".repeat(64)
+        val h = parseHostRecord(rec("host-123", "home-worker-2", "192.168.1.70", "9777", fp, "required"))!!
+        assertEquals("host-123", h.key)
+        assertEquals("home-worker-2", h.name)
+        assertEquals("192.168.1.70", h.host)
+        assertEquals(9777, h.port)
+        assertEquals(fp, h.fingerprint)
+        assertTrue(h.pairingRequired)
+    }
+
+    @Test
+    fun optionalPairingAndEmptyFingerprint() {
+        val h = parseHostRecord(rec("id", "name", "10.0.0.5", "9777", "", "optional"))!!
+        assertNull(h.fingerprint)
+        assertEquals(false, h.pairingRequired)
+    }
+
+    @Test
+    fun emptyKeyFallsBackToAddrPort() {
+        // Host advertised no `id` TXT → the native side leaves the key blank; we synthesize addr:port.
+        val h = parseHostRecord(rec("", "name", "10.0.0.5", "9777", "", "required"))!!
+        assertEquals("10.0.0.5:9777", h.key)
+    }
+
+    @Test
+    fun emptyNameFallsBackToAddr() {
+        val h = parseHostRecord(rec("k", "", "10.0.0.5", "9777", "", "optional"))!!
+        assertEquals("10.0.0.5", h.name)
+    }
+
+    @Test
+    fun rejectsTooFewFields() {
+        assertNull(parseHostRecord("only${'\u001F'}three${'\u001F'}fields"))
+        assertNull(parseHostRecord(""))
+    }
+
+    @Test
+    fun rejectsBadPortOrAddress() {
+        assertNull(parseHostRecord(rec("k", "n", "10.0.0.5", "notaport", "", "required")))
+        assertNull(parseHostRecord(rec("k", "n", "10.0.0.5", "0", "", "required")))
+        assertNull(parseHostRecord(rec("k", "n", "10.0.0.5", "70000", "", "required")))
+        assertNull(parseHostRecord(rec("k", "n", "", "9777", "", "required")))
+    }
+}
@@ -0,0 +1,43 @@
+[package]
+name = "punktfunk-client-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 = "../../../crates/punktfunk-core", features = ["quic"] }
+jni = "0.21"
+log = "0.4"
+# LAN host discovery: browse the host's `_punktfunk._udp` mDNS advert — the SAME crate + service the
+# Linux/Windows clients use (`clients/linux/src/discovery.rs`), replacing Android's per-OEM
+# `NsdManager` system daemon with one tested browse path. Pure Rust (socket2/if-addrs/mio), so it
+# cross-compiles to the Android targets AND builds on the host (the JNI seam links into
+# `cargo build --workspace`). Kotlin keeps only the Wi-Fi `MulticastLock` + permission UX.
+mdns-sd = "0.20"
+
+# Android-only deps. Gated so `cargo build --workspace` on the Linux/macOS dev boxes + CI still
+# compiles this crate (as a host cdylib) — the Android-framework glue (logging now; AMediaCodec via
+# `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", "nativewindow", "api-level-31"] }
+# setpriority/gettid to raise the decode thread toward URGENT_DISPLAY (see decode::boost_thread_priority).
+libc = "0.2"
+# 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"
@@ -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),
+    );
+}
@@ -0,0 +1,310 @@
+//! 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::data_space::DataSpace;
+use ndk::media::media_codec::{
+    DequeuedInputBufferResult, DequeuedOutputBufferInfoResult, MediaCodec, MediaCodecDirection,
+};
+use ndk::media::media_format::MediaFormat;
+use ndk::native_window::{FrameRateCompatibility, 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, Instant};
+
+/// 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>,
+    stats: Arc<crate::stats::VideoStats>,
+) {
+    boost_thread_priority();
+    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);
+    // Advisory low-latency hints (KEY_PRIORITY / KEY_OPERATING_RATE), ignored where unsupported:
+    // realtime priority + the target frame rate, so vendor decoders (e.g. Qualcomm) run at full
+    // clocks instead of a power-saving cadence that adds dequeue latency.
+    format.set_i32("priority", 0); // 0 = realtime
+    format.set_i32("operating-rate", mode.refresh_hz as i32);
+
+    // HDR static metadata (ST.2086 mastering + content light level): when an HDR session was
+    // negotiated, set KEY_HDR_STATIC_INFO so the display tone-maps from the source's real grade.
+    // MediaCodec wants it BEFORE configure(), and the host sends a 0xCE right after the handshake,
+    // so it's typically already queued; wait briefly otherwise. The Surface DataSpace (applied on
+    // OutputFormatChanged below) carries transfer/primaries regardless — this adds the luminance the
+    // tone-mapper needs. A non-HDR display still gets sensible SurfaceFlinger tone-mapping.
+    if client.color.is_hdr() {
+        match client.next_hdr_meta(Duration::from_millis(250)) {
+            Ok(meta) => {
+                format.set_buffer("hdr-static-info", &android_hdr_static_info(&meta));
+                log::info!("decode: HDR static metadata applied (KEY_HDR_STATIC_INFO)");
+            }
+            Err(_) => {
+                log::info!("decode: HDR session but no mastering metadata yet — DataSpace only")
+            }
+        }
+    }
+
+    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
+    );
+    // Tell the display the stream's refresh so Android can pick a matching display mode and align
+    // vsync (no 60-in-120 judder on high-refresh panels). minSdk 31 ≥ API 30, so the underlying
+    // ANativeWindow_setFrameRate is always present; non-fatal if the platform declines.
+    if let Err(e) = window.set_frame_rate(mode.refresh_hz as f32, FrameRateCompatibility::Default) {
+        log::warn!(
+            "decode: set_frame_rate({} Hz) failed (non-fatal): {e}",
+            mode.refresh_hz
+        );
+    }
+
+    let mut fed: u64 = 0;
+    let mut rendered: u64 = 0;
+    // Loss recovery: watch the host→client unrecoverable-drop count and ask for an IDR when it
+    // climbs.
+    let mut last_dropped = client.frames_dropped();
+    let mut last_kf_req: Option<Instant> = None;
+    // Capture→client-receipt latency uses the negotiated host-minus-client clock offset (0 if the
+    // host didn't answer the skew handshake — then the HUD flags it "same-host").
+    let clock_offset = client.clock_offset_ns;
+    // The dataspace we've signalled on the Surface so far (None = default/SDR). Set reactively once
+    // the decoder reports an HDR stream (see `drain`); avoids re-applying every format event.
+    let mut applied_ds: Option<DataSpace> = None;
+    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;
+                // HUD stat: capture→client-receipt latency = client_now + (host−client) − capture_pts.
+                let lat_ns = now_realtime_ns() + clock_offset as i128 - frame.pts_ns as i128;
+                let lat_us =
+                    (lat_ns > 0 && lat_ns < 10_000_000_000).then_some((lat_ns / 1000) as u64);
+                stats.note(frame.data.len(), lat_us, clock_offset != 0);
+                feed(&codec, &frame.data, frame.pts_ns / 1000);
+            }
+            Err(PunktfunkError::NoFrame) => {} // timeout — still drain output below
+            Err(_) => break,                   // session closed
+        }
+        rendered += drain(&codec, &window, &mut applied_ds);
+
+        // Loss recovery: under infinite GOP the only recovery keyframe is one we request. The
+        // reassembler drops unrecoverable AUs (frames_dropped); the decoder then conceals the
+        // reference-missing delta frames that follow and renders them without error, so keying off
+        // a decode error rarely fires. Request an IDR when the drop count climbs, throttled — the
+        // decode stays wedged for several frames until the IDR lands, so requesting every frame
+        // would flood the control stream.
+        let dropped = client.frames_dropped();
+        if dropped > last_dropped {
+            last_dropped = dropped;
+            let now = Instant::now();
+            if last_kf_req.is_none_or(|t| now.duration_since(t) >= Duration::from_millis(100)) {
+                last_kf_req = Some(now);
+                let _ = client.request_keyframe();
+                log::debug!("decode: requested keyframe (loss recovery, dropped={dropped})");
+            }
+        }
+
+        if fed > 0 && fed % 300 == 0 {
+            log::info!("decode: fed={fed} rendered={rendered}");
+        }
+    }
+
+    let _ = codec.stop();
+    log::info!("decode: stopped (fed={fed} rendered={rendered})");
+}
+
+/// Wall-clock now in nanoseconds (CLOCK_REALTIME basis), to compare against the host-stamped
+/// capture `pts_ns` after the skew offset is applied.
+fn now_realtime_ns() -> i128 {
+    use std::time::{SystemTime, UNIX_EPOCH};
+    SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .map(|d| d.as_nanos() as i128)
+        .unwrap_or(0)
+}
+
+/// Best-effort: raise the decode thread toward Android's URGENT_DISPLAY band so background work
+/// can't preempt it under load (which shows up as late/dropped frames). Non-fatal if the platform
+/// refuses (foreground apps may set their own threads; the exact floor is policy-dependent).
+fn boost_thread_priority() {
+    // SAFETY: `gettid`/`setpriority` on the calling thread are always-safe syscalls. PRIO_PROCESS
+    // with a TID targets that one task on Linux — the same idiom `Process.setThreadPriority` uses.
+    unsafe {
+        let tid = libc::gettid();
+        if libc::setpriority(libc::PRIO_PROCESS, tid as libc::id_t, -10) != 0 {
+            log::warn!(
+                "decode: setpriority(-10) failed (non-fatal): {}",
+                std::io::Error::last_os_error()
+            );
+        }
+    }
+}
+
+/// 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. Also reacts to `OutputFormatChanged` to signal HDR on the Surface.
+fn drain(codec: &MediaCodec, window: &NativeWindow, applied_ds: &mut Option<DataSpace>) -> u64 {
+    let mut n = 0;
+    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;
+            }
+            Ok(DequeuedOutputBufferInfoResult::OutputFormatChanged) => {
+                // The decoder has parsed the SPS and now reports the stream's real colour signalling
+                // (the AMediaCodec analogue of VideoToolbox's format description on the Apple client).
+                // If it's HDR (BT.2020 PQ/HLG), tell the Surface so the compositor/display switch to
+                // HDR; SDR streams leave the default dataspace alone. The decoder itself picks a
+                // Main10 path from the SPS — no profile override needed. Keep looping (buffers follow).
+                if let Some(ds) = hdr_dataspace(codec) {
+                    if *applied_ds != Some(ds) {
+                        match window.set_buffers_data_space(ds) {
+                            Ok(()) => {
+                                *applied_ds = Some(ds);
+                                log::info!("decode: HDR stream → Surface dataspace {ds}");
+                            }
+                            Err(e) => log::warn!(
+                                "decode: set_buffers_data_space({ds}) failed (non-fatal): {e}"
+                            ),
+                        }
+                    }
+                }
+            }
+            // TryAgainLater / OutputBuffersChanged — nothing to render now.
+            Ok(_) => break,
+            Err(e) => {
+                log::warn!("decode: dequeue_output_buffer: {e}");
+                break;
+            }
+        }
+    }
+    n
+}
+
+/// Map the decoder's reported output colour to a BT.2020 HDR dataspace, or `None` for SDR. The
+/// integer values are the Android MediaFormat colour constants the NDK shares: COLOR_TRANSFER
+/// ST2084 = 6 (PQ/HDR10), HLG = 7; COLOR_RANGE FULL = 1, LIMITED = 2 (the host encodes limited).
+fn hdr_dataspace(codec: &MediaCodec) -> Option<DataSpace> {
+    let fmt = codec.output_format();
+    let full_range = fmt.i32("color-range") == Some(1);
+    match fmt.i32("color-transfer") {
+        Some(6) => Some(if full_range {
+            DataSpace::Bt2020Pq
+        } else {
+            DataSpace::Bt2020ItuPq
+        }),
+        Some(7) => Some(if full_range {
+            DataSpace::Bt2020Hlg
+        } else {
+            DataSpace::Bt2020ItuHlg
+        }),
+        _ => None, // SDR (BT.709 / SDR_VIDEO) or unspecified
+    }
+}
+
+/// Serialize [`HdrMeta`](punktfunk_core::quic::HdrMeta) into Android's `KEY_HDR_STATIC_INFO`
+/// (`hdr-static-info`) layout: a 25-byte CTA-861.3 / `HDRStaticInfo.Type1` blob — descriptor id 0,
+/// then primaries in **R, G, B** order, white point, max/min display luminance, MaxCLL, MaxFALL, all
+/// **little-endian** `u16`. Two conversions vs our wire form: HdrMeta stores primaries in ST.2086
+/// **G, B, R** order (reorder to R, G, B), and `max_display_mastering_luminance` is in 0.0001-cd/m²
+/// units while Android wants **whole nits** (min stays 0.0001-nit). Chromaticities (1/50000) and
+/// MaxCLL/MaxFALL (nits) match 1:1.
+fn android_hdr_static_info(m: &punktfunk_core::quic::HdrMeta) -> [u8; 25] {
+    let [g, b_, r] = m.display_primaries; // ST.2086 G, B, R
+    let max_nits = (m.max_display_mastering_luminance / 10_000).min(u16::MAX as u32) as u16;
+    let min_units = m.min_display_mastering_luminance.min(u16::MAX as u32) as u16;
+    let fields: [u16; 12] = [
+        r[0],
+        r[1],
+        g[0],
+        g[1],
+        b_[0],
+        b_[1], // R, G, B primaries
+        m.white_point[0],
+        m.white_point[1], // white point
+        max_nits,
+        min_units, // max (nits) / min (0.0001-nit) display luminance
+        m.max_cll,
+        m.max_fall, // MaxCLL / MaxFALL (nits)
+    ];
+    let mut out = [0u8; 25]; // out[0] = 0 (Type 1 descriptor id), already zero
+    for (i, v) in fields.iter().enumerate() {
+        out[1 + i * 2..3 + i * 2].copy_from_slice(&v.to_le_bytes());
+    }
+    out
+}
@@ -0,0 +1,303 @@
+//! LAN host discovery over mDNS, in Rust via `mdns-sd` — the same crate + service type the
+//! Linux/Windows clients use (`clients/linux/src/discovery.rs`), exposed to Kotlin over JNI.
+//!
+//! Why not `NsdManager`: that API delegates to a per-OEM system mDNS daemon whose reliability
+//! varies wildly (the Android client's discovery was "mostly broken"). Browsing in our own Rust
+//! core — the crate is already linked for the whole protocol — gives one tested code path across
+//! every desktop + mobile client and removes the system-daemon dependency. Kotlin still holds the
+//! Wi-Fi `MulticastLock` for the browse lifetime (raw multicast *reception* needs it) and owns the
+//! permission UX; this module owns the socket + resolve.
+//!
+//! Shape: [`Java_io_unom_punktfunk_kit_NativeBridge_nativeDiscoveryStart`] spins up a
+//! [`ServiceDaemon`] browsing `_punktfunk._udp.local.` on a background thread that folds
+//! resolve/remove events into a shared map; Kotlin polls `nativeDiscoveryPoll` ~1 Hz for a
+//! newline-joined snapshot and calls `nativeDiscoveryStop` to tear it down. Polling (not a JVM
+//! callback) mirrors `nativeVideoStats`: no `AttachCurrentThread`/global-ref lifecycle to get
+//! wrong, and 1 Hz is plenty for a host picker.
+
+use crate::session::jni_guard;
+use jni::objects::JObject;
+use jni::sys::jlong;
+use jni::JNIEnv;
+use mdns_sd::{ResolvedService, ServiceDaemon, ServiceEvent};
+use std::collections::HashMap;
+use std::sync::{Arc, Mutex};
+use std::thread::JoinHandle;
+
+/// DNS-SD service type punktfunk hosts advertise (host side: `punktfunk_host::discovery`).
+const SERVICE_TYPE: &str = "_punktfunk._udp.local.";
+/// Wire protocol id in the `proto` TXT record; a host advertising anything else is skipped.
+const PROTO: &str = "punktfunk/1";
+/// Field separator inside one serialized record (ASCII Unit Separator — never in a field value).
+const FIELD_SEP: char = '\u{1f}';
+
+/// One resolved host, serialized to Kotlin as `key␟name␟addr␟port␟fp␟pair` (`␟` = [`FIELD_SEP`]).
+/// Records are newline-joined in a poll snapshot; [`Host::encode`] strips the framing bytes from
+/// every field so no value can break it.
+#[derive(Clone, PartialEq)]
+struct Host {
+    key: String,
+    name: String,
+    addr: String,
+    port: u16,
+    fp: String,
+    pair: String,
+}
+
+impl Host {
+    fn encode(&self) -> String {
+        // mDNS instance labels + TXT values are arbitrary UTF-8 from an UNauthenticated source, so
+        // strip the field/record separators: a rogue advert that smuggled '\n'/U+001F could otherwise
+        // inject or suppress picker rows. (Trust is still gated on connect — this only protects the
+        // list's integrity.)
+        fn clean(s: &str) -> String {
+            s.replace(['\n', '\r', FIELD_SEP], "")
+        }
+        format!(
+            "{}{FIELD_SEP}{}{FIELD_SEP}{}{FIELD_SEP}{}{FIELD_SEP}{}{FIELD_SEP}{}",
+            clean(&self.key),
+            clean(&self.name),
+            clean(&self.addr),
+            self.port,
+            clean(&self.fp),
+            clean(&self.pair),
+        )
+    }
+}
+
+/// A running browse behind the `jlong` handle: the daemon, the shared resolved-host map keyed by
+/// mDNS fullname (stable across re-announce and present on both resolve *and* remove — which fixes
+/// the old `NsdManager` key mismatch that leaked stale hosts), and the event-fold thread.
+struct Discovery {
+    daemon: ServiceDaemon,
+    hosts: Arc<Mutex<HashMap<String, Host>>>,
+    thread: Option<JoinHandle<()>>,
+}
+
+impl Discovery {
+    fn start() -> Option<Discovery> {
+        let daemon = match ServiceDaemon::new() {
+            Ok(d) => d,
+            Err(e) => {
+                log::error!("mDNS daemon failed — discovery disabled: {e}");
+                return None;
+            }
+        };
+        let rx = match daemon.browse(SERVICE_TYPE) {
+            Ok(r) => r,
+            Err(e) => {
+                log::error!("mDNS browse failed — discovery disabled: {e}");
+                let _ = daemon.shutdown();
+                return None;
+            }
+        };
+        let hosts: Arc<Mutex<HashMap<String, Host>>> = Arc::new(Mutex::new(HashMap::new()));
+        let map = hosts.clone();
+        let spawned = std::thread::Builder::new()
+            .name("pf-mdns".into())
+            .spawn(move || {
+                // Exits when the daemon is shut down (the browse channel closes → recv errors).
+                while let Ok(event) = rx.recv() {
+                    match event {
+                        ServiceEvent::ServiceResolved(info) => {
+                            if let Some(host) = resolve(&info) {
+                                map.lock()
+                                    .unwrap()
+                                    .insert(info.get_fullname().to_string(), host);
+                            }
+                        }
+                        ServiceEvent::ServiceRemoved(_ty, fullname) => {
+                            map.lock().unwrap().remove(&fullname);
+                        }
+                        _ => {}
+                    }
+                }
+            });
+        let thread = match spawned {
+            Ok(t) => t,
+            Err(e) => {
+                // The daemon thread + bound :5353 socket outlive a dropped handle (no Drop impl), so
+                // shut it down explicitly — same cleanup as the browse-failure path above.
+                log::error!("mDNS fold thread spawn failed: {e}");
+                let _ = daemon.shutdown();
+                return None;
+            }
+        };
+        log::info!("native mDNS discovery started ({SERVICE_TYPE})");
+        Some(Discovery {
+            daemon,
+            hosts,
+            thread: Some(thread),
+        })
+    }
+
+    /// Current resolved-host set, newline-joined (empty string = none). Sorted for a stable order
+    /// across polls; Kotlin re-sorts by display name.
+    fn snapshot(&self) -> String {
+        let mut records: Vec<String> = self
+            .hosts
+            .lock()
+            .unwrap()
+            .values()
+            .map(Host::encode)
+            .collect();
+        records.sort();
+        records.join("\n")
+    }
+
+    fn stop(mut self) {
+        let _ = self.daemon.shutdown(); // closes the browse channel → the fold thread exits
+        if let Some(t) = self.thread.take() {
+            let _ = t.join();
+        }
+    }
+}
+
+/// Build a [`Host`] from a resolved mDNS record, or `None` if it isn't a usable punktfunk host
+/// (incompatible advertised proto, or no IPv4 address). IPv4 only on purpose: the core dials with
+/// `format!("{host}:{port}").parse::<SocketAddr>()`, which can't parse a bare/scoped IPv6 literal
+/// (it needs the `[addr%scope]:port` form), so surfacing a v6-only host would present a card that
+/// fails on every tap. Dropping it shows the honest "not found" instead.
+fn resolve(info: &ResolvedService) -> Option<Host> {
+    let val = |k: &str| info.get_property_val_str(k).unwrap_or("").to_string();
+    let proto = val("proto");
+    if !proto.is_empty() && proto != PROTO {
+        return None; // some other DNS-SD service sharing the type — ignore
+    }
+    let addr = info
+        .get_addresses_v4()
+        .iter()
+        .next()
+        .map(|a| a.to_string())?;
+    let id = val("id");
+    let fullname = info.get_fullname();
+    Some(Host {
+        key: if id.is_empty() {
+            fullname.to_string()
+        } else {
+            id
+        },
+        name: fullname.split('.').next().unwrap_or("?").to_string(),
+        addr,
+        port: info.get_port(),
+        fp: val("fp"),
+        pair: val("pair"),
+    })
+}
+
+/// `NativeBridge.nativeDiscoveryStart(): Long` — start browsing `_punktfunk._udp`; returns an opaque
+/// handle, or `0` on failure (logged). Pair with exactly one [`nativeDiscoveryStop`]. Kotlin must
+/// hold the Wi-Fi `MulticastLock` for the browse lifetime.
+///
+/// [`nativeDiscoveryStop`]: Java_io_unom_punktfunk_kit_NativeBridge_nativeDiscoveryStop
+#[no_mangle]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeDiscoveryStart(
+    _env: JNIEnv,
+    _this: JObject,
+) -> jlong {
+    jni_guard(0, || match Discovery::start() {
+        Some(d) => Box::into_raw(Box::new(d)) as jlong,
+        None => 0,
+    })
+}
+
+/// `NativeBridge.nativeDiscoveryPoll(handle): String` — the current resolved-host snapshot,
+/// newline-joined records of `key␟name␟addr␟port␟fp␟pair` (`␟` = U+001F). Empty string = no hosts /
+/// `0` handle. Poll ~1 Hz from the UI thread (cheap: a mutex lock + string build).
+#[no_mangle]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeDiscoveryPoll<'local>(
+    env: JNIEnv<'local>,
+    _this: JObject<'local>,
+    handle: jlong,
+) -> jni::sys::jstring {
+    jni_guard(std::ptr::null_mut(), || {
+        let out = if handle == 0 {
+            String::new()
+        } else {
+            // SAFETY: live handle per the start/stop contract — Kotlin owns the lifecycle and never
+            // polls after stop (it nulls the handle first).
+            let d = unsafe { &*(handle as *const Discovery) };
+            d.snapshot()
+        };
+        match env.new_string(out) {
+            Ok(s) => s.into_raw(),
+            Err(_) => std::ptr::null_mut(),
+        }
+    })
+}
+
+/// `NativeBridge.nativeDiscoveryStop(handle)` — stop the browse, shut the daemon down and join its
+/// thread. No-op on `0`.
+///
+/// # Safety contract
+/// `handle` must be `0` or a live handle from [`nativeDiscoveryStart`], stopped exactly once and not
+/// concurrently with [`nativeDiscoveryPoll`] (Kotlin owns this; all calls are on the main thread).
+///
+/// [`nativeDiscoveryStart`]: Java_io_unom_punktfunk_kit_NativeBridge_nativeDiscoveryStart
+/// [`nativeDiscoveryPoll`]: Java_io_unom_punktfunk_kit_NativeBridge_nativeDiscoveryPoll
+#[no_mangle]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeDiscoveryStop(
+    _env: JNIEnv,
+    _this: JObject,
+    handle: jlong,
+) {
+    jni_guard((), || {
+        if handle != 0 {
+            // SAFETY: live handle from nativeDiscoveryStart, stopped exactly once per the contract.
+            let d = unsafe { Box::from_raw(handle as *mut Discovery) };
+            d.stop();
+        }
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn encode_round_trips_all_fields_with_unit_separator() {
+        let h = Host {
+            key: "host-123".into(),
+            name: "home-worker-2".into(),
+            addr: "192.168.1.70".into(),
+            port: 9777,
+            fp: "ab".repeat(32),
+            pair: "required".into(),
+        };
+        let encoded = h.encode();
+        let fields: Vec<&str> = encoded.split(FIELD_SEP).collect();
+        assert_eq!(fields.len(), 6);
+        assert_eq!(fields[0], "host-123");
+        assert_eq!(fields[1], "home-worker-2");
+        assert_eq!(fields[2], "192.168.1.70");
+        assert_eq!(fields[3], "9777");
+        assert_eq!(fields[4], "ab".repeat(32));
+        assert_eq!(fields[5], "required");
+        assert!(
+            !encoded.contains('\n'),
+            "a record must never contain the record separator"
+        );
+    }
+
+    #[test]
+    fn encode_strips_injected_separators_from_a_hostile_advert() {
+        // A rogue advert could carry framing bytes in its instance label / TXT; encode must strip
+        // them so the snapshot stays exactly one record of exactly six fields.
+        let h = Host {
+            key: "k\u{1f}injected".into(),
+            name: "evil\nhost\r".into(),
+            addr: "10.0.0.5".into(),
+            port: 9777,
+            fp: "ab\u{1f}cd".into(),
+            pair: "required\n".into(),
+        };
+        let encoded = h.encode();
+        assert_eq!(encoded.matches(FIELD_SEP).count(), 5, "exactly six fields");
+        assert!(!encoded.contains('\n') && !encoded.contains('\r'));
+        let fields: Vec<&str> = encoded.split(FIELD_SEP).collect();
+        assert_eq!(fields[0], "kinjected");
+        assert_eq!(fields[1], "evilhost");
+        assert_eq!(fields[4], "abcd");
+        assert_eq!(fields[5], "required");
+    }
+}
@@ -0,0 +1,120 @@
+//! 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::{jni_guard, 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 {
+    // Runs on a Kotlin poll thread, so a panic here would abort the process; guard the boundary.
+    jni_guard(-1, || {
+        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 — unbounded) 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 {
+    // Runs on a Kotlin poll thread, so a panic here would abort the process; guard the boundary.
+    jni_guard(-1, || {
+        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
+    })
+}
@@ -0,0 +1,82 @@
+//! 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, the
+//! Wi-Fi `MulticastLock` + permission UX, Keystore). The JNI seam below is the one place the two
+//! languages meet.
+//!
+//! Why Rust-heavy: Kotlin cannot `import` the cbindgen C header the way Swift can, so a native
+//! bridge is unavoidable. Writing it in Rust lets the Android client reuse the Linux client's
+//! orchestration verbatim — audio jitter ring, the VK keymap inverse, latency/skew math, the
+//! input capture state machine, trust/pairing logic, **mDNS discovery** ([`discovery`], the same
+//! `mdns-sd` browse the Linux/Windows clients use) — instead of re-porting it into Kotlin. Kotlin
+//! keeps only the Android-framework surface it must (Compose UI, `SurfaceView`, input capture, the
+//! Wi-Fi `MulticastLock` + permission UX, Keystore identity).
+//!
+//! JNI symbols map to `io.unom.punktfunk.kit.NativeBridge` in the `:kit` Gradle module
+//! (`clients/android`). The current surface is the scaffold's native-link proof
+//! (`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;
+// Ungated: pure `mdns-sd` + `jni`, so the browse + its JNI seam link into the host workspace build
+// (and its unit test runs there) exactly like `session`/`stats`. Kotlin only ever calls it on device.
+mod discovery;
+mod feedback;
+#[cfg(target_os = "android")]
+mod mic;
+mod session;
+mod stats;
+
+/// 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(),
+    }
+}
@@ -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),
+    );
+}
@@ -0,0 +1,732 @@
+//! Session lifecycle + plane wiring over JNI.
+//!
+//! A connected session is a [`SessionHandle`] — an `Arc<NativeClient>` plus the decode thread it
+//! feeds — boxed and handed to Kotlin as an opaque `jlong`. The connector is `Sync`, so the decode
+//! thread pulls the video plane (`next_frame`) directly while Kotlin still holds the handle.
+//!
+//! Wired: connect/close, the video plane (HEVC `next_frame` → NDK AMediaCodec → the SurfaceView's
+//! `ANativeWindow`, see [`crate::decode`]), host→client audio ([`crate::audio`]), input
+//! (`send_input` — mouse/keyboard/gamepad), rumble/DualSense HID feedback ([`crate::feedback`]),
+//! and the trust surface: `nativeGenerateIdentity` (persistent identity, Keystore-wrapped on the
+//! Kotlin side), `nativeConnect` with identity + pin (TOFU / pinned), and `nativePair` (SPAKE2 PIN).
+//!
+//! TODO(M4 Android stage 1): client→host DualSense rich input (`send_rich_input`), mode
+//! renegotiation. Port the remaining orchestration from `clients/linux`.
+
+use jni::objects::{JObject, JString};
+use jni::sys::{jboolean, jdoubleArray, jint, jlong, jsize};
+use jni::JNIEnv;
+use punktfunk_core::client::NativeClient;
+use punktfunk_core::config::{CompositorPref, GamepadPref, Mode};
+use punktfunk_core::input::{InputEvent, InputKind};
+use std::panic::AssertUnwindSafe;
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::{Arc, Mutex};
+use std::thread::JoinHandle;
+use std::time::Duration;
+
+/// Run a JNI body, catching any panic at the FFI boundary and returning `default` instead.
+///
+/// A panic unwinding out of an `extern "system"` function aborts the whole process on Rust ≥ 1.81 —
+/// a hard crash of the embedding Android app with no logcat trace. This mirrors the discipline the C
+/// ABI already enforces (`punktfunk_core::abi` wraps every entry point in `catch_unwind`); the
+/// `panic = "unwind"` profile in the workspace `Cargo.toml` exists precisely so these guards work.
+/// We apply it to the teardown + background-thread shims (the "leaving a stream" path), where an
+/// unexpected panic (e.g. a poisoned `Mutex` during concurrent teardown) must degrade to a logged
+/// no-op rather than kill the app.
+pub(crate) fn jni_guard<T>(default: T, f: impl FnOnce() -> T) -> T {
+    std::panic::catch_unwind(AssertUnwindSafe(f)).unwrap_or_else(|_| {
+        log::error!("punktfunk JNI: caught a panic at the FFI boundary (returning default)");
+        default
+    })
+}
+
+/// A live session behind the `jlong` handle: the connector + the decode thread it feeds.
+pub(crate) struct SessionHandle {
+    // Read only by the android decode path (`nativeStartVideo` → `crate::decode`); on the host
+    // build (CI's workspace clippy/build) those readers are cfg'd out, so it's intentionally unused.
+    #[cfg_attr(not(target_os = "android"), allow(dead_code))]
+    pub client: Arc<NativeClient>,
+    video: Mutex<Option<VideoThread>>,
+    #[cfg(target_os = "android")]
+    audio: Mutex<Option<crate::audio::AudioPlayback>>,
+    #[cfg(target_os = "android")]
+    mic: Mutex<Option<crate::mic::MicCapture>>,
+}
+
+struct VideoThread {
+    shutdown: Arc<AtomicBool>,
+    join: Option<JoinHandle<()>>,
+    /// Live decode stats, written by the decode thread and drained ~1 Hz by `nativeVideoStats`.
+    stats: Arc<crate::stats::VideoStats>,
+}
+
+impl SessionHandle {
+    /// Signal the decode thread to stop and join it. Idempotent.
+    fn stop_video(&self) {
+        if let Some(mut vt) = self.video.lock().unwrap().take() {
+            vt.shutdown.store(true, Ordering::SeqCst);
+            if let Some(j) = vt.join.take() {
+                let _ = j.join();
+            }
+        }
+    }
+
+    /// Stop + close audio playback. Dropping the [`crate::audio::AudioPlayback`] joins its decode
+    /// thread and closes the AAudio stream. Idempotent.
+    #[cfg(target_os = "android")]
+    fn stop_audio(&self) {
+        let _ = self.audio.lock().unwrap().take();
+    }
+
+    /// Stop mic uplink. Dropping the [`crate::mic::MicCapture`] joins its encode thread and closes
+    /// the AAudio input stream. Idempotent.
+    #[cfg(target_os = "android")]
+    fn stop_mic(&self) {
+        let _ = self.mic.lock().unwrap().take();
+    }
+}
+
+impl Drop for SessionHandle {
+    fn drop(&mut self) {
+        self.stop_video();
+        #[cfg(target_os = "android")]
+        self.stop_audio();
+        #[cfg(target_os = "android")]
+        self.stop_mic();
+    }
+}
+
+/// SHA-256 fingerprint → 64 lowercase hex chars (matches the host log + client-rs).
+fn hex32(fp: &[u8; 32]) -> String {
+    use std::fmt::Write;
+    fp.iter().fold(String::with_capacity(64), |mut s, b| {
+        let _ = write!(s, "{b:02x}");
+        s
+    })
+}
+
+/// 64-hex → [u8; 32]; `None` on bad length/char.
+fn parse_hex32(s: &str) -> Option<[u8; 32]> {
+    if s.len() != 64 {
+        return None;
+    }
+    let mut out = [0u8; 32];
+    for (i, b) in out.iter_mut().enumerate() {
+        *b = u8::from_str_radix(&s[2 * i..2 * i + 2], 16).ok()?;
+    }
+    Some(out)
+}
+
+/// `NativeBridge.nativeGenerateIdentity(): String` — mint a fresh persistent self-signed identity.
+/// Returns `"<certPem>\n-----PUNKTFUNK-KEY-----\n<keyPem>"`, or `""` on failure (logged). Kotlin
+/// persists it (Keystore-wrapped) and only calls this again when the store is genuinely empty.
+#[no_mangle]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeGenerateIdentity<'local>(
+    env: JNIEnv<'local>,
+    _this: JObject<'local>,
+) -> jni::sys::jstring {
+    let out = match punktfunk_core::quic::endpoint::generate_identity() {
+        Ok((cert, key)) => format!("{cert}\n-----PUNKTFUNK-KEY-----\n{key}"),
+        Err(e) => {
+            log::error!("nativeGenerateIdentity failed: {e}");
+            String::new()
+        }
+    };
+    match env.new_string(out) {
+        Ok(s) => s.into_raw(),
+        Err(_) => JObject::null().into_raw(),
+    }
+}
+
+/// `NativeBridge.nativeConnect(host, port, w, h, hz, certPem, keyPem, pinHex, bitrateKbps,
+/// compositorPref, gamepadPref): Long`. `certPem`/`keyPem` empty = anonymous, else presented as the
+/// persistent identity. `pinHex` empty = TOFU (read `nativeHostFingerprint` after), else 64-hex
+/// SHA-256 to pin the host (mismatch → 0). `bitrateKbps` 0 = host default. `compositorPref`/
+/// `gamepadPref` are `CompositorPref`/`GamepadPref` wire bytes (0 = Auto; unknown → Auto).
+/// Returns an opaque handle, or 0 on failure (logged).
+#[no_mangle]
+#[allow(clippy::too_many_arguments)]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeConnect<'local>(
+    mut env: JNIEnv<'local>,
+    _this: JObject<'local>,
+    host: JString<'local>,
+    port: jint,
+    width: jint,
+    height: jint,
+    refresh_hz: jint,
+    cert_pem: JString<'local>,
+    key_pem: JString<'local>,
+    pin_hex: JString<'local>,
+    bitrate_kbps: jint,
+    compositor_pref: jint,
+    gamepad_pref: jint,
+    hdr_enabled: jboolean,
+) -> jlong {
+    let host: String = match env.get_string(&host) {
+        Ok(s) => s.into(),
+        Err(_) => return 0,
+    };
+    let cert: String = env
+        .get_string(&cert_pem)
+        .map(Into::into)
+        .unwrap_or_default();
+    let key: String = env.get_string(&key_pem).map(Into::into).unwrap_or_default();
+    let pin_hex: String = env.get_string(&pin_hex).map(Into::into).unwrap_or_default();
+
+    let identity: Option<(String, String)> = if cert.is_empty() || key.is_empty() {
+        None
+    } else {
+        Some((cert, key))
+    };
+    let pin: Option<[u8; 32]> = if pin_hex.is_empty() {
+        None
+    } else {
+        match parse_hex32(&pin_hex) {
+            Some(fp) => Some(fp),
+            None => {
+                log::error!("nativeConnect: bad pin hex (len {})", pin_hex.len());
+                return 0;
+            }
+        }
+    };
+    let mode = Mode {
+        width: width as u32,
+        height: height as u32,
+        refresh_hz: refresh_hz as u32,
+    };
+    match NativeClient::connect(
+        &host,
+        port as u16,
+        mode,
+        CompositorPref::from_u8(compositor_pref.clamp(0, u8::MAX as jint) as u8),
+        GamepadPref::from_u8(gamepad_pref.clamp(0, u8::MAX as jint) as u8),
+        bitrate_kbps.max(0) as u32, // 0 = host default
+        // Advertise 10-bit + HDR ONLY when this device's display can actually present it (Kotlin
+        // checks Display.getHdrCapabilities() and passes the result): the host (e.g. Windows) then
+        // upgrades to a Main10 / BT.2020 PQ encode. On an SDR display we advertise 0 so the host
+        // sends a proper 8-bit BT.709 stream rather than PQ the panel would mis-tone-map. AMediaCodec
+        // decodes Main10 from the SPS and the decode loop signals the Surface HDR dataspace + static
+        // metadata (see crate::decode).
+        if hdr_enabled != 0 {
+            punktfunk_core::quic::VIDEO_CAP_10BIT | punktfunk_core::quic::VIDEO_CAP_HDR
+        } else {
+            0
+        },
+        None,     // launch: default app
+        pin,      // Some → Crypto on host-fp mismatch
+        identity, // owned (cert, key) PEM, or None (anonymous)
+        Duration::from_secs(10),
+    ) {
+        Ok(client) => {
+            let handle = SessionHandle {
+                client: Arc::new(client),
+                video: Mutex::new(None),
+                #[cfg(target_os = "android")]
+                audio: Mutex::new(None),
+                #[cfg(target_os = "android")]
+                mic: Mutex::new(None),
+            };
+            Box::into_raw(Box::new(handle)) as jlong
+        }
+        Err(e) => {
+            log::error!("nativeConnect to {host}:{port} failed: {e}");
+            0
+        }
+    }
+}
+
+/// `NativeBridge.nativeClose(handle)` — drop the session (stops the decode thread, then RAII-tears
+/// down the connector). No-op on `0`.
+///
+/// # Safety contract
+/// `handle` must be `0` or a live handle from [`Java_io_unom_punktfunk_kit_NativeBridge_nativeConnect`],
+/// closed exactly once and not concurrently with other calls on the same handle (Kotlin owns this).
+#[no_mangle]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeClose(
+    _env: JNIEnv,
+    _this: JObject,
+    handle: jlong,
+) {
+    jni_guard((), || {
+        if handle != 0 {
+            // SAFETY: per the contract, `handle` is a live `Box<SessionHandle>` pointer.
+            unsafe { drop(Box::from_raw(handle as *mut SessionHandle)) };
+        }
+    })
+}
+
+/// `NativeBridge.nativeHostFingerprint(handle): String` — the SHA-256 (64-hex) of the cert the host
+/// presented on this connection. Valid after a successful `nativeConnect`; Kotlin pins it on a TOFU
+/// connect. `""` on a `0` handle.
+#[no_mangle]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeHostFingerprint<'local>(
+    env: JNIEnv<'local>,
+    _this: JObject<'local>,
+    handle: jlong,
+) -> jni::sys::jstring {
+    let out = if handle == 0 {
+        String::new()
+    } else {
+        // SAFETY: live handle per the nativeConnect/nativeClose contract.
+        let h = unsafe { &*(handle as *const SessionHandle) };
+        hex32(&h.client.host_fingerprint)
+    };
+    match env.new_string(out) {
+        Ok(s) => s.into_raw(),
+        Err(_) => JObject::null().into_raw(),
+    }
+}
+
+/// `NativeBridge.nativePair(host, port, certPem, keyPem, pin, name): String` — run the SPAKE2 PIN
+/// ceremony, presenting our persistent identity. On success returns the host's verified fingerprint
+/// (64-hex) to persist + pin; on any failure (wrong PIN / MITM / host reject / unreachable) returns
+/// `""` (logged). Blocking — Kotlin calls it off the UI thread.
+#[no_mangle]
+#[allow(clippy::too_many_arguments)]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativePair<'local>(
+    mut env: JNIEnv<'local>,
+    _this: JObject<'local>,
+    host: JString<'local>,
+    port: jint,
+    cert_pem: JString<'local>,
+    key_pem: JString<'local>,
+    pin: JString<'local>,
+    name: JString<'local>,
+) -> jni::sys::jstring {
+    let g = |e: &mut JNIEnv<'local>, j: &JString<'local>| -> String {
+        e.get_string(j).map(Into::into).unwrap_or_default()
+    };
+    let host = g(&mut env, &host);
+    let cert = g(&mut env, &cert_pem);
+    let key = g(&mut env, &key_pem);
+    let pin = g(&mut env, &pin);
+    let name = g(&mut env, &name);
+
+    let out = if host.is_empty() || cert.is_empty() || key.is_empty() {
+        log::error!("nativePair: missing host/identity");
+        String::new()
+    } else {
+        match NativeClient::pair(
+            &host,
+            port as u16,
+            (&cert, &key), // borrowed identity
+            &pin,
+            &name,
+            Duration::from_secs(60),
+        ) {
+            Ok(host_fp) => hex32(&host_fp),
+            Err(e) => {
+                // Crypto error == wrong PIN / MITM; anything else == transport/host reject.
+                log::error!("nativePair to {host}:{port} failed: {e}");
+                String::new()
+            }
+        }
+    };
+    match env.new_string(out) {
+        Ok(s) => s.into_raw(),
+        Err(_) => JObject::null().into_raw(),
+    }
+}
+
+/// `NativeBridge.nativeStartVideo(handle, surface)` — wrap the SurfaceView's `Surface` as an
+/// `ANativeWindow` and start the HEVC decode thread rendering onto it. No-op if already started.
+#[cfg(target_os = "android")]
+#[no_mangle]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeStartVideo(
+    env: JNIEnv,
+    _this: JObject,
+    handle: jlong,
+    surface: JObject,
+) {
+    if handle == 0 {
+        return;
+    }
+    // SAFETY: live handle per the nativeConnect/nativeClose contract.
+    let h = unsafe { &*(handle as *const SessionHandle) };
+    let mut guard = h.video.lock().unwrap();
+    if guard.is_some() {
+        return; // already streaming
+    }
+    // SAFETY: `env`/`surface` are valid JNI pointers for this call. `as *mut _` bridges any
+    // jni-sys version skew between the `jni` and `ndk` crates (both are raw `*mut _` pointers).
+    let window = match unsafe {
+        ndk::native_window::NativeWindow::from_surface(
+            env.get_native_interface() as *mut _,
+            surface.as_raw() as *mut _,
+        )
+    } {
+        Some(w) => w,
+        None => {
+            log::error!("nativeStartVideo: no ANativeWindow from Surface");
+            return;
+        }
+    };
+    let shutdown = Arc::new(AtomicBool::new(false));
+    let stats = Arc::new(crate::stats::VideoStats::new());
+    let client = h.client.clone();
+    let sd = shutdown.clone();
+    let st = stats.clone();
+    let join = std::thread::Builder::new()
+        .name("pf-decode".into())
+        .spawn(move || crate::decode::run(client, window, sd, st))
+        .ok();
+    *guard = Some(VideoThread {
+        shutdown,
+        join,
+        stats,
+    });
+}
+
+/// `NativeBridge.nativeStopVideo(handle)` — stop + join the decode thread (without closing the
+/// session). No-op on `0`.
+#[no_mangle]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeStopVideo(
+    _env: JNIEnv,
+    _this: JObject,
+    handle: jlong,
+) {
+    jni_guard((), || {
+        if handle != 0 {
+            // SAFETY: live handle per the contract.
+            let h = unsafe { &*(handle as *const SessionHandle) };
+            h.stop_video();
+        }
+    })
+}
+
+/// `NativeBridge.nativeVideoStats(handle): DoubleArray?` — drain ~1 s of decode stats for the HUD.
+/// Returns 10 doubles
+/// `[fps, mbps, latP50Ms, latP95Ms, latValid, skewCorrected, width, height, refreshHz, framesDropped]`
+/// (the two flags are 1.0/0.0), or `null` when no decode thread is running. Poll ~1 Hz from the UI;
+/// each call resets the measurement window. Not android-gated — pure `jni` + connector reads, so it
+/// links on the host build too (Kotlin only ever calls it on device).
+#[no_mangle]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeVideoStats(
+    env: JNIEnv,
+    _this: JObject,
+    handle: jlong,
+) -> jdoubleArray {
+    jni_guard(std::ptr::null_mut(), || {
+        if handle == 0 {
+            return std::ptr::null_mut();
+        }
+        // SAFETY: live handle per the nativeConnect/nativeClose contract.
+        let h = unsafe { &*(handle as *const SessionHandle) };
+        let snap = match h.video.lock().unwrap().as_ref() {
+            Some(vt) => vt.stats.drain(),
+            None => return std::ptr::null_mut(), // not streaming → no stats
+        };
+        let mode = h.client.mode();
+        let buf: [f64; 10] = [
+            snap.fps,
+            snap.mbps,
+            snap.lat_p50_ms,
+            snap.lat_p95_ms,
+            if snap.lat_valid { 1.0 } else { 0.0 },
+            if snap.skew_corrected { 1.0 } else { 0.0 },
+            mode.width as f64,
+            mode.height as f64,
+            mode.refresh_hz as f64,
+            h.client.frames_dropped() as f64,
+        ];
+        let arr = match env.new_double_array(buf.len() as jsize) {
+            Ok(a) => a,
+            Err(_) => return std::ptr::null_mut(),
+        };
+        if env.set_double_array_region(&arr, 0, &buf).is_err() {
+            return std::ptr::null_mut();
+        }
+        arr.into_raw()
+    })
+}
+
+/// `NativeBridge.nativeStartAudio(handle)` — start the Opus→AAudio playback thread. No-op if already
+/// started or on a `0` handle. Best-effort: a failure leaves video streaming.
+#[cfg(target_os = "android")]
+#[no_mangle]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeStartAudio(
+    _env: JNIEnv,
+    _this: JObject,
+    handle: jlong,
+) {
+    if handle == 0 {
+        return;
+    }
+    // SAFETY: live handle per the nativeConnect/nativeClose contract.
+    let h = unsafe { &*(handle as *const SessionHandle) };
+    let mut guard = h.audio.lock().unwrap();
+    if guard.is_some() {
+        return; // already playing
+    }
+    match crate::audio::AudioPlayback::start(h.client.clone()) {
+        Some(p) => *guard = Some(p),
+        None => log::error!("nativeStartAudio: playback init failed (video unaffected)"),
+    }
+}
+
+/// `NativeBridge.nativeStopAudio(handle)` — stop + join the audio thread and close AAudio (without
+/// closing the session). No-op on `0`.
+#[cfg(target_os = "android")]
+#[no_mangle]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeStopAudio(
+    _env: JNIEnv,
+    _this: JObject,
+    handle: jlong,
+) {
+    jni_guard((), || {
+        if handle != 0 {
+            // SAFETY: live handle per the contract.
+            let h = unsafe { &*(handle as *const SessionHandle) };
+            h.stop_audio();
+        }
+    })
+}
+
+/// `NativeBridge.nativeStartMic(handle)` — start mic capture (AAudio input → Opus → host `send_mic`).
+/// No-op if already running or on a `0` handle. Caller MUST hold RECORD_AUDIO; a failure (e.g. no
+/// permission) leaves the rest of the session streaming.
+#[cfg(target_os = "android")]
+#[no_mangle]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeStartMic(
+    _env: JNIEnv,
+    _this: JObject,
+    handle: jlong,
+) {
+    if handle == 0 {
+        return;
+    }
+    // SAFETY: live handle per the nativeConnect/nativeClose contract.
+    let h = unsafe { &*(handle as *const SessionHandle) };
+    let mut guard = h.mic.lock().unwrap();
+    if guard.is_some() {
+        return; // already capturing
+    }
+    match crate::mic::MicCapture::start(h.client.clone()) {
+        Some(m) => *guard = Some(m),
+        None => log::error!("nativeStartMic: mic init failed (RECORD_AUDIO? — session unaffected)"),
+    }
+}
+
+/// `NativeBridge.nativeStopMic(handle)` — stop + join the mic thread and close the AAudio input
+/// stream (without closing the session). No-op on `0`.
+#[cfg(target_os = "android")]
+#[no_mangle]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeStopMic(
+    _env: JNIEnv,
+    _this: JObject,
+    handle: jlong,
+) {
+    jni_guard((), || {
+        if handle != 0 {
+            // SAFETY: live handle per the contract.
+            let h = unsafe { &*(handle as *const SessionHandle) };
+            h.stop_mic();
+        }
+    })
+}
+
+// ---- Input plane: Kotlin capture → NativeClient::send_input ----------------------------------
+// All four are `&self` on the `Sync` connector (send_input is a non-blocking datagram push), safe
+// from the Kotlin UI thread. NOT android-gated — send_input exists on the host build too, so these
+// compile everywhere (parity with nativeConnect/nativeClose). The wire codes are the GameStream
+// conventions: buttons 1=left/2=middle/3=right/4=X1/5=X2; scroll axis 0=vertical/1=horizontal,
+// signed 120-unit delta, +=up/right; keys are Windows VK (mapped from KEYCODE_* on the Kotlin side).
+
+/// `NativeBridge.nativeSendPointerMove(handle, dx, dy)` — relative mouse motion (screen +y down).
+#[no_mangle]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSendPointerMove(
+    _env: JNIEnv,
+    _this: JObject,
+    handle: jlong,
+    dx: jint,
+    dy: jint,
+) {
+    if handle == 0 {
+        return;
+    }
+    // SAFETY: live handle per the nativeConnect/nativeClose contract; send_input is &self.
+    let h = unsafe { &*(handle as *const SessionHandle) };
+    let _ = h.client.send_input(&InputEvent {
+        kind: InputKind::MouseMove,
+        _pad: [0; 3],
+        code: 0,
+        x: dx,
+        y: dy,
+        flags: 0,
+    });
+}
+
+/// `NativeBridge.nativeSendPointerAbs(handle, x, y, surfaceWidth, surfaceHeight)` — absolute cursor
+/// position: the host moves the pointer to `x`/`y` in a `surfaceWidth`×`surfaceHeight` pixel space,
+/// normalizing against the size packed into `flags` as `(w << 16) | h` and mapping into the output
+/// region (it drops the event if that size is zero). This is the touch "direct pointing" path — the
+/// cursor jumps to the finger — and matches the Apple client's absolute touch forwarding.
+#[no_mangle]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSendPointerAbs(
+    _env: JNIEnv,
+    _this: JObject,
+    handle: jlong,
+    x: jint,
+    y: jint,
+    surface_width: jint,
+    surface_height: jint,
+) {
+    if handle == 0 {
+        return;
+    }
+    // SAFETY: live handle per the contract.
+    let h = unsafe { &*(handle as *const SessionHandle) };
+    let w = (surface_width.max(0) as u32) & 0xffff;
+    let ht = (surface_height.max(0) as u32) & 0xffff;
+    let _ = h.client.send_input(&InputEvent {
+        kind: InputKind::MouseMoveAbs,
+        _pad: [0; 3],
+        code: 0,
+        x,
+        y,
+        flags: (w << 16) | ht,
+    });
+}
+
+/// `NativeBridge.nativeSendPointerButton(handle, button, down)` — one button transition.
+/// `button`: GameStream id (1=left, 2=middle, 3=right, 4=X1, 5=X2). `down`: 1=press, 0=release.
+#[no_mangle]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSendPointerButton(
+    _env: JNIEnv,
+    _this: JObject,
+    handle: jlong,
+    button: jint,
+    down: jboolean,
+) {
+    if handle == 0 {
+        return;
+    }
+    // SAFETY: live handle per the contract.
+    let h = unsafe { &*(handle as *const SessionHandle) };
+    let _ = h.client.send_input(&InputEvent {
+        kind: if down != 0 {
+            InputKind::MouseButtonDown
+        } else {
+            InputKind::MouseButtonUp
+        },
+        _pad: [0; 3],
+        code: button as u32,
+        x: 0,
+        y: 0,
+        flags: 0,
+    });
+}
+
+/// `NativeBridge.nativeSendScroll(handle, axis, delta)` — one scroll step. `axis`: 0=vertical,
+/// 1=horizontal. `delta`: signed, WHEEL_DELTA(120)-scaled, +=up/right.
+#[no_mangle]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSendScroll(
+    _env: JNIEnv,
+    _this: JObject,
+    handle: jlong,
+    axis: jint,
+    delta: jint,
+) {
+    if handle == 0 {
+        return;
+    }
+    // SAFETY: live handle per the contract.
+    let h = unsafe { &*(handle as *const SessionHandle) };
+    let _ = h.client.send_input(&InputEvent {
+        kind: InputKind::MouseScroll,
+        _pad: [0; 3],
+        code: axis as u32,
+        x: delta,
+        y: 0,
+        flags: 0,
+    });
+}
+
+/// `NativeBridge.nativeSendKey(handle, vk, down, mods)` — one key transition. `vk`: Windows
+/// Virtual-Key code (0 = unmapped → dropped). `down`: 1=press, 0=release. `mods`: VK modifier
+/// bitmask (0 for now — the host folds modifiers from the L/R modifier key events themselves).
+#[no_mangle]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSendKey(
+    _env: JNIEnv,
+    _this: JObject,
+    handle: jlong,
+    vk: jint,
+    down: jboolean,
+    mods: jint,
+) {
+    if handle == 0 || vk == 0 {
+        return;
+    }
+    // SAFETY: live handle per the contract.
+    let h = unsafe { &*(handle as *const SessionHandle) };
+    let _ = h.client.send_input(&InputEvent {
+        kind: if down != 0 {
+            InputKind::KeyDown
+        } else {
+            InputKind::KeyUp
+        },
+        _pad: [0; 3],
+        code: vk as u32,
+        x: 0,
+        y: 0,
+        flags: mods as u32,
+    });
+}
+
+// ---- Gamepad: Kotlin captures (KeyEvent/MotionEvent) → NativeClient::send_input ---------------
+// Single-pad model: exactly one controller, forwarded as pad 0 (flags = 0). Buttons carry the
+// gamepad::BTN_* bit in `code` and pressed/released in `x` (1/0); axes carry the gamepad::AXIS_* id
+// in `code` and the value in `x` (sticks i16 −32768..32767, +y = up; triggers 0..255). The host
+// accumulates the incremental events into its virtual xpad. Wire contract: input.rs::gamepad.
+
+/// `NativeBridge.nativeSendGamepadButton(handle, bit, down)` — one gamepad button transition.
+/// `bit`: a `gamepad::BTN_*` bit (e.g. BTN_A = 0x1000). `down`: 1=press, 0=release.
+#[no_mangle]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSendGamepadButton(
+    _env: JNIEnv,
+    _this: JObject,
+    handle: jlong,
+    bit: jint,
+    down: jboolean,
+) {
+    if handle == 0 {
+        return;
+    }
+    // SAFETY: live handle per the contract.
+    let h = unsafe { &*(handle as *const SessionHandle) };
+    let _ = h.client.send_input(&InputEvent {
+        kind: InputKind::GamepadButton,
+        _pad: [0; 3],
+        code: bit as u32,
+        x: i32::from(down != 0),
+        y: 0,
+        flags: 0, // pad index 0 — single-pad model
+    });
+}
+
+/// `NativeBridge.nativeSendGamepadAxis(handle, axisId, value)` — one gamepad axis update.
+/// `axisId`: a `gamepad::AXIS_*` id (LS_X=0..RT=5). `value`: stick i16 (−32768..32767, +y=up) or
+/// trigger 0..255.
+#[no_mangle]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSendGamepadAxis(
+    _env: JNIEnv,
+    _this: JObject,
+    handle: jlong,
+    axis_id: jint,
+    value: jint,
+) {
+    if handle == 0 {
+        return;
+    }
+    // SAFETY: live handle per the contract.
+    let h = unsafe { &*(handle as *const SessionHandle) };
+    let _ = h.client.send_input(&InputEvent {
+        kind: InputKind::GamepadAxis,
+        _pad: [0; 3],
+        code: axis_id as u32,
+        x: value,
+        y: 0,
+        flags: 0, // pad index 0 — single-pad model
+    });
+}
@@ -0,0 +1,93 @@
+//! Live decode stats for the on-stream HUD (mirrors the Apple client's stats overlay): FPS,
+//! receive throughput, and capture→client-receipt latency (p50/p95). The decode thread is the sole
+//! writer (`note` per access unit); the JNI accessor `nativeVideoStats` drains a snapshot ~1 Hz and
+//! resets the window. Pure `std` so it compiles on the host build too (the decode thread is
+//! android-only, but `VideoThread` holds the shared handle unconditionally).
+
+use std::sync::Mutex;
+use std::time::Instant;
+
+/// Rolling per-window accumulator. Rates are computed over the actual elapsed wall-time at drain
+/// (robust to poll jitter), so a poll that lands at 0.9 s or 1.1 s still reports the right FPS.
+pub struct VideoStats {
+    inner: Mutex<Inner>,
+}
+
+struct Inner {
+    window_start: Instant,
+    frames: u64,
+    bytes: u64,
+    /// capture→client-receipt latency samples for this window, in microseconds.
+    lat_us: Vec<u64>,
+    /// Whether the host answered the clock-skew handshake (latency is cross-machine valid).
+    skew_corrected: bool,
+}
+
+/// A drained, computed view of one window. `lat_valid` is false when no in-range latency sample
+/// landed (then p50/p95 are 0 and the HUD hides the latency line, exactly like the Apple client).
+pub struct Snapshot {
+    pub fps: f64,
+    pub mbps: f64,
+    pub lat_p50_ms: f64,
+    pub lat_p95_ms: f64,
+    pub lat_valid: bool,
+    pub skew_corrected: bool,
+}
+
+impl VideoStats {
+    // `new`/`note` are driven only by the android-only decode thread; `drain` (the JNI accessor) is
+    // ungated, so on the host build these two are unreferenced — that's expected, not dead code.
+    #[cfg_attr(not(target_os = "android"), allow(dead_code))]
+    pub fn new() -> VideoStats {
+        VideoStats {
+            inner: Mutex::new(Inner {
+                window_start: Instant::now(),
+                frames: 0,
+                bytes: 0,
+                lat_us: Vec::with_capacity(256),
+                skew_corrected: false,
+            }),
+        }
+    }
+
+    /// Record one decoded access unit: its wire size and (if in range) its capture→client latency.
+    #[cfg_attr(not(target_os = "android"), allow(dead_code))]
+    pub fn note(&self, bytes: usize, lat_us: Option<u64>, skew_corrected: bool) {
+        let mut g = self.inner.lock().unwrap();
+        g.frames += 1;
+        g.bytes += bytes as u64;
+        g.skew_corrected = skew_corrected;
+        if let Some(l) = lat_us {
+            g.lat_us.push(l);
+        }
+    }
+
+    /// Compute the window's rates + latency percentiles, then reset for the next window.
+    pub fn drain(&self) -> Snapshot {
+        let mut g = self.inner.lock().unwrap();
+        let elapsed = g.window_start.elapsed().as_secs_f64().max(1e-3);
+        let fps = g.frames as f64 / elapsed;
+        let mbps = g.bytes as f64 * 8.0 / 1_000_000.0 / elapsed;
+        let (p50, p95, valid) = if g.lat_us.is_empty() {
+            (0.0, 0.0, false)
+        } else {
+            g.lat_us.sort_unstable();
+            let n = g.lat_us.len();
+            let at = |p: f64| g.lat_us[((n as f64 * p) as usize).min(n - 1)] as f64 / 1000.0;
+            (at(0.50), at(0.95), true)
+        };
+        let skew = g.skew_corrected;
+        g.window_start = Instant::now();
+        g.frames = 0;
+        g.bytes = 0;
+        g.lat_us.clear();
+        Snapshot {
+            fps,
+            mbps,
+            lat_p50_ms: p50,
+            lat_p95_ms: p95,
+            lat_valid: valid,
+            skew_corrected: skew,
+        }
+    }
+}
@@ -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")
@@ -0,0 +1,38 @@
+{
+  "colors" : [
+    {
+      "color" : {
+        "color-space" : "srgb",
+        "components" : {
+          "alpha" : "1.000",
+          "blue" : "0xF2",
+          "green" : "0x56",
+          "red" : "0x66"
+        }
+      },
+      "idiom" : "universal"
+    },
+    {
+      "appearances" : [
+        {
+          "appearance" : "luminosity",
+          "value" : "dark"
+        }
+      ],
+      "color" : {
+        "color-space" : "srgb",
+        "components" : {
+          "alpha" : "1.000",
+          "blue" : "0xF5",
+          "green" : "0x78",
+          "red" : "0x86"
+        }
+      },
+      "idiom" : "universal"
+    }
+  ],
+  "info" : {
+    "author" : "xcode",
+    "version" : 1
+  }
+}
@@ -0,0 +1,13 @@
+{
+  "images": [
+    {
+      "filename": "back@1x.png",
+      "idiom": "tv",
+      "scale": "1x"
+    }
+  ],
+  "info": {
+    "author": "xcode",
+    "version": 1
+  }
+}
@@ -0,0 +1,6 @@
+{
+  "info": {
+    "author": "xcode",
+    "version": 1
+  }
+}
@@ -0,0 +1,13 @@
+{
+  "images": [
+    {
+      "filename": "circle1@1x.png",
+      "idiom": "tv",
+      "scale": "1x"
+    }
+  ],
+  "info": {
+    "author": "xcode",
+    "version": 1
+  }
+}
@@ -0,0 +1,6 @@
+{
+  "info": {
+    "author": "xcode",
+    "version": 1
+  }
+}
@@ -0,0 +1,13 @@
+{
+  "images": [
+    {
+      "filename": "circle2@1x.png",
+      "idiom": "tv",
+      "scale": "1x"
+    }
+  ],
+  "info": {
+    "author": "xcode",
+    "version": 1
+  }
+}
@@ -0,0 +1,6 @@
+{
+  "info": {
+    "author": "xcode",
+    "version": 1
+  }
+}
@@ -0,0 +1,20 @@
+{
+  "layers": [
+    {
+      "filename": "Front.imagestacklayer"
+    },
+    {
+      "filename": "Circle2.imagestacklayer"
+    },
+    {
+      "filename": "Circle1.imagestacklayer"
+    },
+    {
+      "filename": "Back.imagestacklayer"
+    }
+  ],
+  "info": {
+    "author": "xcode",
+    "version": 1
+  }
+}
@@ -0,0 +1,13 @@
+{
+  "images": [
+    {
+      "filename": "front@1x.png",
+      "idiom": "tv",
+      "scale": "1x"
+    }
+  ],
+  "info": {
+    "author": "xcode",
+    "version": 1
+  }
+}
@@ -0,0 +1,6 @@
+{
+  "info": {
+    "author": "xcode",
+    "version": 1
+  }
+}
@@ -0,0 +1,18 @@
+{
+  "images": [
+    {
+      "filename": "back@1x.png",
+      "idiom": "tv",
+      "scale": "1x"
+    },
+    {
+      "filename": "back@2x.png",
+      "idiom": "tv",
+      "scale": "2x"
+    }
+  ],
+  "info": {
+    "author": "xcode",
+    "version": 1
+  }
+}
@@ -0,0 +1,6 @@
+{
+  "info": {
+    "author": "xcode",
+    "version": 1
+  }
+}
@@ -0,0 +1,18 @@
+{
+  "images": [
+    {
+      "filename": "circle1@1x.png",
+      "idiom": "tv",
+      "scale": "1x"
+    },
+    {
+      "filename": "circle1@2x.png",
+      "idiom": "tv",
+      "scale": "2x"
+    }
+  ],
+  "info": {
+    "author": "xcode",
+    "version": 1
+  }
+}
@@ -0,0 +1,6 @@
+{
+  "info": {
+    "author": "xcode",
+    "version": 1
+  }
+}
--- a/Show More
+++ b/Show More