feat(resize/apple): resize overlay — blur + spinner during mid-stream resize

Make a Match-window resize deliberate instead of a stutter: blur the live
stream and show a spinner while the host rebuilds its virtual display +
encoder and VideoToolbox re-inits on the new-mode IDR. No new protocol —
driven entirely by existing client signals.

- ResizeIndicator (pure core, unit-tested): START = follower steering,
  END = a decoded frame at the target size, TIMEOUT = 2.5s safety net for a
  rejected/capped switch that never yields a new-size frame; re-arms only on
  a CHANGED target, not a repeated same-size drag.
- MatchWindowFollower.onResizeTarget fires the instant the window differs
  from the live mode (deduped via lastSteered); a new onDecodedSize callback
  threads each new-mode IDR's coded dims through StreamPump/Stage2Pipeline →
  SessionPresenter → both stream views.
- SessionModel gains @Published resizing (+ resizeTargeted/resizeDecoded, a
  tick on the 1 Hz stats timer, reset on disconnect); ContentView blurs the
  stream 16px and overlays ResizeIndicatorView while resizing (the 32px
  trust-prompt blur is unchanged and takes precedence).

tvOS declares the props but never fires the follower (it drives modes via
AVDisplayManager), so the overlay stays dormant there. Pure core verified on
the Linux toolchain; full AppKit/UIKit build pending on a Mac.

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

.gitea/workflows/android.yml

@@ -103,6 +103,23 @@ jobs:
           # AAB for Play; a universal APK (all ABIs) for direct sideload/testing — same upload key.
           ./gradlew :app:bundleRelease :app:assembleRelease --stacktrace
 
+      # Attach the built APK to the workflow run so it's a one-click sideload download straight from the
+      # run page (no need to know the generic-registry URL) — on EVERY trigger, incl. a PR or a
+      # workflow_dispatch. The debug APK is built on every run; the signed universal release APK exists
+      # only on a main/tag push (its build step above is push-gated), so grab whichever were produced.
+      - name: Attach APK(s) to the workflow run
+        if: always()
+        # v3, not v4: Gitea's artifact backend identifies as GHES, which upload-artifact@v4 refuses
+        # (same reason as apple.yml / *-screenshots.yml). Download is a zip of the matched APK(s).
+        uses: actions/upload-artifact@v3
+        with:
+          name: punktfunk-android-apk
+          path: |
+            clients/android/app/build/outputs/apk/release/*.apk
+            clients/android/app/build/outputs/apk/debug/*.apk
+          if-no-files-found: warn
+          retention-days: 30
+
       # 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

.gitea/workflows/apple.yml

@@ -16,8 +16,17 @@ on:
   workflow_dispatch:
 
 jobs:
+  # SECURITY: builds/tests PULL-REQUEST code on the host-mode, persistent `macos-arm64` runner shared
+  # with the release-signing job (release.yml, which loads the App Store Connect key). Untrusted PR
+  # code could persist on it or harvest signing material. Definitive fix is server-side: enable Gitea's
+  # "require approval for PRs from outside collaborators/forks", and/or isolate PR CI on ephemeral
+  # runners. The `if:` is a fail-open backstop — it skips fork PRs where Gitea reports the fork flag and
+  # still runs same-repo PRs (and where the flag is absent), so it never blocks internal PR CI.
   swift:
     runs-on: macos-arm64
+    if: >-
+      gitea.event_name != 'pull_request' ||
+      gitea.event.pull_request.head.repo.fork != true
     timeout-minutes: 60
     steps:
       - uses: actions/checkout@v4

.gitea/workflows/arch.yml

@@ -42,7 +42,7 @@ jobs:
       - name: Install build + runtime-dev deps
         run: |
           pacman -Syu --noconfirm --needed \
-            git nodejs rust clang cmake nasm pkgconf python \
+            git nodejs rust clang cmake nasm pkgconf python vulkan-headers \
             gtk4 libadwaita sdl3 ffmpeg pipewire wayland libxkbcommon opus libei \
             mesa libglvnd unzip libarchive
           # bun builds the punktfunk-web console AND is vendored as its runtime (PF_WITH_WEB=1);

.gitea/workflows/deb.yml

@@ -60,8 +60,10 @@ jobs:
         run: |
           apt-get update
           # python3 is used by scripts/ci/gitea-release.sh for the stable-tag release attach.
+          # libvulkan-dev: /usr/include/vulkan/vulkan.h for the client's pf-ffvk bindgen
+          # (FFmpeg's hwcontext_vulkan.h includes it).
           apt-get install -y --no-install-recommends dpkg-dev python3 \
-            libgtk-4-dev libadwaita-1-dev libsdl3-dev
+            libgtk-4-dev libadwaita-1-dev libsdl3-dev libvulkan-dev
 
       # Share ci.yml's cache keys so the release build reuses its registry + target artifacts.
       - name: Cache keys
@@ -86,7 +88,10 @@ jobs:
           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
+          # punktfunk-client-session is the Vulkan/Skia streamer the shell execs for a connect —
+          # both client binaries must ship (build-client-deb.sh installs both).
+          cargo build --release --locked \
+            -p punktfunk-host -p punktfunk-client-linux -p punktfunk-client-session
 
       - name: Build + smoke-boot web console (bun preset)
         # Gate the .deb on a real bun boot: the punktfunk-web .deb runs the Nitro `bun` preset

.gitea/workflows/deploy-services.yml

@@ -0,0 +1,101 @@
+# Deploy-only: bring up the two unom-1 pieces that live in THIS repo but whose normal
+# deploys are coupled to heavy build workflows — docs to docker.yml's 5-image matrix,
+# the flatpak server to flatpak.yml's full flatpak-builder run. This workflow does
+# NEITHER build: it just (re)places the compose files and pulls the already-published
+# images, so unom/infra's deploy-all can bring a fresh unom-1 fully up in a single
+# dispatch without triggering those rebuilds.
+#
+#   docs     -> pulls git.unom.io/unom/punktfunk-docs:latest (built by docker.yml) and
+#               brings it up on :3220.
+#   flatpak  -> brings up the caddy:2-alpine static server on :3230. The OSTree repo
+#               CONTENT (./site) is NOT shipped here — it is regenerated by flatpak.yml
+#               on the next client build, or restored from the unom-1 backup
+#               (unom/infra scripts/restore-unom-1.sh, `files` tag). A fresh box serves
+#               an empty repo until then; that is expected.
+#
+# Dispatched by unom/infra scripts/deploy-all.sh: `dispatch-and-wait.sh punktfunk
+# deploy-services.yml`. Uses the same secret set docker.yml/flatpak.yml already rely on:
+# DEPLOY_HOST/USER/PORT/SSH_KEY (the unom-ci-deploy key) + REGISTRY_TOKEN (docs pull).
+name: deploy-services
+run-name: ${{ gitea.actor }} deploy docs + flatpak server
+
+on:
+  workflow_dispatch:
+    inputs:
+      deploy_host:
+        description: "Box IP to deploy to; deploy-all passes the freshly-provisioned target IP. Blank (push) uses the DEPLOY_HOST secret."
+        required: false
+
+jobs:
+  docs:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Sync compose file
+        # SHA-pinned (receives DEPLOY_SSH_KEY): a moved tag would mean credential
+        # exfiltration. v0.1.7 = 917f8b8. Bump the SHA + trailing version together.
+        uses: appleboy/scp-action@917f8b81dfc1ccd331fef9e2d61bdc6c8be94634 # v0.1.7
+        with:
+          host: ${{ inputs.deploy_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
+        # SHA-pinned: receives DEPLOY_SSH_KEY + REGISTRY_TOKEN. v1.2.5 = 0ff4204.
+        uses: appleboy/ssh-action@0ff4204d59e8e51228ff73bce53f80d53301dee2 # v1.2.5
+        env:
+          REGISTRY_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
+        with:
+          host: ${{ inputs.deploy_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
+
+  flatpak:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Sync flatpak server compose + Caddyfile
+        uses: appleboy/scp-action@917f8b81dfc1ccd331fef9e2d61bdc6c8be94634 # v0.1.7
+        with:
+          host: ${{ inputs.deploy_host || secrets.DEPLOY_HOST }}
+          username: ${{ secrets.DEPLOY_USER }}
+          port: ${{ secrets.DEPLOY_PORT }}
+          key: ${{ secrets.DEPLOY_SSH_KEY }}
+          # Land both files flat in ~/unom-flatpak/ (drop the packaging/flatpak/server/ prefix).
+          source: "packaging/flatpak/server/compose.production.yml,packaging/flatpak/server/Caddyfile"
+          target: "~/unom-flatpak"
+          strip_components: 3
+          overwrite: true
+
+      - name: Start flatpak static server
+        uses: appleboy/ssh-action@0ff4204d59e8e51228ff73bce53f80d53301dee2 # v1.2.5
+        with:
+          host: ${{ inputs.deploy_host || secrets.DEPLOY_HOST }}
+          username: ${{ secrets.DEPLOY_USER }}
+          port: ${{ secrets.DEPLOY_PORT }}
+          key: ${{ secrets.DEPLOY_SSH_KEY }}
+          script: |
+            set -euo pipefail
+            # ./site (the OSTree repo) is NOT shipped by this workflow. Ensure the
+            # bind-mount source exists so caddy starts; content is restored from the
+            # unom-1 backup or regenerated by flatpak.yml's next publish.
+            mkdir -p ~/unom-flatpak/site/repo
+            cd ~/unom-flatpak
+            docker compose -f compose.production.yml up -d

.gitea/workflows/flatpak.yml

@@ -25,9 +25,15 @@ on:
     branches: [main]
     # The flatpak is the CLIENT — only rebuild when the client/core/manifest change, not on every
     # design/host push (this is a heavy flatpak-builder run). Tags (v*, the client release) build too.
+    # The bundle ships BOTH client binaries (shell + Vulkan session), so every crate in either
+    # binary's dependency closure must be listed here.
     paths:
       - 'clients/linux/**'
+      - 'clients/session/**'
       - 'crates/punktfunk-core/**'
+      - 'crates/pf-client-core/**'
+      - 'crates/pf-presenter/**'
+      - 'crates/pf-console-ui/**'
       - 'packaging/flatpak/**'
       - 'Cargo.lock'
       - '.gitea/workflows/flatpak.yml'
@@ -53,6 +59,23 @@ jobs:
       image: fedora:43
       options: --privileged
     steps:
+      # DNS fix — MUST run before any network step. fedora:43's nsswitch.conf is
+      # `hosts: files myhostname resolve [!UNAVAIL=return] dns`: the `resolve`
+      # module is nss-resolve (systemd-resolved), which isn't running in a CI
+      # container. glibc getaddrinfo (git, curl, dnf) mostly falls through to the
+      # `dns` module -> Docker's embedded 127.0.0.11 -> works. flatpak/ostree's
+      # resolver does NOT fall through: the absent-daemon socket connect trips
+      # `[!UNAVAIL=return]` and it reports "[6] Could not resolve hostname". This
+      # was masked as an intermittent "busy runner drops DNS" and papered over
+      # with retry.sh — but it's deterministic on a runner where the resolve
+      # module tips that way (surfaced when jobs began landing on home-runner-2).
+      # Drop the `resolve` entry so host lookups use plain `dns`. NOTE: this alone is not
+      # sufficient — the Tooling step's dnf install pulls a systemd package upgrade whose RPM
+      # trigger re-runs authselect and regenerates this file, undoing the fix. It's reapplied
+      # there, right before the first `flatpak` network call.
+      - name: Fix container DNS (drop nss-resolve — no systemd-resolved in CI)
+        run: sed -i 's/resolve \[!UNAVAIL=return\] //' /etc/nsswitch.conf
+
       # 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
@@ -66,8 +89,28 @@ jobs:
           # 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
+          # Belt-and-suspenders: keep nsswitch on plain `dns` even if this dnf transaction pulled
+          # in a fresh systemd-resolved (it does — flatpak recommends xdg-desktop-portal ->
+          # pipewire/wireplumber -> systemd-networkd/-resolved). Verified on the real runner
+          # (2026-07-11) this dnf install does NOT actually rewrite /etc/nsswitch.conf — no
+          # authselect trigger fires — so this line alone was never the fix for the failures
+          # below. See the retry.sh bump for the real cause.
+          sed -i 's/resolve \[!UNAVAIL=return\] //' /etc/nsswitch.conf
           # Flathub provides the GNOME runtime/SDK + the rust-stable + ffmpeg-full extensions.
-          flatpak remote-add --user --if-not-exists flathub \
+          #
+          # ROOT CAUSE (confirmed 2026-07-11 by watching a live run on home-runner-1): this is
+          # NOT a deterministic nsswitch/DNS-config bug. gitea-runner-fleet on home-runner-1 is
+          # a SHARED, resource-capped fleet (3 replicas, --cpus 5 --memory 7g each, on a 16c/24G
+          # box) serving punktfunk AND several other orgs' repos (chatwoot, website, cms, data,
+          # infra, tempblade, played...). A push to punktfunk's main fans out ~8 workflows at
+          # once, and this runner box's Docker embedded DNS resolver (127.0.0.11) genuinely
+          # drops UDP lookups under that concurrent load — exactly what retry.sh's own header
+          # comment already documented. Reproduced: manually dispatching this job when the box
+          # was idle (1 container running) succeeded immediately, with or without the sed above.
+          # 5 attempts (~100s total) isn't always enough to outlast a synchronized multi-org
+          # burst, so bump the bootstrap fetch's budget — never fail the job on a single-shot
+          # fetch. Same treatment for every network command below.
+          bash scripts/ci/retry.sh 10 flatpak remote-add --user --if-not-exists flathub \
             https://dl.flathub.org/repo/flathub.flatpakrepo
           git config --global --add safe.directory "$PWD"
 
@@ -102,7 +145,7 @@ jobs:
         # 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 \
+          curl -fsSL --retry 5 --retry-all-errors --retry-delay 5 -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 \
@@ -136,18 +179,45 @@ jobs:
           DEST="${DEPLOY_USER}@${DEPLOY_HOST}"
           mkdir -p "$PWD/repo"
           # Pull the currently-published repo (all channels' objects + refs) into the repo the build
-          # will extend. No --delete: the local repo starts empty, so this only ADDS. A missing
-          # server repo (very first publish) is fine — we continue with a fresh repo.
-          rsync -az --info=stats1 -e "$SSH" "$DEST:$DEPLOY_DIR/site/repo/" "$PWD/repo/" \
-            || echo "::warning::no published repo to seed (first publish?) — continuing fresh"
+          # will extend. No --delete: the local repo starts empty, so this only ADDS.
+          # Probe first (retried) whether a published repo exists at all: ONLY that case may
+          # continue with a fresh repo. A transient network failure must FAIL the job instead —
+          # a blanket `rsync || continue` here is exactly how a flaky link produces the
+          # single-branch summary that clobbers the other channel (the bug described above).
+          PRESENT=$(bash scripts/ci/retry.sh 5 $SSH "$DEST" \
+            "[ -d $DEPLOY_DIR/site/repo/refs ] && echo present || echo absent")
+          if [ "$PRESENT" = present ]; then
+            bash scripts/ci/retry.sh 5 rsync -az --info=stats1 -e "$SSH" \
+              "$DEST:$DEPLOY_DIR/site/repo/" "$PWD/repo/"
+          else
+            echo "::warning::no published repo on the server (first publish) — continuing fresh"
+          fi
           echo "seeded refs:"; ls "$PWD/repo/refs/heads/app/$APP_ID/x86_64/" 2>/dev/null || echo "  (none)"
 
-      - name: Build the flatpak (install deps from Flathub, offline build)
+      - name: Prefetch deps + sources (retried — the network phase, split off the 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).
+          # All of the job's heavy network I/O happens HERE, retried, so a dropped DNS lookup
+          # or TCP dial costs a backoff-retry instead of the whole (long) compile:
+          #   1) --install-deps-only pulls everything the manifest declares from Flathub: 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).
+          #   2) --download-only fetches every source (all crates in cargo-sources.json) into
+          #      the .flatpak-builder state dir. Both are resumable/idempotent, so re-running
+          #      after a partial failure is safe and cheap.
+          # --disable-rofiles-fuse is the container-safe path (no FUSE).
+          # 10 attempts (~9min budget), matching the remote-add bootstrap above — same shared,
+          # load-sensitive runner, same flathub.org resolution path.
+          bash scripts/ci/retry.sh 10 flatpak-builder --user --force-clean --disable-rofiles-fuse \
+            --install-deps-from=flathub --install-deps-only \
+            "$PWD/build-dir" "$MANIFEST"
+          bash scripts/ci/retry.sh 10 flatpak-builder --user --force-clean --disable-rofiles-fuse \
+            --download-only \
+            "$PWD/build-dir" "$MANIFEST"
+
+      - name: Build the flatpak (offline — deps + sources prefetched above)
+        run: |
+          # Everything is already local (state dir warmed by the prefetch step), so this long
+          # step needs no network; --install-deps-from stays as a no-op safety net.
           # --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).
@@ -266,11 +336,13 @@ jobs:
           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"
+          # All idempotent — retried because the runner's link to unom-1 drops TCP dials under
+          # load (the same flake that hits docker.yml's deploy-docs with "dial tcp: i/o timeout").
+          bash scripts/ci/retry.sh 5 $SSH "$DEST" "mkdir -p ~/$DEPLOY_DIR/site/repo"
+          bash scripts/ci/retry.sh 5 rsync -az --info=stats1 -e "$SSH" repo/ "$DEST:$DEPLOY_DIR/site/repo/"
+          bash scripts/ci/retry.sh 5 rsync -az -e "$SSH" site/unom.flatpakrepo "site/${APP_ID}.flatpakref" "site/${APP_ID}.Canary.flatpakref" site/index.html "$DEST:$DEPLOY_DIR/site/"
+          bash scripts/ci/retry.sh 5 rsync -az -e "$SSH" packaging/flatpak/server/compose.production.yml packaging/flatpak/server/Caddyfile "$DEST:$DEPLOY_DIR/"
+          bash scripts/ci/retry.sh 5 $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)

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

@@ -30,7 +30,7 @@ jobs:
         run: |
           apt-get update
           apt-get install -y --no-install-recommends \
-            libgtk-4-dev libadwaita-1-dev libsdl3-dev \
+            libgtk-4-dev libadwaita-1-dev libsdl3-dev libvulkan-dev \
             xvfb x11-utils imagemagick scrot \
             libgl1-mesa-dri mesa-vulkan-drivers \
             adwaita-icon-theme fonts-cantarell fonts-dejavu-core

.gitea/workflows/rpm.yml

@@ -54,7 +54,9 @@ jobs:
       - name: Prep
         run: |
           git config --global --add safe.directory "$PWD"
-          dnf -y install gtk4-devel libadwaita-devel SDL3-devel
+          # vulkan-headers: the client's pf-ffvk crate runs bindgen over FFmpeg's
+          # libavutil/hwcontext_vulkan.h (#include <vulkan/vulkan.h>).
+          dnf -y install gtk4-devel libadwaita-devel SDL3-devel vulkan-headers
           # sysext build (packaging/bazzite/build-sysext.sh): squashfs + SELinux labeling.
           dnf -y install squashfs-tools cpio libselinux-utils selinux-policy-targeted
           # bun builds the punktfunk-web console (--with web). Baked into the image; install it

.gitea/workflows/windows-drivers.yml

@@ -30,8 +30,15 @@ on:
 # scripts/ci/ensure-windows-toolchain.ps1, a fast no-op once already present.
 
 jobs:
+  # SECURITY: builds PULL-REQUEST code on the host-mode, persistent `windows-amd64` runner shared with
+  # the release-signing jobs (windows-host.yml / windows-msix.yml). See windows.yml for the full
+  # rationale. Definitive fix is server-side (Gitea outside-collaborator approval + isolated PR
+  # runners); the `if:` is a fail-open backstop that never blocks internal PR CI.
   probe-and-proto:
     runs-on: windows-amd64
+    if: >-
+      github.event_name != 'pull_request' ||
+      github.event.pull_request.head.repo.fork != true
     timeout-minutes: 30
     defaults:
       run:
@@ -108,6 +115,9 @@ jobs:
   # DLL's FORCE_INTEGRITY (/INTEGRITYCHECK) bit — the M0 self-signed-load question.
   driver-build:
     runs-on: windows-amd64
+    if: >-
+      github.event_name != 'pull_request' ||
+      github.event.pull_request.head.repo.fork != true
     timeout-minutes: 45
     defaults:
       run:

.gitea/workflows/windows-msix.yml

@@ -33,7 +33,12 @@ on:
     branches: [main]
     paths:
       - 'clients/windows/**'
+      - 'clients/session/**'
       - 'crates/punktfunk-core/**'
+      - 'crates/pf-client-core/**'
+      - 'crates/pf-presenter/**'
+      - 'crates/pf-console-ui/**'
+      - 'crates/pf-ffvk/**'
       - 'Cargo.lock'
       - 'Cargo.toml'
       - '.gitea/workflows/windows-msix.yml'
@@ -57,10 +62,15 @@ jobs:
             target: x86_64-pc-windows-msvc
             ffmpeg: C:\Users\Public\ffmpeg
             td: C:\t
+            session_flags: ''
           - arch: arm64
             target: aarch64-pc-windows-msvc
             ffmpeg: C:\Users\Public\ffmpeg-arm64
             td: C:\t-a64
+            # No skia-binaries prebuilt for aarch64-pc-windows-msvc: the session ships
+            # without the Skia console UI on ARM64 (streaming unaffected) — flip when
+            # rust-skia adds the target.
+            session_flags: '--no-default-features'
     steps:
       - uses: actions/checkout@v4
 
@@ -78,6 +88,8 @@ jobs:
           "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
+          # pf-ffvk's bindgen needs Vulkan headers (arch-independent; provisioned alongside FFmpeg).
+          "PF_FFVK_VULKAN_INCLUDE=C:\Users\Public\vulkan-headers\include" | Out-File -FilePath $env:GITHUB_ENV -Append -Encoding utf8
           rustup target add ${{ matrix.target }}
           $pf = & "$env:GITHUB_WORKSPACE/scripts/ci/pf-version.ps1"   # single source of truth: base is one minor ahead of the latest stable tag
           $parts = if ($env:GITHUB_REF -like 'refs/tags/v*') {
@@ -92,9 +104,11 @@ jobs:
           "MSIX_VERSION=$v" | Out-File -FilePath $env:GITHUB_ENV -Append -Encoding utf8
           Write-Output "MSIX version $v  arch ${{ matrix.arch }}  target ${{ matrix.target }}"
 
+      # Both client binaries — the shell spawns punktfunk-session.exe (a package sibling)
+      # for every stream. --no-default-features on ARM64 is a no-op for the shell.
       - name: Build (release)
         shell: pwsh
-        run: cargo build --release -p punktfunk-client-windows --target ${{ matrix.target }}
+        run: cargo build --release -p punktfunk-client-windows -p punktfunk-client-session ${{ matrix.session_flags }} --target ${{ matrix.target }}
 
       - name: Pack + sign MSIX
         shell: pwsh

.gitea/workflows/windows.yml

@@ -1,9 +1,13 @@
 # Windows client CI — runs on a self-hosted windows-amd64 runner (host mode; the generic runner +
-# toolchain come from unom/infra's windows-runner/; punktfunk's own extras - FFmpeg, WDK, Inno
-# Setup, the ARM64 rustup target - self-provision via the "Ensure Windows toolchain" step below, a
-# fast no-op once already present, so any runner with that label works with no manual dispatch
-# step first). Build + clippy + fmt + test the WinUI 3 client
-# (windows-reactor + D3D11/SwapChainPanel + WASAPI + SDL3).
+# toolchain come from unom/infra's windows-runner/; punktfunk's own extras - FFmpeg,
+# Vulkan-Headers, WDK, Inno Setup, the ARM64 rustup target - self-provision via the "Ensure
+# Windows toolchain" step below, a fast no-op once already present, so any runner with that label
+# works with no manual dispatch step first). Build + clippy + fmt + test BOTH client binaries:
+# the WinUI 3 shell (windows-reactor + WASAPI + SDL3) and the punktfunk-session Vulkan client
+# (pf-presenter/pf-client-core/pf-console-ui/pf-ffvk — every stream runs in it, spawned by the
+# shell). ARM64 note: rust-skia publishes no aarch64-pc-windows-msvc prebuilt binaries, so the
+# session builds --no-default-features there (no Skia console UI; streaming is unaffected) —
+# flip when skia-binaries adds the target.
 #
 # 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
@@ -40,22 +44,44 @@ on:
     branches: [main]
     paths:
       - 'clients/windows/**'
+      - 'clients/session/**'
       - 'crates/punktfunk-core/**'
+      - 'crates/pf-client-core/**'
+      - 'crates/pf-presenter/**'
+      - 'crates/pf-console-ui/**'
+      - 'crates/pf-ffvk/**'
       - 'Cargo.lock'
       - 'Cargo.toml'
       - '.gitea/workflows/windows.yml'
   pull_request:
     paths:
       - 'clients/windows/**'
+      - 'clients/session/**'
       - 'crates/punktfunk-core/**'
+      - 'crates/pf-client-core/**'
+      - 'crates/pf-presenter/**'
+      - 'crates/pf-console-ui/**'
+      - 'crates/pf-ffvk/**'
       - 'Cargo.lock'
       - 'Cargo.toml'
       - '.gitea/workflows/windows.yml'
   workflow_dispatch:
 
 jobs:
+  # SECURITY: this job builds PULL-REQUEST code (attacker-controllable build.rs / cargo build) on the
+  # host-mode, persistent `windows-amd64` runner that the release-SIGNING jobs (windows-host.yml /
+  # windows-msix.yml, which decrypt MSIX_CERT_PFX_B64 + REGISTRY_TOKEN to disk) also run on. Untrusted
+  # PR code could therefore persist on that machine or harvest signing material a later job exposes.
+  # The DEFINITIVE fix is operational and lives outside this file: enable Gitea's "require approval to
+  # run workflows for PRs from outside collaborators/forks", and/or route PR CI to isolated ephemeral
+  # runners. The `if:` below is only a backstop — it skips fork PRs where Gitea reports the fork flag,
+  # and FAILS OPEN (still runs) for same-repo PRs and on Gitea versions that don't populate it, so it
+  # never blocks internal PR CI.
   build:
     runs-on: windows-amd64
+    if: >-
+      github.event_name != 'pull_request' ||
+      github.event.pull_request.head.repo.fork != true
     timeout-minutes: 90
     strategy:
       fail-fast: false
@@ -78,6 +104,8 @@ jobs:
           # Per-arch FFmpeg import libs (provision-windows-punktfunk-extras.ps1 fetches both).
           $ff = if ('${{ matrix.target }}' -eq 'aarch64-pc-windows-msvc') { 'C:\Users\Public\ffmpeg-arm64' } else { 'C:\Users\Public\ffmpeg' }
           "FFMPEG_DIR=$ff" | Out-File -FilePath $env:GITHUB_ENV -Append -Encoding utf8
+          # pf-ffvk's bindgen needs Vulkan headers (arch-independent; provisioned alongside FFmpeg).
+          "PF_FFVK_VULKAN_INCLUDE=C:\Users\Public\vulkan-headers\include" | Out-File -FilePath $env:GITHUB_ENV -Append -Encoding utf8
           # $ff\bin on PATH too (not just FFMPEG_DIR, which only satisfies the linker): the test
           # binary needs the actual DLLs to load at runtime. Set here rather than relying on the
           # daemon's own env (project-env.ps1) - on a freshly cloned/registered runner the daemon
@@ -89,20 +117,29 @@ jobs:
           cargo --version
           Write-Output "target ${{ matrix.target }}  target-dir $td  ffmpeg $ff"
 
+      # Both client binaries. ARM64: no skia-binaries prebuilt for the target, so the session
+      # drops its `ui` feature there (pf-console-ui excluded; --no-default-features is a no-op
+      # for the shell, which has no features).
       - name: Build
         shell: pwsh
-        run: cargo build -p punktfunk-client-windows --target ${{ matrix.target }}
+        run: |
+          $sf = @(); if ('${{ matrix.target }}' -eq 'aarch64-pc-windows-msvc') { $sf = @('--no-default-features') }
+          cargo build -p punktfunk-client-windows -p punktfunk-client-session @sf --target ${{ matrix.target }}
 
       - name: Clippy (-D warnings)
         shell: pwsh
-        run: cargo clippy -p punktfunk-client-windows --all-targets --target ${{ matrix.target }} -- -D warnings
+        run: |
+          $pkgs = @('-p','punktfunk-client-windows','-p','punktfunk-client-session','-p','pf-client-core','-p','pf-presenter','-p','pf-ffvk')
+          $sf = @()
+          if ('${{ matrix.target }}' -eq 'aarch64-pc-windows-msvc') { $sf = @('--no-default-features') } else { $pkgs += @('-p','pf-console-ui') }
+          cargo clippy @pkgs --all-targets @sf --target ${{ matrix.target }} -- -D warnings
 
       - name: Rustfmt check
         if: matrix.target == 'x86_64-pc-windows-msvc'
         shell: pwsh
-        run: cargo fmt -p punktfunk-client-windows -- --check
+        run: cargo fmt -p punktfunk-client-windows -p punktfunk-client-session -p pf-client-core -p pf-presenter -p pf-console-ui -p pf-ffvk -- --check
 
       - name: Test
         if: matrix.target == 'x86_64-pc-windows-msvc'
         shell: pwsh
-        run: cargo test -p punktfunk-client-windows --target ${{ matrix.target }}
+        run: cargo test -p punktfunk-client-windows -p punktfunk-client-session -p pf-client-core -p pf-presenter -p pf-console-ui -p pf-ffvk --target ${{ matrix.target }}

.gitignore

@@ -34,3 +34,7 @@ __pycache__/
 
 # Claude Code project instructions — local to each dev box, not part of the repo.
 CLAUDE.md
+
+# Local flatpak-builder output (build-flatpak.sh) — ostree repo + build dir at the repo root.
+.flatpak-repo/
+.flatpak-build/

CONTRIBUTING.md

@@ -40,4 +40,6 @@ Generated artifacts are checked in and CI fails on drift: `include/punktfunk_cor
 `api/openapi.json` (`cargo run -p punktfunk-host -- openapi`). Match the surrounding code's comment
 density and naming. Commit messages end with the `Co-Authored-By` trailer (see `git log`).
 
-See [`CLAUDE.md`](CLAUDE.md) for the full build/test/run guide and design invariants.
+See the [README's Build & test section](README.md#build--test-from-source) and
+[Design invariants](README.md#design-invariants) for the full build/test/run guide, and the
+[docs site](https://docs.punktfunk.unom.io) for architecture and per-platform guides.

Cargo.lock

@@ -472,6 +472,8 @@ dependencies = [
  "cexpr",
  "clang-sys",
  "itertools 0.13.0",
+ "log",
+ "prettyplease",
  "proc-macro2",
  "quote",
  "regex",
@@ -889,9 +891,9 @@ dependencies = [
 
 [[package]]
 name = "crossbeam-epoch"
-version = "0.9.18"
+version = "0.9.20"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "5b82ac4a3c2ca9c3460964f020e1402edd5753411d7737aa39c3714ad1b5420e"
+checksum = "2d6914041f254d6e9176c01941b21115dcfb7089e55135a35411081bd106ef3f"
 dependencies = [
  "crossbeam-utils",
 ]
@@ -1144,6 +1146,9 @@ name = "fastrand"
 version = "2.4.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9f1f227452a390804cdb637b74a86990f2a7d7ba4b7d5693aac9b4dd6defd8d6"
+dependencies = [
+ "getrandom 0.3.4",
+]
 
 [[package]]
 name = "fec-rs"
@@ -1193,6 +1198,16 @@ dependencies = [
  "rustc_version",
 ]
 
+[[package]]
+name = "filetime"
+version = "0.2.29"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5c287a33c7f0a620c38e641e7f60827713987b3c0f26e8ddc9462cc69cf75759"
+dependencies = [
+ "cfg-if",
+ "libc",
+]
+
 [[package]]
 name = "find-msvc-tools"
 version = "0.1.9"
@@ -1221,6 +1236,7 @@ version = "0.12.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "5e139bc46ca777eb5efaf62df0ab8cc5fd400866427e56c68b22e414e53bd3be"
 dependencies = [
+ "fastrand",
  "futures-core",
  "futures-sink",
  "spin",
@@ -1247,6 +1263,15 @@ dependencies = [
  "percent-encoding",
 ]
 
+[[package]]
+name = "fragile"
+version = "2.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8878864ba14bb86e818a412bfd6f18f9eabd4ec0f008a28e8f7eb61db532fcf9"
+dependencies = [
+ "futures-core",
+]
+
 [[package]]
 name = "fs-err"
 version = "3.3.0"
@@ -2129,7 +2154,7 @@ dependencies = [
 
 [[package]]
 name = "latency-probe"
-version = "0.8.2"
+version = "0.9.2"
 
 [[package]]
 name = "lazy_static"
@@ -2261,7 +2286,7 @@ checksum = "0ceec5bc11778974d1bcb055b18002eba7f4b3518b6a0081b3af5f21666da9ad"
 
 [[package]]
 name = "loss-harness"
-version = "0.8.2"
+version = "0.9.2"
 dependencies = [
  "punktfunk-core",
 ]
@@ -2382,8 +2407,6 @@ dependencies = [
 [[package]]
 name = "ndk"
 version = "0.9.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c3f42e7bbe13d351b6bead8286a43aac9534b82bd3cc43e47037f012ebfd62d4"
 dependencies = [
  "bitflags",
  "jni-sys 0.3.1",
@@ -2740,6 +2763,42 @@ version = "2.3.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9b4f627cb1b25917193a259e49bdad08f671f8d9708acfd5fe0a8c1455d87220"
 
+[[package]]
+name = "pf-client-core"
+version = "0.9.2"
+dependencies = [
+ "anyhow",
+ "async-channel",
+ "ffmpeg-next",
+ "mdns-sd",
+ "opus",
+ "pf-ffvk",
+ "pipewire",
+ "punktfunk-core",
+ "rustls",
+ "sdl3",
+ "serde",
+ "serde_json",
+ "tracing",
+ "ureq",
+ "wasapi",
+ "windows 0.62.2 (git+https://github.com/microsoft/windows-rs?rev=a4f7b2cb7c63c6bb7fc77a2affe57145be1d8c4f)",
+]
+
+[[package]]
+name = "pf-console-ui"
+version = "0.9.2"
+dependencies = [
+ "anyhow",
+ "ash",
+ "pf-client-core",
+ "pf-presenter",
+ "punktfunk-core",
+ "sdl3",
+ "skia-safe",
+ "tracing",
+]
+
 [[package]]
 name = "pf-driver-proto"
 version = "0.0.1"
@@ -2747,6 +2806,30 @@ dependencies = [
  "bytemuck",
 ]
 
+[[package]]
+name = "pf-ffvk"
+version = "0.9.2"
+dependencies = [
+ "ash",
+ "bindgen",
+ "pkg-config",
+]
+
+[[package]]
+name = "pf-presenter"
+version = "0.9.2"
+dependencies = [
+ "anyhow",
+ "ash",
+ "async-channel",
+ "pf-client-core",
+ "pf-ffvk",
+ "punktfunk-core",
+ "sdl3",
+ "tracing",
+ "windows-sys 0.61.2",
+]
+
 [[package]]
 name = "pin-project-lite"
 version = "0.2.17"
@@ -2869,13 +2952,23 @@ dependencies = [
  "zerocopy",
 ]
 
+[[package]]
+name = "prettyplease"
+version = "0.2.37"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "479ca8adacdd7ce8f1fb39ce9ecccbfe93a3f1344b3d0d97f20bc0196208f62b"
+dependencies = [
+ "proc-macro2",
+ "syn",
+]
+
 [[package]]
 name = "proc-macro-crate"
 version = "3.5.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e67ba7e9b2b56446f1d419b1d807906278ffa1a658a8a5d8a39dcb1f5a78614f"
 dependencies = [
- "toml_edit",
+ "toml_edit 0.25.12+spec-1.1.0",
 ]
 
 [[package]]
@@ -2908,7 +3001,7 @@ dependencies = [
 
 [[package]]
 name = "punktfunk-client-android"
-version = "0.8.2"
+version = "0.9.2"
 dependencies = [
  "android_logger",
  "jni",
@@ -2916,6 +3009,7 @@ dependencies = [
  "log",
  "mdns-sd",
  "ndk",
+ "ndk-sys",
  "opus",
  "punktfunk-core",
  "tracing",
@@ -2923,30 +3017,38 @@ dependencies = [
 
 [[package]]
 name = "punktfunk-client-linux"
-version = "0.8.2"
+version = "0.9.2"
 dependencies = [
  "anyhow",
  "async-channel",
- "ffmpeg-next",
  "gtk4",
- "khronos-egl",
  "libadwaita",
- "mdns-sd",
- "opus",
- "pipewire",
+ "pf-client-core",
  "punktfunk-core",
- "rustls",
- "sdl3",
- "serde",
+ "relm4",
  "serde_json",
  "tracing",
  "tracing-subscriber",
- "ureq",
+]
+
+[[package]]
+name = "punktfunk-client-session"
+version = "0.9.2"
+dependencies = [
+ "anyhow",
+ "pf-client-core",
+ "pf-console-ui",
+ "pf-presenter",
+ "punktfunk-core",
+ "serde_json",
+ "tracing",
+ "tracing-subscriber",
+ "winresource",
 ]
 
 [[package]]
 name = "punktfunk-client-windows"
-version = "0.8.2"
+version = "0.9.2"
 dependencies = [
  "anyhow",
  "async-channel",
@@ -2954,6 +3056,7 @@ dependencies = [
  "ffmpeg-next",
  "mdns-sd",
  "opus",
+ "pf-client-core",
  "punktfunk-core",
  "sdl3",
  "serde",
@@ -2969,7 +3072,7 @@ dependencies = [
 
 [[package]]
 name = "punktfunk-core"
-version = "0.8.2"
+version = "0.9.2"
 dependencies = [
  "aes-gcm",
  "bytes",
@@ -3000,7 +3103,7 @@ dependencies = [
 
 [[package]]
 name = "punktfunk-host"
-version = "0.8.2"
+version = "0.9.2"
 dependencies = [
  "aes",
  "aes-gcm",
@@ -3072,7 +3175,7 @@ dependencies = [
 
 [[package]]
 name = "punktfunk-probe"
-version = "0.8.2"
+version = "0.9.2"
 dependencies = [
  "anyhow",
  "mdns-sd",
@@ -3086,7 +3189,7 @@ dependencies = [
 
 [[package]]
 name = "punktfunk-tray"
-version = "0.8.2"
+version = "0.9.2"
 dependencies = [
  "anyhow",
  "ksni",
@@ -3371,6 +3474,41 @@ dependencies = [
  "tokio",
 ]
 
+[[package]]
+name = "relm4"
+version = "0.11.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6420f090f0545e9ec9656469d139a4e1b66ff9c30b808fe2247892724f71a198"
+dependencies = [
+ "flume",
+ "fragile",
+ "futures",
+ "gtk4",
+ "libadwaita",
+ "once_cell",
+ "relm4-css",
+ "relm4-macros",
+ "tokio",
+ "tracing",
+]
+
+[[package]]
+name = "relm4-css"
+version = "0.11.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f3b81d263f784b103c815afa29124486b59741eca069ce7a5999efb14f13c368"
+
+[[package]]
+name = "relm4-macros"
+version = "0.11.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "36c9dbf50a60c82375e66b61d522c936b187a11b25c0a42e91c516326ad24a4f"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
 [[package]]
 name = "ring"
 version = "0.17.14"
@@ -3691,6 +3829,7 @@ version = "0.6.6+SDL-3.4.10"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "04e7f134def04ed72e6f55187c6c29c72f7dab5d359c4be0dd49c9b97fef59c7"
 dependencies = [
+ "ash",
  "cc",
  "cmake",
  "pkg-config",
@@ -3813,6 +3952,15 @@ dependencies = [
  "syn",
 ]
 
+[[package]]
+name = "serde_spanned"
+version = "0.6.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bf41e0cfaf7226dca15e8197172c295a782857fcb97fad1808a166870dee75a3"
+dependencies = [
+ "serde",
+]
+
 [[package]]
 name = "serde_spanned"
 version = "1.1.1"
@@ -3898,6 +4046,35 @@ version = "1.0.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "8ee5873ec9cce0195efcb7a4e9507a04cd49aec9c83d0389df45b1ef7ba2e649"
 
+[[package]]
+name = "skia-bindings"
+version = "0.87.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "704242769235d2ffe66a2a0a3002661262fc4af08d32807c362d7b0160ee703c"
+dependencies = [
+ "bindgen",
+ "cc",
+ "flate2",
+ "heck",
+ "lazy_static",
+ "pkg-config",
+ "regex",
+ "serde_json",
+ "tar",
+ "toml 0.8.23",
+]
+
+[[package]]
+name = "skia-safe"
+version = "0.87.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0f7d94f3e7537c71ad4cf132eb26e3be8c8a886ed3649c4525c089041fc312b2"
+dependencies = [
+ "bitflags",
+ "lazy_static",
+ "skia-bindings",
+]
+
 [[package]]
 name = "slab"
 version = "0.4.12"
@@ -4033,6 +4210,17 @@ dependencies = [
  "version-compare",
 ]
 
+[[package]]
+name = "tar"
+version = "0.4.46"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3f6221d9a6003c78398e3b239969f352578258df48c8eb051caadae0015bc840"
+dependencies = [
+ "filetime",
+ "libc",
+ "xattr",
+]
+
 [[package]]
 name = "target-lexicon"
 version = "0.13.5"
@@ -4218,6 +4406,18 @@ dependencies = [
  "tokio",
 ]
 
+[[package]]
+name = "toml"
+version = "0.8.23"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dc1beb996b9d83529a9e75c17a1686767d148d70663143c7854d8b4a09ced362"
+dependencies = [
+ "serde",
+ "serde_spanned 0.6.9",
+ "toml_datetime 0.6.11",
+ "toml_edit 0.22.27",
+]
+
 [[package]]
 name = "toml"
 version = "0.9.12+spec-1.1.0"
@@ -4226,7 +4426,7 @@ checksum = "cf92845e79fc2e2def6a5d828f0801e29a2f8acc037becc5ab08595c7d5e9863"
 dependencies = [
  "indexmap",
  "serde_core",
- "serde_spanned",
+ "serde_spanned 1.1.1",
  "toml_datetime 0.7.5+spec-1.1.0",
  "toml_parser",
  "toml_writer",
@@ -4241,13 +4441,22 @@ checksum = "81f3d15e84cbcd896376e6730314d59fb5a87f31e4b038454184435cd57defee"
 dependencies = [
  "indexmap",
  "serde_core",
- "serde_spanned",
+ "serde_spanned 1.1.1",
  "toml_datetime 1.1.1+spec-1.1.0",
  "toml_parser",
  "toml_writer",
  "winnow 1.0.3",
 ]
 
+[[package]]
+name = "toml_datetime"
+version = "0.6.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "22cddaf88f4fbc13c51aebbf5f8eceb5c7c5a9da2ac40a13519eb5b0a0e8f11c"
+dependencies = [
+ "serde",
+]
+
 [[package]]
 name = "toml_datetime"
 version = "0.7.5+spec-1.1.0"
@@ -4266,6 +4475,20 @@ dependencies = [
  "serde_core",
 ]
 
+[[package]]
+name = "toml_edit"
+version = "0.22.27"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "41fe8c660ae4257887cf66394862d21dbca4a6ddd26f04a3560410406a2f819a"
+dependencies = [
+ "indexmap",
+ "serde",
+ "serde_spanned 0.6.9",
+ "toml_datetime 0.6.11",
+ "toml_write",
+ "winnow 0.7.15",
+]
+
 [[package]]
 name = "toml_edit"
 version = "0.25.12+spec-1.1.0"
@@ -4287,6 +4510,12 @@ dependencies = [
  "winnow 1.0.3",
 ]
 
+[[package]]
+name = "toml_write"
+version = "0.1.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5d99f8c9a7727884afe522e9bd5edbfc91a3312b36a77b5fb8926e4c31a41801"
+
 [[package]]
 name = "toml_writer"
 version = "1.1.1+spec-1.1.0"
@@ -5330,6 +5559,9 @@ name = "winnow"
 version = "0.7.15"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "df79d97927682d2fd8adb29682d1140b343be4ac0f08fd68b7765d9c059d3945"
+dependencies = [
+ "memchr",
+]
 
 [[package]]
 name = "winnow"
@@ -5389,6 +5621,16 @@ dependencies = [
  "time",
 ]
 
+[[package]]
+name = "xattr"
+version = "1.6.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "32e45ad4206f6d2479085147f02bc2ef834ac85886624a23575ae137c8aa8156"
+dependencies = [
+ "libc",
+ "rustix",
+]
+
 [[package]]
 name = "xkbcommon"
 version = "0.8.0"

Cargo.toml

@@ -5,19 +5,37 @@ members = [
     "crates/punktfunk-host",
     "crates/punktfunk-host/vendor/usbip-sim",
     "crates/punktfunk-tray",
+    "crates/pf-client-core",
+    "crates/pf-presenter",
+    "crates/pf-console-ui",
+    "crates/pf-ffvk",
     "crates/pf-driver-proto",
     "clients/probe",
     "clients/linux",
+    "clients/session",
     "clients/windows",
     "clients/android/native",
     "tools/latency-probe",
     "tools/loss-harness",
 ]
 # Standalone PoC (built on its own; pulls usbip/tokio/libusb we don't want in the workspace).
-exclude = ["packaging/linux/steam-deck-gadget/usbip-poc"]
+# The vendored `ndk` is a [patch.crates-io] source, not a member: it only compiles for the
+# `*-linux-android` targets, so workspace membership would break host `cargo build --workspace`.
+exclude = [
+    "packaging/linux/steam-deck-gadget/usbip-poc",
+    "clients/android/native/vendor/ndk",
+]
+
+# ndk 0.9.0 verbatim from crates.io plus ONE visibility change (and two warning fixes — an
+# unnecessary `std::` qualification and a feature-gated `Result` import): `MediaCodec::as_ptr` made public
+# (upstream keeps it private and exposes no frame-rendered binding), so the Android client can
+# call `AMediaCodec_setOnFrameRenderedCallback` via ndk-sys for the HUD's `display` stage
+# (design/stats-unification.md). Drop the patch when upstream exposes the pointer or the callback.
+[patch.crates-io]
+ndk = { path = "clients/android/native/vendor/ndk" }
 
 [workspace.package]
-version = "0.8.2"
+version = "0.9.2"
 edition = "2021"
 rust-version = "1.82"
 license = "MIT OR Apache-2.0"

README.md

@@ -22,7 +22,8 @@ punktfunk pairs a **virtual-display streaming host** with native clients on ever
 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.
+protocol, FEC, and crypto, linked into the host and every native client — directly as a Rust crate
+on Linux and Windows, and over a stable C ABI from the Apple and Android apps.
 
 ## What makes it different
 
@@ -58,12 +59,16 @@ protocol, FEC, and crypto, linked into the host and every client over a stable C
 | **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** (Windows 11 22H2+, x64) | 🟡 Implemented & shipping as a signed installer: its own all-Rust IddCx **virtual display** (secure-desktop capable) with a **sealed IDD-push** capture path — finished frames pushed straight into its own driver, not screen-scraped (no DDA/WGC) · GPU encode (NVENC on NVIDIA, AMF/QSV on AMD/Intel, software H.264 without a GPU) · WASAPI audio · bundled virtual-gamepad drivers (no ViGEmBus) · HDR incl. Vulkan-game HDR. NVIDIA live-validated; AMD/Intel CI-green |
-| **macOS / iOS / tvOS client** (`clients/apple`) | ✅ Streaming live: VideoToolbox decode, controllers incl. DualSense, discovery, pairing, speed test |
-| **Linux client** (`clients/linux`, GTK4) | ✅ Streaming live: FFmpeg + VAAPI zero-copy decode, PipeWire audio, SDL3 controllers; ships as Flatpak/apt/rpm/Arch |
+| **macOS / iOS / tvOS client** (`clients/apple`) | ✅ Streaming live: VideoToolbox decode (HEVC, and AV1 on hardware that decodes it), controllers incl. DualSense, discovery, pairing, speed test |
+| **Linux client** (`clients/linux` + `clients/session`) | ✅ Streaming live: relm4/GTK4 launcher shell that spawns a Vulkan session binary — Vulkan Video / VAAPI / software decode, PipeWire audio, SDL3 controllers, Skia console UI; ships as Flatpak/apt/rpm/Arch |
 | **Android client** (`clients/android`, phone + TV) | ✅ Streaming live: AMediaCodec decode + HDR10, AAudio audio, controllers, discovery, pairing |
-| **Windows client** (`clients/windows`, WinUI 3) | ✅ Streaming live: D3D11VA hardware decode on all GPU vendors (NVIDIA + Intel validated on glass) with software fallback, WASAPI audio, SDL3 controllers, discovery, pairing; ships as signed MSIX (x64 + ARM64). HDR10 implemented, on-glass validation pending |
+| **Windows client** (`clients/windows`, WinUI 3) | ✅ Streaming live: WinUI 3 shell + Vulkan session presenter, hardware decode on all GPU vendors via Vulkan Video → D3D11VA → software (NVIDIA + Intel validated on glass), WASAPI audio, SDL3 controllers, discovery, pairing; ships as signed MSIX (x64 + ARM64). HDR10 implemented, on-glass validation pending |
 | **Web console + management API** (`web/`) | ✅ TanStack console over the OpenAPI mgmt API: host status, paired devices, on-demand PIN pairing, GPU selection, performance capture graphs, live host logs |
 
+Every native client also ships a tiered **stats overlay** (Compact / Normal / Detailed) with a
+shared vocabulary across platforms, and the session client carries a full gamepad-driven **console
+shell** (`pf-console-ui`): host list, PIN pairing, settings, and an on-screen keyboard.
+
 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,
@@ -117,7 +122,7 @@ Each client discovers hosts on the network automatically and does a one-time
 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 build --workspace          # core, host, tray, shared client crates, Linux shell + session client, probe (Linux & macOS)
 cargo test  --workspace          # unit + loopback + proptest + C ABI harness
 cargo clippy --workspace --all-targets -- -D warnings
 cargo fmt --all --check
@@ -137,18 +142,27 @@ and the [docs site](https://docs.punktfunk.unom.io).
 crates/
   punktfunk-core/   protocol · FEC · pacing · crypto · QUIC control plane — the C ABI (lib + cdylib + staticlib)
   punktfunk-host/   the host (Linux + Windows): virtual displays · capture · encode · input · GameStream · punktfunk/1 · mgmt
+  pf-client-core/   shared client plumbing (Linux + Windows): session pump · FFmpeg decode · audio · SDL3 gamepads · trust · discovery
+  pf-presenter/     Vulkan session presenter: SDL3 window · ash swapchain · frame present · input capture
+  pf-console-ui/    Skia console UI for the session client: gamepad shell · stats OSD · pairing · on-screen keyboard
+  pf-ffvk/          FFmpeg Vulkan hwcontext bindings (AVVkFrame) for Vulkan Video decode on the presenter's device
+  pf-driver-proto/  host ↔ pf-vdisplay driver contract: control IOCTLs + IDD-push frame transport (no_std)
+  punktfunk-tray/   host tray icon (Windows notification area / Linux StatusNotifierItem)
 clients/
   apple/    macOS / iOS / tvOS app (Swift · VideoToolbox · Metal · GameController)
-  linux/    Linux desktop app (Rust · GTK4/libadwaita · FFmpeg/VAAPI · PipeWire · SDL3)
+  linux/    Linux launcher shell (Rust · relm4 / GTK4 / libadwaita) — spawns the session client to stream
+  session/  punktfunk-session, the Vulkan streaming session (Rust · SDL3 · ash · Skia console UI) — also runs standalone (gamescope, Decky)
   windows/  Windows desktop app (Rust · WinUI 3 · D3D11 · WASAPI · SDL3)
   android/  Android phone + TV app (Kotlin · Rust JNI core · AMediaCodec · AAudio)
   probe/    headless reference / measurement client for punktfunk/1
   decky/    Steam Deck Decky plugin
 web/                         web console (TanStack) over the management API — status · devices · pairing · GPUs · performance · logs
+api/openapi.json             management-API OpenAPI spec (regenerated via `punktfunk-host openapi`, checked in)
 packaging/                   apt · rpm / COPR · Arch · Flatpak · Bazzite bootc image
 docs-site/                   public documentation site (Fumadocs) — https://docs.punktfunk.unom.io
 include/punktfunk_core.h     cbindgen-generated C header (checked in)
 tools/                       latency-probe · loss-harness (measurement)
+ci/                          CI container images (rust-ci · fedora-rpm)
 ```
 
 ## Design invariants

SECURITY.md

@@ -14,7 +14,7 @@ exposes other users before a fix exists.
 
 The more of this you can give us, the faster we can act:
 
-- The component and version (e.g. `punktfunk-host 0.6.0`, Windows or Linux, which client).
+- The component and version (e.g. `punktfunk-host 0.9.0`, Windows or Linux, which client).
 - The impact — what an attacker can do, and from what position (same LAN, a local service account,
   admin, a paired client, …).
 - Steps to reproduce, a proof-of-concept, or a crash/log if you have one.

api/openapi.json

@@ -10,7 +10,7 @@
       "name": "MIT OR Apache-2.0",
       "identifier": "MIT OR Apache-2.0"
     },
-    "version": "0.8.2"
+    "version": "0.9.1"
   },
   "paths": {
     "/api/v1/clients": {
@@ -2517,6 +2517,10 @@
         "type": "object",
         "description": "The user-facing display-management policy — what `display-settings.json` holds and what the mgmt\nAPI GETs/PUTs. When [`preset`](Self::preset) is not [`Preset::Custom`] the explicit fields are\nignored (the console writes one or the other); [`effective`](Self::effective) resolves both to a\nsingle [`EffectivePolicy`].",
         "properties": {
+          "ddc_power_off": {
+            "type": "boolean",
+            "description": "EXPERIMENTAL (Windows): command physical monitors' panels off over DDC/CI (VCP 0xD6 →\nDPMS off) right before an `Exclusive` isolate deactivates them, and back on at restore.\nTargets the \"connected-but-dark head\" periodic-stutter class (monitor standby\nauto-input-scan / DP link churn while the virtual display is the sole active display) at\nthe monitor-firmware level. Best-effort — monitors without DDC/CI (or with it disabled in\nthe OSD) are skipped. Orthogonal to `preset` (like `game_session`): preserved across\npreset changes; `#[serde(default)]` = off so existing `display-settings.json` files are\nuntouched."
+          },
           "game_session": {
             "$ref": "#/components/schemas/GameSession",
             "description": "How a game-launching session is served (`design/gamemode-and-dedicated-sessions.md` §5.2).\nOrthogonal to `preset`/lifecycle — preserved across preset changes; `#[serde(default)]` = `Auto`\nso existing `display-settings.json` files are untouched."
@@ -2539,6 +2543,10 @@
           "mode_conflict": {
             "$ref": "#/components/schemas/ModeConflict"
           },
+          "pnp_disable_monitors": {
+            "type": "boolean",
+            "description": "EXPERIMENTAL (Windows): after an `Exclusive` isolate deactivates the physical monitors,\nadditionally DISABLE their PnP device nodes (persistently, so a standby monitor/TV whose\nhot-plug events re-arrive stays disabled) and re-enable them at restore. Targets the same\n\"connected-but-dark head\" periodic-stutter class as [`Self::ddc_power_off`], but at the\nWindows-reaction level: a disabled devnode's wake events trigger no PnP arrival, no CCD\nre-evaluation, no DWM invalidation. A crash-recovery journal re-enables leftovers on host\nstartup. Orthogonal to `preset` (like `game_session`); `#[serde(default)]` = off."
+          },
           "preset": {
             "$ref": "#/components/schemas/Preset"
           },

ci/fedora-rpm.Dockerfile

@@ -27,6 +27,8 @@ RUN dnf -y install \
       mesa-libGL-devel mesa-libgbm-devel \
       # punktfunk-client link deps (GTK4 shell + SDL3 gamepads)
       gtk4-devel libadwaita-devel SDL3-devel \
+      # pf-ffvk bindgen over libavutil/hwcontext_vulkan.h needs <vulkan/vulkan.h>
+      vulkan-headers \
   && dnf clean all
 
 # bun — both the BUILD tool and the RUNTIME for the punktfunk-web console (`bun run build` -> the

ci/rust-ci.Dockerfile

@@ -22,6 +22,8 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
     libgl-dev libegl-dev libgbm-dev \
     # punktfunk-client-linux (GTK4/libadwaita shell, SDL3 gamepads)
     libgtk-4-dev libadwaita-1-dev libsdl3-dev \
+    # pf-ffvk (bindgen over libavutil/hwcontext_vulkan.h needs <vulkan/vulkan.h>)
+    libvulkan-dev \
     && rm -rf /var/lib/apt/lists/*
 
 # bun — builds the punktfunk-web console in deb.yml (which runs the web build in THIS image).

clients/android/README.md

@@ -58,7 +58,7 @@ kit/              :kit — NativeBridge · native mDNS discovery · Gamepad · K
 `build-tools;37.0.0`, **`cmake;3.22.1`** (builds libopus); **JDK 21** (AGP 9.2 runs on JDK 17–21, not
 a newer default); Rust with `rustup target add aarch64-linux-android armv7-linux-androideabi x86_64-linux-android` and
 `cargo install cargo-ndk`. Toolchain is pinned (AGP 9.2 · Gradle 9.4.1 · Kotlin 2.3.21 · Compose BOM
-2026.05.01 · compileSdk 37 · minSdk 31).
+2026.05.01 · compileSdk 37 · minSdk 28).
 
 **Android Studio:** open `clients/android` — it uses its bundled JBR 21, and the `cargoNdk*` task
 builds the `.so` as part of the normal build.

clients/android/app/build.gradle.kts

@@ -11,7 +11,7 @@ plugins {
 
 android {
     namespace = "io.unom.punktfunk"
-    compileSdk = 37 // Android 17 — required by androidx.core 1.19.0; targetSdk stays 36 for now.
+    compileSdk = 37 // Android 17 — required by androidx.core 1.19.0.
 
     defaultConfig {
         // Load from .env if it exists (local dev), otherwise from System.getenv (CI)
@@ -26,7 +26,11 @@ android {
         // the handful of API 31+ APIs we use are runtime-gated (Material You → brand palette, rumble
         // → legacy Vibrator, NEARBY_WIFI/lights/ADPF already gated), so nothing is lost above 28.
         minSdk = 28
-        targetSdk = 36
+        // Android 17: targeting 37 makes Local Network Protection MANDATORY — all LAN traffic (the
+        // QUIC dial, mDNS, WoL, the library fetch) is blocked until the user grants the
+        // ACCESS_LOCAL_NETWORK runtime permission. ConnectScreen owns that request/rationale flow;
+        // don't bump past 37 without re-checking the next release's behavior changes.
+        targetSdk = 37
         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

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

@@ -19,8 +19,9 @@
          Its absence went unnoticed for weeks because the acquire was wrapped in a silent
          runCatching (now logged). -->
     <uses-permission android:name="android.permission.WAKE_LOCK" />
-    <!-- Enforced from Android 17 (SDK 37) for ALL local-network traffic incl. the QUIC socket.
-         Harmless to declare on earlier releases. -->
+    <!-- Enforced from Android 17 (SDK 37, our targetSdk) for ALL local-network traffic incl. the
+         QUIC socket — a RUNTIME permission (NEARBY_DEVICES group): ConnectScreen requests it on
+         entry and gates every dial/wake on the grant. 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" />

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

@@ -155,6 +155,35 @@ internal fun TrustNewHostDialog(
     )
 }
 
+/**
+ * Android 17+ Local Network Protection rationale: ACCESS_LOCAL_NETWORK was denied, so discovery and
+ * every connect are dead — offer the system prompt again and a settings deep link (a permanently-
+ * denied request returns instantly without ever showing the prompt, so "Allow" alone isn't enough).
+ */
+@Composable
+internal fun LocalNetworkDialog(onAllow: () -> Unit, onSettings: () -> Unit, onDismiss: () -> Unit) {
+    AlertDialog(
+        onDismissRequest = onDismiss,
+        title = { Text("Allow local network access") },
+        text = {
+            Text(
+                "Android blocks punktfunk from talking to devices on your network, so it can't " +
+                    "find or reach any host until you allow it. If no prompt appears when you tap " +
+                    "Allow, enable “Nearby devices” for punktfunk in system settings.",
+            )
+        },
+        confirmButton = {
+            TextButton(onClick = onAllow) { Text("Allow") }
+        },
+        dismissButton = {
+            Row {
+                TextButton(onClick = onSettings) { Text("Open settings") }
+                TextButton(onClick = onDismiss) { Text("Not now") }
+            }
+        },
+    )
+}
+
 /** The pinned fingerprint no longer matches — force re-pairing (never a silent re-trust). */
 @Composable
 internal fun FingerprintChangedDialog(

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

@@ -2,7 +2,9 @@ package io.unom.punktfunk
 
 import android.Manifest
 import android.content.Context
+import android.content.Intent
 import android.content.pm.PackageManager
+import android.net.Uri
 import android.os.Build
 import androidx.activity.compose.rememberLauncherForActivityResult
 import androidx.activity.result.contract.ActivityResultContracts
@@ -30,6 +32,7 @@ import androidx.compose.material3.Icon
 import androidx.compose.material3.MaterialTheme
 import androidx.compose.material3.Surface
 import androidx.compose.material3.Text
+import androidx.compose.material3.TextButton
 import androidx.compose.runtime.Composable
 import androidx.compose.runtime.DisposableEffect
 import androidx.compose.runtime.LaunchedEffect
@@ -37,6 +40,7 @@ import androidx.compose.runtime.getValue
 import androidx.compose.runtime.mutableStateOf
 import androidx.compose.runtime.remember
 import androidx.compose.runtime.rememberCoroutineScope
+import androidx.compose.runtime.rememberUpdatedState
 import androidx.compose.runtime.setValue
 import androidx.compose.ui.Alignment
 import androidx.compose.ui.Modifier
@@ -44,6 +48,9 @@ import androidx.compose.ui.platform.LocalContext
 import androidx.compose.ui.text.style.TextAlign
 import androidx.compose.ui.unit.dp
 import androidx.core.content.ContextCompat
+import androidx.lifecycle.Lifecycle
+import androidx.lifecycle.LifecycleEventObserver
+import androidx.lifecycle.LifecycleOwner
 import io.unom.punktfunk.components.EmptyHostsState
 import io.unom.punktfunk.components.HostCard
 import io.unom.punktfunk.components.SectionLabel
@@ -60,6 +67,7 @@ import io.unom.punktfunk.models.HostStatus
 import io.unom.punktfunk.models.PendingTrust
 import java.util.concurrent.atomic.AtomicBoolean
 import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.delay
 import kotlinx.coroutines.launch
 import kotlinx.coroutines.withContext
 
@@ -111,14 +119,57 @@ fun ConnectScreen(
     // denial used to leave discovery dead forever.
     val discovery = remember { HostDiscovery(context) }
     var discovered by remember { mutableStateOf<List<DiscoveredHost>>(emptyList()) }
+    // Android 17 Local Network Protection: with targetSdk 37, EVERYTHING this screen does — the mDNS
+    // browse, the QUIC dial (UDP 9777), Wake-on-LAN, the library fetch — is blocked until the user
+    // grants ACCESS_LOCAL_NETWORK (a runtime permission in the NEARBY_DEVICES group). Blocked UDP
+    // fails with EPERM, which quinn experiences as a silent handshake timeout — so without this gate
+    // a denial looks exactly like a dead host. Unlike NEARBY_WIFI_DEVICES below, this one is
+    // load-bearing: request it on entry, and surface a denial as an actionable dialog/banner (with a
+    // system-settings deep link) instead of dead-ending on timeouts.
+    var lnpGranted by remember { mutableStateOf(hasLocalNetworkPermission(context)) }
+    var lnpPrompt by remember { mutableStateOf(false) }
+    val localNetLauncher = rememberLauncherForActivityResult(
+        ActivityResultContracts.RequestPermission(),
+    ) { granted ->
+        lnpGranted = granted
+        if (granted) {
+            lnpPrompt = false
+            // The browse started while blocked (its sockets failed or received nothing) — restart it
+            // now that the grant makes them work.
+            discovery.stop()
+            discovery.start()
+        } else {
+            lnpPrompt = true // rationale + "Open settings" (a permanently-denied request returns instantly)
+        }
+    }
     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)) {
+        if (!lnpGranted) {
+            localNetLauncher.launch(Manifest.permission.ACCESS_LOCAL_NETWORK)
+        } else if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU && !hasNearbyPermission(context)) {
+            // The old opportunistic multicast hedge (some OEMs filter multicast without it). On API
+            // 37+ it shares the NEARBY_DEVICES group with ACCESS_LOCAL_NETWORK, so once that is
+            // granted this auto-grants without a second prompt.
             nearbyLauncher.launch(Manifest.permission.NEARBY_WIFI_DEVICES)
         }
     }
+    // Re-check on resume: our dialog deep-links to system settings, and granting there doesn't kill
+    // or otherwise notify the app — this observer is what turns the grant into a live discovery.
+    DisposableEffect(Unit) {
+        val lifecycle = (context as? LifecycleOwner)?.lifecycle
+        val obs = LifecycleEventObserver { _, event ->
+            if (event == Lifecycle.Event.ON_RESUME && !lnpGranted && hasLocalNetworkPermission(context)) {
+                lnpGranted = true
+                lnpPrompt = false
+                discovery.stop()
+                discovery.start()
+            }
+        }
+        lifecycle?.addObserver(obs)
+        onDispose { lifecycle?.removeObserver(obs) }
+    }
     DisposableEffect(Unit) {
         discovery.onChange = { discovered = it }
         discovery.start()
@@ -154,6 +205,29 @@ fun ConnectScreen(
         }
         if (learned) savedHosts = knownHostStore.all()
     }
+    // Saved hosts proven reachable by a QUIC probe this cycle, keyed "address:port" — the
+    // routed-network (Tailscale/VPN) counterpart to mDNS presence, since such hosts never
+    // advertise. OR'd into `isOnline` below so their pips light up. Probe only saved hosts NOT
+    // already seen on mDNS, off the main thread, every ~12 s; gated on LNP (blocked UDP would
+    // just time out). `rememberUpdatedState` keeps the 1 Hz mDNS updates from restarting the loop.
+    var reachable by remember { mutableStateOf<Set<String>>(emptySet()) }
+    val discoveredNow by rememberUpdatedState(discovered)
+    LaunchedEffect(savedHosts, lnpGranted) {
+        if (!lnpGranted) {
+            reachable = emptySet()
+            return@LaunchedEffect
+        }
+        while (true) {
+            val targets = savedHosts.filter { kh -> discoveredNow.none { kh.matches(it) } }
+            reachable = withContext(Dispatchers.IO) {
+                targets
+                    .filter { NativeBridge.nativeProbe(it.address, it.port, 3_000) }
+                    .map { "${it.address}:${it.port}" }
+                    .toSet()
+            }
+            delay(12_000)
+        }
+    }
     // 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) }
@@ -185,8 +259,10 @@ fun ConnectScreen(
 
     // The actual dial (identity already ready). On a TOFU connect (pinHex null), pin the fingerprint
     // the host presented (as an unpaired known host) so the next connect goes straight through and it
-    // appears in the saved-hosts list.
-    fun doConnectDirect(targetHost: String, targetPort: Int, name: String, pinHex: String?) {
+    // appears in the saved-hosts list. [onFailure], when set, takes over a failed dial (the wake-wait
+    // fallback) instead of the error status line — discovery is already restarted when it runs, so
+    // the wait can observe the host reappear.
+    fun doConnectDirect(targetHost: String, targetPort: Int, name: String, pinHex: String?, onFailure: (() -> Unit)? = null) {
         val id = identity ?: run {
             status = "Identity not ready yet — try again in a moment"
             return
@@ -206,18 +282,25 @@ fun ConnectScreen(
                 }
                 onConnected(handle)
             } else {
-                status = "Connection failed — check host/port, PIN, and logcat"
                 discovery.start()
+                if (onFailure != null) {
+                    status = ""
+                    onFailure()
+                } else {
+                    status = "Connection failed — check host/port, PIN, and logcat"
+                }
             }
         }
     }
 
     // Wake-aware connect. If auto-wake is on (Settings.autoWakeEnabled) and the target is a saved
-    // host with a learned MAC that ISN'T currently advertising (asleep/off, or just missing from
-    // mDNS), wake it and WAIT for it to reappear on mDNS (WakeController shows the "Waking…" overlay)
-    // before dialing — discovery stays running meanwhile so we can see it come back. A fire-and-forget
-    // packet + the connect timeout wasn't enough for a cold boot. Otherwise (auto-wake off, no MAC, or
-    // already seen live) dial straight through.
+    // host with a learned MAC that ISN'T currently advertising, fire a wake packet and DIAL
+    // IMMEDIATELY — mDNS absence does NOT mean unreachable (a host reached over a routed network —
+    // Tailscale/VPN/another subnet — is mDNS-blind forever, and gating the dial on presence bricked
+    // exactly those reconnects). A genuinely-asleep box is already booting while the dial times out;
+    // only a FAILED dial falls into the wake-and-WAIT-for-mDNS flow (WakeController's "Waking…"
+    // overlay), which redials once the host reappears. Otherwise (auto-wake off, no MAC, or already
+    // seen live) dial straight through.
     fun doConnect(targetHost: String, targetPort: Int, name: String, pinHex: String?) {
         if (identity == null) {
             status = "Identity not ready yet — try again in a moment"
@@ -232,23 +315,28 @@ fun ConnectScreen(
             if (kh != null) discovered.firstOrNull { kh.matches(it) }
             else discovered.firstOrNull { it.host == targetHost && it.port == targetPort }
         if (settings.autoWakeEnabled && macs.isNotEmpty() && liveAdvert() == null) {
-            waker.start(
-                hostName = name,
-                connectsAfter = true,
-                macs = macs,
-                lastIp = targetHost,
-                isOnline = { liveAdvert() != null },
-                onOnline = {
-                    val live = liveAdvert()
-                    // Woke back on a new address? Re-key the saved record so it (and future connects)
-                    // point at the live one, then dial there.
-                    if (live != null && kh != null && (live.host != kh.address || live.port != kh.port)) {
-                        knownHostStore.update(kh.address, kh.port, kh.copy(address = live.host, port = live.port))
-                        savedHosts = knownHostStore.all()
-                    }
-                    doConnectDirect(live?.host ?: targetHost, live?.port ?: targetPort, name, pinHex)
-                },
-            )
+            // Fire-and-forget first packet (harmless if it's awake), then dial-first.
+            scope.launch(Dispatchers.IO) { NativeBridge.nativeWakeOnLan(macs.joinToString(","), targetHost) }
+            doConnectDirect(targetHost, targetPort, name, pinHex, onFailure = {
+                waker.start(
+                    hostName = name,
+                    connectsAfter = true,
+                    macs = macs,
+                    lastIp = targetHost,
+                    isOnline = { liveAdvert() != null },
+                    onOnline = {
+                        val live = liveAdvert()
+                        // Woke back on a new address? Re-key the saved record so it (and future
+                        // connects) point at the live one, then dial there (no fallback on this
+                        // redial — a second failure surfaces as the plain error).
+                        if (live != null && kh != null && (live.host != kh.address || live.port != kh.port)) {
+                            knownHostStore.update(kh.address, kh.port, kh.copy(address = live.host, port = live.port))
+                            savedHosts = knownHostStore.all()
+                        }
+                        doConnectDirect(live?.host ?: targetHost, live?.port ?: targetPort, name, pinHex)
+                    },
+                )
+            })
         } else {
             doConnectDirect(targetHost, targetPort, name, pinHex)
         }
@@ -311,6 +399,12 @@ fun ConnectScreen(
         dh: DiscoveredHost? = null,
         manualName: String? = null,
     ) {
+        // Every dial/pair path funnels through here — with local network access denied the connect
+        // can only EPERM its way to a 10 s timeout, so ask instead of pretending to try.
+        if (!lnpGranted) {
+            lnpPrompt = true
+            return
+        }
         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
@@ -347,7 +441,7 @@ fun ConnectScreen(
                         title = kh.name,
                         subtitle = "${kh.address}:${kh.port}",
                         filled = true,
-                        online = discovered.any { it.host == kh.address && it.port == kh.port },
+                        online = kh.isOnline(discovered, reachable),
                         paired = kh.paired,
                         knownHost = kh,
                         activate = { connect(kh.address, kh.port) },
@@ -384,7 +478,8 @@ fun ConnectScreen(
             // handle — the touch grid guards the same way with enabled=!connecting), or while the whole
             // console home is cross-fading out.
             navActive = navGate && !connecting && !showManualSheet && pendingTrust == null &&
-                awaiting == null && editTarget == null && optionsTarget == null && waker.waking == null,
+                awaiting == null && editTarget == null && optionsTarget == null &&
+                waker.waking == null && !lnpPrompt,
             onActivate = { it.activate() },
             onOpenLibrary = { it.knownHost?.let(onOpenLibrary) },
             onOpenSettings = onOpenSettings,
@@ -451,6 +546,38 @@ fun ConnectScreen(
                 }
             }
 
+            if (!lnpGranted) {
+                // Local network access denied: discovery can't ever find anything and every connect
+                // would time out — say so at the top, with the fix one tap away, instead of letting
+                // the screen look idle/broken.
+                item(span = { GridItemSpan(maxLineSpan) }) {
+                    Surface(
+                        color = MaterialTheme.colorScheme.errorContainer,
+                        shape = MaterialTheme.shapes.medium,
+                        modifier = Modifier.fillMaxWidth(),
+                    ) {
+                        Column(
+                            Modifier.padding(horizontal = 16.dp, vertical = 12.dp),
+                            horizontalAlignment = Alignment.CenterHorizontally,
+                        ) {
+                            Text(
+                                "Local network access is off",
+                                style = MaterialTheme.typography.titleSmall,
+                                color = MaterialTheme.colorScheme.onErrorContainer,
+                            )
+                            Text(
+                                "Android blocks punktfunk from finding or reaching hosts until you allow it.",
+                                style = MaterialTheme.typography.bodyMedium,
+                                color = MaterialTheme.colorScheme.onErrorContainer,
+                                textAlign = TextAlign.Center,
+                            )
+                            TextButton(onClick = { lnpPrompt = true }) { Text("Allow…") }
+                        }
+                    }
+                    Spacer(Modifier.height(12.dp))
+                }
+            }
+
             if (savedHosts.isEmpty() && discoveredUnsaved.isEmpty()) {
                 item(span = { GridItemSpan(maxLineSpan) }) {
                     EmptyHostsState()
@@ -466,6 +593,7 @@ fun ConnectScreen(
                         name = kh.name,
                         address = "${kh.address}:${kh.port}",
                         status = if (kh.paired) HostStatus.PAIRED else HostStatus.TOFU,
+                        online = kh.isOnline(discovered, reachable),
                         enabled = !connecting,
                         onConnect = { connect(kh.address, kh.port) },
                         onForget = {
@@ -477,16 +605,21 @@ fun ConnectScreen(
                         // through the WakeController so it shows the "Waking…" overlay and waits for
                         // the host to come online (matched by fingerprint, so a new DHCP address on a
                         // cold boot still counts as "up") rather than firing a single silent packet.
-                        onWake = if (kh.mac.isNotEmpty() && discovered.none { kh.matches(it) }) {
+                        onWake = if (kh.mac.isNotEmpty() && !kh.isOnline(discovered, reachable)) {
                             {
-                                waker.start(
-                                    hostName = kh.name,
-                                    connectsAfter = false,
-                                    macs = kh.mac,
-                                    lastIp = kh.address,
-                                    isOnline = { discovered.any { kh.matches(it) } },
-                                    onOnline = {},
-                                )
+                                // The magic packet is UDP broadcast — LNP-blocked like everything else.
+                                if (!lnpGranted) {
+                                    lnpPrompt = true
+                                } else {
+                                    waker.start(
+                                        hostName = kh.name,
+                                        connectsAfter = false,
+                                        macs = kh.mac,
+                                        lastIp = kh.address,
+                                        isOnline = { discovered.any { kh.matches(it) } },
+                                        onOnline = {},
+                                    )
+                                }
                             }
                         } else {
                             null
@@ -505,6 +638,7 @@ fun ConnectScreen(
                         name = dh.name,
                         address = "${dh.host}:${dh.port}",
                         status = if (dh.pairingRequired) HostStatus.PAIRING else HostStatus.TOFU,
+                        online = true, // in the discovered list ⇒ live on mDNS right now
                         enabled = !connecting,
                         onConnect = { connect(dh.host, dh.port, dh) },
                         onForget = null,
@@ -514,8 +648,10 @@ fun ConnectScreen(
 
             // 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()) {
+            // rather than looking idle/empty. Suppressed while local network access is denied —
+            // a spinner would be a lie there (the browse can't receive anything); the banner above
+            // owns that state.
+            if (lnpGranted && !connecting && discovered.isEmpty()) {
                 item(span = { GridItemSpan(maxLineSpan) }) {
                     Row(
                         modifier = Modifier.fillMaxWidth().padding(vertical = 12.dp),
@@ -615,17 +751,22 @@ fun ConnectScreen(
 
     // Console host options (Up on a saved carousel tile): Wake / Edit / Forget.
     optionsTarget?.let { kh ->
-        val offline = discovered.none { kh.matches(it) }
+        val offline = !kh.isOnline(discovered, reachable)
         GamepadHostOptionsDialog(
             hostName = kh.name,
             canWake = kh.mac.isNotEmpty() && offline,
             onWake = {
                 optionsTarget = null
-                waker.start(
-                    hostName = kh.name, connectsAfter = false, macs = kh.mac, lastIp = kh.address,
-                    isOnline = { discovered.any { kh.matches(it) } },
-                    onOnline = {},
-                )
+                // The magic packet is UDP broadcast — LNP-blocked like everything else.
+                if (!lnpGranted) {
+                    lnpPrompt = true
+                } else {
+                    waker.start(
+                        hostName = kh.name, connectsAfter = false, macs = kh.mac, lastIp = kh.address,
+                        isOnline = { discovered.any { kh.matches(it) } },
+                        onOnline = {},
+                    )
+                }
             },
             // A saved host always has a library (it's a knownHost) → offer it when the setting's on,
             // so a TV remote reaches the library here instead of via the Y face button.
@@ -673,6 +814,29 @@ fun ConnectScreen(
         }
     }
 
+    if (lnpPrompt) {
+        // Android 17+ local-network-permission rationale: re-request (a permanently-denied request
+        // returns instantly without a system prompt — hence the settings deep link alongside).
+        val onAllow = {
+            lnpPrompt = false
+            localNetLauncher.launch(Manifest.permission.ACCESS_LOCAL_NETWORK)
+        }
+        val onSettings = {
+            lnpPrompt = false
+            context.startActivity(
+                Intent(
+                    android.provider.Settings.ACTION_APPLICATION_DETAILS_SETTINGS,
+                    Uri.fromParts("package", context.packageName, null),
+                ),
+            )
+        }
+        if (gamepadUi) {
+            GamepadLocalNetworkDialog(onAllow = onAllow, onSettings = onSettings, onDismiss = { lnpPrompt = false })
+        } else {
+            LocalNetworkDialog(onAllow = onAllow, onSettings = onSettings, onDismiss = { lnpPrompt = false })
+        }
+    }
+
     // Topmost: the "Waking…" overlay rides over both the touch grid and the console home.
     WakeOverlay(waker, gamepadUi)
 }
@@ -687,6 +851,18 @@ fun hasNearbyPermission(context: Context): Boolean =
         ContextCompat.checkSelfPermission(context, Manifest.permission.NEARBY_WIFI_DEVICES) ==
         PackageManager.PERMISSION_GRANTED
 
+/**
+ * Whether ACCESS_LOCAL_NETWORK is held (API 37+; below, the permission doesn't exist and local
+ * network access is implicit). Android 17's Local Network Protection blocks ALL local-network
+ * traffic for apps targeting SDK 37 without this runtime grant: UDP sends fail with EPERM, so the
+ * QUIC dial surfaces as a silent handshake timeout and the mDNS browse receives nothing. Unlike
+ * [hasNearbyPermission] this is load-bearing — nothing on the connect screen works without it.
+ */
+fun hasLocalNetworkPermission(context: Context): Boolean =
+    Build.VERSION.SDK_INT < Build.VERSION_CODES.CINNAMON_BUN ||
+        ContextCompat.checkSelfPermission(context, Manifest.permission.ACCESS_LOCAL_NETWORK) ==
+        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.
@@ -697,3 +873,11 @@ private fun KnownHost.matches(dh: DiscoveredHost): Boolean {
     if (!advFp.isNullOrEmpty() && fpHex.isNotEmpty() && fpHex.lowercase() == advFp) return true
     return address == dh.host && port == dh.port
 }
+
+/**
+ * True when a saved host is reachable RIGHT NOW: advertising on mDNS OR answering the QUIC probe
+ * (a host reached over a routed network — Tailscale/VPN — never advertises but is reachable). The
+ * display-side companion to dial-first: presence no longer means "on this LAN".
+ */
+private fun KnownHost.isOnline(discovered: List<DiscoveredHost>, reachable: Set<String>): Boolean =
+    discovered.any { matches(it) } || reachable.contains("$address:$port")

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

@@ -229,6 +229,29 @@ fun GamepadHostOptionsDialog(
     }
 }
 
+/** Console counterpart of [LocalNetworkDialog] — the Android 17+ ACCESS_LOCAL_NETWORK rationale. */
+@Composable
+fun GamepadLocalNetworkDialog(onAllow: () -> Unit, onSettings: () -> Unit, onDismiss: () -> Unit) {
+    GamepadDialog(
+        title = "Allow local network access",
+        onDismiss = onDismiss,
+        actions = listOf(
+            DialogAction("Allow", primary = true, onClick = onAllow),
+            DialogAction("Open settings", onClick = onSettings),
+            DialogAction("Not now", onClick = onDismiss),
+        ),
+    ) {
+        DialogText(
+            "Android blocks punktfunk from talking to devices on your network, so it can't find " +
+                "or reach any host until you allow it.",
+        )
+        DialogText(
+            "If no prompt appears after Allow, enable “Nearby devices” for punktfunk in " +
+                "system settings.",
+        )
+    }
+}
+
 @Composable
 fun GamepadTrustNewDialog(pt: PendingTrust, onTrust: () -> Unit, onPairInstead: () -> Unit, onDismiss: () -> Unit) {
     GamepadDialog(

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

@@ -297,8 +297,17 @@ private fun buildSettingsRows(s: Settings, update: (Settings) -> Unit): List<GpR
     return listOf(
         choice(
             "resolution", "Stream", "Resolution",
-            "The host creates a virtual display at exactly this size — no scaling.",
-            RESOLUTION_OPTIONS.map { (w, h, lbl) -> (w to h) to lbl }, s.width to s.height,
+            "The host creates a virtual display at exactly this size — no scaling. " +
+                "Custom sizes are typed in the touch settings.",
+            // A custom size (typed in the touch settings) leads the list so it stays visible and
+            // selectable here instead of being silently snapped to Native — a pad can keep a
+            // custom size, it just can't type one.
+            (if (s.isCustomResolution()) {
+                listOf((s.width to s.height) to "Custom · ${s.width} × ${s.height}")
+            } else {
+                emptyList()
+            }) + RESOLUTION_OPTIONS.map { (w, h, lbl) -> (w to h) to lbl },
+            s.width to s.height,
         ) { (w, h) -> update(s.copy(width = w, height = h)) },
         choice(
             "refresh", null, "Refresh rate", "Frame rate the host renders and streams at.",
@@ -327,7 +336,7 @@ private fun buildSettingsRows(s: Settings, update: (Settings) -> Unit): List<GpR
         ) { update(s.copy(hdrEnabled = it)) },
         toggle(
             "lowLatency", null, "Low-latency mode",
-            "Experimental — aggressive decoder and system tuning. Turn off if the stream stutters or glitches.",
+            "The fast pipeline (async decode + system tuning). On by default — turn off to fall back if the stream stutters or glitches.",
             s.lowLatencyMode,
         ) { update(s.copy(lowLatencyMode = it)) },
 
@@ -346,11 +355,12 @@ private fun buildSettingsRows(s: Settings, update: (Settings) -> Unit): List<GpR
             GAMEPAD_OPTIONS.mapIndexed { i, lbl -> i to lbl }, s.gamepad,
         ) { update(s.copy(gamepad = it)) },
 
-        toggle(
+        choice(
             "hud", "Interface", "Statistics overlay",
-            "Show FPS, throughput and latency while streaming.",
-            s.statsHudEnabled,
-        ) { update(s.copy(statsHudEnabled = it)) },
+            "How much the overlay shows: Compact (one line) → Normal → Detailed (full HUD). " +
+                "A 3-finger tap cycles the tiers live.",
+            STATS_VERBOSITY_OPTIONS, s.statsVerbosity,
+        ) { update(s.copy(statsVerbosity = it)) },
         toggle(
             "library", null, "Game library",
             "Browse a paired host's games with Y (experimental).",

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

@@ -3,6 +3,7 @@ package io.unom.punktfunk
 import android.content.Context
 import io.unom.punktfunk.kit.Gamepad
 import io.unom.punktfunk.kit.NativeBridge
+import io.unom.punktfunk.kit.VideoDecoders
 import io.unom.punktfunk.kit.security.ClientIdentity
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.withContext
@@ -41,7 +42,10 @@ suspend fun connectToHost(
             host, port, w, h, hz,
             identity.certPem, identity.privateKeyPem, pinHex,
             settings.bitrateKbps, settings.compositor, gamepadPref,
-            hdrEnabled, settings.audioChannels, settings.preferredCodec(), timeoutMs,
+            hdrEnabled, settings.audioChannels,
+            // What this device can decode (H.264|HEVC always, AV1 when a real decoder exists) +
+            // the user's soft codec preference — the host resolves the emitted codec from both.
+            VideoDecoders.decodableCodecBits(), settings.preferredCodec(), timeoutMs,
             launch,
         )
     }

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

@@ -26,12 +26,18 @@ data class Settings(
     /** Requested audio channel count: 2 (stereo), 6 (5.1) or 8 (7.1). The host clamps to what it
      * can capture; the resolved count drives the decoder + AAudio layout. */
     val audioChannels: Int = 2,
-    /** Preferred video codec: `"auto"` (host decides), `"hevc"`, or `"h264"`. A soft preference — the
-     * host emits it when it can, else falls back. AMediaCodec decodes whichever the host resolves. */
+    /** Preferred video codec: `"auto"` (host decides), `"hevc"`, `"h264"`, or `"av1"`. A soft
+     * preference — the host emits it when it can, else falls back. AMediaCodec decodes whichever
+     * the host resolves (AV1 is only advertised/offered when the device has a real AV1 decoder). */
     val codec: String = "auto",
     val micEnabled: Boolean = false,
-    /** Show the live stats overlay (FPS / throughput / latency) during a stream. */
-    val statsHudEnabled: Boolean = true,
+    /**
+     * How much the in-stream stats overlay shows — see [StatsVerbosity]. Defaults to
+     * [StatsVerbosity.NORMAL] (the res/fps line + latency headline + reliability counters); the full
+     * decoder/feed/equation HUD is [StatsVerbosity.DETAILED], and a single terse line is
+     * [StatsVerbosity.COMPACT]. A 3-finger tap cycles through the tiers live.
+     */
+    val statsVerbosity: StatsVerbosity = StatsVerbosity.NORMAL,
     /**
      * Touch input model — how touchscreen fingers drive the host. [TouchMode.TRACKPAD] (default):
      * the cursor stays put on touch-down and moves by the finger's relative delta (swipe to nudge,
@@ -55,14 +61,18 @@ data class Settings(
      */
     val libraryEnabled: Boolean = true,
     /**
-     * "Low-latency mode (experimental)" — the master switch over the latency overhaul: decoder
-     * ranking + per-SoC vendor keys + the async decode loop (native), pipeline thread boosts + ADPF
-     * max-performance, game-tagged AAudio, DSCP marking on the media sockets, HDMI ALLM, and the
-     * forced TV mode switch. (The Wi-Fi locks are NOT part of this — both are always held while
-     * streaming; see StreamScreen.) Off (default): the original decode pipeline, kept as the
-     * known-good baseline until the aggressive stack is proven per-device.
+     * "Low-latency mode" — the master switch over the latency pipeline: the async decode loop
+     * (native; burst-feed + present-newest-per-vsync, the Apple client's discipline), decoder ranking
+     * + per-SoC vendor keys, pipeline thread boosts + ADPF max-performance, game-tagged AAudio, DSCP
+     * marking on the media sockets, HDMI ALLM, and the forced TV mode switch. (The Wi-Fi locks are NOT
+     * part of this — both are always held while streaming; see StreamScreen.) On (default): the fast
+     * pipeline. Off restores the original synchronous decode loop byte-for-byte, kept as a per-device
+     * escape hatch. Promoted to default once the receive-side latency ratchet the overhaul interacted
+     * badly with was fixed in the shared core — the pump now jumps to live on a standing backlog
+     * instead of accumulating it (see `punktfunk-core` `FrameChannel`), so the async loop no longer
+     * feeds a queue that only grows.
      */
-    val lowLatencyMode: Boolean = false,
+    val lowLatencyMode: Boolean = true,
     /**
      * Wake-on-LAN a saved host before connecting when it isn't currently seen on mDNS. On (default):
      * a connect to a host with a learned MAC that isn't advertising sends a magic packet and waits
@@ -77,6 +87,27 @@ data class Settings(
 /** [Settings.touchMode] values; persisted by name. */
 enum class TouchMode { TRACKPAD, POINTER, TOUCH }
 
+/**
+ * Stats-overlay detail tiers, in cycling order (persisted by name). Each tier is a strict superset
+ * of the previous one, so toning down never hides a number a lower tier keeps:
+ * - [OFF] — no overlay (and native sampling is gated off, one atomic load per frame).
+ * - [COMPACT] — one line: `fps · end-to-end ms · Mb/s` (+ a loss flag when frames drop).
+ * - [NORMAL] — adds the resolution/refresh line, the end-to-end p50/p95 headline, and the
+ *   reliability counters (lost / skipped / FEC) when nonzero. The default.
+ * - [DETAILED] — the full HUD: also the decoder label, the video-feed descriptor, and the
+ *   `host+network + decode` stage equation.
+ * A 3-finger tap in-stream cycles Off → Compact → Normal → Detailed → Off (see [next]).
+ */
+enum class StatsVerbosity(val label: String) {
+    OFF("Off"),
+    COMPACT("Compact"),
+    NORMAL("Normal"),
+    DETAILED("Detailed");
+
+    /** The next tier for the live 3-finger-tap cycle (wraps Detailed → Off). */
+    fun next(): StatsVerbosity = entries[(ordinal + 1) % entries.size]
+}
+
 /** Loads/saves [Settings] in the app-private `punktfunk_settings` prefs. */
 class SettingsStore(context: Context) {
     private val prefs =
@@ -93,14 +124,23 @@ class SettingsStore(context: Context) {
         audioChannels = prefs.getInt(K_AUDIO_CH, 2),
         codec = prefs.getString(K_CODEC, "auto") ?: "auto",
         micEnabled = prefs.getBoolean(K_MIC, false),
-        statsHudEnabled = prefs.getBoolean(K_HUD, true),
+        statsVerbosity = prefs.getString(K_STATS_VERBOSITY, null)
+            ?.let { name -> StatsVerbosity.entries.firstOrNull { it.name == name } }
+            // Migration from the pre-tier Boolean "stats_hud_enabled": an explicit OFF stays off;
+            // everyone else (incl. fresh installs) lands on NORMAL — the old always-full HUD toned
+            // down to the new default, which is the whole point of adding tiers.
+            ?: if (prefs.contains(K_HUD) && !prefs.getBoolean(K_HUD, true)) {
+                StatsVerbosity.OFF
+            } else {
+                StatsVerbosity.NORMAL
+            },
         touchMode = prefs.getString(K_TOUCH_MODE, null)
             ?.let { name -> TouchMode.entries.firstOrNull { it.name == name } }
             // Migration: the pre-enum Boolean "trackpad_mode" (true = trackpad, false = direct).
             ?: if (prefs.getBoolean(K_TRACKPAD, true)) TouchMode.TRACKPAD else TouchMode.POINTER,
         gamepadUiEnabled = prefs.getBoolean(K_GAMEPAD_UI, true),
         libraryEnabled = prefs.getBoolean(K_LIBRARY, true),
-        lowLatencyMode = prefs.getBoolean(K_LOW_LATENCY, false),
+        lowLatencyMode = prefs.getBoolean(K_LOW_LATENCY, true),
         autoWakeEnabled = prefs.getBoolean(K_AUTO_WAKE, true),
     )
 
@@ -116,7 +156,7 @@ class SettingsStore(context: Context) {
             .putInt(K_AUDIO_CH, s.audioChannels)
             .putString(K_CODEC, s.codec)
             .putBoolean(K_MIC, s.micEnabled)
-            .putBoolean(K_HUD, s.statsHudEnabled)
+            .putString(K_STATS_VERBOSITY, s.statsVerbosity.name)
             .putString(K_TOUCH_MODE, s.touchMode.name)
             .putBoolean(K_GAMEPAD_UI, s.gamepadUiEnabled)
             .putBoolean(K_LIBRARY, s.libraryEnabled)
@@ -136,18 +176,26 @@ class SettingsStore(context: Context) {
         const val K_AUDIO_CH = "audio_channels"
         const val K_CODEC = "codec"
         const val K_MIC = "mic_enabled"
+        const val K_STATS_VERBOSITY = "stats_verbosity"
+
+        /** Pre-tier Boolean the [K_STATS_VERBOSITY] enum replaced — read once for migration, never
+         * written. */
         const val K_HUD = "stats_hud_enabled"
         const val K_TOUCH_MODE = "touch_mode"
         const val K_GAMEPAD_UI = "gamepad_ui_enabled"
         const val K_LIBRARY = "library_enabled"
 
         /**
-         * Deliberately NOT the original `"low_latency_mode"` key: that one shipped default-ON, so
-         * any install that ever saved settings persisted `true` — under the old key, flipping the
-         * default to off would leave exactly the regressed devices stuck on the overhaul. The fresh
-         * key restarts everyone at the safe default; the stale one is abandoned unread.
+         * Bumped AGAIN to restart every install at the new default (ON). History: the original
+         * `"low_latency_mode"` shipped default-ON; `"low_latency_mode_experimental"` restarted
+         * everyone at OFF after the overhaul regressed on some phones. That regression was the
+         * receive-side latency ratchet the async loop fed (a standing queue that only grew) — now
+         * fixed in the shared core (`punktfunk-core` `FrameChannel`: the pump jumps to live on a
+         * standing backlog instead of accumulating it), so the fast pipeline is the default again. A
+         * fresh key re-defaults every install — including ones persisted OFF under the old key — to
+         * on; both stale keys are abandoned unread. The toggle stays as a per-device escape hatch.
          */
-        const val K_LOW_LATENCY = "low_latency_mode_experimental"
+        const val K_LOW_LATENCY = "low_latency_mode_v2"
         const val K_AUTO_WAKE = "auto_wake_enabled"
 
         /** Legacy Boolean the enum replaced — read once as the migration default, never written. */
@@ -205,6 +253,12 @@ val RESOLUTION_OPTIONS = listOf(
     Triple(3840, 2160, "3840 × 2160"),
 )
 
+/** True when the stored size is none of the [RESOLUTION_OPTIONS] presets — a custom resolution
+ * typed in the touch settings. Detected from the size itself rather than a persisted flag, so it
+ * can never disagree with what's actually stored (mirrors the Apple client). */
+fun Settings.isCustomResolution(): Boolean =
+    RESOLUTION_OPTIONS.none { (w, h, _) -> w == width && h == height }
+
 /** (hz, label). `0` = native refresh. */
 val REFRESH_OPTIONS = listOf(
     0 to "Native",
@@ -224,14 +278,17 @@ val AUDIO_CHANNEL_OPTIONS = listOf(
     8 to "7.1 Surround",
 )
 
-/** (stored value, label) for the preferred video codec. `"auto"` = host decides. */
+/** (stored value, label) for the preferred video codec. `"auto"` = host decides. The `"av1"` row
+ * only makes sense on a device with a real AV1 decoder — SettingsScreen filters it out otherwise. */
 val CODEC_OPTIONS = listOf(
     "auto" to "Automatic",
     "hevc" to "HEVC (H.265)",
     "h264" to "H.264 (AVC)",
+    "av1" to "AV1",
 )
 
-/** The [Settings.codec] string as a `quic::CODEC_*` preference byte (`0` = auto). H264=1, HEVC=2. */
+/** The [Settings.codec] string as a `quic::CODEC_*` preference byte (`0` = auto). H264=1, HEVC=2,
+ * AV1=4. */
 fun Settings.preferredCodec(): Int = when (codec) {
     "h264" -> 1
     "hevc" -> 2
@@ -261,6 +318,9 @@ val COMPOSITOR_OPTIONS = listOf(
     "gamescope",
 )
 
+/** (verbosity, label) for the stats-overlay detail picker. Order = the live 3-finger-tap cycle. */
+val STATS_VERBOSITY_OPTIONS = StatsVerbosity.entries.map { it to it.label }
+
 /** (mode, label) for the touch-input model. */
 val TOUCH_MODE_OPTIONS = listOf(
     TouchMode.TRACKPAD to "Trackpad",

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

@@ -28,6 +28,7 @@ import androidx.compose.foundation.layout.size
 import androidx.compose.foundation.layout.width
 import androidx.compose.foundation.rememberScrollState
 import androidx.compose.foundation.shape.RoundedCornerShape
+import androidx.compose.foundation.text.KeyboardOptions
 import androidx.compose.foundation.verticalScroll
 import androidx.compose.material.icons.Icons
 import androidx.compose.material.icons.automirrored.filled.ArrowBack
@@ -60,11 +61,14 @@ 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.graphics.Color
 import androidx.compose.ui.graphics.vector.ImageVector
 import androidx.compose.ui.platform.LocalContext
+import androidx.compose.ui.text.input.KeyboardType
 import androidx.compose.ui.unit.dp
 import androidx.core.content.ContextCompat
+import io.unom.punktfunk.kit.VideoDecoders
 
 /**
  * Stream settings, organised as an iOS-Settings / Android-system-settings style list of category
@@ -283,12 +287,40 @@ private fun CategoryDetail(
 @Composable
 private fun DisplaySettings(s: Settings, update: (Settings) -> Unit, context: android.content.Context) {
     val (nw, nh, nhz) = nativeDisplayMode(context)
+    // "Custom…" picked while the stored size is still a preset — keeps the size fields visible
+    // until an edit actually makes it custom (or a preset is re-picked). Custom itself is detected
+    // from the stored size, never flagged (see [isCustomResolution]), so nothing new persists.
+    var customPicked by remember { mutableStateOf(false) }
+    val showCustom = customPicked || s.isCustomResolution()
     SettingsCard {
         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)) }
+            options = RESOLUTION_OPTIONS.map { (w, h, lbl) -> (w to h) to (if (w == 0) "$lbl ($nw × $nh)" else lbl) } +
+                // The (-1, -1) sentinel can't collide with a real size; once a custom size is
+                // stored its label carries the live value, like the native row carries ($nw × $nh).
+                ((-1 to -1) to if (s.isCustomResolution()) "Custom (${s.width} × ${s.height})" else "Custom…"),
+            selected = if (showCustom) -1 to -1 else s.width to s.height,
+        ) { (w, h) ->
+            if (w < 0) {
+                // Seed from the current *effective* size so the fields start from something
+                // sensible (the resolved native mode, not the 0 × 0 placeholder).
+                customPicked = true
+                update(s.copy(width = if (s.width > 0) s.width else nw, height = if (s.height > 0) s.height else nh))
+            } else {
+                customPicked = false
+                update(s.copy(width = w, height = h))
+            }
+        }
+        if (showCustom) {
+            Row(horizontalArrangement = Arrangement.spacedBy(12.dp)) {
+                ResolutionField(label = "Width", value = s.width, modifier = Modifier.weight(1f)) { w ->
+                    update(s.copy(width = w))
+                }
+                ResolutionField(label = "Height", value = s.height, modifier = Modifier.weight(1f)) { h ->
+                    update(s.copy(height = h))
+                }
+            }
+        }
 
         SettingDropdown(
             label = "Refresh rate",
@@ -300,7 +332,12 @@ private fun DisplaySettings(s: Settings, update: (Settings) -> Unit, context: an
             update(s.copy(bitrateKbps = kbps))
         }
 
-        SettingDropdown(label = "Video codec", options = CODEC_OPTIONS, selected = s.codec) { c ->
+        // AV1 is only offered when the device has a real AV1 decoder (it's never advertised to the
+        // host otherwise, so preferring it would be a dead setting). A stored "av1" from a capable
+        // device stays visible so the selection is always representable.
+        val av1Capable = remember { VideoDecoders.pickDecoder("video/av01") != null }
+        val codecOptions = CODEC_OPTIONS.filter { (v, _) -> v != "av1" || av1Capable || s.codec == "av1" }
+        SettingDropdown(label = "Video codec", options = codecOptions, selected = s.codec) { c ->
             update(s.copy(codec = c))
         }
 
@@ -326,10 +363,10 @@ private fun DisplaySettings(s: Settings, update: (Settings) -> Unit, context: an
         ) { c -> update(s.copy(compositor = c)) }
 
         ToggleRow(
-            title = "Low-latency mode (experimental)",
-            subtitle = "Aggressive decoder and system tuning (per-device decoder selection, async " +
-                "decode, HDMI game mode). Can lower latency, but may stutter or glitch on " +
-                "some devices — turn off if the stream misbehaves.",
+            title = "Low-latency mode",
+            subtitle = "The fast pipeline (async decode, per-device decoder selection, HDMI game " +
+                "mode). On by default — turn off to fall back to the plain decode path if the stream " +
+                "stutters or glitches on this device.",
             checked = s.lowLatencyMode,
             onCheckedChange = { on -> update(s.copy(lowLatencyMode = on)) },
         )
@@ -403,11 +440,17 @@ private fun InterfaceSettings(s: Settings, update: (Settings) -> Unit) {
             checked = s.autoWakeEnabled,
             onCheckedChange = { on -> update(s.copy(autoWakeEnabled = on)) },
         )
-        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)) },
+        SettingDropdown(
+            label = "Stats overlay",
+            options = STATS_VERBOSITY_OPTIONS,
+            selected = s.statsVerbosity,
+        ) { v -> update(s.copy(statsVerbosity = v)) }
+        Text(
+            "How much the in-stream overlay shows: Compact is a single fps · latency · bitrate " +
+                "line; Normal adds the resolution and reliability lines; Detailed adds the decoder, " +
+                "colour and latency-breakdown lines. A 3-finger tap cycles the tiers live.",
+            style = MaterialTheme.typography.bodySmall,
+            color = MaterialTheme.colorScheme.onSurfaceVariant,
         )
     }
 }
@@ -523,3 +566,30 @@ private fun <T> SettingDropdown(
         }
     }
 }
+
+/** One side of a custom resolution. Digits only; every usable keystroke commits — coerced even
+ * (encoders reject odd dimensions) and capped at 8192, the HEVC/AV1 per-side ceiling (the host
+ * clamps H.264's tighter 4096 itself) — while the field keeps the raw text so intermediate states
+ * ("15" on the way to "1512") aren't rewritten mid-typing; it snaps to the committed value when
+ * focus leaves. */
+@Composable
+private fun ResolutionField(
+    label: String,
+    value: Int,
+    modifier: Modifier = Modifier,
+    onCommit: (Int) -> Unit,
+) {
+    var text by remember { mutableStateOf(if (value > 0) value.toString() else "") }
+    OutlinedTextField(
+        value = text,
+        onValueChange = { raw ->
+            text = raw.filter { it.isDigit() }.take(4)
+            val v = (text.toIntOrNull() ?: 0).let { it - it % 2 }.coerceAtMost(8192)
+            if (v > 0) onCommit(v)
+        },
+        label = { Text(label) },
+        singleLine = true,
+        keyboardOptions = KeyboardOptions(keyboardType = KeyboardType.Number),
+        modifier = modifier.onFocusChanged { if (!it.isFocused) text = if (value > 0) value.toString() else "" },
+    )
+}

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

@@ -15,89 +15,141 @@ import io.unom.punktfunk.kit.NativeBridge
 import kotlin.math.roundToInt
 
 /**
- * The live stats overlay — the unified HUD (`design/stats-unification.md`, Android v1: headline is
- * `capture→decoded`, tiled by `host+network` + `decode`). Reads the 18-double layout from
- * [NativeBridge.nativeVideoStats]:
- * `[fps, mbps, e2eP50Ms, e2eP95Ms, latValid, skew, w, h, hz, lost, bitDepth, colorPrimaries,
- * colorTransfer, chromaFormatIdc, hostNetP50Ms, decodeP50Ms, hostP50Ms, netP50Ms]`. Indexes 10–13
- * (present on a current native lib) describe the negotiated video feed and render as a
- * codec/depth/colour/chroma line; 14/15 render as the stage equation — split into
- * `host + network + decode` when the Phase-2 terms at 16/17 are nonzero (a current host sends
- * per-AU 0xCF timings; an old host leaves them 0 and the combined `host+network` term stands);
- * older layouts just omit those lines.
+ * The live stats overlay — the unified HUD (`design/stats-unification.md`): headline is
+ * `capture→displayed` tiled by `host+network` + `decode` + `display` when the platform delivered
+ * OnFrameRendered render callbacks this window (`dispValid`), falling back to the v1
+ * `capture→decoded` headline without the `display` term when it didn't. Reads the 26-double
+ * layout from [NativeBridge.nativeVideoStats]:
+ * `[fps, mbps, e2eP50Ms, e2eP95Ms, latValid, skew, w, h, hz, lostTotal, bitDepth, colorPrimaries,
+ * colorTransfer, chromaFormatIdc, hostNetP50Ms, decodeP50Ms, hostP50Ms, netP50Ms, lost, skipped,
+ * fec, frames, dispValid, displayP50Ms, e2eDispP50Ms, e2eDispP95Ms]`.
+ *
+ * [verbosity] selects how many lines render (each tier a superset of the last — see
+ * [StatsVerbosity]):
+ * - [StatsVerbosity.COMPACT] — one line, `fps · end-to-end ms · Mb/s` (+ a loss flag).
+ * - [StatsVerbosity.NORMAL] — the res/fps/Mb·s line, the end-to-end p50/p95 headline, and the
+ *   reliability counters (18–21) when nonzero.
+ * - [StatsVerbosity.DETAILED] — also the decoder label, the video-feed descriptor (10–13), and the
+ *   stage equation (14/15, split into `host + network` when the Phase-2 terms at 16/17 are nonzero).
+ * [StatsVerbosity.OFF] renders nothing. Older native layouts simply omit the lines they lack (the
+ * counter line falls back to the cumulative `lostTotal` at index 9 on a pre-window lib).
  */
 @Composable
-internal fun StatsOverlay(s: DoubleArray, decoderLabel: String = "", modifier: Modifier = Modifier) {
-    if (s.size < 10) return
+internal fun StatsOverlay(
+    s: DoubleArray,
+    verbosity: StatsVerbosity,
+    decoderLabel: String = "",
+    modifier: Modifier = Modifier,
+) {
+    if (verbosity == StatsVerbosity.OFF || s.size < 10) return
     val w = s[6].toInt()
     val h = s[7].toInt()
     val hz = s[8].toInt()
     val latValid = s[4] != 0.0
     val skew = s[5] != 0.0
     val lost = s[9].toLong()
+    val detailed = verbosity == StatsVerbosity.DETAILED
+
     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 (decoderLabel.isNotEmpty()) {
-            Text(
-                decoderLabel,
-                color = Color(0xFFB0D0FF),
-                fontFamily = FontFamily.Monospace,
-                fontSize = 12.sp,
-            )
+        // Compact: everything the glance-value needs on one line, nothing else.
+        if (verbosity == StatsVerbosity.COMPACT) {
+            statLine(compactLine(s, latValid), Color.White)
+            return@Column
         }
-        videoFeedLine(s)?.let { feed ->
-            Text(
-                feed,
-                color = Color.White,
-                fontFamily = FontFamily.Monospace,
-                fontSize = 12.sp,
-            )
+
+        statLine("$w×$h@$hz   ${s[0].roundToInt()} fps   ${"%.1f".format(s[1])} Mb/s", Color.White)
+        if (detailed && decoderLabel.isNotEmpty()) {
+            statLine(decoderLabel, Color(0xFFB0D0FF))
+        }
+        if (detailed) {
+            videoFeedLine(s)?.let { statLine(it, Color.White) }
         }
         if (latValid) {
+            // Display stage (s[22]–s[25], from OnFrameRendered): when a render timestamp landed
+            // this window the headline is the directly-measured capture→displayed pair and the
+            // equation gains its `display` term; otherwise (older lib / no callbacks) the endpoint
+            // honestly stays capture→decoded — the equation always tiles the headline interval.
+            val dispValid = s.size >= 26 && s[22] != 0.0
             val tag = if (skew) "" else " (same-host clock)"
-            Text(
-                "end-to-end ${"%.1f".format(s[2])} ms p50 · ${"%.1f".format(s[3])} p95 · capture→decoded$tag",
-                color = Color.White,
-                fontFamily = FontFamily.Monospace,
-                fontSize = 12.sp,
+            val (p50, p95, endpoint) = if (dispValid) {
+                Triple(s[24], s[25], "capture→displayed")
+            } else {
+                Triple(s[2], s[3], "capture→decoded")
+            }
+            statLine(
+                "end-to-end ${"%.1f".format(p50)} ms p50 · ${"%.1f".format(p95)} p95 · $endpoint$tag",
+                Color.White,
             )
-            if (s.size >= 16) {
+            if (detailed && s.size >= 16) {
                 // Phase-2 split (s[16]/s[17]): render `host + network` separately when the host
                 // reported its share this window; otherwise the combined term (old host / no
                 // matched 0xCF timing).
-                val equation = if (s.size >= 18 && s[16] > 0) {
-                    "= host ${"%.1f".format(s[16])} + network ${"%.1f".format(s[17])} + decode ${"%.1f".format(s[15])}"
+                val hostTerms = if (s.size >= 18 && s[16] > 0) {
+                    "host ${"%.1f".format(s[16])} + network ${"%.1f".format(s[17])}"
                 } else {
-                    "= host+network ${"%.1f".format(s[14])} + decode ${"%.1f".format(s[15])}"
+                    "host+network ${"%.1f".format(s[14])}"
                 }
-                Text(
-                    equation,
-                    color = Color.White,
-                    fontFamily = FontFamily.Monospace,
-                    fontSize = 12.sp,
-                )
+                val displayTerm = if (dispValid) " + display ${"%.1f".format(s[23])}" else ""
+                statLine("= $hostTerms + decode ${"%.1f".format(s[15])}$displayTerm", Color.White)
             }
         }
-        if (lost > 0) {
-            Text(
-                "lost $lost",
-                color = Color(0xFFFFB0B0),
-                fontFamily = FontFamily.Monospace,
-                fontSize = 12.sp,
-            )
-        }
+        counterLine(s, lost)?.let { statLine(it, Color(0xFFFFB0B0)) }
     }
 }
 
+/** One monospace HUD line — the shared type ramp so every tier's rows line up. */
+@Composable
+private fun statLine(text: String, color: Color) {
+    Text(text, color = color, fontFamily = FontFamily.Monospace, fontSize = 12.sp)
+}
+
+/**
+ * The single [StatsVerbosity.COMPACT] line: `238 fps · 1.3 ms · 921 Mb/s`. The end-to-end p50 term
+ * is dropped when no in-range latency sample landed (`latValid` false), and a loss flag
+ * `· ⚠ lost {n}` is appended when the window (or, on an old lib, the session) dropped frames — the
+ * one reliability signal worth surfacing even at the tersest tier.
+ */
+private fun compactLine(s: DoubleArray, latValid: Boolean): String {
+    // Prefer the capture→displayed end-to-end (s[24]) when a render timestamp landed this window.
+    val e2eP50 = if (s.size >= 26 && s[22] != 0.0) s[24] else s[2]
+    val parts = buildList {
+        add("${s[0].roundToInt()} fps")
+        if (latValid) add("${"%.1f".format(e2eP50)} ms")
+        add("${s[1].roundToInt()} Mb/s")
+    }
+    val lostWindow = if (s.size >= 22) s[18].toLong() else s[9].toLong()
+    val suffix = if (lostWindow > 0) "   ⚠ lost $lostWindow" else ""
+    return parts.joinToString(" · ") + suffix
+}
+
+/**
+ * Format the spec's line-4 counters from the per-window doubles at 18–21 —
+ * `lost {n} ({pct}%) · skipped {m} · FEC {k}`, each term only when nonzero, the whole line `null`
+ * when all are zero (spec: "only rendered when any value is nonzero"). `pct = lost/(frames+lost)`
+ * (the received count rides at index 21). A pre-window layout (< 22 doubles) falls back to the
+ * session-cumulative `lostTotal` so an older native lib still reports loss.
+ */
+private fun counterLine(s: DoubleArray, lostTotal: Long): String? {
+    if (s.size < 22) return if (lostTotal > 0) "lost $lostTotal" else null
+    val lost = s[18].toLong()
+    val skipped = s[19].toLong()
+    val fec = s[20].toLong()
+    val frames = s[21].toLong()
+    if (lost == 0L && skipped == 0L && fec == 0L) return null
+    return buildList {
+        if (lost > 0) {
+            val pct = 100.0 * lost / (frames + lost).coerceAtLeast(1)
+            add("lost $lost (${"%.1f".format(pct)}%)")
+        }
+        if (skipped > 0) add("skipped $skipped")
+        if (fec > 0) add("FEC $fec")
+    }.joinToString(" · ")
+}
+
 /**
  * Format the negotiated video-feed descriptor from the trailing four stats doubles
  * `[bitDepth, colorPrimaries, colorTransfer, chromaFormatIdc]`, e.g.

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

@@ -54,28 +54,32 @@ fun StreamScreen(handle: Long, micEnabled: Boolean, onDisconnect: () -> Unit) {
         Manifest.permission.RECORD_AUDIO,
     ) == PackageManager.PERMISSION_GRANTED
 
-    // Live decode stats for the HUD. `showStats` gates the whole pipeline: the native per-frame
-    // sampling (nativeSetVideoStatsEnabled — hidden HUD costs one atomic load per frame) AND the
-    // 1 s poll loop, which only runs while the overlay is visible. Enabling resets the native
-    // window, so re-showing never renders stale data. A 3-finger tap toggles it live; the default
-    // comes from Settings.
+    // Live decode stats for the HUD. `statsOn` (verbosity != OFF) gates the whole native pipeline:
+    // the per-frame sampling (nativeSetVideoStatsEnabled — a hidden HUD costs one atomic load per
+    // frame) AND the 1 s poll loop, which only runs while the overlay is visible. Enabling resets
+    // the native window, so re-showing never renders stale data. A 3-finger tap cycles the
+    // verbosity tier live (Off → Compact → Normal → Detailed → Off); the default comes from
+    // Settings. The tier only changes how many lines `StatsOverlay` draws — switching between the
+    // visible tiers keeps sampling running (the effect keys on `statsOn`, not the tier) so it never
+    // blanks the numbers for a poll interval.
     val initialSettings = remember { SettingsStore(context).load() }
     var stats by remember { mutableStateOf<DoubleArray?>(null) }
     var decoderLabel by remember { mutableStateOf("") }
-    var showStats by remember { mutableStateOf(initialSettings.statsHudEnabled) }
+    var statsVerbosity by remember { mutableStateOf(initialSettings.statsVerbosity) }
+    val statsOn = statsVerbosity != StatsVerbosity.OFF
     // Touch model is fixed per session (re-keys the gesture handler below if it ever changes).
     val touchMode = initialSettings.touchMode
-    // "Low-latency mode (experimental)" master toggle, resolved once for the session. Off (the
-    // default) runs the original decode pipeline; on enables the aggressive stack — decoder
-    // ranking + vendor keys + async loop (native side), HDMI ALLM below, game-tagged audio, and
-    // DSCP marking (applied earlier, at connect).
+    // "Low-latency mode" master toggle, resolved once for the session. On (the default) enables the
+    // fast pipeline — decoder ranking + vendor keys + async loop (native side), HDMI ALLM below,
+    // game-tagged audio, and DSCP marking (applied earlier, at connect); off falls back to the
+    // original synchronous decode pipeline as a per-device escape hatch.
     val lowLatencyMode = initialSettings.lowLatencyMode
     // TV form factor (leanback): the decoder actively switches the HDMI output mode to the stream
     // refresh; a phone/tablet gets the softer seamless frame-rate hint instead.
     val isTv = remember { context.packageManager.hasSystemFeature(PackageManager.FEATURE_LEANBACK) }
-    LaunchedEffect(handle, showStats) {
-        NativeBridge.nativeSetVideoStatsEnabled(handle, showStats)
-        if (showStats) {
+    LaunchedEffect(handle, statsOn) {
+        NativeBridge.nativeSetVideoStatsEnabled(handle, statsOn)
+        if (statsOn) {
             while (true) {
                 delay(1000)
                 stats = NativeBridge.nativeVideoStats(handle)
@@ -250,8 +254,10 @@ fun StreamScreen(handle: Long, micEnabled: Boolean, onDisconnect: () -> Unit) {
         )
         // 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, decoderLabel, Modifier.align(Alignment.TopStart).padding(12.dp)) }
+        if (statsOn) {
+            stats?.let {
+                StatsOverlay(it, statsVerbosity, decoderLabel, Modifier.align(Alignment.TopStart).padding(12.dp))
+            }
         }
         // Touch input per the Settings model: trackpad/direct-pointer mouse (the shared gesture
         // vocabulary) or real multi-touch passthrough — see TouchInput.kt.
@@ -262,7 +268,7 @@ fun StreamScreen(handle: Long, micEnabled: Boolean, onDisconnect: () -> Unit) {
                     else -> streamTouchInput(
                         handle,
                         trackpad = touchMode == TouchMode.TRACKPAD,
-                        onToggleStats = { showStats = !showStats },
+                        onCycleStats = { statsVerbosity = statsVerbosity.next() },
                     )
                 }
             },

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

@@ -40,7 +40,7 @@ private const val ACCEL_MAX = 3.0f
  *
  * Both share the same gesture vocabulary: tap = left click; two-finger tap = right click;
  * two-finger drag = scroll; tap-then-press-and-drag = left-drag (text selection / moving
- * windows); three-finger tap = [onToggleStats] (the stats HUD).
+ * windows); three-finger tap = [onCycleStats] (cycle the stats-HUD verbosity tier).
  */
 /**
  * Real multi-touch passthrough ([TouchMode.TOUCH]): every finger forwards as a host touchscreen
@@ -93,7 +93,7 @@ internal suspend fun PointerInputScope.streamTouchPassthrough(handle: Long) {
 internal suspend fun PointerInputScope.streamTouchInput(
     handle: Long,
     trackpad: Boolean,
-    onToggleStats: () -> Unit,
+    onCycleStats: () -> Unit,
 ) {
     var lastTapUp = 0L
     var lastTapX = 0f
@@ -127,6 +127,7 @@ internal suspend fun PointerInputScope.streamTouchInput(
         var moved = false
         var maxFingers = 1
         var scrolling = false
+        var scrollCount = 0 // pointer count the scroll centroid is anchored at
         var prevCx = startX
         var prevCy = startY
         var upTime = down.uptimeMillis
@@ -149,11 +150,18 @@ internal suspend fun PointerInputScope.streamTouchInput(
             if (pressed.size > maxFingers) maxFingers = pressed.size
 
             if (pressed.size >= 2) {
-                // Two fingers → scroll by the centroid delta; never move the cursor.
+                // 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) {
+                // (Re-)anchor whenever the finger COUNT changes, not just on scroll start: the
+                // centroid of three fingers sits far from the centroid of two, and real fingers
+                // never land (or lift) in the same input frame — so the 2→3 transition would
+                // otherwise read as a scroll notch, sending a phantom wheel tick to the host AND
+                // setting `moved`, which disqualified the tap classification below and made the
+                // 3-finger stats tap unreachable on real hardware.
+                if (!scrolling || pressed.size != scrollCount) {
                     scrolling = true
+                    scrollCount = pressed.size
                     prevCx = cx
                     prevCy = cy
                 }
@@ -218,7 +226,7 @@ internal suspend fun PointerInputScope.streamTouchInput(
             NativeBridge.nativeSendPointerButton(handle, 1, false) // end the drag
         } else if (!moved) {
             when {
-                maxFingers >= 3 -> onToggleStats() // in-stream HUD toggle
+                maxFingers >= 3 -> onCycleStats() // in-stream HUD verbosity cycle
                 maxFingers == 2 -> { // two-finger tap → right click
                     NativeBridge.nativeSendPointerButton(handle, 3, true)
                     NativeBridge.nativeSendPointerButton(handle, 3, false)

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

@@ -2,6 +2,7 @@ package io.unom.punktfunk.components
 
 import androidx.compose.foundation.background
 import androidx.compose.foundation.border
+import androidx.compose.foundation.layout.Arrangement
 import androidx.compose.foundation.layout.Box
 import androidx.compose.foundation.layout.Column
 import androidx.compose.foundation.layout.Row
@@ -56,6 +57,7 @@ fun HostCard(
     name: String,
     address: String,
     status: HostStatus,
+    online: Boolean = false,
     enabled: Boolean,
     onConnect: () -> Unit,
     onForget: (() -> Unit)?,
@@ -105,7 +107,13 @@ fun HostCard(
                     textAlign = TextAlign.Center,
                 )
                 Spacer(Modifier.height(12.dp))
-                StatusPill(status)
+                Row(
+                    verticalAlignment = Alignment.CenterVertically,
+                    horizontalArrangement = Arrangement.spacedBy(12.dp),
+                ) {
+                    PresencePill(online)
+                    StatusPill(status)
+                }
             }
 
             if (onForget != null || onEdit != null || onWake != null) {
@@ -173,6 +181,27 @@ fun HostAvatar(name: String) {
     }
 }
 
+/**
+ * A small dot + label for live presence: green Online when the host advertises on mDNS OR answers
+ * the reachability probe (so a routed/VPN host that never advertises still reads Online), dimmed
+ * Offline otherwise.
+ */
+@Composable
+fun PresencePill(online: Boolean) {
+    val color =
+        if (online) MaterialTheme.colorScheme.primary
+        else MaterialTheme.colorScheme.onSurfaceVariant
+    Row(verticalAlignment = Alignment.CenterVertically) {
+        Box(Modifier.size(8.dp).clip(CircleShape).background(color))
+        Spacer(Modifier.width(6.dp))
+        Text(
+            if (online) "Online" else "Offline",
+            style = MaterialTheme.typography.labelMedium,
+            color = color,
+        )
+    }
+}
+
 /** A small colored dot + label for the host's trust state. */
 @Composable
 fun StatusPill(status: HostStatus) {

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

@@ -58,7 +58,15 @@ class ScreenshotTest {
 
     @Test
     @Config(sdk = [36], qualifiers = "w800dp-h360dp-xxhdpi") // landscape — the stream is immersive
-    fun stream() = shootRoot("stream") { StreamScene() }
+    fun stream() = shootRoot("stream") { StreamScene(io.unom.punktfunk.StatsVerbosity.DETAILED) }
+
+    @Test
+    @Config(sdk = [36], qualifiers = "w800dp-h360dp-xxhdpi")
+    fun streamCompact() = shootRoot("stream-compact") { StreamScene(io.unom.punktfunk.StatsVerbosity.COMPACT) }
+
+    @Test
+    @Config(sdk = [36], qualifiers = "w800dp-h360dp-xxhdpi")
+    fun streamNormal() = shootRoot("stream-normal") { StreamScene(io.unom.punktfunk.StatsVerbosity.NORMAL) }
 
     @Test
     fun trust() = shootScreen("trust") {

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

@@ -30,6 +30,7 @@ import io.unom.punktfunk.Settings
 import io.unom.punktfunk.TouchMode
 import io.unom.punktfunk.SettingsScreen
 import io.unom.punktfunk.StatsOverlay
+import io.unom.punktfunk.StatsVerbosity
 import io.unom.punktfunk.components.HostCard
 import io.unom.punktfunk.components.SectionLabel
 import io.unom.punktfunk.models.HostStatus
@@ -109,7 +110,7 @@ internal fun SettingsScene() {
                 compositor = 1,
                 gamepad = 2,
                 micEnabled = true,
-                statsHudEnabled = true,
+                statsVerbosity = StatsVerbosity.DETAILED,
                 touchMode = TouchMode.TRACKPAD,
             ),
             onChange = {},
@@ -177,9 +178,12 @@ internal fun PairDialog() {
     )
 }
 
-/** The live stats HUD (the real StatsOverlay) over a synthetic "streamed frame" gradient. */
+/**
+ * The live stats HUD (the real StatsOverlay) over a synthetic "streamed frame" gradient, at the
+ * given [verbosity] tier — one scene per tier documents how far each tones the overlay down.
+ */
 @Composable
-internal fun StreamScene() {
+internal fun StreamScene(verbosity: StatsVerbosity = StatsVerbosity.DETAILED) {
     Box(
         Modifier
             .fillMaxSize()
@@ -187,17 +191,25 @@ internal fun StreamScene() {
                 Brush.linearGradient(listOf(Color(0xFF2A1E5C), Color(0xFF0E1B3D), Color(0xFF06122B))),
             ),
     ) {
-        // The full 18-double unified layout (design/stats-unification.md): [fps, mbps, e2eP50,
-        // e2eP95, latValid, skew, w, h, hz, lost, bitDepth, colorPrimaries, colorTransfer,
-        // chromaFormatIdc, hostNetP50, decodeP50, hostP50, netP50]. 10/9/16/1 = a 10-bit BT.2020
-        // PQ (HDR) 4:2:0 feed so the HUD renders its video-feed line; the Phase-2 stage terms
-        // (host 0.6 + network 0.3 + decode 0.4) tile the 1.3 ms headline so it renders the full
-        // split equation, and the decoder label line shows the ranked low-latency decoder.
+        // The full 26-double unified layout (design/stats-unification.md): [fps, mbps, e2eP50,
+        // e2eP95, latValid, skew, w, h, hz, lostTotal, bitDepth, colorPrimaries, colorTransfer,
+        // chromaFormatIdc, hostNetP50, decodeP50, hostP50, netP50, lost, skipped, fec, frames,
+        // dispValid, displayP50, e2eDispP50, e2eDispP95].
+        // 10/9/16/1 = a 10-bit BT.2020 PQ (HDR) 4:2:0 feed so the DETAILED HUD renders its
+        // video-feed line; the display stage is valid (dispValid 1) so the headline is the
+        // directly-measured capture→displayed pair (1.8/2.6) and the Phase-2 stage terms
+        // (host 0.6 + network 0.3 + decode 0.4 + display 0.5) tile it, rendering the full split
+        // equation; the decoder label shows the ranked low-latency decoder. Light per-window loss
+        // (lost 2 · skipped 1 · FEC 5 of 238) so the reliability line (NORMAL/DETAILED) and the
+        // compact loss flag both render.
         StatsOverlay(
             doubleArrayOf(
-                238.0, 921.4, 1.3, 2.1, 1.0, 1.0, 5120.0, 1440.0, 240.0, 0.0,
+                238.0, 921.4, 1.3, 2.1, 1.0, 1.0, 5120.0, 1440.0, 240.0, 2.0,
                 10.0, 9.0, 16.0, 1.0, 0.9, 0.4, 0.6, 0.3,
+                2.0, 1.0, 5.0, 238.0,
+                1.0, 0.5, 1.8, 2.6,
             ),
+            verbosity = verbosity,
             decoderLabel = "c2.qti.hevc.decoder · low-latency",
             modifier = Modifier.align(Alignment.TopStart).padding(12.dp),
         )

clients/android/build.gradle.kts

@@ -3,7 +3,7 @@
 // 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.
+// 2026.05.01 · compileSdk 37 · targetSdk 37 · minSdk 28.
 plugins {
     id("com.android.application") version "9.2.1" apply false
     id("com.android.library") version "9.2.1" apply false

clients/android/kit/build.gradle.kts

@@ -91,9 +91,12 @@ fun registerCargoNdk(taskName: String, release: Boolean) =
         val cmd = mutableListOf(
             "$cargoBin/cargo", "ndk",
             "-t", "arm64-v8a", "-t", "armeabi-v7a", "-t", "x86_64",
-            // Link against the minSdk-28 sysroot: libaaudio (API 26) is present, and building at the
-            // floor makes the linker reject any accidental >28 hard import (the one API-30 call we
-            // make, ANativeWindow_setFrameRate, is dlsym-resolved — see decode::try_set_frame_rate).
+            // Link against the minSdk-28 sysroot (libaaudio, API 26, is present). NOTE: this does
+            // NOT reject an accidental >28 hard import — a cdylib link permits undefined symbols,
+            // which then fail at System.loadLibrary on every device below the symbol's API level
+            // (the 0.9.0 Android-≤12 regression). The checkJniImports* task after this build is
+            // what actually enforces the floor; >28 entry points must be dlsym-resolved (see
+            // decode::try_set_frame_rate, decode::install_render_callback, adpf).
             "--platform", "28",
             "-o", file("src/main/jniLibs").absolutePath,
             "build", "-p", "punktfunk-client-android",
@@ -102,8 +105,28 @@ fun registerCargoNdk(taskName: String, release: Boolean) =
         commandLine(cmd)
     }
 
+// Post-link floor check: every undefined symbol in the built .so must exist in the API-28 stubs,
+// else System.loadLibrary fails on devices at the minSdk floor (see the script header for the
+// 0.9.0 incident this guards against). Runs right after its cargo-ndk task; the APK build depends
+// on this task (not the cargo one directly), so a violation fails the build, local and CI alike.
+fun registerCheckJniImports(taskName: String, cargoTask: TaskProvider<Exec>) =
+    tasks.register<Exec>(taskName) {
+        group = "rust"
+        description = "verify libpunktfunk_android.so imports stay within the API-28 floor"
+        dependsOn(cargoTask)
+        workingDir = repoRoot
+        commandLine(
+            "sh", File(repoRoot, "scripts/ci/check-android-jni-imports.sh").absolutePath,
+            "${androidSdkDir()}/ndk/$ndkVer",
+            file("src/main/jniLibs").absolutePath,
+            "28",
+        )
+    }
+
 val cargoNdkDebug = registerCargoNdk("cargoNdkDebug", release = false)
 val cargoNdkRelease = registerCargoNdk("cargoNdkRelease", release = true)
+val checkJniImportsDebug = registerCheckJniImports("checkJniImportsDebug", cargoNdkDebug)
+val checkJniImportsRelease = registerCheckJniImports("checkJniImportsRelease", cargoNdkRelease)
 
 afterEvaluate {
     // `-PskipRustBuild` skips the cargo-ndk native build — for JVM-only tasks (the Roborazzi
@@ -120,8 +143,9 @@ afterEvaluate {
     // debug build); only the cargo profile changes. `-PrustDebug` restores a debug-profile native
     // build for the rare session that actually steps through Rust.
     if (!project.hasProperty("skipRustBuild")) {
-        val debugRust = if (project.hasProperty("rustDebug")) cargoNdkDebug else cargoNdkRelease
+        val debugRust =
+            if (project.hasProperty("rustDebug")) checkJniImportsDebug else checkJniImportsRelease
         tasks.named("preDebugBuild").configure { dependsOn(debugRust) }
-        tasks.named("preReleaseBuild").configure { dependsOn(cargoNdkRelease) }
+        tasks.named("preReleaseBuild").configure { dependsOn(checkJniImportsRelease) }
     }
 }

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

@@ -175,6 +175,12 @@ object Gamepad {
      * 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).
+     *
+     * Single-source: only ONE qualifying controller feeds pad 0. Events must come from a device
+     * whose source classes include GAMEPAD (see [onMotion]) and the mapper pins itself to the
+     * first such device — a controller's joystick-classified sibling nodes (DualSense/DS4 motion
+     * sensors) and any second pad report every axis as 0, and folding them into the same state
+     * flapped a held trigger/stick between its value and 0 on every event interleave.
      */
     class AxisMapper(private val handle: Long) {
         // Sentinel so the first real value (incl. 0) always sends once after attach (Linux parity).
@@ -182,10 +188,29 @@ object Gamepad {
         private var hatX = 0 // -1 / 0 / +1
         private var hatY = 0
 
+        /** deviceId of the controller pad 0 is pinned to; −1 until the first qualifying event. */
+        private var deviceId = -1
+
         /** 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
+            // Only a true gamepad drives pad 0. A joystick ACTION_MOVE's own source is plain
+            // JOYSTICK for every sender, so qualify by the DEVICE's source classes: a real pad
+            // carries the GAMEPAD (button) class too, its sensor/touchpad sibling nodes and
+            // joystick-class remotes don't — and those report every pad axis as 0 (see the
+            // class doc for the held-trigger flap this caused).
+            val dev = event.device ?: return false
+            if (dev.sources and InputDevice.SOURCE_GAMEPAD != InputDevice.SOURCE_GAMEPAD) return false
+            // Single-pad model: pin to the first qualifying controller so a second pad (or its
+            // stick drift) can't fight pad 0; re-adopt only once the pinned device is gone.
+            if (deviceId != event.deviceId) {
+                if (deviceId != -1) {
+                    if (InputDevice.getDevice(deviceId) != null) return false
+                    reset() // the pinned pad is gone — lift its held state before adopting
+                }
+                deviceId = event.deviceId
+            }
 
             // 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)))
@@ -193,9 +218,27 @@ object Gamepad {
             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)))
+            // Triggers: pads report LTRIGGER/RTRIGGER or BRAKE/GAS (some mirror both) — merge
+            // with max, the same fold as the Controllers screen probe, so a pad that reports
+            // only one pair and a pad that reports both behave identically; 0..1 → 0..255.
+            sendAxis(
+                AXIS_LT,
+                trigger(
+                    maxOf(
+                        event.getAxisValue(MotionEvent.AXIS_LTRIGGER),
+                        event.getAxisValue(MotionEvent.AXIS_BRAKE),
+                    ),
+                ),
+            )
+            sendAxis(
+                AXIS_RT,
+                trigger(
+                    maxOf(
+                        event.getAxisValue(MotionEvent.AXIS_RTRIGGER),
+                        event.getAxisValue(MotionEvent.AXIS_GAS),
+                    ),
+                ),
+            )
 
             // HAT → dpad button transitions (track previous, emit only the deltas).
             val hx = sign(event.getAxisValue(MotionEvent.AXIS_HAT_X))
@@ -237,10 +280,5 @@ object Gamepad {
         private fun trigger(v: Float): Int = (v.coerceIn(0f, 1f) * 255f).toInt()
 
         private fun sign(v: Float): Int = if (v < -0.5f) -1 else if (v > 0.5f) 1 else 0
-
-        private fun firstNonZero(e: MotionEvent, a: Int, b: Int): Float {
-            val va = e.getAxisValue(a)
-            return if (va != 0f) va else e.getAxisValue(b)
-        }
     }
 }

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

@@ -35,6 +35,9 @@ class GamepadFeedback(private val handle: Long) {
         const val TAG_LED: Byte = 0x01
         const val TAG_PLAYER_LEDS: Byte = 0x02
         const val TAG_TRIGGER: Byte = 0x03
+        // Fallback one-shot duration against a legacy host (no v2 TTL lease): the prior fixed value.
+        // A new host renews far below this, so it never actually holds this long there.
+        const val LEGACY_RUMBLE_MS = 60_000L
     }
 
     @Volatile private var running = false
@@ -66,7 +69,17 @@ class GamepadFeedback(private val handle: Long) {
             while (running) {
                 val ev = NativeBridge.nativeNextRumble(handle)
                 if (ev < 0L) continue // timeout / closed
-                renderRumble(((ev ushr 16) and 0xFFFF).toInt(), (ev and 0xFFFF).toInt())
+                // ev bit 48 = has a v2 lease; bits 32..47 = ttl_ms; 16..31 = low; 0..15 = high. The
+                // lease flag is out-of-band, so any ttl_ms (incl. 0xFFFF) is a real lease — no
+                // in-band sentinel. No lease (legacy host) → the prior long one-shot.
+                val hasLease = ((ev ushr 48) and 0x1L) == 0x1L
+                val ttl = ((ev ushr 32) and 0xFFFF).toInt()
+                val durationMs = if (hasLease) ttl.toLong() else LEGACY_RUMBLE_MS
+                renderRumble(
+                    ((ev ushr 16) and 0xFFFF).toInt(),
+                    (ev and 0xFFFF).toInt(),
+                    durationMs,
+                )
             }
         }, "pf-rumble").apply { isDaemon = true; start() }
 
@@ -143,9 +156,14 @@ class GamepadFeedback(private val handle: Long) {
         }
     }
 
-    /** 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
+    /**
+     * low = heavy/left motor, high = light/right motor; both 0..0xFFFF (the host's u16 amplitudes).
+     * `durationMs` is the host's v2 envelope TTL — the one-shot self-terminates after it unless the
+     * host renews, so a lost stop (or a dead host) silences at the lease instead of the old fixed
+     * 60 s. Against a legacy host it is [LEGACY_RUMBLE_MS] (the prior fixed duration).
+     */
+    private fun renderRumble(low: Int, high: Int, durationMs: Long) {
+        Log.i(TAG, "rumble low=$low high=$high ttlMs=$durationMs") // verification line — BEFORE any no-op return
         val lo = toAmplitude(low)
         val hi = toAmplitude(high)
         val m = vm
@@ -157,12 +175,12 @@ class GamepadFeedback(private val handle: Long) {
             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))
+                if (hi != 0) combo.addVibrator(vibratorIds[0], oneShot(hi, durationMs))
+                if (lo != 0) combo.addVibrator(vibratorIds[1], oneShot(lo, durationMs))
             } 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))
+                for (id in vibratorIds) combo.addVibrator(id, oneShot(a, durationMs))
             }
             runCatching { m.vibrate(combo.combine()) }
             return
@@ -175,7 +193,10 @@ class GamepadFeedback(private val handle: Long) {
         }
         val a = (lo * 0.8 + hi * 0.33).toInt().coerceIn(1, 255)
         runCatching {
-            lv.vibrate(if (amplitudeControlled) oneShot(a) else oneShot(VibrationEffect.DEFAULT_AMPLITUDE))
+            lv.vibrate(
+                if (amplitudeControlled) oneShot(a, durationMs)
+                else oneShot(VibrationEffect.DEFAULT_AMPLITUDE, durationMs)
+            )
         }
     }
 
@@ -185,8 +206,10 @@ class GamepadFeedback(private val handle: Long) {
         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)
+    // One-shot held for `durationMs` — the host's v2 TTL (renewed while the level holds), so it
+    // self-terminates on a lost stop; cancel on zero.
+    private fun oneShot(amp: Int, durationMs: Long): VibrationEffect =
+        VibrationEffect.createOneShot(durationMs, amp)
 
     // ---- HID output ----
 

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

@@ -48,6 +48,9 @@ object NativeBridge {
         gamepadPref: Int,
         hdrEnabled: Boolean,
         audioChannels: Int,
+        /** `quic::CODEC_*` bitfield of codecs this device decodes ([VideoDecoders.decodableCodecBits]);
+         *  `0` falls back to H.264|HEVC. The host resolves the emitted codec from this ∩ its GPU. */
+        videoCodecs: Int,
         /** Preferred video codec as a `quic::CODEC_*` bit (`0` = auto). Soft — the host falls back. */
         preferredCodec: Int,
         timeoutMs: Int,
@@ -123,6 +126,15 @@ object NativeBridge {
      */
     external fun nativeWakeOnLan(macsCsv: String, lastIp: String): Boolean
 
+    /**
+     * Bounded, trust-agnostic QUIC reachability probe to [host]:[port] (mDNS-independent): true if
+     * the host completed the handshake within [timeoutMs]. No pin/identity presented. Lets a saved
+     * host reached over a routed network (Tailscale/VPN/another subnet) — which never advertises on
+     * mDNS — still show as online. Blocking (builds its own runtime) — run on a background
+     * dispatcher, never the main thread.
+     */
+    external fun nativeProbe(host: String, port: Int, timeoutMs: Int): Boolean
+
     /**
      * Apply the user's "Low-latency mode (experimental)" toggle to the process-wide transport
      * defaults — today just DSCP/QoS marking on the media sockets. Must be called BEFORE
@@ -171,16 +183,22 @@ object NativeBridge {
 
     /**
      * Drain ~1 s of live decode stats for the on-stream HUD, or `null` when no decode thread runs.
-     * Returns 18 doubles (unified stats spec, `design/stats-unification.md`):
+     * Returns 26 doubles (unified stats spec, `design/stats-unification.md`):
      * `[fps, mbps, e2eP50Ms, e2eP95Ms, latValid, skewCorrected, width, height, refreshHz, framesLost,
      * bitDepth, colorPrimaries, colorTransfer, chromaFormatIdc, hostNetP50Ms, decodeP50Ms, hostP50Ms,
-     * netP50Ms]`
-     * (the two flags are 1.0/0.0; indexes 2/3 are the end-to-end capture→decoded headline; 10–13
+     * netP50Ms, lostWindow, skippedWindow, fecWindow, framesWindow, dispValid, displayP50Ms,
+     * e2eDispP50Ms, e2eDispP95Ms]`
+     * (the flags are 1.0/0.0; indexes 2/3 are the end-to-end capture→decoded headline; 10–13
      * describe the negotiated video feed — bit depth 8/10, CICP primaries/transfer, and the HEVC
      * chroma_format_idc 1=4:2:0 / 3=4:4:4; 14/15 are the stage p50s tiling the headline —
      * `host+network` = capture→received, `decode` = received→decoded; 16/17 split the
      * `host+network` term via the host's per-AU 0xCF timings — `host` = the host's capture→sent,
-     * `network` = the remainder — both 0.0 when no timing matched this window, i.e. an old host).
+     * `network` = the remainder — both 0.0 when no timing matched this window, i.e. an old host;
+     * 18–21 are the per-window reliability counters — lost/skipped/FEC/received; 22–25 are the
+     * `display` stage from the OnFrameRendered render timestamps — when `dispValid` is 1.0 the
+     * headline becomes the directly-measured capture→displayed pair at 24/25, tiled by
+     * `host+network` + `decode` + `display` (23), and when 0.0 the HUD falls back to the
+     * capture→decoded headline at 2/3 without the `display` term).
      * Poll ~1 Hz; each call resets the measurement window.
      */
     external fun nativeVideoStats(handle: Long): DoubleArray?

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

@@ -44,6 +44,15 @@ object VideoDecoders {
      * Pick the best decoder for [mime] (`"video/hevc"` / `"video/avc"` / `"video/av01"`), or `null`
      * to let the platform resolve its default. Enumerates once — call at stream start.
      */
+    /**
+     * The `quic::CODEC_*` bitfield of codecs this device can decode, advertised in the Hello so the
+     * host never emits a codec the decode loop can't open: H.264 (1) and HEVC (2) always (universal
+     * on Android hardware), plus AV1 (4) only when [pickDecoder] finds a real (hardware, non-blocked)
+     * `video/av01` decoder. Enumerates `MediaCodecList` — call at connect time, not per frame.
+     */
+    fun decodableCodecBits(): Int =
+        1 or 2 or (if (pickDecoder("video/av01") != null) 4 else 0)
+
     fun pickDecoder(mime: String): DecoderChoice? {
         if (mime.isEmpty()) return null
         val infos = runCatching { MediaCodecList(MediaCodecList.REGULAR_CODECS).codecInfos }

clients/android/native/Cargo.toml

@@ -20,7 +20,7 @@ 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
+# Linux/Windows clients use (`crates/pf-client-core/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.
@@ -43,10 +43,21 @@ tracing = { version = "0.1", default-features = false, features = ["std", "log"]
 # 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).
 # api-level-28 matches the app's minSdk floor (Android 9). AAudio (26), AMediaCodec (21) and
-# ANativeWindow_setBuffersDataSpace (28) are all ≤28; the one API-30 call we make
-# (ANativeWindow_setFrameRate) is dlsym-resolved at runtime (see decode::try_set_frame_rate), not
-# linked, so the .so still loads on API 28/29.
+# ANativeWindow_setBuffersDataSpace (28) are all ≤28; every call above the floor —
+# ANativeWindow_setFrameRate (30), …WithChangeStrategy (31), AMediaCodec_setOnFrameRenderedCallback
+# (33), the ADPF hints — is dlsym-resolved at runtime (decode::try_set_frame_rate,
+# decode::install_render_callback, adpf), never linked, so the .so still loads on API 28+.
 ndk = { version = "0.9", features = ["media", "audio", "nativewindow", "api-level-28"] }
+# Raw FFI *types* for the one AMediaCodec entry point the `ndk` wrapper lacks:
+# `AMediaCodec_setOnFrameRenderedCallback` — the per-frame render-timestamp callback behind the
+# HUD's `display` stage (see decode::DisplayTracker). The symbol is API 33 ("Available since
+# Android T"), ABOVE the minSdk-28 floor, so it is dlsym-resolved at runtime
+# (decode::install_render_callback), NEVER hard-linked: 0.9.0 hard-linked it and
+# `System.loadLibrary` failed on every pre-Android-13 device. Only ndk-sys's pointer/typedef
+# types are referenced, which creates no import. Reaching it needs the codec's raw pointer, which
+# is why the workspace pins `ndk` to the vendored copy whose only patch makes `MediaCodec::as_ptr`
+# public (vendor/ndk, wired in the root Cargo.toml).
+ndk-sys = { version = "0.6", features = ["media"] }
 # 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

clients/android/native/src/audio.rs

@@ -355,45 +355,70 @@ fn decode_loop(
     };
     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) {
+    let mut gaps = punktfunk_core::audio::AudioGapTracker::new();
+    let mut frame_samples = 0usize; // per-channel samples of the last decoded frame — the PLC unit
+    'pump: 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());
+            Ok(pkt) => {
+                // Conceal lost packets (a seq gap) with libopus PLC before decoding the one that
+                // arrived: empty input synthesizes `frame_samples` of interpolation per missing
+                // packet — an inaudible fade instead of the click a hard gap makes in the ring.
+                for _ in 0..gaps.missing_before(pkt.seq) {
+                    let plc = frame_samples * channels;
+                    if plc == 0 {
+                        break; // no decoded frame yet to size the concealment from
                     }
-                    // The ring's pre-reservation in `start` assumes the protocol's 5 ms (≤480-f32/ch)
-                    // frames; a larger frame would force a one-time realloc on the RT thread. Catch a
-                    // future host frame-size change here in debug, not as a silent audio glitch.
-                    debug_assert!(
-                        n <= 5 * ms,
-                        "audio frame {n} f32 exceeds the 5 ms ring reserve"
-                    );
-                    let count = counters.opus_decoded.fetch_add(1, Ordering::Relaxed) + 1;
-                    // Reuse a recycled buffer if the callback handed one back; only allocate when the
-                    // free-list is momentarily empty (startup / after a backpressure drop).
-                    let mut buf = free_rx
-                        .try_recv()
-                        .unwrap_or_else(|_| Vec::with_capacity(pcm_scratch));
-                    buf.clear();
-                    buf.extend_from_slice(&pcm[..n]);
-                    match tx.try_send(buf) {
-                        Ok(()) | Err(TrySendError::Full(_)) => {} // drop-newest under backpressure
-                        Err(TrySendError::Disconnected(_)) => break,
-                    }
-                    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;
+                    if let Ok(samples) = dec.decode_float(&[], &mut pcm[..plc], false) {
+                        let mut buf = free_rx
+                            .try_recv()
+                            .unwrap_or_else(|_| Vec::with_capacity(pcm_scratch));
+                        buf.clear();
+                        buf.extend_from_slice(&pcm[..samples * channels]);
+                        match tx.try_send(buf) {
+                            Ok(()) | Err(TrySendError::Full(_)) => {}
+                            Err(TrySendError::Disconnected(_)) => break 'pump,
+                        }
                     }
                 }
-                Err(e) => log::debug!("audio: opus decode: {e}"),
-            },
+                match dec.decode_float(&pkt.data, &mut pcm, false) {
+                    Ok(samples) => {
+                        frame_samples = samples;
+                        let n = samples * channels;
+                        for &s in &pcm[..n] {
+                            window_peak = window_peak.max(s.abs());
+                        }
+                        // The ring's pre-reservation in `start` assumes the protocol's 5 ms (≤480-f32/ch)
+                        // frames; a larger frame would force a one-time realloc on the RT thread. Catch a
+                        // future host frame-size change here in debug, not as a silent audio glitch.
+                        debug_assert!(
+                            n <= 5 * ms,
+                            "audio frame {n} f32 exceeds the 5 ms ring reserve"
+                        );
+                        let count = counters.opus_decoded.fetch_add(1, Ordering::Relaxed) + 1;
+                        // Reuse a recycled buffer if the callback handed one back; only allocate when the
+                        // free-list is momentarily empty (startup / after a backpressure drop).
+                        let mut buf = free_rx
+                            .try_recv()
+                            .unwrap_or_else(|_| Vec::with_capacity(pcm_scratch));
+                        buf.clear();
+                        buf.extend_from_slice(&pcm[..n]);
+                        match tx.try_send(buf) {
+                            Ok(()) | Err(TrySendError::Full(_)) => {} // drop-newest under backpressure
+                            Err(TrySendError::Disconnected(_)) => break,
+                        }
+                        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
         }

clients/android/native/src/decode.rs

@@ -18,7 +18,7 @@ use punktfunk_core::error::PunktfunkError;
 use punktfunk_core::session::Frame;
 use std::collections::VecDeque;
 use std::ffi::c_void;
-use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::atomic::{AtomicBool, AtomicI64, Ordering};
 use std::sync::{mpsc, Arc, Mutex};
 use std::time::{Duration, Instant};
 
@@ -36,11 +36,17 @@ const IN_FLIGHT_CAP: usize = 64;
 /// this deep is a lost datagram (or an old host that never sends any) and gets evicted.
 const PENDING_SPLIT_CAP: usize = 256;
 
+/// Cap on rendered frames parked in [`DisplayTracker`] awaiting their `OnFrameRendered` render
+/// timestamp: the callback trails its release by at most a vsync or two, so anything this deep
+/// means the platform stopped delivering render callbacks (allowed under load, per the docs) and
+/// gets evicted.
+const RENDERED_CAP: usize = 64;
+
 /// Whether low-latency mode uses the event-driven async decode loop (default) or the synchronous
 /// poll loop. Flip to `false` to A/B the two on the HUD (`design/…`); the async loop presents a
 /// decoded frame the instant it's ready instead of waiting out a poll interval. Only consulted when
-/// the user's "Low-latency mode (experimental)" toggle is ON — off, the sync loop always runs (the
-/// original pipeline).
+/// the user's "Low-latency mode" toggle is ON (now the default) — off, the sync loop always runs (the
+/// original pipeline, kept as the per-device escape hatch).
 const USE_ASYNC_DECODE: bool = true;
 
 /// Per-session decode configuration, resolved by the JNI layer (`nativeStartVideo`) and passed to
@@ -52,10 +58,10 @@ pub(crate) struct DecodeOptions {
     /// Whether Kotlin found the chosen decoder advertises `FEATURE_LowLatency` (queryable only via
     /// the Java `CodecCapabilities` API) — surfaced on the HUD next to the decoder name.
     pub ll_feature: bool,
-    /// The user's "Low-latency mode (experimental)" master toggle. On ⇒ the full overhaul: async
+    /// The user's "Low-latency mode" master toggle. On (default) ⇒ the full fast pipeline: async
     /// decode loop, per-SoC vendor keys, pipeline thread boosts, ADPF max-performance, forced TV
-    /// mode switch. Off (default) ⇒ the original pre-overhaul pipeline, kept as the known-good
-    /// baseline while the overhaul is experimental.
+    /// mode switch. Off ⇒ the original synchronous pre-overhaul pipeline, kept as the per-device
+    /// escape hatch.
     pub low_latency_mode: bool,
     /// TV form factor (Kotlin's `UiModeManager`): actively drive the HDMI output into the stream's
     /// refresh mode, vs. the softer seamless hint on a phone/tablet.
@@ -196,6 +202,8 @@ fn run_sync(
     let mut fed: u64 = 0;
     let mut rendered: u64 = 0;
     let mut discarded: u64 = 0;
+    // AUs larger than the codec input buffer, dropped whole (see `feed`/`feed_ready`).
+    let mut oversized_dropped: u64 = 0;
     // The AU waiting for a free codec input buffer. `feed` is non-blocking; on transient input
     // pressure the AU stays parked here instead of being dropped (a drop forces a keyframe
     // round-trip) and we only pop the next one once it's queued.
@@ -207,7 +215,13 @@ fn run_sync(
     // Skew-corrected latency stats (spec: design/stats-unification.md) use the negotiated
     // host-minus-client clock offset (0 if the host didn't answer the skew handshake — then the
     // HUD flags it "(same-host clock)").
-    let clock_offset = client.clock_offset_ns;
+    let clock_offset = client.clock_offset_shared();
+    // Display stage (spec `display` + the capture→displayed headline): frames released with
+    // render = true are parked in the tracker; the OnFrameRendered callback pairs them with
+    // SurfaceFlinger's render timestamp. `render_cb` is the callback's leaked Arc refcount,
+    // reclaimed after the codec is dropped below.
+    let tracker = DisplayTracker::new(stats.clone(), clock_offset.clone());
+    let render_cb = install_render_callback(&codec, &tracker);
     // HUD stage split: receipt timestamps keyed by the pts we queue into the codec, so the decoded
     // point (output-buffer dequeue — MediaCodec round-trips presentationTimeUs) can be paired back
     // to its receipt for the `decode` stage. Only fed while the HUD is visible.
@@ -244,6 +258,7 @@ fn run_sync(
                     // the output buffer) for the decoded-point pairing in `drain`.
                     if stats.enabled() {
                         let received_ns = now_realtime_ns();
+                        let clock_offset = clock_offset.load(Ordering::Relaxed);
                         let lat_ns = received_ns + clock_offset as i128 - frame.pts_ns as i128;
                         let lat_us = (lat_ns > 0 && lat_ns < 10_000_000_000)
                             .then_some((lat_ns / 1000) as u64);
@@ -283,7 +298,13 @@ fn run_sync(
         // and excluded, so ADPF sees this thread's real per-frame CPU cost, not the poll timeout.
         let work_t0 = Instant::now();
         if let Some(frame) = pending.take() {
-            if feed(&codec, &frame.data, frame.pts_ns / 1000) {
+            if feed(
+                &codec,
+                &client,
+                &frame.data,
+                frame.pts_ns / 1000,
+                &mut oversized_dropped,
+            ) {
                 fed += 1;
                 if fed % 300 == 0 {
                     log::info!("decode: fed={fed} rendered={rendered} discarded={discarded}");
@@ -308,7 +329,8 @@ fn run_sync(
             wait,
             &stats,
             &mut in_flight,
-            clock_offset,
+            clock_offset.load(Ordering::Relaxed),
+            &tracker,
         );
         rendered += r;
         discarded += d;
@@ -367,6 +389,11 @@ fn run_sync(
     }
 
     let _ = codec.stop();
+    drop(codec); // AMediaCodec_delete — after this no render callback can fire
+    if let Some(ud) = render_cb {
+        // SAFETY: the codec was dropped above; this registration's single reclaim.
+        unsafe { release_render_callback(ud) };
+    }
     log::info!("decode: stopped (fed={fed} rendered={rendered} discarded={discarded})");
 }
 
@@ -380,6 +407,174 @@ fn now_realtime_ns() -> i128 {
         .unwrap_or(0)
 }
 
+/// `CLOCK_MONOTONIC` now in nanoseconds — the base of the `systemNano` render timestamp the
+/// `OnFrameRendered` callback reports (Android's `System.nanoTime`), read only to re-base that
+/// stamp onto `CLOCK_REALTIME` (see [`on_frame_rendered`]).
+fn now_monotonic_ns() -> i128 {
+    let mut ts = libc::timespec {
+        tv_sec: 0,
+        tv_nsec: 0,
+    };
+    // SAFETY: `clock_gettime` with a valid out-pointer is an always-safe syscall.
+    unsafe { libc::clock_gettime(libc::CLOCK_MONOTONIC, &mut ts) };
+    ts.tv_sec as i128 * 1_000_000_000 + ts.tv_nsec as i128
+}
+
+/// State shared between the decode loop and the `AMediaCodec` `OnFrameRendered` callback (which
+/// fires on a codec-internal thread): rendered frames awaiting their render timestamp, so the HUD
+/// gets the spec's `display` stage (decoded→displayed) and the `capture→displayed` end-to-end
+/// headline (`design/stats-unification.md` — this replaces Android's v1 `capture→decoded`
+/// endpoint whenever the platform delivers render callbacks).
+struct DisplayTracker {
+    stats: Arc<crate::stats::VideoStats>,
+    /// Live host-minus-client clock offset (ns) for the skew-corrected end-to-end sample —
+    /// loaded per callback so mid-stream re-syncs apply. Holding the handle (not the client)
+    /// keeps the leaked render-callback refcount from pinning the whole session alive.
+    clock_offset: Arc<AtomicI64>,
+    /// `(pts_us, decoded_real_ns)` of frames released with `render = true`, in release order,
+    /// awaiting their callback. Pushes are HUD-gated by the caller, so this stays empty (and the
+    /// callback early-outs) while the overlay is hidden.
+    rendered: Mutex<VecDeque<(u64, i128)>>,
+}
+
+impl DisplayTracker {
+    fn new(
+        stats: Arc<crate::stats::VideoStats>,
+        clock_offset: Arc<AtomicI64>,
+    ) -> Arc<DisplayTracker> {
+        Arc::new(DisplayTracker {
+            stats,
+            clock_offset,
+            rendered: Mutex::new(VecDeque::new()),
+        })
+    }
+
+    /// Park one just-rendered frame's `(pts, decoded stamp)` for the render callback to pair.
+    /// Caller gates on the HUD being visible.
+    fn note_rendered(&self, pts_us: u64, decoded_ns: i128) {
+        let mut g = self
+            .rendered
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner);
+        g.push_back((pts_us, decoded_ns));
+        if g.len() > RENDERED_CAP {
+            g.pop_front(); // render callbacks stopped coming (allowed under load) — evict
+        }
+    }
+}
+
+/// Register [`on_frame_rendered`] on the codec (`AMediaCodec_setOnFrameRenderedCallback`,
+/// **API 33** — "Available since Android T" per the NDK header; only the *Java* listener dates
+/// back further). That sits above the API-28 floor, so the entry point is dlsym-resolved at
+/// runtime like [`try_set_frame_rate`] — hard-linking it (as 0.9.0 shipped) made
+/// `System.loadLibrary` fail on every pre-Android-13 device, taking down all of `NativeBridge`.
+/// The `ndk` wrapper has no binding and the call needs the raw codec pointer, which is what the
+/// vendored crate's public `as_ptr` patch is for. Returns the userdata pointer holding a leaked
+/// `Arc<DisplayTracker>` refcount; the caller MUST reclaim it with [`release_render_callback`]
+/// AFTER dropping the codec (`AMediaCodec_delete` is what guarantees no further callback can
+/// fire). `None` (nothing to reclaim) if the symbol is absent (API < 33) or the platform refused —
+/// the HUD then simply has no `display` stage, exactly the pre-callback behaviour.
+fn install_render_callback(
+    codec: &MediaCodec,
+    tracker: &Arc<DisplayTracker>,
+) -> Option<*const DisplayTracker> {
+    // media_status_t AMediaCodec_setOnFrameRenderedCallback(
+    //     AMediaCodec*, AMediaCodecOnFrameRendered, void*)                            (API 33)
+    type SetOnFrameRenderedFn = unsafe extern "C" fn(
+        *mut ndk_sys::AMediaCodec,
+        ndk_sys::AMediaCodecOnFrameRendered,
+        *mut c_void,
+    ) -> ndk_sys::media_status_t;
+    // SAFETY: `dlopen` of `libmediandk.so`, which the `ndk` media wrapper already links — always
+    // mapped, so this only bumps its refcount (never closed — process-lifetime handle). `dlsym`
+    // returns null when the symbol is absent (device below API 33), checked before transmuting the
+    // non-null pointer to its fn-pointer type.
+    let set_on_frame_rendered = unsafe {
+        let lib = libc::dlopen(c"libmediandk.so".as_ptr(), libc::RTLD_NOW);
+        if lib.is_null() {
+            return None;
+        }
+        let sym = libc::dlsym(lib, c"AMediaCodec_setOnFrameRenderedCallback".as_ptr());
+        if sym.is_null() {
+            log::info!("decode: no render callback on this API level (<33) — no display stage");
+            return None;
+        }
+        std::mem::transmute::<*mut c_void, SetOnFrameRenderedFn>(sym)
+    };
+    let ud = Arc::into_raw(tracker.clone());
+    // SAFETY: `codec.as_ptr()` is the live codec this thread owns; `ud` outlives the registration
+    // (reclaimed only after the codec is deleted, per this function's contract).
+    let status = unsafe {
+        set_on_frame_rendered(codec.as_ptr(), Some(on_frame_rendered), ud as *mut c_void)
+    };
+    if status == ndk_sys::media_status_t::AMEDIA_OK {
+        Some(ud)
+    } else {
+        log::warn!("decode: setOnFrameRenderedCallback failed ({status:?}) — no display stage");
+        // SAFETY: registration failed, so the codec never took the reference — reclaim it now.
+        unsafe { drop(Arc::from_raw(ud)) };
+        None
+    }
+}
+
+/// Reclaim [`install_render_callback`]'s leaked `Arc` refcount.
+///
+/// # Safety
+/// Call exactly once, and only after the codec the callback was registered on has been dropped —
+/// deleting the codec stops its internal threads, so no callback can still be running (or run
+/// later) against this pointer.
+unsafe fn release_render_callback(ud: *const DisplayTracker) {
+    drop(Arc::from_raw(ud));
+}
+
+/// The `AMediaCodecOnFrameRendered` trampoline: fires (possibly batched) on a codec-internal
+/// thread once per output frame actually placed on the output surface, with SurfaceFlinger's
+/// render timestamp. That timestamp (`system_nano`) is on `CLOCK_MONOTONIC`, so it is re-based
+/// onto `CLOCK_REALTIME` here — against monotonic-now at callback time, which also cancels any lag
+/// between the frame rendering and the (batchable) callback delivery — to subtract against the
+/// receipt/decode stamps and the host capture pts. Records the HUD's `displayed` point:
+/// `end-to-end` = capture→displayed (skew-corrected) and `display` = decoded→displayed
+/// (single-clock local). Panic-free by construction (poison-proof lock, saturating math) — an
+/// unwind out of an `extern "C"` fn would abort the process.
+unsafe extern "C" fn on_frame_rendered(
+    _codec: *mut ndk_sys::AMediaCodec,
+    userdata: *mut c_void,
+    media_time_us: i64,
+    system_nano: i64,
+) {
+    let t = &*(userdata as *const DisplayTracker);
+    if !t.stats.enabled() {
+        return; // HUD hidden — the ring is empty too (pushes are caller-gated)
+    }
+    let displayed_ns = now_realtime_ns() - (now_monotonic_ns() - system_nano as i128);
+    let pts_us = media_time_us.max(0) as u64;
+    // Pair the frame back to its release record, evicting older entries (their callbacks were
+    // dropped by the platform, or the entry predates a HUD toggle) — same monotonic-eviction
+    // discipline as `note_decoded_pts`.
+    let mut decoded_ns = None;
+    {
+        let mut g = t
+            .rendered
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner);
+        while let Some(&(p, d)) = g.front() {
+            if p > pts_us {
+                break; // future frame — leave it for its own callback
+            }
+            g.pop_front();
+            if p == pts_us {
+                decoded_ns = Some(d);
+                break;
+            }
+        }
+    }
+    let e2e_ns =
+        displayed_ns + t.clock_offset.load(Ordering::Relaxed) as i128 - pts_us as i128 * 1000;
+    let e2e_us = (e2e_ns > 0 && e2e_ns < 10_000_000_000).then_some((e2e_ns / 1000) as u64);
+    let display_us = decoded_ns.map(|d| ((displayed_ns - d).max(0) / 1000) as u64);
+    t.stats.note_displayed(e2e_us, display_us);
+}
+
 /// The MediaCodec MIME for the codec the host resolved (`Welcome.codec`). Shared by the decode
 /// thread and `nativeVideoMime` (which tells Kotlin what to rank decoders for). AV1 uses the
 /// AOSP `video/av01` type; anything not H.264/AV1 is treated as HEVC (every pre-negotiation host
@@ -409,10 +604,10 @@ fn create_codec(mime: &str, preferred: Option<&str>) -> Option<MediaCodec> {
 
 /// Apply the low-latency MediaFormat keys for `codec_name`.
 ///
-/// `aggressive` = the "Low-latency mode (experimental)" master toggle. **Off** (default) ⇒ the
-/// pre-overhaul key set, byte-for-byte — the standard `low-latency` key, the blind Qualcomm vendor
-/// twin, `priority = 0` AND `operating-rate = MAX` set together — kept as the known-good baseline
-/// (the profile every device streamed with before the overhaul). **On** ⇒ the Moonlight-parity
+/// `aggressive` = the "Low-latency mode" master toggle. **Off** ⇒ the pre-overhaul key set,
+/// byte-for-byte — the standard `low-latency` key, the blind Qualcomm vendor twin, `priority = 0` AND
+/// `operating-rate = MAX` set together — kept as the per-device escape hatch (the profile every device
+/// streamed with before the overhaul). **On** (default) ⇒ the Moonlight-parity
 /// profile: MediaTek's `vdec-lowlatency` (unconditionally — ignored off MediaTek), the per-SoC
 /// vendor extension keys (gated on the decoder-name prefix the way Moonlight-Android does, since a
 /// key one vendor honours is meaningless on another), and one *mutually exclusive* clock hint.
@@ -493,10 +688,14 @@ fn decoder_supports_max_operating_rate(name_lower: &str) -> bool {
 }
 
 /// One decoded output buffer ready to release: its codec buffer index + the pts the codec echoed
-/// (from the output callback's `BufferInfo`), used to pair the `decode` HUD stat.
+/// (from the output callback's `BufferInfo`), used to pair the `decode` HUD stat, and the
+/// wall-clock instant the output callback fired — the spec's `decoded` point ("decoder output
+/// frame available"), stamped at the callback so the event-channel hop + coalescing wait in the
+/// loop never inflates the decode stage.
 struct OutputReady {
     index: usize,
     pts_us: u64,
+    decoded_ns: i128,
 }
 
 /// Events the async decode loop reacts to. The codec's async-notify callbacks (which run on its
@@ -507,8 +706,12 @@ enum DecodeEvent {
     Au(Frame),
     /// An input buffer slot freed (index) — we can queue an AU into it.
     InputAvailable(usize),
-    /// A decoded frame is ready (buffer index + echoed pts).
-    OutputAvailable { index: usize, pts_us: u64 },
+    /// A decoded frame is ready (buffer index + echoed pts + the callback-time `decoded` stamp).
+    OutputAvailable {
+        index: usize,
+        pts_us: u64,
+        decoded_ns: i128,
+    },
     /// The output format changed — re-check the stream's colour signalling (HDR DataSpace).
     FormatChanged,
     /// The codec reported an error; `fatal` when neither recoverable nor transient.
@@ -569,6 +772,10 @@ fn run_async(
                 let _ = out_tx.send(DecodeEvent::OutputAvailable {
                     index: idx,
                     pts_us: info.presentation_time_us().max(0) as u64,
+                    // The `decoded` HUD point: stamp HERE, on the codec's looper thread, so the
+                    // decode stage ends when the frame actually became available — not after the
+                    // channel hop + whatever work the loop coalesces in front of presenting it.
+                    decoded_ns: now_realtime_ns(),
                 });
             })),
             on_format_changed: Some(Box::new(move |_fmt| {
@@ -635,8 +842,14 @@ fn run_async(
     // pts we queue) live in a shared map: the feeder writes them at receipt, this loop pairs decoded
     // output back to them. Behind a `Mutex` since two threads touch it — only ever locked while the
     // HUD is visible.
-    let clock_offset = client.clock_offset_ns;
+    let clock_offset = client.clock_offset_shared();
     let in_flight = Arc::new(Mutex::new(VecDeque::<(u64, i128)>::new()));
+    // Display stage (spec `display` + the capture→displayed headline): the rendered frame is
+    // parked in the tracker at release; the OnFrameRendered callback pairs it with
+    // SurfaceFlinger's render timestamp. `render_cb` is the callback's leaked Arc refcount,
+    // reclaimed after the codec is dropped below.
+    let tracker = DisplayTracker::new(stats.clone(), clock_offset.clone());
+    let render_cb = install_render_callback(&codec, &tracker);
 
     // Feeder thread: block on the network so this loop doesn't (an AU's arrival becomes an event that
     // wakes us immediately, with no input-side poll latency). It also records the `received` HUD stat.
@@ -644,19 +857,13 @@ fn run_async(
         let client = client.clone();
         let stats = stats.clone();
         let in_flight = in_flight.clone();
+        let clock_offset = clock_offset.clone();
         let shutdown = shutdown.clone();
         let ev_tx = ev_tx.clone();
         std::thread::Builder::new()
             .name("pf-decode-feed".into())
             .spawn(move || {
-                feeder_loop(
-                    client,
-                    stats,
-                    in_flight,
-                    clock_offset as i128,
-                    shutdown,
-                    ev_tx,
-                );
+                feeder_loop(client, stats, in_flight, clock_offset, shutdown, ev_tx);
             })
             .ok()
     };
@@ -680,6 +887,8 @@ fn run_async(
     let mut fed: u64 = 0;
     let mut rendered: u64 = 0;
     let mut discarded: u64 = 0;
+    // AUs larger than the codec input buffer, dropped whole (see `feed`/`feed_ready`).
+    let mut oversized_dropped: u64 = 0;
     let mut last_dropped = client.frames_dropped();
     let mut last_kf_req: Option<Instant> = None;
     // Productive (dispatch+feed+present) time between displayed frames; reported to ADPF once one is
@@ -697,40 +906,49 @@ fn run_async(
         };
         let work_t0 = Instant::now();
         let mut fmt_dirty = false;
-        let mut au_dropped = false;
+        let mut aus_dropped: u64 = 0;
         if let Some(ev) = ev0 {
-            au_dropped |= dispatch_event(
+            aus_dropped += u64::from(dispatch_event(
                 ev,
                 &mut pending_aus,
                 &mut free_inputs,
                 &mut ready,
                 &mut fmt_dirty,
                 &mut fatal,
-            );
+            ));
         }
         // Coalesce every other event already queued into this one work pass — correct newest-only
         // presentation across a decode burst, and batched feeding.
         while let Ok(ev) = ev_rx.try_recv() {
-            au_dropped |= dispatch_event(
+            aus_dropped += u64::from(dispatch_event(
                 ev,
                 &mut pending_aus,
                 &mut free_inputs,
                 &mut ready,
                 &mut fmt_dirty,
                 &mut fatal,
-            );
+            ));
         }
+        stats.note_skipped(aus_dropped); // parked-AU overflow drops are client-side skips too
         if fmt_dirty {
             apply_hdr_dataspace(&codec, &window, &mut applied_ds);
         }
-        feed_ready(&codec, &mut pending_aus, &mut free_inputs, &mut fed);
+        feed_ready(
+            &codec,
+            &client,
+            &mut pending_aus,
+            &mut free_inputs,
+            &mut fed,
+            &mut oversized_dropped,
+        );
         let had_output = !ready.is_empty();
         present_ready(
             &codec,
             &mut ready,
             &stats,
             &in_flight,
-            clock_offset,
+            clock_offset.load(Ordering::Relaxed),
+            &tracker,
             &mut rendered,
             &mut discarded,
         );
@@ -768,7 +986,7 @@ fn run_async(
         // dropped a parked AU on overflow), throttled so a multi-frame recovery gap doesn't flood the
         // control stream.
         let dropped = client.frames_dropped();
-        if dropped > last_dropped || au_dropped {
+        if dropped > last_dropped || aus_dropped > 0 {
             last_dropped = dropped;
             let now = Instant::now();
             if last_kf_req.is_none_or(|t| now.duration_since(t) >= Duration::from_millis(100)) {
@@ -783,6 +1001,11 @@ fn run_async(
     if let Some(j) = feeder {
         let _ = j.join();
     }
+    drop(codec); // AMediaCodec_delete — after this no render callback can fire
+    if let Some(ud) = render_cb {
+        // SAFETY: the codec was dropped above; this registration's single reclaim.
+        unsafe { release_render_callback(ud) };
+    }
     log::info!("decode: stopped (async, fed={fed} rendered={rendered} discarded={discarded})");
 }
 
@@ -794,7 +1017,7 @@ fn feeder_loop(
     client: Arc<NativeClient>,
     stats: Arc<crate::stats::VideoStats>,
     in_flight: Arc<Mutex<VecDeque<(u64, i128)>>>,
-    clock_offset: i128,
+    clock_offset: Arc<AtomicI64>,
     shutdown: Arc<AtomicBool>,
     ev_tx: mpsc::Sender<DecodeEvent>,
 ) {
@@ -805,6 +1028,7 @@ fn feeder_loop(
             Ok(frame) => {
                 if stats.enabled() {
                     let received_ns = now_realtime_ns();
+                    let clock_offset = clock_offset.load(Ordering::Relaxed) as i128;
                     let lat_ns = received_ns + clock_offset - frame.pts_ns as i128;
                     let lat_us =
                         (lat_ns > 0 && lat_ns < 10_000_000_000).then_some((lat_ns / 1000) as u64);
@@ -863,7 +1087,15 @@ fn dispatch_event(
             }
         }
         DecodeEvent::InputAvailable(i) => free_inputs.push_back(i),
-        DecodeEvent::OutputAvailable { index, pts_us } => ready.push(OutputReady { index, pts_us }),
+        DecodeEvent::OutputAvailable {
+            index,
+            pts_us,
+            decoded_ns,
+        } => ready.push(OutputReady {
+            index,
+            pts_us,
+            decoded_ns,
+        }),
         DecodeEvent::FormatChanged => *fmt_dirty = true,
         DecodeEvent::Error { fatal: f } => {
             if f {
@@ -876,12 +1108,15 @@ fn dispatch_event(
 
 /// Queue as many parked AUs as there are free input buffer slots (async mode: the indices come from
 /// `InputAvailable` callbacks, not a dequeue). Each AU is copied into its codec input buffer and
-/// submitted; a too-large AU is truncated (logged) rather than dropped.
+/// submitted; an AU larger than the buffer is DROPPED (+ a recovery keyframe requested) — a
+/// truncated AU is corrupt input the decoder chews on silently, poisoning the reference chain.
 fn feed_ready(
     codec: &MediaCodec,
+    client: &NativeClient,
     pending_aus: &mut VecDeque<Frame>,
     free_inputs: &mut VecDeque<usize>,
     fed: &mut u64,
+    oversized_dropped: &mut u64,
 ) {
     while !pending_aus.is_empty() && !free_inputs.is_empty() {
         let idx = free_inputs.pop_front().unwrap();
@@ -892,14 +1127,20 @@ fn feed_ready(
             continue;
         };
         let au = &frame.data;
-        let n = au.len().min(dst.len());
-        if n < au.len() {
+        if au.len() > dst.len() {
+            // The slot was never queued, so it stays ours — recycle it for the next AU.
+            free_inputs.push_front(idx);
+            *oversized_dropped += 1;
             log::warn!(
-                "decode: AU {} > input buffer {}, truncated",
+                "decode: AU {} > input buffer {} — dropped ({} so far), requesting keyframe",
                 au.len(),
-                dst.len()
+                dst.len(),
+                *oversized_dropped
             );
+            let _ = client.request_keyframe();
+            continue;
         }
+        let n = au.len();
         // SAFETY: `au` (wire AU) and `dst` (codec input buffer) are distinct allocations, both valid
         // for `n` bytes; `MaybeUninit<u8>` is layout-identical to `u8`, so this initializes dst[..n].
         unsafe {
@@ -917,13 +1158,17 @@ fn feed_ready(
 /// burst of stale frames on glass is worse than skipping to the freshest (the sync loop's newest-ready
 /// policy, callback-driven). Every dequeued buffer, rendered or not, is the HUD's `decoded`
 /// measurement point (it finished decoding either way); samples are recorded in pts order so the
-/// receipt-map eviction stays monotonic. `ready` is drained.
+/// receipt-map eviction stays monotonic. The presented frame's `(pts, decoded stamp)` is parked in
+/// `tracker` for the OnFrameRendered callback — the `display` stage's other endpoint. `ready` is
+/// drained.
+#[allow(clippy::too_many_arguments)] // one call site; mirrors the sync loop's drain
 fn present_ready(
     codec: &MediaCodec,
     ready: &mut Vec<OutputReady>,
     stats: &crate::stats::VideoStats,
     in_flight: &Mutex<VecDeque<(u64, i128)>>,
     clock_offset: i64,
+    tracker: &DisplayTracker,
     rendered: &mut u64,
     discarded: &mut u64,
 ) {
@@ -935,15 +1180,24 @@ fn present_ready(
             .lock()
             .unwrap_or_else(std::sync::PoisonError::into_inner);
         for o in ready.iter() {
-            note_decoded_pts(stats, &mut g, clock_offset, o.pts_us);
+            note_decoded_pts(stats, &mut g, clock_offset, o.pts_us, o.decoded_ns);
         }
     }
     let last = ready.len() - 1;
+    let mut skipped: u64 = 0;
     for (i, o) in ready.drain(..).enumerate() {
         let render = i == last;
         match codec.release_output_buffer_by_index(o.index, render) {
-            Ok(()) if render => *rendered += 1,
-            Ok(()) => *discarded += 1,
+            Ok(()) if render => {
+                *rendered += 1;
+                if stats.enabled() {
+                    tracker.note_rendered(o.pts_us, o.decoded_ns);
+                }
+            }
+            Ok(()) => {
+                *discarded += 1;
+                skipped += 1;
+            }
             Err(e) => {
                 log::warn!(
                     "decode: release_output_buffer_by_index({}, {render}): {e}",
@@ -952,6 +1206,7 @@ fn present_ready(
             }
         }
     }
+    stats.note_skipped(skipped); // HUD `skipped` counter (newest-wins drops); no-op while hidden
 }
 
 /// React to an output-format change by signalling the stream's HDR dataspace on the Surface (SDR
@@ -1071,27 +1326,44 @@ fn try_set_frame_rate(window: &NativeWindow, frame_rate: f32, is_tv: bool) -> bo
 /// Try to copy one access unit into a codec input buffer and queue it, without blocking. Returns
 /// `false` only on `TryAgainLater` (no input buffer free) — the caller keeps the AU pending and
 /// retries; a hard dequeue/queue error counts as consumed (retrying can't salvage the AU, and
-/// parking it forever would wedge the loop on a broken codec).
-fn feed(codec: &MediaCodec, au: &[u8], pts_us: u64) -> bool {
+/// parking it forever would wedge the loop on a broken codec). An AU larger than the input
+/// buffer is DROPPED (+ a recovery keyframe requested), never truncated — a truncated AU is
+/// corrupt input the decoder chews on silently, poisoning the reference chain.
+fn feed(
+    codec: &MediaCodec,
+    client: &NativeClient,
+    au: &[u8],
+    pts_us: u64,
+    oversized_dropped: &mut u64,
+) -> bool {
     match codec.dequeue_input_buffer(Duration::ZERO) {
         Ok(DequeuedInputBufferResult::Buffer(mut buf)) => {
             let n = {
                 let dst = buf.buffer_mut();
-                let n = au.len().min(dst.len());
-                if n < au.len() {
+                if au.len() > dst.len() {
+                    *oversized_dropped += 1;
                     log::warn!(
-                        "decode: AU {} > input buffer {}, truncated",
+                        "decode: AU {} > input buffer {} — dropped ({} so far), requesting keyframe",
                         au.len(),
-                        dst.len()
+                        dst.len(),
+                        *oversized_dropped
                     );
+                    let _ = client.request_keyframe();
+                    0 // return the slot with zero valid bytes — a no-op input, not corrupt data
+                } else {
+                    let n = au.len();
+                    // SAFETY: `au` and `dst` are distinct allocations (wire AU vs. codec buffer),
+                    // both valid for `n` bytes; `MaybeUninit<u8>` is layout-identical to `u8`, so
+                    // the cast write initializes exactly `dst[..n]`.
+                    unsafe {
+                        std::ptr::copy_nonoverlapping(
+                            au.as_ptr(),
+                            dst.as_mut_ptr().cast::<u8>(),
+                            n,
+                        );
+                    }
+                    n
                 }
-                // SAFETY: `au` and `dst` are distinct allocations (wire AU vs. codec buffer), both
-                // valid for `n` bytes; `MaybeUninit<u8>` is layout-identical to `u8`, so the cast
-                // write initializes exactly `dst[..n]`.
-                unsafe {
-                    std::ptr::copy_nonoverlapping(au.as_ptr(), dst.as_mut_ptr().cast::<u8>(), n);
-                }
-                n
             };
             if let Err(e) = codec.queue_input_buffer(buf, 0, n, pts_us, 0) {
                 log::warn!("decode: queue_input_buffer: {e}");
@@ -1117,7 +1389,10 @@ fn feed(codec: &MediaCodec, au: &[u8], pts_us: u64) -> bool {
 /// Each dequeued buffer is also the HUD's `decoded` measurement point (rendered or not — the frame
 /// finished decoding either way): end-to-end = decoded + clock_offset − capture pts, and the
 /// `decode` stage pairs the buffer's echoed presentationTimeUs back to the receipt stamp in
-/// `in_flight` (single-clock local difference, no skew involved).
+/// `in_flight` (single-clock local difference, no skew involved). The presented frame's
+/// `(pts, decoded stamp)` is additionally parked in `tracker` for the OnFrameRendered callback —
+/// the `display` stage's other endpoint.
+#[allow(clippy::too_many_arguments)] // one call site; mirrors the async loop's present_ready
 fn drain(
     codec: &MediaCodec,
     window: &NativeWindow,
@@ -1126,23 +1401,33 @@ fn drain(
     stats: &crate::stats::VideoStats,
     in_flight: &mut VecDeque<(u64, i128)>,
     clock_offset: i64,
+    tracker: &DisplayTracker,
 ) -> (u64, u64) {
-    let mut held = None; // newest ready buffer so far, presented after the loop
+    // Newest ready buffer so far (presented after the loop) with its HUD metadata —
+    // `Some((pts_us, decoded_ns))` only while the HUD is visible (the stamp read is gated).
+    let mut held: Option<(OutputBuffer<'_>, Option<(u64, i128)>)> = None;
     let mut discarded: u64 = 0;
     let mut wait = first_wait;
     loop {
         match codec.dequeue_output_buffer(wait) {
             Ok(DequeuedOutputBufferInfoResult::Buffer(buf)) => {
                 wait = Duration::ZERO; // only the first dequeue may block
-                if stats.enabled() {
-                    note_decoded(stats, in_flight, clock_offset, &buf);
-                }
-                if let Some(stale) = held.replace(buf) {
+                let meta = if stats.enabled() {
+                    // The dequeue IS the sync loop's decoded-availability instant.
+                    let pts_us = buf.info().presentation_time_us().max(0) as u64;
+                    let decoded_ns = now_realtime_ns();
+                    note_decoded_pts(stats, in_flight, clock_offset, pts_us, decoded_ns);
+                    Some((pts_us, decoded_ns))
+                } else {
+                    None
+                };
+                if let Some((stale, _)) = held.replace((buf, meta)) {
                     // A newer frame is ready — drop the held one without rendering.
                     if let Err(e) = codec.release_output_buffer(stale, false) {
                         log::warn!("decode: release_output_buffer(discard): {e}");
                     }
                     discarded += 1;
+                    stats.note_skipped(1); // HUD `skipped` counter; no-op while hidden
                 }
             }
             Ok(DequeuedOutputBufferInfoResult::OutputFormatChanged) => {
@@ -1175,46 +1460,37 @@ fn drain(
             }
         }
     }
-    // Present the newest ready frame, if any.
+    // Present the newest ready frame, if any, and park its metadata for the render callback.
     let mut rendered = 0;
-    if let Some(buf) = held {
+    if let Some((buf, meta)) = held {
         match codec.release_output_buffer(buf, true) {
-            Ok(()) => rendered = 1,
+            Ok(()) => {
+                rendered = 1;
+                if let Some((pts_us, decoded_ns)) = meta {
+                    tracker.note_rendered(pts_us, decoded_ns);
+                }
+            }
             Err(e) => log::warn!("decode: release_output_buffer: {e}"),
         }
     }
     (rendered, discarded)
 }
 
-/// HUD `decoded` point for one dequeued output buffer: build the end-to-end (capture→decoded,
-/// skew-corrected, clamped to (0, 10 s)) and `decode` (received→decoded, single-clock local, ≥ 0)
-/// samples and hand them to [`crate::stats::VideoStats::note_decoded`]. The codec echoes the input
-/// `presentationTimeUs` on the output buffer, which keys the receipt stamp in `in_flight`; entries
-/// older than the echoed pts are evicted (decode order == input order here — low-latency, no
+/// HUD `decoded` point for one dequeued output frame, keyed by the echoed `presentationTimeUs`:
+/// build the end-to-end (capture→decoded, skew-corrected, clamped to (0, 10 s)) and `decode`
+/// (received→decoded, single-clock local, ≥ 0) samples and hand them to
+/// [`crate::stats::VideoStats::note_decoded`]. The pts keys the receipt stamp in `in_flight`;
+/// entries older than it are evicted (decode order == input order here — low-latency, no
 /// B-frames — so anything before it was dropped inside the codec or stamped before a flush).
-fn note_decoded(
-    stats: &crate::stats::VideoStats,
-    in_flight: &mut VecDeque<(u64, i128)>,
-    clock_offset: i64,
-    buf: &OutputBuffer<'_>,
-) {
-    note_decoded_pts(
-        stats,
-        in_flight,
-        clock_offset,
-        buf.info().presentation_time_us().max(0) as u64,
-    );
-}
-
-/// The [`note_decoded`] body keyed by the echoed `presentationTimeUs` directly — the async loop has
-/// the pts (from the output callback's `BufferInfo`) but no borrowed `OutputBuffer`, so it calls this.
+/// `decoded_ns` is the availability instant: the dequeue (sync loop) or the output callback's
+/// stamp (async loop).
 fn note_decoded_pts(
     stats: &crate::stats::VideoStats,
     in_flight: &mut VecDeque<(u64, i128)>,
     clock_offset: i64,
     pts_us: u64,
+    decoded_ns: i128,
 ) {
-    let decoded_ns = now_realtime_ns();
     // Pair the echoed pts back to its receipt stamp, evicting stale (older) entries as we go.
     let mut received_ns = None;
     while let Some(&(p, r)) = in_flight.front() {

clients/android/native/src/discovery.rs

@@ -1,5 +1,5 @@
 //! 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.
+//! Linux/Windows clients use (`crates/pf-client-core/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

clients/android/native/src/feedback.rs

@@ -24,8 +24,12 @@ 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.
+/// Returns a packed positive long: bit 48 = "has a v2 lease", bits 32..47 = `ttl_ms`, bits 16..31 =
+/// `low`, bits 0..15 = `high` (`low`/`high` 0..=0xFFFF, `0/0` = stop). The lease flag is
+/// out-of-band so ANY 16-bit `ttl_ms` — including 0xFFFF — is unambiguous (no in-band sentinel to
+/// collide with a real 65535 ms lease). No lease (legacy host) → bit 48 clear, and Kotlin falls
+/// back to its long one-shot. `-1` on timeout / session closed (all packed values are positive, so
+/// `-1` stays unambiguous). Pad index is dropped (single-pad model). Run from a Kotlin poll thread.
 #[no_mangle]
 pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeNextRumble(
     _env: JNIEnv,
@@ -37,12 +41,20 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeNextRumble(
         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
+        // SAFETY: live handle per the nativeConnect/nativeClose contract; next_rumble_ttl 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),
+        match h.client.next_rumble_ttl(PULL_TIMEOUT) {
+            Ok((_pad, low, high, ttl)) => {
+                // The reorder gate already ran in the core, so this update is fresh. Encode the
+                // Option out-of-band: a real lease sets bit 48 and carries ttl_ms verbatim.
+                let (lease_flag, ttl_bits) = match ttl {
+                    Some(ms) => (1i64 << 48, jlong::from(ms) << 32),
+                    None => (0, 0),
+                };
+                lease_flag | ttl_bits | (jlong::from(low) << 16) | jlong::from(high)
+            }
             Err(_) => -1, // NoFrame (timeout) or Closed — Kotlin loops on its running flag
         }
     })

clients/android/native/src/lib.rs

@@ -42,6 +42,9 @@ mod stats;
 // Ungated like `discovery`: pure `jni` + `punktfunk_core::wol` (no Android framework), so it links
 // into the host workspace build too. Kotlin only ever calls it on device.
 mod wol;
+// Ungated like `wol`: pure `jni` + `punktfunk_core::client` (the reachability probe). Kotlin calls
+// it off the main thread to light saved-host "online" pips independently of mDNS.
+mod probe;
 
 /// Initialize `android_logger` once when the JVM loads the library. Logs land in logcat under the
 /// `punktfunk` tag. Core `tracing` events (transport warnings: socket-buffer clamp, QoS failures)

clients/android/native/src/probe.rs

@@ -0,0 +1,36 @@
+//! JNI seam for the reachability probe: a bounded, trust-agnostic QUIC handshake to a saved host
+//! (`punktfunk_core::client::NativeClient::probe`). Like [`crate::wol`] it takes no session handle
+//! and links into the host workspace build (pure `jni` + `punktfunk_core`). Kotlin calls it
+//! periodically, on a background dispatcher, to light the "online" pip for saved hosts that never
+//! advertise on mDNS (reached over Tailscale / VPN / another subnet) — the display-side companion
+//! to the dial-first connect fix.
+
+use jni::objects::{JObject, JString};
+use jni::sys::{jboolean, jint};
+use jni::JNIEnv;
+use punktfunk_core::client::NativeClient;
+use std::time::Duration;
+
+/// `NativeBridge.nativeProbe(host, port, timeoutMs): Boolean` — true if `host:port` completed a
+/// QUIC handshake within `timeoutMs`. No pin/identity presented (trust-agnostic), mDNS-independent.
+/// Blocking (builds its own runtime) — Kotlin runs it on `Dispatchers.IO`, never the main thread.
+#[no_mangle]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeProbe<'local>(
+    mut env: JNIEnv<'local>,
+    _this: JObject<'local>,
+    host: JString<'local>,
+    port: jint,
+    timeout_ms: jint,
+) -> jboolean {
+    let host: String = match env.get_string(&host) {
+        Ok(s) => s.into(),
+        Err(_) => return 0,
+    };
+    let port = port.clamp(0, u16::MAX as jint) as u16;
+    let timeout = Duration::from_millis(timeout_ms.max(0) as u64);
+    if NativeClient::probe(&host, port, timeout) {
+        1
+    } else {
+        0
+    }
+}

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

@@ -76,6 +76,7 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeConnect<'lo
     gamepad_pref: jint,
     hdr_enabled: jboolean,
     audio_channels: jint,
+    video_codecs: jint,
     preferred_codec: jint,
     timeout_ms: jint,
     launch: JString<'local>,
@@ -142,11 +143,27 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeConnect<'lo
         // decoder + AAudio layout (read in `crate::audio::AudioPlayback::start`). Anything else
         // normalizes to stereo here.
         punktfunk_core::audio::normalize_channels(audio_channels.clamp(0, u8::MAX as jint) as u8),
-        // Codecs this device can decode — AMediaCodec decodes both HEVC and H.264 (AV1 isn't wired;
-        // hosts don't emit it on the native path yet). The host resolves the emitted codec from these
-        // + the soft `preferred_codec` and echoes it in `connector.codec`, which drives the mime below.
-        punktfunk_core::quic::CODEC_H264 | punktfunk_core::quic::CODEC_HEVC,
+        // Codecs this device can decode, ranked on the Kotlin side (`VideoDecoders.decodableCodecBits`:
+        // H.264 + HEVC always, AV1 when a real `video/av01` decoder exists — AMediaCodec is
+        // mime-driven, see `codec_mime`). Mask to the known bits and fall back to the pre-AV1
+        // H.264|HEVC pair on 0 so a bogus value can't advertise nothing and kill the handshake.
+        // The host resolves the emitted codec from these + the soft `preferred_codec` and echoes it
+        // in `connector.codec`, which drives the mime below.
+        {
+            let bits = (video_codecs.clamp(0, u8::MAX as jint) as u8)
+                & (punktfunk_core::quic::CODEC_H264
+                    | punktfunk_core::quic::CODEC_HEVC
+                    | punktfunk_core::quic::CODEC_AV1);
+            if bits == 0 {
+                punktfunk_core::quic::CODEC_H264 | punktfunk_core::quic::CODEC_HEVC
+            } else {
+                bits
+            }
+        },
         preferred_codec.clamp(0, u8::MAX as jint) as u8,
+        // No display-volume forwarding from Android yet (the panel tone-maps PQ itself via the
+        // Surface dataspace + static metadata) — the host keeps its virtual-display EDID defaults.
+        None,
         launch,   // a store-qualified library id to boot into a game, or None for the desktop
         pin,      // Some → Crypto on host-fp mismatch
         identity, // owned (cert, key) PEM, or None (anonymous)

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

@@ -144,16 +144,25 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeStopVideo(
 }
 
 /// `NativeBridge.nativeVideoStats(handle): DoubleArray?` — drain ~1 s of decode stats for the HUD
-/// (unified stats spec, `design/stats-unification.md`). Returns 18 doubles
+/// (unified stats spec, `design/stats-unification.md`). Returns 26 doubles
 /// `[fps, mbps, e2eP50Ms, e2eP95Ms, latValid, skewCorrected, width, height, refreshHz, framesLost,
 /// bitDepth, colorPrimaries, colorTransfer, chromaFormatIdc, hostNetP50Ms, decodeP50Ms, hostP50Ms,
-/// netP50Ms]`
-/// (the two flags are 1.0/0.0; indexes 0–15 match the previous 16-double layout — 0–13 the original
+/// netP50Ms, lostWindow, skippedWindow, fecWindow, framesWindow, dispValid, displayP50Ms,
+/// e2eDispP50Ms, e2eDispP95Ms]`
+/// (the flags are 1.0/0.0; indexes 0–21 match the previous 22-double layout — 0–13 the original
 /// 14-double one with the latency pair re-based to the end-to-end capture→decoded headline, 14/15
 /// the stage p50s tiling it: `host+network` = capture→received, `decode` = received→decoded; 16/17
 /// are the Phase-2 split of the `host+network` term from the per-AU 0xCF host timings — `host` =
 /// the host's capture→sent, `network` = the remainder — both 0.0 when no timing matched this
-/// window, i.e. an old host), or `null` when no decode thread is running. Poll ~1 Hz from the UI; each call
+/// window, i.e. an old host; 18–21 are the spec's per-window line-4 counters — `lost` =
+/// unrecoverable drops this window, `skipped` = client newest-wins/pacing drops, `fec` = shards
+/// recovered, `frames` = AUs received, so the HUD can compute `lost/(frames+lost)` — index 9 stays
+/// the cumulative session total for older readers; 22–25 are the `display` stage from the
+/// OnFrameRendered render timestamps — when `dispValid` is 1.0 the HUD headline becomes the
+/// directly-measured capture→displayed pair at 24/25 with `display` = decoded→displayed p50 at 23
+/// closing the equation, and when 0.0 — no render callback landed this window — it falls back to
+/// the capture→decoded headline at 2/3), 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]
@@ -171,10 +180,12 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeVideoStats(
         if h.video.lock().unwrap().is_none() {
             return std::ptr::null_mut(); // not streaming → no stats
         }
-        let snap = h.stats.drain();
+        let snap = h
+            .stats
+            .drain(h.client.frames_dropped(), h.client.fec_recovered_shards());
         let mode = h.client.mode();
         let color = h.client.color;
-        let buf: [f64; 18] = [
+        let buf: [f64; 26] = [
             snap.fps,
             snap.mbps,
             snap.e2e_p50_ms,
@@ -200,6 +211,21 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeVideoStats(
             // when no timing matched this window (old host) — the HUD keeps the combined term.
             snap.host_p50_ms,
             snap.net_p50_ms,
+            // Spec line-4 counters, per-window: lost (unrecoverable drops), skipped (client
+            // newest-wins/pacing drops), FEC shards recovered, and the received-AU count so the
+            // HUD computes the loss percentage `lost/(frames+lost)` exactly.
+            snap.lost as f64,
+            snap.skipped as f64,
+            snap.fec as f64,
+            snap.frames as f64,
+            // `display` stage (OnFrameRendered render timestamps): validity flag, the
+            // decoded→displayed stage p50, and the directly-measured capture→displayed headline
+            // pair that supersedes 2/3 whenever the flag is set (spec: the equation always tiles
+            // the headline interval, so endpoint and terms move together).
+            if snap.disp_valid { 1.0 } else { 0.0 },
+            snap.display_p50_ms,
+            snap.e2e_disp_p50_ms,
+            snap.e2e_disp_p95_ms,
         ];
         let arr = match env.new_double_array(buf.len() as jsize) {
             Ok(a) => a,
@@ -228,7 +254,13 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSetVideoSta
         if handle != 0 {
             // SAFETY: live handle per the nativeConnect/nativeClose contract.
             let h = unsafe { &*(handle as *const SessionHandle) };
-            h.stats.set_enabled(enabled != 0);
+            // The current cumulative counters seed the window baselines, so the first snapshot's
+            // `lost`/`FEC` cover only time the HUD was actually up.
+            h.stats.set_enabled(
+                enabled != 0,
+                h.client.frames_dropped(),
+                h.client.fec_recovered_shards(),
+            );
         }
     })
 }

clients/android/native/src/stats.rs

@@ -1,9 +1,15 @@
 //! Live decode stats for the on-stream HUD, following the unified stats spec
-//! (`design/stats-unification.md`): FPS, receive throughput, and the Android v1 stage split —
-//! headline `end-to-end` = capture→decoded (p50/p95) tiled by `host+network` = capture→received
-//! and `decode` = received→decoded (stage p50s). When the host emits per-AU 0xCF host timings, the
-//! `host+network` term further splits into `host` + `network` (Phase 2, `note_host_split`); an old
-//! host emits none and the combined term stands. The decode thread is the sole writer
+//! (`design/stats-unification.md`): FPS, receive throughput, and the full stage split — headline
+//! `end-to-end` = capture→displayed (p50/p95, measured directly from the `OnFrameRendered` render
+//! timestamps — `note_displayed`) tiled by `host+network` = capture→received, `decode` =
+//! received→decoded, and `display` = decoded→displayed (stage p50s). When the platform delivers no
+//! render callbacks (allowed under load; `disp_valid` false), the HUD falls back to the v1
+//! capture→decoded headline without the `display` term. When the host emits per-AU 0xCF host
+//! timings, the `host+network` term further splits into `host` + `network` (Phase 2,
+//! `note_host_split`); an old host emits none and the combined term stands. The spec's line-4 counters are per-window too:
+//! `lost` / `FEC` are windowed here from the connector's cumulative counters (the caller passes the
+//! current totals into `set_enabled`/`drain`), `skipped` counts the client's own newest-wins drops
+//! (`note_skipped`). The decode thread is the sole writer
 //! (`note_received` per access unit at receipt, `note_decoded` per decoder output buffer); the JNI
 //! accessor `nativeVideoStats` drains a snapshot ~1 Hz and resets the window. Sampling is gated on
 //! the HUD actually being visible (`set_enabled`, driven by `nativeSetVideoStatsEnabled`) so the
@@ -54,6 +60,21 @@ struct Inner {
     net_us: Vec<u64>,
     /// `decode` stage = received→decoded samples, in microseconds (client-local, single clock).
     decode_us: Vec<u64>,
+    /// `display` stage = decoded→displayed samples, in microseconds (client-local, single clock),
+    /// from the `OnFrameRendered` render timestamps. Empty when the platform delivers no render
+    /// callbacks — the HUD then drops the term and the headline endpoint moves back to `decoded`.
+    display_us: Vec<u64>,
+    /// `end-to-end` = capture→displayed samples, µs (skew-corrected) — the spec's headline,
+    /// measured directly (not summed from stages). Empty under the same fallback as `display_us`.
+    e2e_disp_us: Vec<u64>,
+    /// Client-side newest-wins/pacing drops this window (decoded frames released without
+    /// rendering, or parked AUs dropped on overflow) — the spec's `skipped` counter.
+    skipped: u64,
+    /// Baselines for windowing the session-cumulative connector counters: the unrecoverable-drop
+    /// and FEC-recovered totals as of the last drain (or the enable that opened the window), so
+    /// each snapshot reports only THIS window's `lost` / `FEC` (spec line 4).
+    last_dropped_total: u64,
+    last_fec_total: u64,
     /// Whether the host answered the clock-skew handshake (latency is cross-machine valid).
     skew_corrected: bool,
 }
@@ -64,18 +85,38 @@ struct Inner {
 pub struct Snapshot {
     pub fps: f64,
     pub mbps: f64,
-    /// Headline `end-to-end` (capture→decoded) percentiles, ms.
+    /// Headline `end-to-end` (capture→decoded) percentiles, ms — the fallback headline when no
+    /// render callback landed this window (`disp_valid` false).
     pub e2e_p50_ms: f64,
     pub e2e_p95_ms: f64,
-    /// Stage p50s (ms): `host+network` (capture→received) and `decode` (received→decoded).
+    /// The full headline: `end-to-end` = capture→displayed percentiles, ms, measured directly from
+    /// the render timestamps. Meaningful only when `disp_valid`.
+    pub e2e_disp_p50_ms: f64,
+    pub e2e_disp_p95_ms: f64,
+    /// Stage p50s (ms): `host+network` (capture→received), `decode` (received→decoded), and
+    /// `display` (decoded→displayed; 0.0 when `disp_valid` is false — the HUD drops the term).
     pub hostnet_p50_ms: f64,
     pub decode_p50_ms: f64,
+    pub display_p50_ms: f64,
+    /// Whether any capture→displayed sample landed this window — gates the HUD's headline endpoint
+    /// (`capture→displayed` vs the capture→decoded fallback) and the equation's `display` term.
+    pub disp_valid: bool,
     /// Phase-2 `host` / `network` split p50s (ms) — 0.0 when no 0xCF timing matched this window
     /// (old host / no samples yet), in which case the HUD keeps the combined `host+network` term.
     pub host_p50_ms: f64,
     pub net_p50_ms: f64,
     pub lat_valid: bool,
     pub skew_corrected: bool,
+    /// Access units received this window (the count behind `fps`) — lets the HUD compute the
+    /// spec's loss percentage `lost / (received + lost)` exactly.
+    pub frames: u64,
+    /// Unrecoverable network frame drops this window (spec `lost`, windowed from the
+    /// session-cumulative connector counter).
+    pub lost: u64,
+    /// Client-side newest-wins/pacing drops this window (spec `skipped`).
+    pub skipped: u64,
+    /// FEC shards recovered this window (spec `FEC`, windowed from the cumulative counter).
+    pub fec: u64,
 }
 
 /// Percentile over a sorted-in-place µs sample vec, in ms. 0.0 when empty.
@@ -101,6 +142,11 @@ impl VideoStats {
                 host_us: Vec::with_capacity(256),
                 net_us: Vec::with_capacity(256),
                 decode_us: Vec::with_capacity(256),
+                display_us: Vec::with_capacity(256),
+                e2e_disp_us: Vec::with_capacity(256),
+                skipped: 0,
+                last_dropped_total: 0,
+                last_fec_total: 0,
                 skew_corrected: false,
             }),
         }
@@ -115,8 +161,10 @@ impl VideoStats {
     }
 
     /// Toggle sampling. Enabling resets the window, so the first HUD poll after a show never mixes
-    /// in counters (or a window start) from before the overlay was visible.
-    pub fn set_enabled(&self, on: bool) {
+    /// in counters (or a window start) from before the overlay was visible. `dropped_total` /
+    /// `fec_total` are the connector's session-cumulative counters at this instant — they seed the
+    /// windowing baselines so the first snapshot's `lost` / `FEC` cover only time the HUD was up.
+    pub fn set_enabled(&self, on: bool, dropped_total: u64, fec_total: u64) {
         let was = self.enabled.swap(on, Ordering::Relaxed);
         if on && !was {
             let mut g = self
@@ -131,6 +179,11 @@ impl VideoStats {
             g.host_us.clear();
             g.net_us.clear();
             g.decode_us.clear();
+            g.display_us.clear();
+            g.e2e_disp_us.clear();
+            g.skipped = 0;
+            g.last_dropped_total = dropped_total;
+            g.last_fec_total = fec_total;
         }
     }
 
@@ -206,6 +259,22 @@ impl VideoStats {
         g.net_us.push(net_us);
     }
 
+    /// Record client-side frame skips (spec `skipped`): decoded output buffers released without
+    /// rendering under the newest-wins policy, or parked AUs dropped on queue overflow.
+    // Driven only by the android-only decode thread; unreferenced on the host build — expected.
+    #[cfg_attr(not(target_os = "android"), allow(dead_code))]
+    pub fn note_skipped(&self, n: u64) {
+        if n == 0 || !self.enabled.load(Ordering::Relaxed) {
+            return; // HUD hidden — skip the lock
+        }
+        // Poison-proof for the same reason as `note_received`.
+        let mut g = self
+            .inner
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner);
+        g.skipped += n;
+    }
+
     /// Record one decoded output frame: its capture→decoded `end-to-end` sample and its
     /// received→decoded `decode` stage sample (either may be absent — e.g. the receipt stamp for
     /// this pts predates the HUD being shown).
@@ -228,8 +297,34 @@ impl VideoStats {
         }
     }
 
+    /// Record one displayed frame (the `OnFrameRendered` render timestamp, re-based to the
+    /// realtime clock): its capture→displayed `end-to-end` sample and its decoded→displayed
+    /// `display` stage sample (either may be absent — the e2e clamp rejected an out-of-range
+    /// value, or the decoded stamp for this pts was already evicted/pre-HUD). Fired from the
+    /// codec's render-callback thread, not the decode thread — the lock makes that safe.
+    // Driven only by the android-only decode path; unreferenced on the host build — expected.
+    #[cfg_attr(not(target_os = "android"), allow(dead_code))]
+    pub fn note_displayed(&self, e2e_us: Option<u64>, display_us: Option<u64>) {
+        if !self.enabled.load(Ordering::Relaxed) {
+            return; // HUD hidden — skip the lock (the callback already skipped the clock reads)
+        }
+        // Poison-proof for the same reason as `note_received`.
+        let mut g = self
+            .inner
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner);
+        if let Some(l) = e2e_us {
+            g.e2e_disp_us.push(l);
+        }
+        if let Some(l) = display_us {
+            g.display_us.push(l);
+        }
+    }
+
     /// Compute the window's rates + latency percentiles, then reset for the next window.
-    pub fn drain(&self) -> Snapshot {
+    /// `dropped_total` / `fec_total` are the connector's session-cumulative counters now; the
+    /// snapshot's `lost` / `fec` are their deltas since the last drain (or the enabling show).
+    pub fn drain(&self, dropped_total: u64, fec_total: u64) -> Snapshot {
         // Poison-proof for the same reason as `note_received` — a poisoned window still drains
         // fine.
         let mut g = self
@@ -244,17 +339,27 @@ impl VideoStats {
         g.host_us.sort_unstable();
         g.net_us.sort_unstable();
         g.decode_us.sort_unstable();
+        g.display_us.sort_unstable();
+        g.e2e_disp_us.sort_unstable();
         let snap = Snapshot {
             fps,
             mbps,
             e2e_p50_ms: pctl_ms(&g.e2e_us, 0.50),
             e2e_p95_ms: pctl_ms(&g.e2e_us, 0.95),
+            e2e_disp_p50_ms: pctl_ms(&g.e2e_disp_us, 0.50),
+            e2e_disp_p95_ms: pctl_ms(&g.e2e_disp_us, 0.95),
             hostnet_p50_ms: pctl_ms(&g.hostnet_us, 0.50),
             decode_p50_ms: pctl_ms(&g.decode_us, 0.50),
+            display_p50_ms: pctl_ms(&g.display_us, 0.50),
+            disp_valid: !g.e2e_disp_us.is_empty(),
             host_p50_ms: pctl_ms(&g.host_us, 0.50),
             net_p50_ms: pctl_ms(&g.net_us, 0.50),
             lat_valid: !g.e2e_us.is_empty(),
             skew_corrected: g.skew_corrected,
+            frames: g.frames,
+            lost: dropped_total.saturating_sub(g.last_dropped_total),
+            skipped: g.skipped,
+            fec: fec_total.saturating_sub(g.last_fec_total),
         };
         g.window_start = Instant::now();
         g.frames = 0;
@@ -264,6 +369,11 @@ impl VideoStats {
         g.host_us.clear();
         g.net_us.clear();
         g.decode_us.clear();
+        g.display_us.clear();
+        g.e2e_disp_us.clear();
+        g.skipped = 0;
+        g.last_dropped_total = dropped_total;
+        g.last_fec_total = fec_total;
         snap
     }
 }

clients/android/native/vendor/ndk/.gitignore

@@ -0,0 +1,3 @@
+/target
+**/*.rs.bk
+Cargo.lock

clients/android/native/vendor/ndk/CHANGELOG.md

@@ -0,0 +1,137 @@
+# Unreleased
+
+# 0.9.0 (2024-04-26)
+
+- Move `MediaFormat` from `media::media_codec` to its own `media::media_format` module. (#442)
+- media_format: Expose `MediaFormat::copy()` and `MediaFormat::clear()` from API level 29. (#449)
+- **Breaking:** media_format: Mark all `fn set_*()` and `fn str()` as taking `self` by `&mut`. (#452)
+- **Breaking:** Require all `dyn Fn*` types to implement `Send` when the FFI implementation invokes them on a separate thread: (#455)
+  - `audio::AudioStreamDataCallback`;
+  - `audio::AudioStreamErrorCallback`;
+  - `media::image_reader::BufferRemovedListener`;
+  - `media::image_reader::ImageListener`;
+  - `media::media_codec::ErrorCallback`;
+  - `media::media_codec::FormatChangedCallback`;
+  - `media::media_codec::InputAvailableCallback`;
+  - `media::media_codec::OutputAvailableCallback`.
+- Drop previous `Box`ed callbacks _after_ registering new ones, instead of before. (#455)
+- input_queue: Add `from_java()` constructor, available since API level 33. (#456)
+- event: Add `from_java()` constructors to `KeyEvent` and `MotionEvent`, available since API level 31. (#456)
+- **Breaking:** image_reader: Special-case return statuses in `Image`-acquire functions. (#457)
+- **Breaking:** image_reader: Mark `ImageReader::acquire_latest_image_async()` `unsafe` to match the safety requirements on `ImageReader::acquire_next_image_async()`. (#457)
+- event: Implement `SourceClass` `bitflag` and provide `Source::class()` getter. (#458)
+- Ensure all `bitflags` implementations consider all (including unknown) bits in negation and `all()`. (#458)
+- **Breaking:** Mark all enums as `non_exhaustive` and fix `repr` types. (#459)
+- **Breaking:** native_window: Remove redundant `TRANSFORM_` prefix from `NativeWindowTransform` variants. (#460)
+- **Breaking:** hardware_buffer: Convert `HardwareBufferUsage` to `bitflags`. (#461)
+- bitmap: Guard `BitmapCompressError` behind missing `api-level-30` feature. (#462)
+- native_window: Require linking against `libnativewindow` for most API >= 26 functions. (#465)
+- **Breaking:** audio: Merge `AudioResult` variant enum into `AudioError`. (#467)
+- data_space: Add missing `DataSpaceRange::Unspecified` variant. (#468)
+- **Breaking:** looper: Require `Send` marker when adding fd event callbacks on `ForeignLooper`. (#469)
+- **Breaking:** Upgrade to [`ndk-sys 0.6.0`](../ndk-sys/CHANGELOG.md#060-2024-04-26). (#472)
+
+# 0.8.0 (2023-10-15)
+
+- event: Add `tool_type` getter for `Pointer`. (#323)
+- input_queue: Allow any non-zero return code from `pre_dispatch()` again, as per documentation. (#325)
+- asset: Use entire asset length when mapping buffer. (#387)
+- Bump MSRV to 1.66 for `raw-window-handle 0.5.1`, `num_enum`'s `catch_all` with arbitrary enum discriminants. (#388, #431)
+- Bump optional `jni` dependency for doctest example from `0.19` to `0.21`. (#390)
+- **Breaking:** Upgrade to [`ndk-sys 0.5.0`](../ndk-sys/CHANGELOG.md#050-2023-10-15). (#370)
+- **Breaking:** Upgrade `bitflags` crate from `1` to `2`. (#394)
+- bitmap: Add `try_format()` to `AndroidBitmapInfo` to handle unexpected formats without panicking. (#395)
+- Add `Font` bindings. (#397)
+- **Breaking:** Upgrade `num_enum` crate from `0.5.1` to `0.7`. (#398, #419)
+- **Breaking:** Renamed, moved and flattened "`media`" error types and helpers to a new `media_error` module. (#399, #432)
+- **Breaking:** media_codec: Wrap common dequeued-buffer status codes in enum. (#401)
+- **Breaking:** media_codec: Return `MaybeUninit` bytes in `buffer_mut()`. (#403)
+- native_window: Add `lock()` to blit raw pixel data. (#404)
+- hardware_buffer_format: Add `YCbCr_P010` and `R8_UNORM` variants. (#405)
+- **Breaking:** hardware_buffer_format: Add catch-all variant. (#407)
+- asset: Add missing `is_allocated()` and `open_file_descriptor()` methods. (#409)
+- **Breaking:** media_codec: Add support for asynchronous notification callbacks. (#410)
+- Add panic guards to callbacks. (#412)
+- looper: Add `remove_fd()` to unregister events/callbacks for a file descriptor. (#416)
+- **Breaking:** Use `BorrowedFd` and `OwnedFd` to clarify possible ownership transitions. (#417)
+- **Breaking:** Upgrade to [`ndk-sys 0.5.0`](../ndk-sys/CHANGELOG.md#050-2023-10-15). (#420)
+- Add bindings for `sync.h`. (#423)
+- **Breaking:** bitmap: Provide detailed implementation for `AndroidBitmapInfoFlags`. (#424)
+- native_window: Add `set_buffers_transform()`, `try_allocate_buffers()` and `set_frame_rate*()`. (#425)
+- Add bindings for `ASharedMemory`. (#427)
+- hardware_buffer: Add `id()` to retrieve a system-wide unique identifier for a `HardwareBuffer`. (#428)
+- **Breaking:** bitmap: Strip `Android` prefix from structs and enums, and `Bitmap` from `Result`. (#430)
+- **Breaking:** `raw-window-handle 0.5` support is now behind an _optional_ `rwh_05` crate feature and `raw-window-handle` `0.4` and `0.6` support is provided via the new `rwh_04` and (default-enabled) `rwh_06` crate features. (#434)
+- **Breaking:** looper: Provide `event` value to file descriptor poll callback. (#435)
+- **Breaking:** `HardwareBufferFormat` is no longer exported from `hardware_buffer` and `native_window`, and can only be reached through the `hardware_buffer_format` module. (#436)
+- **Breaking:** `get_` prefixes have been removed from all public functions in light of the [C-GETTER](https://rust-lang.github.io/api-guidelines/naming.html#getter-names-follow-rust-convention-c-getter) convention. (#437)
+- Add `DataSpace` type and relevant functions on `Bitmap` and `NativeWindow`. (#438)
+- bitmap: Add `Bitmap::compress()` and `Bitmap::compress_raw()` functions. (#440)
+- **Breaking:** Turn `BitmapError` into a `non_exhaustive` `enum`. (#440)
+- **Breaking:** audio: Rename `AudioErrorResult` to `AudioResult` and turn into a `non_exhaustive` `enum`. (#441)
+
+# 0.7.0 (2022-07-24)
+
+- hardware_buffer: Make `HardwareBuffer::as_ptr()` public for interop with Vulkan. (#213)
+- **Breaking:** `Configuration::country()` now returns `None` when the country is unset (akin to `Configuration::language()`). (#220)
+- Add `MediaCodec` and `MediaFormat` bindings. (#216)
+- **Breaking:** Upgrade to [`ndk-sys 0.4.0`](../ndk-sys/CHANGELOG.md#040-2022-07-24) and use new `enum` newtype wrappers. (#245)
+- native_window: Use `release`/`acquire` for `Drop` and `Clone` respectively. (#207)
+- **Breaking:** audio: Rename from `aaudio` to `audio` and drop `A` prefix. (#273)
+- Implement `HasRawWindowHandle` directly on `NativeWindow`. (#274, #319)
+- **Breaking:** native_activity: Replace `CStr` return types with `Path`. (#279)
+- native_window: Add `format()` getter and `set_buffers_geometry()` setter. (#276)
+- native_activity: Add `set_window_format()` setter. (#277)
+- native_activity: Add `set_window_flags()` to change window behavior. (#278)
+- Add `SurfaceTexture` bindings. (#267)
+- Improve library and structure documentation, linking back to the NDK docs more rigorously. (#290)
+- **Breaking:** input_queue: `get_event()` now returns a `Result` with `std::io::Error`; `InputQueueError` has been removed. (#292)
+- **Breaking:** input_queue: `has_events()` now returns a `bool` directly without being wrapped in `Result`. (#294)
+- **Breaking:** hardware_buffer: `HardwareBufferError` has been removed and replaced with `std::io::Error` in return types. (#295)
+- Fixed `HardwareBuffer` leak on buffers returned from `AndroidBitmap::get_hardware_buffer()`. (#296)
+- Bump optional `jni` dependency for doctest example from `0.18` to `0.19`. (#300)
+- hardware_buffer: Made `HardwareBufferDesc` fields `pub`. (#313)
+- **Breaking:** Remove `hardware_buffer` and `trace` features in favour of using `api-level-26` or `api-level-23` directly. (#320)
+
+# 0.6.0 (2022-01-05)
+
+- **Breaking:** Upgrade to [`ndk-sys 0.3.0`](../ndk-sys/CHANGELOG.md#030-2022-01-05) and migrate to `jni-sys` types that it now directly uses in its bindings. (#209 / #214)
+
+# 0.5.0 (2021-11-22)
+
+- **Breaking:** Replace `add_fd_with_callback` `ident` with constant value `ALOOPER_POLL_CALLBACK`,
+  as per <https://developer.android.com/ndk/reference/group/looper#alooper_addfd>.
+- **Breaking:** Accept unboxed closure in `add_fd_with_callback`.
+- aaudio: Replace "Added in" comments with missing `#[cfg(feature)]`.
+- aaudio: Add missing `fn get_allowed_capture_policy()`.
+- configuration: Add missing `api-level-30` feature to `fn screen_round()`.
+
+# 0.4.0 (2021-08-02)
+
+- **Breaking:** Model looper file descriptor events integer as `bitflags`.
+
+# 0.3.0 (2021-01-30)
+
+- **Breaking:** Looper `ident` not passed in `data` pointer anymore.
+  `attach_looper` now only sets the `ident` field when attaching an
+  `InputQueue` to a `ForeignLooper`.
+  If you are relying on `Poll::Event::data` to tell event fd and
+  input queue apart, please use `Poll::Event::ident` and the new
+  constants introduced in `ndk-glue`!
+
+# 0.2.1 (2020-10-15)
+
+- Fix documentation build on docs.rs
+
+# 0.2.0 (2020-09-15)
+
+- **Breaking:** Updated to use [ndk-sys 0.2.0](../ndk-sys/CHANGELOG.md#020-2020-09-15)
+- Added `media` bindings
+- Added `bitmap` and `hardware_buffer` bindings
+- Added `aaudio` bindings
+- Fixed assets directory path to be relative to the manifest
+- Added `trace` feature for native tracing
+
+# 0.1.0 (2020-04-22)
+
+- Initial release! 🎉

clients/android/native/vendor/ndk/Cargo.toml

@@ -0,0 +1,125 @@
+# THIS FILE IS AUTOMATICALLY GENERATED BY CARGO
+#
+# When uploading crates to the registry Cargo will automatically
+# "normalize" Cargo.toml files for maximal compatibility
+# with all versions of Cargo and also rewrite `path` dependencies
+# to registry (e.g., crates.io) dependencies.
+#
+# If you are reading this file be aware that the original Cargo.toml
+# will likely look very different (and much more reasonable).
+# See Cargo.toml.orig for the original contents.
+
+[package]
+edition = "2021"
+rust-version = "1.66"
+name = "ndk"
+version = "0.9.0"
+authors = ["The Rust Mobile contributors"]
+description = "Safe Rust bindings to the Android NDK"
+homepage = "https://github.com/rust-mobile/ndk"
+documentation = "https://docs.rs/ndk"
+readme = "README.md"
+keywords = [
+    "android",
+    "ndk",
+]
+license = "MIT OR Apache-2.0"
+repository = "https://github.com/rust-mobile/ndk"
+
+[package.metadata.docs.rs]
+features = [
+    "jni",
+    "all",
+]
+rustdoc-args = [
+    "--cfg",
+    "docsrs",
+]
+targets = [
+    "aarch64-linux-android",
+    "armv7-linux-androideabi",
+    "i686-linux-android",
+    "x86_64-linux-android",
+]
+
+[dependencies.bitflags]
+version = "2.4"
+
+[dependencies.ffi]
+version = "0.6.0"
+package = "ndk-sys"
+
+[dependencies.jni]
+version = "0.21"
+optional = true
+
+[dependencies.jni-sys]
+version = "0.3"
+
+[dependencies.log]
+version = "0.4.6"
+
+[dependencies.num_enum]
+version = "0.7"
+
+[dependencies.rwh_04]
+version = "0.4"
+optional = true
+package = "raw-window-handle"
+
+[dependencies.rwh_05]
+version = "0.5"
+optional = true
+package = "raw-window-handle"
+
+[dependencies.rwh_06]
+version = "0.6"
+optional = true
+package = "raw-window-handle"
+
+[dependencies.thiserror]
+version = "1.0.23"
+
+[dev-dependencies.libc]
+version = "0.2.3"
+
+[features]
+all = [
+    "audio",
+    "bitmap",
+    "media",
+    "nativewindow",
+    "sync",
+    "api-level-33",
+    "rwh_04",
+    "rwh_05",
+    "rwh_06",
+]
+api-level-23 = []
+api-level-24 = ["api-level-23"]
+api-level-25 = ["api-level-24"]
+api-level-26 = ["api-level-25"]
+api-level-27 = ["api-level-26"]
+api-level-28 = ["api-level-27"]
+api-level-29 = ["api-level-28"]
+api-level-30 = ["api-level-29"]
+api-level-31 = ["api-level-30"]
+api-level-32 = ["api-level-31"]
+api-level-33 = ["api-level-32"]
+audio = [
+    "ffi/audio",
+    "api-level-26",
+]
+bitmap = ["ffi/bitmap"]
+default = ["rwh_06"]
+media = ["ffi/media"]
+nativewindow = ["ffi/nativewindow"]
+sync = [
+    "ffi/sync",
+    "api-level-26",
+]
+test = [
+    "ffi/test",
+    "jni",
+    "all",
+]

clients/android/native/vendor/ndk/README.md

@@ -0,0 +1,21 @@
+[![ci](https://github.com/rust-mobile/ndk/actions/workflows/rust.yml/badge.svg)](https://github.com/rust-mobile/ndk/actions/workflows/rust.yml) ![MIT license](https://img.shields.io/badge/License-MIT-green.svg) ![APACHE2 license](https://img.shields.io/badge/License-APACHE2-green.svg)
+
+Rust bindings to the [Android NDK](https://developer.android.com/ndk)
+
+Name | Description | Badges
+--- | --- | ---
+[`ndk-sys`](./ndk-sys) | Raw FFI bindings to the NDK | [![crates.io](https://img.shields.io/crates/v/ndk-sys.svg)](https://crates.io/crates/ndk-sys) [![Docs](https://docs.rs/ndk-sys/badge.svg)](https://docs.rs/ndk-sys) [![MSRV](https://img.shields.io/badge/rustc-1.60.0+-ab6000.svg)](https://blog.rust-lang.org/2022/04/07/Rust-1.60.0.html)
+[`ndk`](./ndk) | Safe abstraction of the bindings | [![crates.io](https://img.shields.io/crates/v/ndk.svg)](https://crates.io/crates/ndk) [![Docs](https://docs.rs/ndk/badge.svg)](https://docs.rs/ndk) [![MSRV](https://img.shields.io/badge/rustc-1.64.0+-ab6000.svg)](https://blog.rust-lang.org/2022/09/22/Rust-1.64.0.html)
+
+See these [`ndk-examples`](https://github.com/rust-mobile/cargo-apk/tree/main/examples/examples) and these [`rust-android-examples`](https://github.com/rust-mobile/rust-android-examples) for examples using the NDK.
+
+> [!IMPORTANT]
+> This repository was recently [modularized](https://github.com/rust-mobile/ndk/issues/372) and the following crates were split into separate repositories:
+>
+> Crate | New Location | Notes
+> ------|--------------|------
+> ndk-context | https://github.com/rust-mobile/ndk-context |
+> ndk-glue | https://github.com/rust-mobile/ndk-glue | ⛔ _deprecated_ - see [android-activity](https://github.com/rust-mobile/android-activity)
+> ndk-macro | https://github.com/rust-mobile/ndk-glue | ⛔ _deprecated_ - see [android-activity](https://github.com/rust-mobile/android-activity)
+> ndk-build | https://github.com/rust-mobile/cargo-apk | ⛔ _deprecated_ - see [xbuild](https://github.com/rust-mobile/xbuild)
+> cargo-apk | https://github.com/rust-mobile/cargo-apk | ⛔ _deprecated_ - see [xbuild](https://github.com/rust-mobile/xbuild)

clients/android/native/vendor/ndk/README.punktfunk.md

@@ -0,0 +1,14 @@
+# Vendored `ndk` 0.9.0 (patched)
+
+Verbatim copy of the published `ndk` 0.9.0 crate (https://crates.io/crates/ndk,
+MIT OR Apache-2.0, © the rust-mobile contributors), wired in via `[patch.crates-io]`
+in the workspace root.
+
+**The only change** is in `src/media/media_codec.rs`: `MediaCodec::as_ptr` is made
+`pub` (upstream keeps it private) so the Android client can register
+`AMediaCodec_setOnFrameRenderedCallback` through `ndk-sys` — the render-timestamp
+callback behind the HUD's `display` stage (punktfunk-planning: `stats-unification.md`), which the
+wrapper doesn't expose. Grep for `punktfunk vendored patch` to find it.
+
+Drop this vendor copy when upstream exposes the raw pointer or a frame-rendered
+callback binding (tracked against https://github.com/rust-mobile/ndk).

clients/android/native/vendor/ndk/src/asset.rs

@@ -0,0 +1,323 @@
+//! Bindings for [`AAsset`], [`AAssetDir`] and [`AAssetManager`]
+//!
+//! [`AAsset`]: https://developer.android.com/ndk/reference/group/asset#aasset
+//! [`AAssetDir`]: https://developer.android.com/ndk/reference/group/asset#aassetdir
+//! [`AAssetManager`]: https://developer.android.com/ndk/reference/group/asset#aassetmanager
+
+use std::{
+    ffi::{CStr, CString},
+    io,
+    os::fd::{FromRawFd, OwnedFd},
+    ptr::NonNull,
+};
+
+/// A native [`AAssetManager *`]
+///
+/// [`AAssetManager *`]: https://developer.android.com/ndk/reference/group/asset#aassetmanager
+#[derive(Debug)]
+#[doc(alias = "AAssetManager")]
+pub struct AssetManager {
+    ptr: NonNull<ffi::AAssetManager>,
+}
+
+// AAssetManager is thread safe.
+// See https://developer.android.com/ndk/reference/group/asset#aassetmanager
+unsafe impl Send for AssetManager {}
+unsafe impl Sync for AssetManager {}
+
+impl AssetManager {
+    /// Create an `AssetManager` from a pointer
+    ///
+    /// # Safety
+    /// By calling this function, you assert that the pointer is a valid pointer to a native
+    /// `AAssetManager`.
+    pub unsafe fn from_ptr(ptr: NonNull<ffi::AAssetManager>) -> Self {
+        Self { ptr }
+    }
+
+    /// Returns the pointer to the native `AAssetManager`.
+    pub fn ptr(&self) -> NonNull<ffi::AAssetManager> {
+        self.ptr
+    }
+
+    /// Open the asset. Returns [`None`] if opening the asset fails.
+    ///
+    /// This currently always opens the asset in the streaming mode.
+    #[doc(alias = "AAssetManager_open")]
+    pub fn open(&self, filename: &CStr) -> Option<Asset> {
+        unsafe {
+            let ptr = ffi::AAssetManager_open(
+                self.ptr.as_ptr(),
+                filename.as_ptr(),
+                ffi::AASSET_MODE_STREAMING as i32,
+            );
+            Some(Asset::from_ptr(NonNull::new(ptr)?))
+        }
+    }
+
+    /// Open an asset directory. Returns [`None`] if opening the directory fails.
+    #[doc(alias = "AAssetManager_openDir")]
+    pub fn open_dir(&self, filename: &CStr) -> Option<AssetDir> {
+        unsafe {
+            let ptr = ffi::AAssetManager_openDir(self.ptr.as_ptr(), filename.as_ptr());
+            Some(AssetDir::from_ptr(NonNull::new(ptr)?))
+        }
+    }
+}
+
+/// A native [`AAssetDir *`]
+///
+/// ```no_run
+/// # use std::ffi::CString;
+/// # use ndk::asset::AssetManager;
+/// # let asset_manager: AssetManager = unimplemented!();
+/// use std::io::Read;
+///
+/// let mut my_dir = asset_manager
+///     .open_dir(&CString::new("my_dir").unwrap())
+///     .expect("Could not open directory");
+///
+/// // Use it as an iterator
+/// let all_files = my_dir.collect::<Vec<CString>>();
+///
+/// // Reset the iterator
+/// my_dir.rewind();
+///
+/// // Use .with_next() to iterate without allocating `CString`s
+/// while let Some(asset) = my_dir.with_next(|cstr| asset_manager.open(cstr).unwrap()) {
+///     let mut text = String::new();
+///     asset.read_to_string(&mut text);
+///     // ...
+/// }
+/// ```
+///
+/// [`AAssetDir *`]: https://developer.android.com/ndk/reference/group/asset#aassetdir
+#[derive(Debug)]
+#[doc(alias = "AAssetDir")]
+pub struct AssetDir {
+    ptr: NonNull<ffi::AAssetDir>,
+}
+
+// It's unclear if AAssetDir is thread safe.
+// However, AAsset is not, so there's a good chance that AAssetDir is not either.
+
+impl Drop for AssetDir {
+    #[doc(alias = "AAssetDir_close")]
+    fn drop(&mut self) {
+        unsafe { ffi::AAssetDir_close(self.ptr.as_ptr()) }
+    }
+}
+
+impl AssetDir {
+    /// Construct an `AssetDir` from the native `AAssetDir *`.  This gives ownership of the
+    /// `AAssetDir *` to the `AssetDir`, which will handle closing the asset.  Avoid using
+    /// the pointer after calling this function.
+    ///
+    /// # Safety
+    /// By calling this function, you assert that it points to a valid native `AAssetDir`.
+    pub unsafe fn from_ptr(ptr: NonNull<ffi::AAssetDir>) -> Self {
+        Self { ptr }
+    }
+
+    /// The corresponding native `AAssetDir *`
+    pub fn ptr(&self) -> NonNull<ffi::AAssetDir> {
+        self.ptr
+    }
+
+    /// Get the next filename, if any, and process it.  Like [`Iterator::next()`], but performs
+    /// no additional allocation.
+    ///
+    /// The filenames are in the correct format to be passed to [`AssetManager::open()`].
+    #[doc(alias = "AAssetDir_getNextFileName")]
+    pub fn with_next<T>(&mut self, f: impl for<'a> FnOnce(&'a CStr) -> T) -> Option<T> {
+        unsafe {
+            let next_name = ffi::AAssetDir_getNextFileName(self.ptr.as_ptr());
+            if next_name.is_null() {
+                None
+            } else {
+                Some(f(CStr::from_ptr(next_name)))
+            }
+        }
+    }
+
+    /// Reset the iteration state
+    #[doc(alias = "AAssetDir_rewind")]
+    pub fn rewind(&mut self) {
+        unsafe {
+            ffi::AAssetDir_rewind(self.ptr.as_ptr());
+        }
+    }
+}
+
+impl Iterator for AssetDir {
+    type Item = CString;
+
+    fn next(&mut self) -> Option<CString> {
+        self.with_next(|cstr| cstr.to_owned())
+    }
+}
+
+/// A native [`AAsset *`], opened in streaming mode
+///
+/// ```no_run
+/// # use std::ffi::CString;
+/// # use ndk::asset::AssetManager;
+/// # let asset_manager: AssetManager = unimplemented!();
+/// use std::io::Read;
+///
+/// let asset = asset_manager
+///     .open(&CString::new("path/to/asset").unwrap())
+///     .expect("Could not open asset");
+///
+/// let mut data = vec![];
+/// asset.read_to_end(&mut data);
+/// // ... use data ...
+/// ```
+///
+/// [`AAsset *`]: https://developer.android.com/ndk/reference/group/asset#aasset
+#[derive(Debug)]
+#[doc(alias = "AAsset")]
+pub struct Asset {
+    ptr: NonNull<ffi::AAsset>,
+}
+
+// AAsset is *not* thread safe.
+// See https://developer.android.com/ndk/reference/group/asset#aasset
+
+impl Drop for Asset {
+    #[doc(alias = "AAsset_close")]
+    fn drop(&mut self) {
+        unsafe { ffi::AAsset_close(self.ptr.as_ptr()) }
+    }
+}
+
+impl Asset {
+    /// Construct an `Asset` from the native `AAsset *`.  This gives ownership of the `AAsset *` to
+    /// the `Asset`, which will handle closing the asset.  Avoid using the pointer after calling
+    /// this function.
+    ///
+    /// # Safety
+    /// By calling this function, you assert that it points to a valid native `AAsset`, open
+    /// in the streaming mode.
+    pub unsafe fn from_ptr(ptr: NonNull<ffi::AAsset>) -> Self {
+        Self { ptr }
+    }
+
+    /// The corresponding native `AAsset *`
+    pub fn ptr(&self) -> NonNull<ffi::AAsset> {
+        self.ptr
+    }
+
+    /// Returns the total length of the asset, in bytes
+    #[doc(alias = "AAsset_getLength64")]
+    pub fn length(&self) -> usize {
+        unsafe { ffi::AAsset_getLength64(self.ptr.as_ptr()) as usize }
+    }
+
+    /// Returns the remaining length of the asset, in bytes
+    #[doc(alias = "AAsset_getRemainingLength64")]
+    pub fn remaining_length(&self) -> usize {
+        unsafe { ffi::AAsset_getRemainingLength64(self.ptr.as_ptr()) as usize }
+    }
+
+    /// Maps all data into a buffer and returns it
+    #[doc(alias = "AAsset_getBuffer")]
+    pub fn buffer(&mut self) -> io::Result<&[u8]> {
+        unsafe {
+            let buf_ptr = ffi::AAsset_getBuffer(self.ptr.as_ptr());
+            if buf_ptr.is_null() {
+                Err(io::Error::new(
+                    io::ErrorKind::Other,
+                    "Android Asset error creating buffer",
+                ))
+            } else {
+                Ok(std::slice::from_raw_parts(
+                    buf_ptr as *const u8,
+                    self.length(),
+                ))
+            }
+        }
+    }
+
+    /// Returns whether this asset's internal buffer is allocated in ordinary RAM (i.e. not `mmap`ped).
+    #[doc(alias = "AAsset_isAllocated")]
+    pub fn is_allocated(&self) -> bool {
+        unsafe { ffi::AAsset_isAllocated(self.ptr.as_ptr()) != 0 }
+    }
+
+    /// Open a new file descriptor that can be used to read the asset data.
+    ///
+    /// Returns an error if direct fd access is not possible (for example, if the asset is compressed).
+    #[doc(alias = "AAsset_openFileDescriptor64")]
+    pub fn open_file_descriptor(&self) -> io::Result<OpenedFileDescriptor> {
+        let mut offset = 0;
+        let mut size = 0;
+        let res =
+            unsafe { ffi::AAsset_openFileDescriptor64(self.ptr.as_ptr(), &mut offset, &mut size) };
+        if res >= 0 {
+            Ok(OpenedFileDescriptor {
+                fd: unsafe { OwnedFd::from_raw_fd(res) },
+                offset: offset as usize,
+                size: size as usize,
+            })
+        } else {
+            Err(io::Error::new(
+                io::ErrorKind::Other,
+                "Android Asset openFileDescriptor error",
+            ))
+        }
+    }
+}
+
+impl io::Read for Asset {
+    #[doc(alias = "AAsset_read")]
+    fn read(&mut self, buf: &mut [u8]) -> io::Result<usize> {
+        unsafe {
+            let res = ffi::AAsset_read(self.ptr.as_ptr(), buf.as_mut_ptr() as *mut _, buf.len());
+            if res >= 0 {
+                Ok(res as usize)
+            } else {
+                Err(io::Error::new(
+                    io::ErrorKind::Other,
+                    "Android Asset read error",
+                ))
+            }
+        }
+    }
+}
+
+impl io::Seek for Asset {
+    #[doc(alias = "AAsset_seek64")]
+    fn seek(&mut self, seek: io::SeekFrom) -> io::Result<u64> {
+        unsafe {
+            let res = match seek {
+                io::SeekFrom::Start(x) => {
+                    ffi::AAsset_seek64(self.ptr.as_ptr(), x as i64, ffi::SEEK_SET as i32)
+                }
+                io::SeekFrom::Current(x) => {
+                    ffi::AAsset_seek64(self.ptr.as_ptr(), x, ffi::SEEK_CUR as i32)
+                }
+                io::SeekFrom::End(x) => {
+                    ffi::AAsset_seek64(self.ptr.as_ptr(), x, ffi::SEEK_END as i32)
+                }
+            };
+            if res < 0 {
+                Err(io::Error::new(
+                    io::ErrorKind::Other,
+                    "Android Asset seek error",
+                ))
+            } else {
+                Ok(res as u64)
+            }
+        }
+    }
+}
+
+/// Contains the opened file descriptor returned by [`Asset::open_file_descriptor()`], together
+/// with the offset and size of the given asset within that file descriptor.
+#[derive(Debug)]
+pub struct OpenedFileDescriptor {
+    pub fd: OwnedFd,
+    pub offset: usize,
+    pub size: usize,
+}

clients/android/native/vendor/ndk/src/bitmap.rs

@@ -0,0 +1,489 @@
+//! Bindings for [`AndroidBitmap`] functions
+//!
+//! These functions operate directly on a JNI [`android.graphics.Bitmap`] instance.
+//!
+//! [`AndroidBitmap`]: https://developer.android.com/ndk/reference/group/bitmap
+//! [`android.graphics.Bitmap`]: https://developer.android.com/reference/android/graphics/Bitmap
+#![cfg(feature = "bitmap")]
+
+use jni_sys::{jobject, JNIEnv};
+use num_enum::{FromPrimitive, IntoPrimitive};
+use std::{error, fmt, mem::MaybeUninit};
+
+#[cfg(feature = "api-level-30")]
+use crate::data_space::DataSpace;
+#[cfg(feature = "api-level-30")]
+use crate::hardware_buffer::HardwareBufferRef;
+
+#[repr(i32)]
+#[derive(Copy, Clone, Debug, PartialEq, Eq, FromPrimitive, IntoPrimitive)]
+#[non_exhaustive]
+pub enum BitmapError {
+    #[doc(alias = "ANDROID_BITMAP_RESULT_ALLOCATION_FAILED")]
+    AllocationFailed = ffi::ANDROID_BITMAP_RESULT_ALLOCATION_FAILED,
+    #[doc(alias = "ANDROID_BITMAP_RESULT_BAD_PARAMETER")]
+    BadParameter = ffi::ANDROID_BITMAP_RESULT_BAD_PARAMETER,
+    #[doc(alias = "ANDROID_BITMAP_RESULT_JNI_EXCEPTION")]
+    JniException = ffi::ANDROID_BITMAP_RESULT_JNI_EXCEPTION,
+
+    // Use the SUCCESS discriminant, as no-one will be able to call `as i32` and only has access to
+    // the constants via `From` provided by `IntoPrimitive` which reads the contained value.
+    // An autogenerated `<previous variant> + 1` discriminant is normally fine, except that the
+    // previous variant is negative and `+ 1` would match the variant before that.
+    #[doc(hidden)]
+    #[num_enum(catch_all)]
+    __Unknown(i32) = ffi::ANDROID_BITMAP_RESULT_SUCCESS,
+}
+
+impl fmt::Display for BitmapError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(f, "{:?}", self)
+    }
+}
+
+impl error::Error for BitmapError {}
+
+pub type Result<T, E = BitmapError> = std::result::Result<T, E>;
+
+impl BitmapError {
+    pub(crate) fn from_status(status: i32) -> Result<()> {
+        match status {
+            ffi::ANDROID_BITMAP_RESULT_SUCCESS => Ok(()),
+            x => Err(Self::from(x)),
+        }
+    }
+}
+
+fn construct<T>(with_ptr: impl FnOnce(*mut T) -> i32) -> Result<T> {
+    let mut result = MaybeUninit::uninit();
+    let status = with_ptr(result.as_mut_ptr());
+    BitmapError::from_status(status).map(|()| unsafe { result.assume_init() })
+}
+
+#[repr(i32)]
+#[derive(Clone, Copy, Debug, PartialEq, Eq, IntoPrimitive, FromPrimitive)]
+#[allow(non_camel_case_types)]
+#[doc(alias = "AndroidBitmapFormat")]
+#[non_exhaustive]
+pub enum BitmapFormat {
+    #[doc(alias = "ANDROID_BITMAP_FORMAT_NONE")]
+    NONE = ffi::AndroidBitmapFormat::ANDROID_BITMAP_FORMAT_NONE.0 as i32,
+    #[doc(alias = "ANDROID_BITMAP_FORMAT_RGBA_8888")]
+    RGBA_8888 = ffi::AndroidBitmapFormat::ANDROID_BITMAP_FORMAT_RGBA_8888.0 as i32,
+    #[doc(alias = "ANDROID_BITMAP_FORMAT_RGB_565")]
+    RGB_565 = ffi::AndroidBitmapFormat::ANDROID_BITMAP_FORMAT_RGB_565.0 as i32,
+    #[deprecated = "Deprecated in API level 13. Because of the poor quality of this configuration, it is advised to use ARGB_8888 instead."]
+    #[doc(alias = "ANDROID_BITMAP_FORMAT_RGBA_4444")]
+    RGBA_4444 = ffi::AndroidBitmapFormat::ANDROID_BITMAP_FORMAT_RGBA_4444.0 as i32,
+    #[doc(alias = "ANDROID_BITMAP_FORMAT_A_8")]
+    A_8 = ffi::AndroidBitmapFormat::ANDROID_BITMAP_FORMAT_A_8.0 as i32,
+    #[doc(alias = "ANDROID_BITMAP_FORMAT_RGBA_F16")]
+    RGBA_F16 = ffi::AndroidBitmapFormat::ANDROID_BITMAP_FORMAT_RGBA_F16.0 as i32,
+    #[doc(alias = "ANDROID_BITMAP_FORMAT_RGBA_1010102")]
+    RGBA_1010102 = ffi::AndroidBitmapFormat::ANDROID_BITMAP_FORMAT_RGBA_1010102.0 as i32,
+
+    #[doc(hidden)]
+    #[num_enum(catch_all)]
+    __Unknown(i32),
+}
+
+/// An immediate wrapper over [`android.graphics.Bitmap`]
+///
+/// [`android.graphics.Bitmap`]: https://developer.android.com/reference/android/graphics/Bitmap
+#[derive(Debug)]
+pub struct Bitmap {
+    env: *mut JNIEnv,
+    inner: jobject,
+}
+
+impl Bitmap {
+    /// Create a [`Bitmap`] wrapper from JNI pointers
+    ///
+    /// # Safety
+    /// This function should be called with a healthy JVM pointer and with a non-null
+    /// [`android.graphics.Bitmap`], which must be kept alive on the Java/Kotlin side.
+    ///
+    /// [`android.graphics.Bitmap`]: https://developer.android.com/reference/android/graphics/Bitmap
+    pub unsafe fn from_jni(env: *mut JNIEnv, bitmap: jobject) -> Self {
+        Self { env, inner: bitmap }
+    }
+
+    /// Fills out and returns the [`BitmapInfo`] struct for the given Java bitmap object.
+    #[doc(alias = "AndroidBitmap_getInfo")]
+    pub fn info(&self) -> Result<BitmapInfo> {
+        let inner =
+            construct(|res| unsafe { ffi::AndroidBitmap_getInfo(self.env, self.inner, res) })?;
+
+        Ok(BitmapInfo { inner })
+    }
+
+    /// Returns the [`DataSpace`] of this [`Bitmap`].
+    ///
+    /// Note that [`DataSpace`] only exposes a few values. This may return [`DataSpace::Unknown`],
+    /// even for Named ColorSpaces, if they have no corresponding [`DataSpace`].
+    #[cfg(feature = "api-level-30")]
+    #[doc(alias = "AndroidBitmap_getDataSpace")]
+    pub fn data_space(&self) -> DataSpace {
+        let value = unsafe { ffi::AndroidBitmap_getDataSpace(self.env, self.inner) };
+        value.into()
+    }
+
+    /// Attempt to lock the pixel address.
+    ///
+    /// Locking will ensure that the memory for the pixels will not move until the
+    /// [`Bitmap::unlock_pixels()`] call, and ensure that, if the pixels had been previously purged,
+    /// they will have been restored.
+    ///
+    /// If this call succeeds, it must be balanced by a call to [`Bitmap::unlock_pixels()`], after
+    /// which time the address of the pixels should no longer be used.
+    #[doc(alias = "AndroidBitmap_lockPixels")]
+    pub fn lock_pixels(&self) -> Result<*mut std::os::raw::c_void> {
+        construct(|res| unsafe { ffi::AndroidBitmap_lockPixels(self.env, self.inner, res) })
+    }
+
+    /// Call this to balance a successful call to [`Bitmap::lock_pixels()`].
+    #[doc(alias = "AndroidBitmap_unlockPixels")]
+    pub fn unlock_pixels(&self) -> Result<()> {
+        let status = unsafe { ffi::AndroidBitmap_unlockPixels(self.env, self.inner) };
+        BitmapError::from_status(status)
+    }
+
+    /// Retrieve the native object associated with an [`ffi::ANDROID_BITMAP_FLAGS_IS_HARDWARE`]
+    /// [`Bitmap`] (requires [`BitmapInfoFlags::is_hardware()`] on [`BitmapInfo::flags()`] to return
+    /// [`true`]).
+    ///
+    /// Client must not modify it while a [`Bitmap`] is wrapping it.
+    #[cfg(feature = "api-level-30")]
+    #[doc(alias = "AndroidBitmap_getHardwareBuffer")]
+    pub fn hardware_buffer(&self) -> Result<HardwareBufferRef> {
+        unsafe {
+            let result =
+                construct(|res| ffi::AndroidBitmap_getHardwareBuffer(self.env, self.inner, res))?;
+            let non_null = if cfg!(debug_assertions) {
+                std::ptr::NonNull::new(result).expect("result should never be null")
+            } else {
+                std::ptr::NonNull::new_unchecked(result)
+            };
+            Ok(HardwareBufferRef::from_ptr(non_null))
+        }
+    }
+
+    /// [Lock] the pixels in `self` and compress them as described by [`info()`].
+    ///
+    /// Unlike [`compress_raw()`] this requires a [`Bitmap`] object (as `self`) backed by a
+    /// [`jobject`].
+    ///
+    /// # Parameters
+    /// - `format`: [`BitmapCompressFormat`] to compress to.
+    /// - `quality`: Hint to the compressor, `0-100`.  The value is interpreted differently
+    ///   depending on [`BitmapCompressFormat`].
+    /// - `compress_callback`: Closure that writes the compressed data.  Will be called on the
+    ///   current thread, each time the compressor has compressed more data that is ready to be
+    ///   written.  May be called more than once for each call to this method.
+    ///
+    /// [Lock]: Self::lock_pixels()
+    /// [`info()`]: Self::info()
+    /// [`compress_raw()`]: Self::compress_raw()
+    #[cfg(feature = "api-level-30")]
+    #[doc(alias = "AndroidBitmap_compress")]
+    pub fn compress<F: FnMut(&[u8]) -> Result<(), ()>>(
+        &self,
+        format: BitmapCompressFormat,
+        quality: i32,
+        compress_callback: F,
+    ) -> Result<(), BitmapCompressError> {
+        let info = self.info()?;
+        let data_space = self.data_space();
+        let pixels = self.lock_pixels()?;
+        // SAFETY: When lock_pixels() succeeds, assume it returns a valid pointer that stays
+        // valid until we call unlock_pixels().
+        let result = unsafe {
+            Self::compress_raw(
+                &info,
+                data_space,
+                pixels,
+                format,
+                quality,
+                compress_callback,
+            )
+        };
+        self.unlock_pixels()?;
+        result
+    }
+
+    /// Compress `pixels` as described by `info`.
+    ///
+    /// Unlike [`compress()`] this takes a raw pointer to pixels and does not need a [`Bitmap`]
+    /// object backed by a [`jobject`].
+    ///
+    /// # Parameters
+    /// - `info`: Description of the pixels to compress.
+    /// - `data_space`: [`DataSpace`] describing the color space of the pixels.  Should _not_ be
+    ///   [`DataSpace::Unknown`] [^1].
+    /// - `pixels`: Pointer to pixels to compress.
+    /// - `format`: [`BitmapCompressFormat`] to compress to.
+    /// - `quality`: Hint to the compressor, `0-100`.  The value is interpreted differently
+    ///   depending on [`BitmapCompressFormat`].
+    /// - `compress_callback`: Closure that writes the compressed data.  Will be called on the
+    ///   current thread, each time the compressor has compressed more data that is ready to be
+    ///   written.  May be called more than once for each call to this method.
+    ///
+    /// # Safety
+    /// `pixels` must point to a valid buffer that matches the size, stride and format in `info`.
+    ///
+    /// [`compress()`]: Self::compress()
+    /// [^1]: <https://cs.android.com/android/platform/superproject/main/+/main:frameworks/base/libs/hwui/apex/android_bitmap.cpp;l=275-279;drc=7ba5c2fb3d1e35eb37a9cc522b30ba51f49ea491>
+    #[cfg(feature = "api-level-30")]
+    #[doc(alias = "AndroidBitmap_compress")]
+    pub unsafe fn compress_raw<F: FnMut(&[u8]) -> Result<(), ()>>(
+        info: &BitmapInfo,
+        data_space: DataSpace,
+        pixels: *const std::ffi::c_void,
+        format: BitmapCompressFormat,
+        quality: i32,
+        compress_callback: F,
+    ) -> Result<(), BitmapCompressError> {
+        if data_space == DataSpace::Unknown {
+            return Err(BitmapCompressError::DataSpaceUnknown);
+        }
+
+        use std::{any::Any, ffi::c_void, panic::AssertUnwindSafe};
+        struct CallbackState<F: FnMut(&[u8]) -> Result<(), ()>> {
+            callback: F,
+            panic: Option<Box<dyn Any + Send>>,
+        }
+        let mut cb_state = CallbackState::<F> {
+            callback: compress_callback,
+            panic: None,
+        };
+
+        extern "C" fn compress_cb<F: FnMut(&[u8]) -> Result<(), ()>>(
+            context: *mut c_void,
+            data: *const c_void,
+            size: usize,
+        ) -> bool {
+            // SAFETY: This callback will only be called serially on a single thread. Both the
+            // panic state and the FnMut context need to be available mutably.
+            let cb_state = unsafe { context.cast::<CallbackState<F>>().as_mut() }.unwrap();
+            let data = unsafe { std::slice::from_raw_parts(data.cast(), size) };
+            let panic = std::panic::catch_unwind(AssertUnwindSafe(|| (cb_state.callback)(data)));
+            match panic {
+                Ok(r) => r.is_ok(),
+                Err(e) => {
+                    cb_state.panic = Some(e);
+                    false
+                }
+            }
+        }
+
+        let status = unsafe {
+            ffi::AndroidBitmap_compress(
+                &info.inner,
+                data_space.into(),
+                pixels,
+                format.into(),
+                quality,
+                <*mut _>::cast(&mut cb_state),
+                Some(compress_cb::<F>),
+            )
+        };
+
+        if let Some(panic) = cb_state.panic {
+            std::panic::resume_unwind(panic)
+        }
+
+        Ok(BitmapError::from_status(status)?)
+    }
+}
+
+/// Possible values for [`ffi::ANDROID_BITMAP_FLAGS_ALPHA_MASK`] within [`BitmapInfoFlags`]
+#[repr(u32)]
+#[cfg(feature = "api-level-30")]
+#[derive(Clone, Copy, Debug, IntoPrimitive, FromPrimitive)]
+#[doc(alias = "ANDROID_BITMAP_FLAGS_ALPHA_MASK")]
+#[non_exhaustive]
+pub enum BitmapInfoFlagsAlpha {
+    /// Pixel components are premultiplied by alpha.
+    #[doc(alias = "ANDROID_BITMAP_FLAGS_ALPHA_PREMUL")]
+    Premultiplied = ffi::ANDROID_BITMAP_FLAGS_ALPHA_PREMUL,
+    /// Pixels are opaque.
+    #[doc(alias = "ANDROID_BITMAP_FLAGS_ALPHA_OPAQUE")]
+    Opaque = ffi::ANDROID_BITMAP_FLAGS_ALPHA_OPAQUE,
+    /// Pixel components are independent of alpha.
+    #[doc(alias = "ANDROID_BITMAP_FLAGS_ALPHA_UNPREMUL")]
+    Unpremultiplied = ffi::ANDROID_BITMAP_FLAGS_ALPHA_UNPREMUL,
+
+    #[doc(hidden)]
+    #[num_enum(catch_all)]
+    __Unknown(u32),
+}
+
+/// Bitfield containing information about the bitmap.
+#[cfg(feature = "api-level-30")]
+#[repr(transparent)]
+#[derive(Clone, Copy, Hash, PartialEq, Eq)]
+pub struct BitmapInfoFlags(u32);
+
+#[cfg(feature = "api-level-30")]
+impl std::fmt::Debug for BitmapInfoFlags {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(
+            f,
+            "BitmapInfoFlags({:#x}, alpha: {:?}, is_hardware: {})",
+            self.0,
+            self.alpha(),
+            self.is_hardware()
+        )
+    }
+}
+
+#[cfg(feature = "api-level-30")]
+impl BitmapInfoFlags {
+    /// Returns the alpha value contained in the [`ffi::ANDROID_BITMAP_FLAGS_ALPHA_MASK`] bit range
+    #[doc(alias = "ANDROID_BITMAP_FLAGS_ALPHA_MASK")]
+    pub fn alpha(self) -> BitmapInfoFlagsAlpha {
+        // Note that ffi::ANDROID_BITMAP_FLAGS_ALPHA_SHIFT is 0 and hence irrelevant.
+        (self.0 & ffi::ANDROID_BITMAP_FLAGS_ALPHA_MASK).into()
+    }
+
+    /// Returns [`true`] when [`ffi::ANDROID_BITMAP_FLAGS_IS_HARDWARE`] is set, meaning this
+    /// [`Bitmap`] uses "HARDWARE Config" and its [`HardwareBufferRef`] can be retrieved via
+    /// [`Bitmap::hardware_buffer()`].
+    #[doc(alias = "ANDROID_BITMAP_FLAGS_IS_HARDWARE")]
+    pub fn is_hardware(self) -> bool {
+        // This constant is defined in a separate anonymous enum which bindgen treats as i32.
+        (self.0 & ffi::ANDROID_BITMAP_FLAGS_IS_HARDWARE as u32) != 0
+    }
+}
+
+/// A native [`AndroidBitmapInfo`]
+///
+/// [`AndroidBitmapInfo`]: https://developer.android.com/ndk/reference/struct/android-bitmap-info#struct_android_bitmap_info
+#[derive(Clone, Copy)]
+#[doc(alias = "AndroidBitmapInfo")]
+pub struct BitmapInfo {
+    inner: ffi::AndroidBitmapInfo,
+}
+
+impl std::fmt::Debug for BitmapInfo {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        let mut f = f.debug_struct("BitmapInfo");
+        f.field("width", &self.width())
+            .field("height", &self.height())
+            .field("stride", &self.stride())
+            .field("format", &self.format());
+
+        #[cfg(feature = "api-level-30")]
+        f.field("flags", &self.flags());
+
+        f.finish()
+    }
+}
+
+impl BitmapInfo {
+    pub fn new(width: u32, height: u32, stride: u32, format: BitmapFormat) -> Self {
+        Self {
+            inner: ffi::AndroidBitmapInfo {
+                width,
+                height,
+                stride,
+                format: format.into(),
+                flags: 0,
+            },
+        }
+    }
+
+    #[cfg(feature = "api-level-30")]
+    pub fn new_with_flags(
+        width: u32,
+        height: u32,
+        stride: u32,
+        format: BitmapFormat,
+        flags: BitmapInfoFlags,
+    ) -> Self {
+        Self {
+            inner: ffi::AndroidBitmapInfo {
+                flags: flags.0,
+                ..Self::new(width, height, stride, format).inner
+            },
+        }
+    }
+
+    /// The bitmap width in pixels.
+    pub fn width(&self) -> u32 {
+        self.inner.width
+    }
+
+    /// The bitmap height in pixels.
+    pub fn height(&self) -> u32 {
+        self.inner.height
+    }
+
+    /// The number of byte per row.
+    pub fn stride(&self) -> u32 {
+        self.inner.stride
+    }
+
+    /// Convert the internal, native [`ffi::AndroidBitmapInfo::format`] into a [`BitmapFormat`].
+    pub fn format(&self) -> BitmapFormat {
+        self.inner.format.into()
+    }
+
+    /// Bitfield containing information about the bitmap.
+    #[cfg(feature = "api-level-30")]
+    pub fn flags(&self) -> BitmapInfoFlags {
+        BitmapInfoFlags(self.inner.flags)
+    }
+}
+
+/// Specifies the formats that can be compressed to with [`Bitmap::compress()`] and
+/// [`Bitmap::compress_raw()`].
+#[cfg(feature = "api-level-30")]
+#[repr(i32)]
+#[derive(Clone, Copy, Debug, Hash, PartialEq, Eq, FromPrimitive, IntoPrimitive)]
+#[doc(alias = "AndroidBitmapCompressFormat")]
+#[non_exhaustive]
+pub enum BitmapCompressFormat {
+    /// Compress to the JPEG format.
+    ///
+    /// quality of `0` means compress for the smallest size. `100` means compress for max visual
+    /// quality.
+    #[doc(alias = "ANDROID_BITMAP_COMPRESS_FORMAT_JPEG")]
+    Jpeg = ffi::AndroidBitmapCompressFormat::ANDROID_BITMAP_COMPRESS_FORMAT_JPEG.0 as i32,
+    /// Compress to the PNG format.
+    ///
+    /// PNG is lossless, so quality is ignored.
+    #[doc(alias = "ANDROID_BITMAP_COMPRESS_FORMAT_PNG")]
+    Png = ffi::AndroidBitmapCompressFormat::ANDROID_BITMAP_COMPRESS_FORMAT_PNG.0 as i32,
+    /// Compress to the WEBP lossless format.
+    ///
+    /// quality refers to how much effort to put into compression. A value of `0` means to
+    /// compress quickly, resulting in a relatively large file size. `100` means to spend more time
+    /// compressing, resulting in a smaller file.
+    #[doc(alias = "ANDROID_BITMAP_COMPRESS_FORMAT_WEBP_LOSSY")]
+    WebPLossy =
+        ffi::AndroidBitmapCompressFormat::ANDROID_BITMAP_COMPRESS_FORMAT_WEBP_LOSSY.0 as i32,
+    /// Compress to the WEBP lossy format.
+    ///
+    /// quality of `0` means compress for the smallest size. `100` means compress for max visual quality.
+    #[doc(alias = "ANDROID_BITMAP_COMPRESS_FORMAT_WEBP_LOSSLESS")]
+    WebPLossless =
+        ffi::AndroidBitmapCompressFormat::ANDROID_BITMAP_COMPRESS_FORMAT_WEBP_LOSSLESS.0 as i32,
+
+    #[doc(hidden)]
+    #[num_enum(catch_all)]
+    __Unknown(i32),
+}
+
+/// Encapsulates possible errors returned by [`Bitmap::compress()`] or [`Bitmap::compress_raw()`].
+#[cfg(feature = "api-level-30")]
+#[derive(Debug, thiserror::Error)]
+pub enum BitmapCompressError {
+    #[error(transparent)]
+    BitmapError(#[from] BitmapError),
+    /// [`Bitmap`] compression requires a known [`DataSpace`].  [`DataSpace::Unknown`] is invalid
+    /// even though it is typically treated as `sRGB`, for that [`DataSpace::Srgb`] has to be passed
+    /// explicitly.
+    #[error("The dataspace for this Bitmap is Unknown")]
+    DataSpaceUnknown,
+}

clients/android/native/vendor/ndk/src/configuration.rs

@@ -0,0 +1,600 @@
+//! Bindings for [`AConfiguration`]
+//!
+//! See also the [NDK docs](https://developer.android.com/ndk/reference/group/configuration) for
+//! [`AConfiguration`], as well as the [docs for providing
+//! resources](https://developer.android.com/guide/topics/resources/providing-resources.html),
+//! which explain many of the configuration values.  The [`android.content.res.Configuration`
+//! javadoc](https://developer.android.com/reference/android/content/res/Configuration.html) may
+//! also have useful information.
+//!
+//! [`AConfiguration`]: https://developer.android.com/ndk/reference/group/configuration#aconfiguration
+
+use crate::asset::AssetManager;
+use num_enum::{FromPrimitive, IntoPrimitive};
+use std::fmt;
+use std::ptr::NonNull;
+
+/// A native [`AConfiguration *`]
+///
+/// [`Configuration`] is an opaque type used to get and set various subsystem configurations.
+///
+/// [`AConfiguration *`]: https://developer.android.com/ndk/reference/group/configuration#aconfiguration
+pub struct Configuration {
+    ptr: NonNull<ffi::AConfiguration>,
+}
+
+unsafe impl Send for Configuration {}
+unsafe impl Sync for Configuration {}
+
+impl Drop for Configuration {
+    fn drop(&mut self) {
+        unsafe { ffi::AConfiguration_delete(self.ptr.as_ptr()) }
+    }
+}
+
+impl Clone for Configuration {
+    fn clone(&self) -> Self {
+        let mut new = Self::new();
+        new.copy(self);
+        new
+    }
+}
+
+impl PartialEq for Configuration {
+    fn eq(&self, other: &Self) -> bool {
+        self.diff(other).0 == 0
+    }
+}
+impl Eq for Configuration {}
+
+impl fmt::Debug for Configuration {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.debug_struct("Configuration")
+            .field("mcc", &self.mcc())
+            .field("mnc", &self.mnc())
+            .field("lang", &self.language())
+            .field("country", &self.country())
+            .field("orientation", &self.orientation())
+            .field("touchscreen", &self.touchscreen())
+            .field("density", &self.density())
+            .field("keyboard", &self.keyboard())
+            .field("navigation", &self.navigation())
+            .field("keys_hidden", &self.keys_hidden())
+            .field("nav_hidden", &self.nav_hidden())
+            .field("sdk_version", &self.sdk_version())
+            .field("screen_size", &self.screen_size())
+            .field("screen_long", &self.screen_long())
+            .field("ui_mode_type", &self.ui_mode_type())
+            .field("ui_mode_night", &self.ui_mode_night())
+            .finish()
+    }
+}
+
+impl Configuration {
+    /// Construct a `Configuration` from a pointer.
+    ///
+    /// # Safety
+    /// By calling this function, you assert that it is a valid pointer to a native
+    /// `AConfiguration`, and give ownership of it to the `Configuration` instance.
+    pub unsafe fn from_ptr(ptr: NonNull<ffi::AConfiguration>) -> Self {
+        Self { ptr }
+    }
+
+    /// Create a new `Configuration`, with the same contents as the `AConfiguration` referenced by
+    /// the pointer.
+    ///
+    /// This is useful if you have a pointer, but not ownership of it.
+    ///
+    /// # Safety
+    /// By calling this function, you assert that it is a valid pointer to a native
+    /// `AConfiguration`.
+    pub unsafe fn clone_from_ptr(ptr: NonNull<ffi::AConfiguration>) -> Self {
+        let conf = Self::new();
+        ffi::AConfiguration_copy(conf.ptr.as_ptr(), ptr.as_ptr());
+        conf
+    }
+
+    /// The pointer to the native `AConfiguration`.  Keep in mind that the `Configuration` object
+    /// still has ownership, and will free it when dropped.
+    pub fn ptr(&self) -> NonNull<ffi::AConfiguration> {
+        self.ptr
+    }
+
+    pub fn from_asset_manager(am: &AssetManager) -> Self {
+        let config = Self::new();
+        unsafe {
+            ffi::AConfiguration_fromAssetManager(config.ptr().as_mut(), am.ptr().as_mut());
+        }
+        config
+    }
+
+    /// Create a new `Configuration`, with none of the values set.
+    pub fn new() -> Self {
+        unsafe {
+            Self {
+                ptr: NonNull::new(ffi::AConfiguration_new()).unwrap(),
+            }
+        }
+    }
+
+    /// `dest.copy(&src)` copies the contents of `src` to `dest`
+    pub fn copy(&mut self, other: &Self) {
+        unsafe { ffi::AConfiguration_copy(self.ptr.as_ptr(), other.ptr.as_ptr()) }
+    }
+
+    /// Information about what fields differ between the two configurations
+    pub fn diff(&self, other: &Self) -> DiffResult {
+        unsafe {
+            DiffResult(ffi::AConfiguration_diff(self.ptr.as_ptr(), other.ptr.as_ptr()) as u32)
+        }
+    }
+
+    /// Returns false if anything in `self` conflicts with `requested`
+    pub fn matches(&self, requested: &Self) -> bool {
+        unsafe { ffi::AConfiguration_match(self.ptr.as_ptr(), requested.ptr.as_ptr()) != 0 }
+    }
+
+    /// Returns the country code, as a [`String`] of two characters, if set
+    pub fn country(&self) -> Option<String> {
+        let mut chars = [0u8; 2];
+        unsafe {
+            ffi::AConfiguration_getCountry(self.ptr.as_ptr(), chars.as_mut_ptr().cast());
+        }
+        if chars[0] == 0 {
+            None
+        } else {
+            Some(std::str::from_utf8(chars.as_slice()).unwrap().to_owned())
+        }
+    }
+
+    /// Returns the screen density in dpi.
+    ///
+    /// On some devices it can return values outside of the density enum.
+    pub fn density(&self) -> Option<u32> {
+        let density = unsafe { ffi::AConfiguration_getDensity(self.ptr.as_ptr()) as u32 };
+        match density {
+            ffi::ACONFIGURATION_DENSITY_DEFAULT => Some(160),
+            ffi::ACONFIGURATION_DENSITY_ANY => None,
+            ffi::ACONFIGURATION_DENSITY_NONE => None,
+            density => Some(density),
+        }
+    }
+
+    /// Returns the keyboard type.
+    pub fn keyboard(&self) -> Keyboard {
+        unsafe { ffi::AConfiguration_getKeyboard(self.ptr.as_ptr()).into() }
+    }
+
+    /// Returns keyboard visibility/availability.
+    pub fn keys_hidden(&self) -> KeysHidden {
+        unsafe { ffi::AConfiguration_getKeysHidden(self.ptr.as_ptr()).into() }
+    }
+
+    /// Returns the language, as a [`String`] of two characters, if set
+    pub fn language(&self) -> Option<String> {
+        let mut chars = [0u8; 2];
+        unsafe {
+            ffi::AConfiguration_getLanguage(self.ptr.as_ptr(), chars.as_mut_ptr().cast());
+        }
+        if chars[0] == 0 {
+            None
+        } else {
+            Some(std::str::from_utf8(chars.as_slice()).unwrap().to_owned())
+        }
+    }
+
+    /// Returns the layout direction
+    pub fn layout_direction(&self) -> LayoutDir {
+        unsafe { ffi::AConfiguration_getLayoutDirection(self.ptr.as_ptr()).into() }
+    }
+
+    /// Returns the mobile country code.
+    pub fn mcc(&self) -> i32 {
+        unsafe { ffi::AConfiguration_getMcc(self.ptr.as_ptr()) }
+    }
+
+    /// Returns the mobile network code, if one is defined
+    pub fn mnc(&self) -> Option<i32> {
+        unsafe {
+            match ffi::AConfiguration_getMnc(self.ptr.as_ptr()) {
+                0 => None,
+                x if x == ffi::ACONFIGURATION_MNC_ZERO as i32 => Some(0),
+                x => Some(x),
+            }
+        }
+    }
+
+    pub fn nav_hidden(&self) -> NavHidden {
+        unsafe { ffi::AConfiguration_getNavHidden(self.ptr.as_ptr()).into() }
+    }
+
+    pub fn navigation(&self) -> Navigation {
+        unsafe { ffi::AConfiguration_getNavigation(self.ptr.as_ptr()).into() }
+    }
+
+    pub fn orientation(&self) -> Orientation {
+        unsafe { ffi::AConfiguration_getOrientation(self.ptr.as_ptr()).into() }
+    }
+
+    pub fn screen_height_dp(&self) -> Option<i32> {
+        unsafe {
+            let height = ffi::AConfiguration_getScreenHeightDp(self.ptr.as_ptr());
+            if height == ffi::ACONFIGURATION_SCREEN_HEIGHT_DP_ANY as i32 {
+                None
+            } else {
+                Some(height)
+            }
+        }
+    }
+
+    pub fn screen_width_dp(&self) -> Option<i32> {
+        unsafe {
+            let width = ffi::AConfiguration_getScreenWidthDp(self.ptr.as_ptr());
+            if width == ffi::ACONFIGURATION_SCREEN_WIDTH_DP_ANY as i32 {
+                None
+            } else {
+                Some(width)
+            }
+        }
+    }
+
+    pub fn screen_long(&self) -> ScreenLong {
+        unsafe { ffi::AConfiguration_getScreenLong(self.ptr.as_ptr()).into() }
+    }
+
+    #[cfg(feature = "api-level-30")]
+    pub fn screen_round(&self) -> ScreenRound {
+        unsafe { ffi::AConfiguration_getScreenRound(self.ptr.as_ptr()).into() }
+    }
+
+    pub fn screen_size(&self) -> ScreenSize {
+        unsafe { ffi::AConfiguration_getScreenSize(self.ptr.as_ptr()).into() }
+    }
+
+    pub fn sdk_version(&self) -> i32 {
+        unsafe { ffi::AConfiguration_getSdkVersion(self.ptr.as_ptr()) }
+    }
+
+    pub fn smallest_screen_width_dp(&self) -> Option<i32> {
+        unsafe {
+            let width = ffi::AConfiguration_getSmallestScreenWidthDp(self.ptr.as_ptr());
+            if width == ffi::ACONFIGURATION_SMALLEST_SCREEN_WIDTH_DP_ANY as i32 {
+                None
+            } else {
+                Some(width)
+            }
+        }
+    }
+
+    pub fn touchscreen(&self) -> Touchscreen {
+        unsafe { ffi::AConfiguration_getTouchscreen(self.ptr.as_ptr()).into() }
+    }
+
+    pub fn ui_mode_night(&self) -> UiModeNight {
+        unsafe { ffi::AConfiguration_getUiModeNight(self.ptr.as_ptr()).into() }
+    }
+
+    pub fn ui_mode_type(&self) -> UiModeType {
+        unsafe { ffi::AConfiguration_getUiModeType(self.ptr.as_ptr()).into() }
+    }
+}
+
+/// A bitfield representing the differences between two [`Configuration`]s
+#[derive(Copy, Clone, Debug, PartialEq, Eq)]
+pub struct DiffResult(pub u32);
+
+impl DiffResult {
+    pub fn mcc(self) -> bool {
+        self.0 & ffi::ACONFIGURATION_MCC != 0
+    }
+    pub fn mnc(self) -> bool {
+        self.0 & ffi::ACONFIGURATION_MNC != 0
+    }
+    pub fn locale(self) -> bool {
+        self.0 & ffi::ACONFIGURATION_LOCALE != 0
+    }
+    pub fn touchscreen(self) -> bool {
+        self.0 & ffi::ACONFIGURATION_TOUCHSCREEN != 0
+    }
+    pub fn keyboard(self) -> bool {
+        self.0 & ffi::ACONFIGURATION_KEYBOARD != 0
+    }
+    pub fn keyboard_hidden(self) -> bool {
+        self.0 & ffi::ACONFIGURATION_KEYBOARD_HIDDEN != 0
+    }
+    pub fn navigation(self) -> bool {
+        self.0 & ffi::ACONFIGURATION_NAVIGATION != 0
+    }
+    pub fn orientation(self) -> bool {
+        self.0 & ffi::ACONFIGURATION_ORIENTATION != 0
+    }
+    pub fn density(self) -> bool {
+        self.0 & ffi::ACONFIGURATION_DENSITY != 0
+    }
+    pub fn screen_size(self) -> bool {
+        self.0 & ffi::ACONFIGURATION_SCREEN_SIZE != 0
+    }
+    pub fn version(self) -> bool {
+        self.0 & ffi::ACONFIGURATION_VERSION != 0
+    }
+    pub fn screen_layout(self) -> bool {
+        self.0 & ffi::ACONFIGURATION_SCREEN_LAYOUT != 0
+    }
+    pub fn ui_mode(self) -> bool {
+        self.0 & ffi::ACONFIGURATION_UI_MODE != 0
+    }
+    pub fn smallest_screen_size(self) -> bool {
+        self.0 & ffi::ACONFIGURATION_SMALLEST_SCREEN_SIZE != 0
+    }
+    pub fn layout_dir(self) -> bool {
+        self.0 & ffi::ACONFIGURATION_LAYOUTDIR != 0
+    }
+    pub fn screen_round(self) -> bool {
+        self.0 & ffi::ACONFIGURATION_SCREEN_ROUND != 0
+    }
+    pub fn color_mode(self) -> bool {
+        self.0 & ffi::ACONFIGURATION_COLOR_MODE != 0
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, FromPrimitive, IntoPrimitive)]
+#[repr(i32)]
+#[non_exhaustive]
+pub enum Orientation {
+    Any = ffi::ACONFIGURATION_ORIENTATION_ANY as i32,
+    Port = ffi::ACONFIGURATION_ORIENTATION_PORT as i32,
+    Land = ffi::ACONFIGURATION_ORIENTATION_LAND as i32,
+    Square = ffi::ACONFIGURATION_ORIENTATION_SQUARE as i32,
+
+    #[doc(hidden)]
+    #[num_enum(catch_all)]
+    __Unknown(i32),
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, FromPrimitive, IntoPrimitive)]
+#[repr(i32)]
+#[non_exhaustive]
+pub enum Touchscreen {
+    Any = ffi::ACONFIGURATION_TOUCHSCREEN_ANY as i32,
+    NoTouch = ffi::ACONFIGURATION_TOUCHSCREEN_NOTOUCH as i32,
+    Stylus = ffi::ACONFIGURATION_TOUCHSCREEN_STYLUS as i32,
+    Finger = ffi::ACONFIGURATION_TOUCHSCREEN_FINGER as i32,
+
+    #[doc(hidden)]
+    #[num_enum(catch_all)]
+    __Unknown(i32),
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, FromPrimitive, IntoPrimitive)]
+#[repr(i32)]
+#[non_exhaustive]
+pub enum Density {
+    Default = ffi::ACONFIGURATION_DENSITY_DEFAULT as i32,
+    Low = ffi::ACONFIGURATION_DENSITY_LOW as i32,
+    Medium = ffi::ACONFIGURATION_DENSITY_MEDIUM as i32,
+    TV = ffi::ACONFIGURATION_DENSITY_TV as i32,
+    High = ffi::ACONFIGURATION_DENSITY_HIGH as i32,
+    XHigh = ffi::ACONFIGURATION_DENSITY_XHIGH as i32,
+    XXHigh = ffi::ACONFIGURATION_DENSITY_XXHIGH as i32,
+    XXXHigh = ffi::ACONFIGURATION_DENSITY_XXXHIGH as i32,
+    Any = ffi::ACONFIGURATION_DENSITY_ANY as i32,
+    None = ffi::ACONFIGURATION_DENSITY_NONE as i32,
+
+    #[doc(hidden)]
+    #[num_enum(catch_all)]
+    __Unknown(i32),
+}
+
+impl Density {
+    /// The DPI associated with the density class.
+    /// See [the Android screen density
+    /// docs](https://developer.android.com/training/multiscreen/screendensities#TaskProvideAltBmp)
+    ///
+    /// There are some [`Density`] values that have no associated DPI; these values return [`None`].
+    pub fn dpi(self) -> Option<u32> {
+        match self {
+            Self::Default => Some(160), // Or should it be None?
+            Self::Low => Some(120),
+            Self::Medium => Some(160),
+            Self::High => Some(240),
+            Self::XHigh => Some(320),
+            Self::XXHigh => Some(480),
+            Self::XXXHigh => Some(640),
+            Self::TV => Some(213),
+            Self::Any => None,
+            Self::None => None,
+            // TODO
+            Self::__Unknown(v) => Some(v as u32),
+        }
+    }
+
+    /// The Hi-DPI factor associated with the density class.  This is the factor by which an
+    /// image/resource should be scaled to match its size across devices.  The baseline is a 160dpi
+    /// screen (i.e., Hi-DPI factor = DPI / 160).
+    /// See [the Android screen density
+    /// docs](https://developer.android.com/training/multiscreen/screendensities#TaskProvideAltBmp)
+    ///
+    /// There are some [`Density`] values that have no associated DPI; these values return [`None`].
+    pub fn approx_hidpi_factor(self) -> Option<f64> {
+        match self {
+            Self::Default => Some(1.), // Or should it be None?
+            Self::Low => Some(0.75),
+            Self::Medium => Some(1.),
+            Self::High => Some(1.5),
+            Self::XHigh => Some(2.),
+            Self::XXHigh => Some(3.),
+            Self::XXXHigh => Some(4.),
+            Self::TV => Some(4. / 3.),
+            Self::Any => None,
+            Self::None => None,
+            Self::__Unknown(_) => None,
+        }
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, FromPrimitive, IntoPrimitive)]
+#[repr(i32)]
+#[non_exhaustive]
+pub enum Keyboard {
+    Any = ffi::ACONFIGURATION_KEYBOARD_ANY as i32,
+    NoKeys = ffi::ACONFIGURATION_KEYBOARD_NOKEYS as i32,
+    Qwerty = ffi::ACONFIGURATION_KEYBOARD_QWERTY as i32,
+    TwelveKey = ffi::ACONFIGURATION_KEYBOARD_12KEY as i32,
+
+    #[doc(hidden)]
+    #[num_enum(catch_all)]
+    __Unknown(i32),
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, FromPrimitive, IntoPrimitive)]
+#[repr(i32)]
+#[non_exhaustive]
+pub enum Navigation {
+    Any = ffi::ACONFIGURATION_NAVIGATION_ANY as i32,
+    NoNav = ffi::ACONFIGURATION_NAVIGATION_NONAV as i32,
+    DPad = ffi::ACONFIGURATION_NAVIGATION_DPAD as i32,
+    Trackball = ffi::ACONFIGURATION_NAVIGATION_TRACKBALL as i32,
+    Wheel = ffi::ACONFIGURATION_NAVIGATION_WHEEL as i32,
+
+    #[doc(hidden)]
+    #[num_enum(catch_all)]
+    __Unknown(i32),
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, FromPrimitive, IntoPrimitive)]
+#[repr(i32)]
+#[non_exhaustive]
+pub enum KeysHidden {
+    Any = ffi::ACONFIGURATION_KEYSHIDDEN_ANY as i32,
+    No = ffi::ACONFIGURATION_KEYSHIDDEN_NO as i32,
+    Yes = ffi::ACONFIGURATION_KEYSHIDDEN_YES as i32,
+    Soft = ffi::ACONFIGURATION_KEYSHIDDEN_SOFT as i32,
+
+    #[doc(hidden)]
+    #[num_enum(catch_all)]
+    __Unknown(i32),
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, FromPrimitive, IntoPrimitive)]
+#[repr(i32)]
+#[non_exhaustive]
+pub enum NavHidden {
+    Any = ffi::ACONFIGURATION_NAVHIDDEN_ANY as i32,
+    No = ffi::ACONFIGURATION_NAVHIDDEN_NO as i32,
+    Yes = ffi::ACONFIGURATION_NAVHIDDEN_YES as i32,
+
+    #[doc(hidden)]
+    #[num_enum(catch_all)]
+    __Unknown(i32),
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, FromPrimitive, IntoPrimitive)]
+#[repr(i32)]
+#[non_exhaustive]
+pub enum ScreenSize {
+    Any = ffi::ACONFIGURATION_SCREENSIZE_ANY as i32,
+    Small = ffi::ACONFIGURATION_SCREENSIZE_SMALL as i32,
+    Normal = ffi::ACONFIGURATION_SCREENSIZE_NORMAL as i32,
+    Large = ffi::ACONFIGURATION_SCREENSIZE_LARGE as i32,
+    XLarge = ffi::ACONFIGURATION_SCREENSIZE_XLARGE as i32,
+
+    #[doc(hidden)]
+    #[num_enum(catch_all)]
+    __Unknown(i32),
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, FromPrimitive, IntoPrimitive)]
+#[repr(i32)]
+#[non_exhaustive]
+pub enum ScreenLong {
+    Any = ffi::ACONFIGURATION_SCREENLONG_ANY as i32,
+    No = ffi::ACONFIGURATION_SCREENLONG_NO as i32,
+    Yes = ffi::ACONFIGURATION_SCREENLONG_YES as i32,
+
+    #[doc(hidden)]
+    #[num_enum(catch_all)]
+    __Unknown(i32),
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, FromPrimitive, IntoPrimitive)]
+#[repr(i32)]
+#[non_exhaustive]
+pub enum ScreenRound {
+    Any = ffi::ACONFIGURATION_SCREENROUND_ANY as i32,
+    No = ffi::ACONFIGURATION_SCREENROUND_NO as i32,
+    Yes = ffi::ACONFIGURATION_SCREENROUND_YES as i32,
+
+    #[doc(hidden)]
+    #[num_enum(catch_all)]
+    __Unknown(i32),
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, FromPrimitive, IntoPrimitive)]
+#[repr(i32)]
+#[non_exhaustive]
+pub enum WideColorGamut {
+    Any = ffi::ACONFIGURATION_WIDE_COLOR_GAMUT_ANY as i32,
+    No = ffi::ACONFIGURATION_WIDE_COLOR_GAMUT_NO as i32,
+    Yes = ffi::ACONFIGURATION_WIDE_COLOR_GAMUT_YES as i32,
+
+    #[doc(hidden)]
+    #[num_enum(catch_all)]
+    __Unknown(i32),
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, FromPrimitive, IntoPrimitive)]
+#[repr(i32)]
+#[non_exhaustive]
+pub enum HDR {
+    Any = ffi::ACONFIGURATION_HDR_ANY as i32,
+    No = ffi::ACONFIGURATION_HDR_NO as i32,
+    Yes = ffi::ACONFIGURATION_HDR_YES as i32,
+
+    #[doc(hidden)]
+    #[num_enum(catch_all)]
+    __Unknown(i32),
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, FromPrimitive, IntoPrimitive)]
+#[repr(i32)]
+#[non_exhaustive]
+pub enum LayoutDir {
+    Any = ffi::ACONFIGURATION_LAYOUTDIR_ANY as i32,
+    Ltr = ffi::ACONFIGURATION_LAYOUTDIR_LTR as i32,
+    Rtl = ffi::ACONFIGURATION_LAYOUTDIR_RTL as i32,
+
+    #[doc(hidden)]
+    #[num_enum(catch_all)]
+    __Unknown(i32),
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, FromPrimitive, IntoPrimitive)]
+#[repr(i32)]
+#[non_exhaustive]
+pub enum UiModeType {
+    Any = ffi::ACONFIGURATION_UI_MODE_TYPE_ANY as i32,
+    Normal = ffi::ACONFIGURATION_UI_MODE_TYPE_NORMAL as i32,
+    Desk = ffi::ACONFIGURATION_UI_MODE_TYPE_DESK as i32,
+    Car = ffi::ACONFIGURATION_UI_MODE_TYPE_CAR as i32,
+    Television = ffi::ACONFIGURATION_UI_MODE_TYPE_TELEVISION as i32,
+    Applicance = ffi::ACONFIGURATION_UI_MODE_TYPE_APPLIANCE as i32,
+    Watch = ffi::ACONFIGURATION_UI_MODE_TYPE_WATCH as i32,
+    VrHeadset = ffi::ACONFIGURATION_UI_MODE_TYPE_VR_HEADSET as i32,
+
+    #[doc(hidden)]
+    #[num_enum(catch_all)]
+    __Unknown(i32),
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, FromPrimitive, IntoPrimitive)]
+#[repr(i32)]
+#[non_exhaustive]
+pub enum UiModeNight {
+    Any = ffi::ACONFIGURATION_UI_MODE_NIGHT_ANY as i32,
+    No = ffi::ACONFIGURATION_UI_MODE_NIGHT_NO as i32,
+    Yes = ffi::ACONFIGURATION_UI_MODE_NIGHT_YES as i32,
+
+    #[doc(hidden)]
+    #[num_enum(catch_all)]
+    __Unknown(i32),
+}

clients/android/native/vendor/ndk/src/data_space.rs

@@ -0,0 +1,648 @@
+//! Bindings for [`ADataSpace`]
+//!
+//! [`ADataSpace`]: https://developer.android.com/ndk/reference/group/a-data-space#group___a_data_space_1ga2759ad19cae46646cc5f7002758c4a1c
+#![cfg(feature = "api-level-28")]
+
+use std::fmt;
+
+use num_enum::{FromPrimitive, IntoPrimitive};
+
+/// Describes how to interpret colors.
+///
+/// <https://developer.android.com/ndk/reference/group/a-data-space#group___a_data_space_1ga2759ad19cae46646cc5f7002758c4a1c>
+#[repr(i32)]
+#[derive(Clone, Copy, Hash, PartialEq, Eq, FromPrimitive, IntoPrimitive)]
+#[doc(alias = "ADataSpace")]
+#[non_exhaustive]
+pub enum DataSpace {
+    /// Default-assumption data space, when not explicitly specified.
+    ///
+    /// It is safest to assume the buffer is an image with `sRGB` primaries and encoding ranges,
+    /// but the consumer and/or the producer of the data may simply be using defaults. No automatic
+    /// gamma transform should be expected, except for a possible display gamma transform when drawn
+    /// to a screen.
+    #[doc(alias = "ADATASPACE_UNKNOWN")]
+    Unknown = ffi::ADataSpace::ADATASPACE_UNKNOWN.0,
+
+    /// Adobe RGB.
+    ///
+    /// Uses [full range], [gamma `2.2` transfer] and [Adobe RGB standard].
+    ///
+    /// Note: Application is responsible for gamma encoding the data as a `2.2` gamma encoding is
+    /// not supported in HW.
+    ///
+    /// [full range]: DataSpaceRange::Full
+    /// [gamma `2.2` transfer]: DataSpaceTransfer::Gamma2_2
+    /// [Adobe RGB standard]: DataSpaceStandard::AdobeRgb
+    #[doc(alias = "ADATASPACE_ADOBE_RGB")]
+    AdobeRgb = ffi::ADataSpace::ADATASPACE_ADOBE_RGB.0,
+    /// ITU-R Recommendation 2020 (`BT.2020`).
+    ///
+    /// Ultra High-definition television.
+    ///
+    /// Uses [full range], [`SMPTE 170M` transfer] and [`BT2020` standard].
+    ///
+    /// [full range]: DataSpaceRange::Full
+    /// [`SMPTE 170M` transfer]: DataSpaceTransfer::Smpte170M
+    /// [`BT2020` standard]: DataSpaceStandard::Bt2020
+    #[doc(alias = "ADATASPACE_BT2020")]
+    Bt2020 = ffi::ADataSpace::ADATASPACE_BT2020.0,
+    /// Hybrid Log Gamma encoding.
+    ///
+    /// Uses [full range], [hybrid log gamma transfer] and [`BT2020` standard].
+    ///
+    /// [full range]: DataSpaceRange::Full
+    /// [hybrid log gamma transfer]: DataSpaceTransfer::HLG
+    /// [`BT2020` standard]: DataSpaceStandard::Bt2020
+    #[doc(alias = "ADATASPACE_BT2020_HLG")]
+    Bt2020Hlg = ffi::ADataSpace::ADATASPACE_BT2020_HLG.0,
+    /// ITU Hybrid Log Gamma encoding.
+    ///
+    /// Uses [limited range], [hybrid log gamma transfer] and [`BT2020` standard].
+    ///
+    /// [limited range]: DataSpaceRange::Limited
+    /// [hybrid log gamma transfer]: DataSpaceTransfer::HLG
+    /// [`BT2020` standard]: DataSpaceStandard::Bt2020
+    #[doc(alias = "ADATASPACE_BT2020_ITU_HLG")]
+    Bt2020ItuHlg = ffi::ADataSpace::ADATASPACE_BT2020_ITU_HLG.0,
+    /// ITU-R Recommendation 2020 (`BT.2020`).
+    ///
+    /// Ultra High-definition television.
+    ///
+    /// Uses [limited range], [`SMPTE 2084 (PQ)` transfer] and [`BT2020` standard].
+    ///
+    /// [limited range]: DataSpaceRange::Limited
+    /// [`SMPTE 2084 (PQ)` transfer]: DataSpaceTransfer::St2084
+    /// [`BT2020` standard]: DataSpaceStandard::Bt2020
+    #[doc(alias = "ADATASPACE_BT2020_ITU_PQ")]
+    Bt2020ItuPq = ffi::ADataSpace::ADATASPACE_BT2020_ITU_PQ.0,
+    /// ITU-R Recommendation 2020 (`BT.2020`).
+    ///
+    /// Ultra High-definition television.
+    ///
+    /// Uses [full range], [`SMPTE 2084 (PQ)` transfer] and [`BT2020` standard].
+    ///
+    /// [full range]: DataSpaceRange::Full
+    /// [`SMPTE 2084 (PQ)` transfer]: DataSpaceTransfer::St2084
+    /// [`BT2020` standard]: DataSpaceStandard::Bt2020
+    #[doc(alias = "ADATASPACE_BT2020_PQ")]
+    Bt2020Pq = ffi::ADataSpace::ADATASPACE_BT2020_PQ.0,
+    /// ITU-R Recommendation 601 (`BT.601`) - 525-line.
+    ///
+    /// Standard-definition television, 525 Lines (NTSC).
+    ///
+    /// Uses [limited range], [`SMPTE 170M` transfer] and [`BT.601_525` standard].
+    ///
+    /// [limited range]: DataSpaceRange::Limited
+    /// [`SMPTE 170M` transfer]: DataSpaceTransfer::Smpte170M
+    /// [`BT.601_525` standard]: DataSpaceStandard::Bt601_525
+    #[doc(alias = "ADATASPACE_BT601_525")]
+    Bt601_525 = ffi::ADataSpace::ADATASPACE_BT601_525.0,
+    /// ITU-R Recommendation 601 (`BT.601`) - 625-line.
+    ///
+    /// Standard-definition television, 625 Lines (PAL).
+    ///
+    /// Uses [limited range], [`SMPTE 170M` transfer] and [`BT.601_625` standard].
+    ///
+    /// [limited range]: DataSpaceRange::Limited
+    /// [`SMPTE 170M` transfer]: DataSpaceTransfer::Smpte170M
+    /// [`BT.601_625` standard]: DataSpaceStandard::Bt601_625
+    #[doc(alias = "ADATASPACE_BT601_625")]
+    Bt601_625 = ffi::ADataSpace::ADATASPACE_BT601_625.0,
+    /// ITU-R Recommendation 709 (`BT.709`).
+    ///
+    /// High-definition television.
+    ///
+    /// Uses [limited range], [`SMPTE 170M` transfer] and [`BT.709` standard].
+    ///
+    /// [limited range]: DataSpaceRange::Limited
+    /// [`SMPTE 170M` transfer]: DataSpaceTransfer::Smpte170M
+    /// [`BT.709` standard]: DataSpaceStandard::Bt709
+    #[doc(alias = "ADATASPACE_BT709")]
+    Bt709 = ffi::ADataSpace::ADATASPACE_BT709.0,
+    /// `SMPTE EG 432-1` and `SMPTE RP 431-2`.
+    ///
+    /// Digital Cinema `DCI-P3`.
+    ///
+    /// Uses [full range], [gamma `2.6` transfer] and [`D65` `DCI-P3` standard].
+    ///
+    /// Note: Application is responsible for gamma encoding the data as a `2.6` gamma encoding is
+    /// not supported in HW.
+    ///
+    /// [full range]: DataSpaceRange::Full
+    /// [gamma `2.6` transfer]: DataSpaceTransfer::Gamma2_6
+    /// [`D65` `DCI-P3` standard]: DataSpaceStandard::DciP3
+    #[doc(alias = "ADATASPACE_DCI_P3")]
+    DciP3 = ffi::ADataSpace::ADATASPACE_DCI_P3.0,
+    /// Display P3.
+    ///
+    /// Uses [full range], [`sRGB` transfer] and [`D65` `DCI-P3` standard].
+    ///
+    /// [full range]: DataSpaceRange::Full
+    /// [`sRGB` transfer]: DataSpaceTransfer::Srgb
+    /// [`D65` `DCI-P3` standard]: DataSpaceStandard::DciP3
+    #[doc(alias = "ADATASPACE_DISPLAY_P3")]
+    DisplayP3 = ffi::ADataSpace::ADATASPACE_DISPLAY_P3.0,
+    /// JPEG File Interchange Format (`JFIF`).
+    ///
+    /// Same model as `BT.601-625`, but all values (`Y`, `Cb`, `Cr`) range from `0` to `255`.
+    ///
+    /// Uses [full range], [`SMPTE 170M` transfer] and [`BT.601_625` standard].
+    ///
+    /// [full range]: DataSpaceRange::Full
+    /// [`SMPTE 170M` transfer]: DataSpaceTransfer::Smpte170M
+    /// [`BT.601_625` standard]: DataSpaceStandard::Bt601_625
+    #[doc(alias = "ADATASPACE_JFIF")]
+    Jfif = ffi::ADataSpace::ADATASPACE_JFIF.0,
+    /// `scRGB`.
+    ///
+    /// The `red`, `green`, and `blue` components are stored in [extended][extended range] `sRGB`
+    /// space, and gamma- encoded using the [`sRGB` transfer] function.
+    ///
+    /// The values are floating point. A pixel value of `1.0`, `1.0`, `1.0` corresponds to `sRGB`
+    /// white (`D65`) at `80` nits. Values beyond the range `[0.0 - 1.0]` would correspond to other
+    /// colors spaces and/or HDR content.
+    ///
+    /// Uses [extended range], [`sRGB` transfer] and [`BT.709` standard].
+    ///
+    /// [extended range]: DataSpaceRange::Extended
+    /// [`sRGB` transfer]: DataSpaceTransfer::Srgb
+    /// [`BT.709` standard]: DataSpaceStandard::Bt709
+    #[doc(alias = "ADATASPACE_SCRGB")]
+    Scrgb = ffi::ADataSpace::ADATASPACE_SCRGB.0,
+    /// `scRGB` linear encoding
+    ///
+    /// The `red`, `green`, and `blue` components are stored in [extended][extended range] `sRGB`
+    /// space, but are linear, not gamma-encoded.
+    ///
+    /// The values are floating point. A pixel value of `1.0`, `1.0`, `1.0` corresponds to `sRGB`
+    /// white (`D65`) at `80` nits. Values beyond the range `[0.0 - 1.0]` would correspond to other
+    /// colors spaces and/or HDR content.
+    ///
+    /// Uses [extended range], [linear transfer] and [`BT.709` standard].
+    ///
+    /// [extended range]: DataSpaceRange::Extended
+    /// [linear transfer]: DataSpaceTransfer::Linear
+    /// [`BT.709` standard]: DataSpaceStandard::Bt709
+    #[doc(alias = "ADATASPACE_SCRGB_LINEAR")]
+    ScrgbLinear = ffi::ADataSpace::ADATASPACE_SCRGB_LINEAR.0,
+    /// `sRGB` gamma encoding.
+    ///
+    /// The `red`, `green` and `blue` components are stored in `sRGB` space, and converted to linear
+    /// space when read, using the [`sRGB` transfer] function for each of the `R`, `G` and `B`
+    /// components. When written, the inverse transformation is performed.
+    ///
+    /// The `alpha` component, if present, is always stored in linear space and is left unmodified
+    /// when read or written.
+    ///
+    /// Uses [full range], [`sRGB` transfer] and [`BT.709` standard].
+    ///
+    /// [full range]: DataSpaceRange::Full
+    /// [`sRGB` transfer]: DataSpaceTransfer::Srgb
+    /// [`BT.709` standard]: DataSpaceStandard::Bt709
+    #[doc(alias = "ADATASPACE_SRGB")]
+    Srgb = ffi::ADataSpace::ADATASPACE_SRGB.0,
+    /// `sRGB` linear encoding.
+    ///
+    /// The `red`, `green`, and `blue` components are stored in `sRGB` space, but are linear, not
+    /// gamma-encoded. The `RGB` primaries and the white point are the same as [`BT.709]`.
+    ///
+    /// The values are encoded using the [full range] (`[0, 255]` for 8-bit) for all components.
+    ///
+    /// Uses [full range], [linear transfer] and [`BT.709` standard].
+    ///
+    /// [full range]: DataSpaceRange::Full
+    /// [linear transfer]: DataSpaceTransfer::Linear
+    /// [`BT.709` standard]: DataSpaceStandard::Bt709
+    #[doc(alias = "ADATASPACE_SRGB_LINEAR")]
+    SrgbLinear = ffi::ADataSpace::ADATASPACE_SRGB_LINEAR.0,
+
+    /// Depth.
+    ///
+    /// This value is valid with formats [`HAL_PIXEL_FORMAT_Y16`] and [`HAL_PIXEL_FORMAT_BLOB`].
+    ///
+    /// [`HAL_PIXEL_FORMAT_Y16`]: https://cs.android.com/android/platform/superproject/main/+/main:frameworks/native/libs/nativewindow/include/vndk/hardware_buffer.h;l=74-75;drc=45317f5c7c966fc816843217adc96a2ddea8bf29
+    /// [`HAL_PIXEL_FORMAT_BLOB`]: super::hardware_buffer_format::HardwareBufferFormat::BLOB
+    #[doc(alias = "ADATASPACE_DEPTH")]
+    Depth = ffi::ADataSpace::ADATASPACE_DEPTH.0,
+    /// ISO `16684-1:2011(E)` Dynamic Depth.
+    ///
+    /// Embedded depth metadata following the dynamic depth specification.
+    #[doc(alias = "ADATASPACE_DYNAMIC_DEPTH")]
+    DynamicDepth = ffi::ADataSpace::ADATASPACE_DYNAMIC_DEPTH.0,
+
+    #[doc(hidden)]
+    #[num_enum(catch_all)]
+    __Unknown(i32),
+}
+
+impl fmt::Display for DataSpace {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.write_str(match self {
+            Self::Unknown => "Unknown",
+            Self::AdobeRgb => "AdobeRgb",
+            Self::Bt2020 => "Bt2020",
+            Self::Bt2020Hlg => "Bt2020Hlg",
+            Self::Bt2020ItuHlg => "Bt2020ItuHlg",
+            Self::Bt2020ItuPq => "Bt2020ItuPq",
+            Self::Bt2020Pq => "Bt2020Pq",
+            Self::Bt601_525 => "Bt601_525",
+            Self::Bt601_625 => "Bt601_625",
+            Self::Bt709 => "Bt709",
+            Self::DciP3 => "DciP3",
+            Self::DisplayP3 => "DisplayP3",
+            Self::Jfif => "Jfif",
+            Self::Scrgb => "Scrgb",
+            Self::ScrgbLinear => "ScrgbLinear",
+            Self::Srgb => "Srgb",
+            Self::SrgbLinear => "SrgbLinear",
+            Self::Depth => "Depth",
+            Self::DynamicDepth => "DynamicDepth",
+            Self::__Unknown(u) => {
+                return write!(
+                    f,
+                    "Unknown DataSpace({u:x?}, standard: {:?}, transfer: {:?}, range: {:?})",
+                    self.standard(),
+                    self.transfer(),
+                    self.range()
+                )
+            }
+        })
+    }
+}
+
+impl fmt::Debug for DataSpace {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(
+            f,
+            "DataSpace({self}, standard: {:?}, transfer: {:?}, range: {:?})",
+            self.standard(),
+            self.transfer(),
+            self.range(),
+        )
+    }
+}
+
+impl DataSpace {
+    /// Construct a [`DataSpace`] from individual `standard`, `transfer` and `range` components.
+    ///
+    /// Together these should correspond to a single format.
+    pub fn from_parts(
+        standard: DataSpaceStandard,
+        transfer: DataSpaceTransfer,
+        range: DataSpaceRange,
+    ) -> Self {
+        Self::from(i32::from(standard) | i32::from(transfer) | i32::from(range))
+    }
+
+    /// Extracts and returns the color-description aspect from this [`DataSpace`].
+    #[doc(alias = "STANDARD_MASK")]
+    pub fn standard(self) -> DataSpaceStandard {
+        let standard = i32::from(self) & ffi::ADataSpace::STANDARD_MASK.0;
+        standard.into()
+    }
+
+    /// Extracts and returns the transfer aspect from this [`DataSpace`].
+    #[doc(alias = "TRANSFER_MASK")]
+    pub fn transfer(self) -> DataSpaceTransfer {
+        let transfer = i32::from(self) & ffi::ADataSpace::TRANSFER_MASK.0;
+        transfer.into()
+    }
+
+    /// Extracts and returns the range aspect from this [`DataSpace`].
+    #[doc(alias = "RANGE_MASK")]
+    pub fn range(self) -> DataSpaceRange {
+        let range = i32::from(self) & ffi::ADataSpace::RANGE_MASK.0;
+        range.into()
+    }
+}
+
+/// Color-description aspects.
+///
+/// The following aspects define various characteristics of the color specification. These represent
+/// bitfields, so that a data space value can specify each of them independently. Standard aspect
+/// defines the chromaticity coordinates of the source primaries in terms of the CIE 1931 definition
+/// of `x` and `y` specified in ISO 11664-1.
+#[repr(i32)]
+#[derive(Clone, Copy, Debug, Hash, PartialEq, Eq, FromPrimitive, IntoPrimitive)]
+#[doc(alias = "STANDARD_MASK")]
+#[non_exhaustive]
+pub enum DataSpaceStandard {
+    /// Chromacity coordinates are unknown or are determined by the application. Implementations
+    /// shall use the following suggested standards:
+    ///
+    /// All `YCbCr` formats: [`BT.709`] if size is `720p` or larger (since most video content is
+    ///                      letterboxed this corresponds to width is `1280` or greater, or height
+    ///                      is 720 or greater). [`BT.601_625`] if size is smaller than `720p` or
+    ///                      is `JPEG`.
+    /// All `RGB` formats:   [`BT.709`].
+    ///
+    /// For all other formats the standard is undefined, and implementations should use an
+    /// appropriate standard for the data represented.
+    ///
+    /// [`BT.709`]: Self::Bt709
+    /// [`BT.601_625`]: Self::Bt601_625
+    #[doc(alias = "STANDARD_UNSPECIFIED")]
+    Unspecified = ffi::ADataSpace::STANDARD_UNSPECIFIED.0,
+    /// | Primaries   | x      | y      |
+    /// | ----------- | ------ | ------ |
+    /// | green       | 0.300  | 0.600  |
+    /// | blue        | 0.150  | 0.060  |
+    /// | red         | 0.640  | 0.330  |
+    /// | white (D65) | 0.3127 | 0.3290 |
+    ///
+    /// Use the unadjusted `KR = 0.2126`, `KB = 0.0722` luminance interpretation for `RGB`
+    /// conversion.
+    #[doc(alias = "STANDARD_BT709")]
+    Bt709 = ffi::ADataSpace::STANDARD_BT709.0,
+    /// | Primaries   | x      | y      |
+    /// | ----------- | ------ | ------ |
+    /// | green       | 0.290  | 0.600  |
+    /// | blue        | 0.150  | 0.060  |
+    /// | red         | 0.640  | 0.330  |
+    /// | white (D65) | 0.3127 | 0.3290 |
+    ///
+    /// `KR = 0.299`, `KB = 0.114`. This adjusts the luminance interpretation for `RGB` conversion
+    /// from the one purely determined by the primaries to minimize the color shift into `RGB`
+    /// space that uses [`BT.709`] primaries.
+    ///
+    /// [`BT.709`]: Self::Bt709
+    #[doc(alias = "STANDARD_BT601_625")]
+    Bt601_625 = ffi::ADataSpace::STANDARD_BT601_625.0,
+    /// | Primaries   | x      | y      |
+    /// | ----------- | ------ | ------ |
+    /// | green       | 0.290  | 0.600  |
+    /// | blue        | 0.150  | 0.060  |
+    /// | red         | 0.640  | 0.330  |
+    /// | white (D65) | 0.3127 | 0.3290 |
+    ///
+    /// Use the unadjusted `KR = 0.222`, `KB = 0.071` luminance interpretation for `RGB` conversion.
+    #[doc(alias = "STANDARD_BT601_625_UNADJUSTED")]
+    Bt601_625Unadjusted = ffi::ADataSpace::STANDARD_BT601_625_UNADJUSTED.0,
+    /// | Primaries   | x      | y      |
+    /// | ----------- | ------ | ------ |
+    /// | green       | 0.310  | 0.595  |
+    /// | blue        | 0.155  | 0.070  |
+    /// | red         | 0.630  | 0.340  |
+    /// | white (D65) | 0.3127 | 0.3290 |
+    ///
+    /// `KR = 0.299`, `KB = 0.114`. This adjusts the luminance interpretation for `RGB` conversion
+    /// from the one purely determined by the primaries to minimize the color shift into `RGB` space
+    /// that uses [`BT.709`] primaries.
+    ///
+    /// [`BT.709`]: Self::Bt709
+    #[doc(alias = "STANDARD_BT601_525")]
+    Bt601_525 = ffi::ADataSpace::STANDARD_BT601_525.0,
+    /// | Primaries   | x      | y      |
+    /// | ----------- | ------ | ------ |
+    /// | green       | 0.310  | 0.595  |
+    /// | blue        | 0.155  | 0.070  |
+    /// | red         | 0.630  | 0.340  |
+    /// | white (D65) | 0.3127 | 0.3290 |
+    ///
+    /// Use the unadjusted `KR = 0.212`, `KB = 0.087` luminance interpretation
+    /// for `RGB` conversion (as in `SMPTE 240M`).
+    #[doc(alias = "STANDARD_BT601_525_UNADJUSTED")]
+    Bt601_525Unadjusted = ffi::ADataSpace::STANDARD_BT601_525_UNADJUSTED.0,
+    /// | Primaries   | x      | y      |
+    /// | ----------- | ------ | ------ |
+    /// | green       | 0.170  | 0.797  |
+    /// | blue        | 0.131  | 0.046  |
+    /// | red         | 0.708  | 0.292  |
+    /// | white (D65) | 0.3127 | 0.3290 |
+    ///
+    /// Use the unadjusted `KR = 0.2627`, `KB = 0.0593` luminance interpretation for `RGB`
+    /// conversion.
+    #[doc(alias = "STANDARD_BT2020")]
+    Bt2020 = ffi::ADataSpace::STANDARD_BT2020.0,
+    /// | Primaries   | x      | y      |
+    /// | ----------- | ------ | ------ |
+    /// | green       | 0.170  | 0.797  |
+    /// | blue        | 0.131  | 0.046  |
+    /// | red         | 0.708  | 0.292  |
+    /// | white (D65) | 0.3127 | 0.3290 |
+    ///
+    /// Use the unadjusted `KR = 0.2627`, `KB = 0.0593` luminance interpretation for `RGB`
+    /// conversion using the linear domain.
+    #[doc(alias = "STANDARD_BT2020_CONSTANT_LUMINANCE")]
+    Bt2020ConstantLuminance = ffi::ADataSpace::STANDARD_BT2020_CONSTANT_LUMINANCE.0,
+    /// | Primaries | x     | y    |
+    /// | --------- | ----- | ---- |
+    /// | green     | 0.21  |0.71  |
+    /// | blue      | 0.14  |0.08  |
+    /// | red       | 0.67  |0.33  |
+    /// | white (C) | 0.310 |0.316 |
+    ///
+    /// Use the unadjusted `KR = 0.30`, `KB = 0.11` luminance interpretation for `RGB` conversion.
+    #[doc(alias = "STANDARD_BT470M")]
+    Bt470M = ffi::ADataSpace::STANDARD_BT470M.0,
+    /// | Primaries | x     | y     |
+    /// | --------- | ----- | ----- |
+    /// | green     | 0.243 | 0.692 |
+    /// | blue      | 0.145 | 0.049 |
+    /// | red       | 0.681 | 0.319 |
+    /// | white (C) | 0.310 | 0.316 |
+    ///
+    /// Use the unadjusted `KR = 0.254`, `KB = 0.068` luminance interpretation for `RGB` conversion.
+    #[doc(alias = "STANDARD_FILM")]
+    Film = ffi::ADataSpace::STANDARD_FILM.0,
+    /// `SMPTE EG 432-1` and `SMPTE RP 431-2`. (`DCI-P3`)
+    ///
+    /// | Primaries   | x      | y      |
+    /// | ----------- | ------ | ------ |
+    /// | green       | 0.265  | 0.690  |
+    /// | blue        | 0.150  | 0.060  |
+    /// | red         | 0.680  | 0.320  |
+    /// | white (D65) | 0.3127 | 0.3290 |
+    #[doc(alias = "STANDARD_DCI_P3")]
+    DciP3 = ffi::ADataSpace::STANDARD_DCI_P3.0,
+    /// Adobe RGB
+    ///
+    /// | Primaries   | x      | y      |
+    /// | ----------- | ------ | ------ |
+    /// | green       | 0.210  | 0.710  |
+    /// | blue        | 0.150  | 0.060  |
+    /// | red         | 0.640  | 0.330  |
+    /// | white (D65) | 0.3127 | 0.3290 |
+    #[doc(alias = "STANDARD_ADOBE_RGB")]
+    AdobeRgb = ffi::ADataSpace::STANDARD_ADOBE_RGB.0,
+
+    #[doc(hidden)]
+    #[num_enum(catch_all)]
+    __Unknown(i32),
+}
+
+/// Transfer aspect.
+///
+/// Transfer characteristics are the opto-electronic transfer characteristic at the source as a
+///function of linear optical intensity (luminance).
+///
+/// For digital signals, `E` corresponds to the recorded value. Normally, the transfer function is
+/// applied in `RGB` space to each of the `R`, `G` and `B` components independently. This may result
+/// in color shift that can be minimized by applying the transfer function in `Lab` space only for
+/// the `L` component. Implementation may apply the transfer function in `RGB` space for all pixel
+/// formats if desired.
+#[repr(i32)]
+#[derive(Clone, Copy, Debug, Hash, PartialEq, Eq, FromPrimitive, IntoPrimitive)]
+#[doc(alias = "TRANSFER_MASK")]
+#[non_exhaustive]
+pub enum DataSpaceTransfer {
+    /// Transfer characteristics are unknown or are determined by the application.
+    ///
+    /// Implementations should use the following transfer functions:
+    ///
+    /// - For `YCbCr` formats: use [`DataSpaceTransfer::Smpte170M`]
+    /// - For `RGB` formats: use [`DataSpaceTransfer::Srgb`]
+    ///
+    /// For all other formats the transfer function is undefined, and implementations should use an
+    /// appropriate standard for the data represented.
+    #[doc(alias = "TRANSFER_UNSPECIFIED")]
+    Unspecified = ffi::ADataSpace::TRANSFER_UNSPECIFIED.0,
+
+    /// Linear transfer.
+    ///
+    /// Transfer characteristic curve:
+    /// ```ignore
+    /// E = L
+    /// ```
+    /// - `L`: luminance of image `0 <= L <= 1` for conventional colorimetry
+    /// - `E`: corresponding electrical signal
+    #[doc(alias = "TRANSFER_LINEAR")]
+    Linear = ffi::ADataSpace::TRANSFER_LINEAR.0,
+    /// `sRGB` transfer.
+    ///
+    /// Transfer characteristic curve:
+    ///
+    /// ```ignore
+    /// E = 1.055 * L^(1/2.4) - 0.055 for 0.0031308 <= L <= 1
+    ///   = 12.92 * L                 for 0 <= L < 0.0031308
+    /// ```
+    /// - `L`: luminance of image `0 <= L <= 1` for conventional colorimetry
+    /// - `E`: corresponding electrical signal
+    #[doc(alias = "TRANSFER_SRGB")]
+    Srgb = ffi::ADataSpace::TRANSFER_SRGB.0,
+    /// SMPTE 170M transfer.
+    ///
+    /// Transfer characteristic curve:
+    /// ```ignore
+    /// E = 1.099 * L ^ 0.45 - 0.099 for 0.018 <= L <= 1
+    ///   = 4.500 * L                for 0 <= L < 0.018
+    /// ```
+    /// - `L`: luminance of image `0 <= L <= 1` for conventional colorimetry
+    /// - `E`: corresponding electrical signal
+    #[doc(alias = "TRANSFER_SMPTE_170M")]
+    Smpte170M = ffi::ADataSpace::TRANSFER_SMPTE_170M.0,
+    /// Display gamma `2.2`.
+    ///
+    /// Transfer characteristic curve:
+    /// ```ignore
+    /// E = L ^ (1/2.2)
+    /// ```
+    /// - `L`: luminance of image `0 <= L <= 1` for conventional colorimetry
+    /// - `E`: corresponding electrical signal
+    #[doc(alias = "TRANSFER_GAMMA2_2")]
+    Gamma2_2 = ffi::ADataSpace::TRANSFER_GAMMA2_2.0,
+    /// Display gamma `2.6`.
+    ///
+    /// Transfer characteristic curve:
+    /// ```ignore
+    /// E = L ^ (1/2.6)
+    /// ```
+    /// - `L`: luminance of image `0 <= L <= 1` for conventional colorimetry
+    /// - `E`: corresponding electrical signal
+    #[doc(alias = "TRANSFER_GAMMA2_6")]
+    Gamma2_6 = ffi::ADataSpace::TRANSFER_GAMMA2_6.0,
+    /// Display gamma `2.8`.
+    ///
+    /// Transfer characteristic curve:
+    /// ```ignore
+    /// E = L ^ (1/2.8)
+    /// ```
+    /// - `L`: luminance of image `0 <= L <= 1` for conventional colorimetry
+    /// - `E`: corresponding electrical signal
+    #[doc(alias = "TRANSFER_GAMMA2_8")]
+    Gamma2_8 = ffi::ADataSpace::TRANSFER_GAMMA2_8.0,
+    /// SMPTE ST 2084 (Dolby Perceptual Quantizer).
+    ///
+    /// Transfer characteristic curve:
+    /// ```ignore
+    /// E = ((c1 + c2 * L^n) / (1 + c3 * L^n)) ^ m
+    /// c1 = c3 - c2 + 1 = 3424 / 4096 = 0.8359375
+    /// c2 = 32 * 2413 / 4096 = 18.8515625
+    /// c3 = 32 * 2392 / 4096 = 18.6875
+    /// m = 128 * 2523 / 4096 = 78.84375
+    /// n = 0.25 * 2610 / 4096 = 0.1593017578125
+    /// ```
+    /// - `L`: luminance of image 0 <= L <= 1 for HDR colorimetry.
+    ///        `L = 1` corresponds to `10000 cd/m2`
+    #[doc(alias = "TRANSFER_ST2084")]
+    St2084 = ffi::ADataSpace::TRANSFER_ST2084.0,
+    /// ARIB STD-B67 Hybrid Log Gamma.
+    ///
+    /// Transfer characteristic curve:
+    /// ```ignore
+    /// E = r * L^0.5                 for 0 <= L <= 1
+    ///   = a * ln(L - b) + c         for 1 < L
+    /// a = 0.17883277
+    /// b = 0.28466892
+    /// c = 0.55991073
+    /// r = 0.5
+    /// ```
+    /// - `L`: luminance of image `0 <= L` for HDR colorimetry.
+    ///        `L = 1` corresponds to reference white level of `100 cd/m2`
+    /// - `E`: corresponding electrical signal
+    #[doc(alias = "TRANSFER_HLG")]
+    HLG = ffi::ADataSpace::TRANSFER_HLG.0,
+
+    #[doc(hidden)]
+    #[num_enum(catch_all)]
+    __Unknown(i32),
+}
+
+/// Range aspect.
+///
+/// Defines the range of values corresponding to the unit range of `0-1`. This is defined for
+/// `YCbCr` only, but can be expanded to `RGB` space.
+#[repr(i32)]
+#[derive(Clone, Copy, Debug, Hash, PartialEq, Eq, FromPrimitive, IntoPrimitive)]
+#[doc(alias = "RANGE_MASK")]
+#[non_exhaustive]
+pub enum DataSpaceRange {
+    /// Range is unknown or are determined by the application.  Implementations shall use the
+    /// following suggested ranges:
+    ///
+    /// - All YCbCr formats: limited range.
+    /// - All RGB or RGBA formats (including RAW and Bayer): full range.
+    /// - All Y formats: full range
+    ///
+    /// For all other formats range is undefined, and implementations should use an appropriate
+    /// range for the data represented.
+    #[doc(alias = "RANGE_UNSPECIFIED")]
+    Unspecified = ffi::ADataSpace::RANGE_UNSPECIFIED.0,
+    /// Full range uses all values for `Y`, `Cb` and `Cr` from `0` to `2^b-1`, where `b` is the bit
+    /// depth of the color format.
+    #[doc(alias = "RANGE_FULL")]
+    Full = ffi::ADataSpace::RANGE_FULL.0,
+    /// Limited range uses values `16/256*2^b` to `235/256*2^b` for `Y`, and `1/16*2^b` to
+    /// `15/16*2^b` for `Cb`, `Cr`, `R`, `G` and `B`, where `b` is the bit depth of the color
+    /// format.
+    ///
+    /// E.g. For 8-bit-depth formats: Luma (`Y`) samples should range from `16` to `235`, inclusive
+    /// Chroma `(Cb, Cr)` samples should range from `16` to `240`, inclusive.
+    ///
+    /// For 10-bit-depth formats: Luma (`Y`) samples should range from `64` to `940`, inclusive
+    /// Chroma `(Cb, Cr)` samples should range from `64` to `960`, inclusive.
+    #[doc(alias = "RANGE_LIMITED")]
+    Limited = ffi::ADataSpace::RANGE_LIMITED.0,
+    /// Extended range is used for `scRGB`.
+    ///
+    /// Intended for use with floating point pixel formats. `[0.0 - 1.0]` is the standard `sRGB`
+    /// space. Values outside the range `0.0 - 1.0` can encode color outside the `sRGB` gamut. Used
+    /// to blend / merge multiple dataspaces on a single display.
+    #[doc(alias = "RANGE_EXTENDED")]
+    Extended = ffi::ADataSpace::RANGE_EXTENDED.0,
+
+    #[doc(hidden)]
+    #[num_enum(catch_all)]
+    __Unknown(i32),
+}

clients/android/native/vendor/ndk/src/font.rs

@@ -0,0 +1,552 @@
+//! Bindings for [`AFont`], [`AFontMatcher`], and [`ASystemFontIterator`]
+//!
+//! [`AFont`]: https://developer.android.com/ndk/reference/group/font
+//! [`AFontMatcher`]: https://developer.android.com/ndk/reference/group/font#afontmatcher_create
+//! [`ASystemFontIterator`]: https://developer.android.com/ndk/reference/group/font#asystemfontiterator_open
+
+#![cfg(feature = "api-level-29")]
+
+use std::convert::TryFrom;
+use std::ffi::{CStr, OsStr};
+use std::fmt::{self, Write};
+use std::os::unix::prelude::OsStrExt;
+use std::path::Path;
+use std::ptr::NonNull;
+
+use num_enum::IntoPrimitive;
+
+/// An integer holding a valid font weight value between 1 and 1000.
+///
+/// See the [`Font::weight`] definition for more details.
+#[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord)]
+pub struct FontWeight(u16);
+
+impl FontWeight {
+    pub const fn new(value: u16) -> Result<Self, FontWeightValueError> {
+        if Self::MIN.0 <= value && value <= Self::MAX.0 {
+            Ok(Self(value))
+        } else {
+            Err(FontWeightValueError(()))
+        }
+    }
+
+    pub const fn to_u16(self) -> u16 {
+        self.0
+    }
+
+    /// The minimum value for the font weight value. Unlike [`ffi::AFONT_WEIGHT_MIN`] being `0`,
+    /// [`FontWeight::MIN`] is `1` to make the `MIN..MAX` range be inclusive, keeping consistency
+    /// between [`FontWeight`] and other types like `std::num::NonZeroU*`.
+    pub const MIN: FontWeight = FontWeight(ffi::AFONT_WEIGHT_MIN as u16 + 1);
+
+    /// A font weight value for the thin weight.
+    pub const THIN: FontWeight = FontWeight(ffi::AFONT_WEIGHT_THIN as u16);
+
+    /// A font weight value for the extra-light weight.
+    pub const EXTRA_LIGHT: FontWeight = FontWeight(ffi::AFONT_WEIGHT_EXTRA_LIGHT as u16);
+
+    /// A font weight value for the light weight.
+    pub const LIGHT: FontWeight = FontWeight(ffi::AFONT_WEIGHT_LIGHT as u16);
+
+    /// A font weight value for the normal weight.
+    pub const NORMAL: FontWeight = FontWeight(ffi::AFONT_WEIGHT_NORMAL as u16);
+
+    /// A font weight value for the medium weight.
+    pub const MEDIUM: FontWeight = FontWeight(ffi::AFONT_WEIGHT_MEDIUM as u16);
+
+    /// A font weight value for the semi-bold weight.
+    pub const SEMI_BOLD: FontWeight = FontWeight(ffi::AFONT_WEIGHT_SEMI_BOLD as u16);
+
+    /// A font weight value for the bold weight.
+    pub const BOLD: FontWeight = FontWeight(ffi::AFONT_WEIGHT_BOLD as u16);
+
+    /// A font weight value for the extra-bold weight.
+    pub const EXTRA_BOLD: FontWeight = FontWeight(ffi::AFONT_WEIGHT_EXTRA_BOLD as u16);
+
+    /// A font weight value for the black weight.
+    pub const BLACK: FontWeight = FontWeight(ffi::AFONT_WEIGHT_BLACK as u16);
+
+    /// The maximum value for the font weight value.
+    pub const MAX: FontWeight = FontWeight(ffi::AFONT_WEIGHT_MAX as u16);
+}
+
+impl fmt::Display for FontWeight {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.write_str(match *self {
+            FontWeight::THIN => "Thin",
+            FontWeight::EXTRA_LIGHT => "Extra Light (Ultra Light)",
+            FontWeight::LIGHT => "Light",
+            FontWeight::NORMAL => "Normal (Regular)",
+            FontWeight::MEDIUM => "Medium",
+            FontWeight::SEMI_BOLD => "Semi Bold (Demi Bold)",
+            FontWeight::BOLD => "Bold",
+            FontWeight::EXTRA_BOLD => "Extra Bold (Ultra Bold)",
+            FontWeight::BLACK => "Black (Heavy)",
+            _ => return writeln!(f, "{}", self.0),
+        })
+    }
+}
+
+/// The error type returned when an invalid font weight value is passed.
+#[derive(Debug)]
+pub struct FontWeightValueError(());
+
+impl fmt::Display for FontWeightValueError {
+    fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
+        fmt.write_str("font weight must be positive and less than or equal to 1000")
+    }
+}
+
+impl std::error::Error for FontWeightValueError {}
+
+impl TryFrom<u16> for FontWeight {
+    type Error = FontWeightValueError;
+
+    fn try_from(value: u16) -> Result<Self, Self::Error> {
+        FontWeight::new(value)
+    }
+}
+
+/// A 4-byte integer representing an OpenType axis tag.
+#[derive(Clone, Copy, PartialEq, Eq)]
+pub struct AxisTag(u32);
+
+impl AxisTag {
+    /// Checks whether the given 4-byte array can construct a valid axis tag and returns
+    /// [`Ok(AxisTag)`] if the array is valid.
+    ///
+    /// Each byte in a tag must be in the range 0x20 to 0x7E. A space character cannot be followed
+    /// by a non-space character. A tag must have one to four non-space characters. See the
+    /// [OpenType spec] for more details.
+    ///
+    /// [OpenType spec]: https://learn.microsoft.com/en-us/typography/opentype/spec/otff#data-types
+    pub const fn from_be_bytes_checked(value: [u8; 4]) -> Result<Self, AxisTagValueError> {
+        // Each byte in a tag must be in the range 0x20 to 0x7E.
+        macro_rules! check_byte_range {
+            ($($e:expr)+) => {
+                $(
+                    if !(value[$e] as char).is_ascii_graphic() && value[$e] != b' ' {
+                        return Err(AxisTagValueError::InvalidCharacter);
+                    }
+                )+
+            };
+        }
+        check_byte_range!(0 1 2 3);
+
+        if value[0] == b' ' {
+            return Err(
+                if value[1] == b' ' && value[2] == b' ' && value[3] == b' ' {
+                    // A tag must have one to four non-space characters.
+                    AxisTagValueError::EmptyTag
+                } else {
+                    // A space character cannot be followed by a non-space character.
+                    AxisTagValueError::InvalidSpacePadding
+                },
+            );
+        }
+
+        macro_rules! check_if_valid {
+            ($e:expr ; $($f:expr)+) => {
+                if value[$e] == b' ' {
+                    return if true $(&& value[$f] == b' ')+ {
+                        Ok(Self(u32::from_be_bytes(value)))
+                    } else {
+                        // A space character cannot be followed by a non-space character.
+                        Err(AxisTagValueError::InvalidSpacePadding)
+                    };
+                }
+            };
+        }
+
+        check_if_valid!(1; 2 3);
+        check_if_valid!(2; 3);
+
+        // Whether or not value[3] is b' ', value is a valid axis tag.
+        Ok(Self(u32::from_be_bytes(value)))
+    }
+
+    /// Checks whether the given 4-byte array can construct a valid axis tag and returns
+    /// [`Ok(AxisTag)`] if the array is valid.
+    ///
+    /// See [`AxisTag::from_be()`] for more details.
+    pub const fn from_be_checked(value: u32) -> Result<Self, AxisTagValueError> {
+        Self::from_be_bytes_checked(value.to_be_bytes())
+    }
+
+    /// Construct an axis tag from the given 4-byte array. If the resulting axis tag is invalid,
+    /// this function panics.
+    ///
+    /// See [`AxisTag::from_be()`] for more details.
+    pub const fn from_be_bytes(value: [u8; 4]) -> Self {
+        Self::unwrap_result(Self::from_be_bytes_checked(value))
+    }
+
+    /// Construct an axis tag from the given 4-byte integer. If the resulting axis tag is invalid,
+    /// this function panics.
+    ///
+    /// See [`AxisTag::from_be()`] for more details.
+    pub const fn from_be(value: u32) -> Self {
+        Self::unwrap_result(Self::from_be_checked(value))
+    }
+
+    /// const-version of [`Result::unwrap`]. Should be removed when [`Option::unwrap`] or
+    /// [`Result::unwrap`] become `const`-stable.
+    const fn unwrap_result(result: Result<Self, AxisTagValueError>) -> Self {
+        match result {
+            Ok(t) => t,
+            Err(e) => panic!("{}", e.as_str()),
+        }
+    }
+
+    pub const fn to_u32(self) -> u32 {
+        self.0
+    }
+
+    pub const fn to_be_bytes(self) -> [u8; 4] {
+        self.0.to_be_bytes()
+    }
+}
+
+impl fmt::Display for AxisTag {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        let bytes = self.to_be_bytes();
+        f.write_char(bytes[0] as char)?;
+        f.write_char(bytes[1] as char)?;
+        f.write_char(bytes[2] as char)?;
+        f.write_char(bytes[3] as char)
+    }
+}
+
+impl fmt::Debug for AxisTag {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(f, "AxisTag({} {:#x})", self, self.0)
+    }
+}
+
+/// The error type returned when an invalid axis tag value is passed.
+#[derive(Clone, Copy, Debug)]
+pub enum AxisTagValueError {
+    /// There is a byte not in the range 0x20 to 0x7E.
+    InvalidCharacter,
+    /// There is a space character followed by a non-space character.
+    InvalidSpacePadding,
+    /// The tag only consists of space characters.
+    EmptyTag,
+}
+
+impl AxisTagValueError {
+    pub const fn as_str(&self) -> &'static str {
+        match self {
+            Self::InvalidCharacter => "each byte in an axis tag must be in the range 0x20 to 0x7E",
+            Self::InvalidSpacePadding => {
+                "a space character cannot be followed by a non-space character"
+            }
+            Self::EmptyTag => "a tag must have one to four non-space characters",
+        }
+    }
+}
+
+impl fmt::Display for AxisTagValueError {
+    fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
+        fmt.write_str(self.as_str())
+    }
+}
+
+impl std::error::Error for AxisTagValueError {}
+
+/// A native [`AFont *`]
+///
+/// [`AFont *`]: https://developer.android.com/ndk/reference/group/font
+#[derive(Debug)]
+pub struct Font {
+    ptr: NonNull<ffi::AFont>,
+}
+
+impl Font {
+    /// Assumes ownership of `ptr`.
+    ///
+    /// # Safety
+    /// `ptr` must be a valid owning pointer to an Android [`ffi::AFont`].
+    pub unsafe fn from_ptr(ptr: NonNull<ffi::AFont>) -> Self {
+        Self { ptr }
+    }
+
+    /// Returns s the pointer to the native [`ffi::AFont`].
+    pub fn ptr(&self) -> NonNull<ffi::AFont> {
+        self.ptr
+    }
+
+    /// Returns a count of font variation settings associated with the current font.
+    ///
+    /// The font variation settings are provided as multiple tag-value pairs.
+    ///
+    /// For example, bold italic font may have following font variation settings: `'wght' 700`,
+    /// `'slnt' -12`. In this case, [`Font::axis_count()`] returns `2` and [`Font::axis_tag_at()`] and
+    /// [`Font::axis_value_at()`] return those variation names and the corresponding values.
+    ///
+    /// ```no_run
+    /// use ndk::font::Font;
+    ///
+    /// let font: Font = todo!();
+    /// for idx in 0..font.axis_count() {
+    ///     log::debug!("{}: {}", font.axis_tag_at(idx), font.axis_value_at(idx));
+    /// }
+    /// // Output:
+    /// // wght: 700
+    /// // slnt: -12
+    /// ```
+    pub fn axis_count(&self) -> usize {
+        unsafe { ffi::AFont_getAxisCount(self.ptr.as_ptr()) }
+    }
+
+    /// Returns an OpenType axis tag associated with the current font.
+    ///
+    /// See [`Font::axis_count()`] for more details.
+    pub fn axis_tag_at(&self, idx: usize) -> AxisTag {
+        // Android returns Axis Tag in big-endian.
+        // See https://cs.android.com/android/platform/superproject/+/refs/heads/master:frameworks/base/native/android/system_fonts.cpp;l=197 for details
+        AxisTag(unsafe { ffi::AFont_getAxisTag(self.ptr.as_ptr(), idx as u32) })
+    }
+
+    /// Returns an OpenType axis value associated with the current font.
+    ///
+    /// See [`Font::axis_count()`] for more details.
+    pub fn axis_value_at(&self, idx: usize) -> f32 {
+        unsafe { ffi::AFont_getAxisValue(self.ptr.as_ptr(), idx as u32) }
+    }
+
+    /// Returns a font collection index value associated with the current font.
+    ///
+    /// In case the target font file is a font collection (e.g. `.ttc` or `.otc`), this returns a
+    /// non-negative value as a font offset in the collection. This always returns 0 if the target
+    /// font file is a regular font.
+    pub fn collection_index(&self) -> usize {
+        unsafe { ffi::AFont_getCollectionIndex(self.ptr.as_ptr()) }
+    }
+
+    /// Returns an absolute path to the current font file.
+    ///
+    /// Here is a list of font formats returned by this method:
+    ///
+    /// * OpenType
+    /// * OpenType Font Collection
+    /// * TrueType
+    /// * TrueType Collection
+    ///
+    /// The file extension could be one of `*.otf`, `*.ttf`, `*.otc` or `*.ttc`.
+    /// The font file specified by the returned path is guaranteed to be openable with `O_RDONLY`.
+    pub fn path(&self) -> &Path {
+        let path = unsafe { CStr::from_ptr(ffi::AFont_getFontFilePath(self.ptr.as_ptr())) };
+        OsStr::from_bytes(path.to_bytes()).as_ref()
+    }
+
+    /// Returns an IETF BCP47 compliant language tag associated with the current font.
+    ///
+    /// For information about IETF BCP47, read [`Locale.forLanguageTag(java.lang.String)`].
+    ///
+    /// [`Locale.forLanguageTag(java.lang.String)`]: https://developer.android.com/reference/java/util/Locale.html#forLanguageTag(java.lang.String)
+    pub fn locale(&self) -> Option<&CStr> {
+        let ptr = unsafe { ffi::AFont_getLocale(self.ptr.as_ptr()) };
+        if ptr.is_null() {
+            None
+        } else {
+            Some(unsafe { CStr::from_ptr(ptr) })
+        }
+    }
+
+    /// Returns a weight value associated with the current font.
+    ///
+    /// The weight values are positive and less than or equal to 1000. Here are pairs of the common
+    /// names and their values.
+    ///
+    /// | Value | Name                      | NDK Definition              |
+    /// | ----- | ------------------------- | --------------------------- |
+    /// | 100   | Thin                      | [`FontWeight::THIN`]        |
+    /// | 200   | Extra Light (Ultra Light) | [`FontWeight::EXTRA_LIGHT`] |
+    /// | 300   | Light                     | [`FontWeight::LIGHT`]       |
+    /// | 400   | Normal (Regular)          | [`FontWeight::NORMAL`]      |
+    /// | 500   | Medium                    | [`FontWeight::MEDIUM`]      |
+    /// | 600   | Semi Bold (Demi Bold)     | [`FontWeight::SEMI_BOLD`]   |
+    /// | 700   | Bold                      | [`FontWeight::BOLD`]        |
+    /// | 800   | Extra Bold (Ultra Bold)   | [`FontWeight::EXTRA_BOLD`]  |
+    /// | 900   | Black (Heavy)             | [`FontWeight::BLACK`]       |
+    pub fn weight(&self) -> FontWeight {
+        FontWeight(unsafe { ffi::AFont_getWeight(self.ptr.as_ptr()) })
+    }
+
+    /// Returns [`true`] if the current font is italic, otherwise returns [`false`].
+    pub fn is_italic(&self) -> bool {
+        unsafe { ffi::AFont_isItalic(self.ptr.as_ptr()) }
+    }
+}
+
+impl Drop for Font {
+    fn drop(&mut self) {
+        unsafe { ffi::AFont_close(self.ptr.as_ptr()) }
+    }
+}
+
+/// Corresponds to [`AFAMILY_VARIANT_*`].
+///
+/// [`AFAMILY_VARIANT_*`]: https://developer.android.com/ndk/reference/group/font#group___font_1gga96a58e29e8dbf2b5bdeb775cba46556ea662aafc7016e35d6758da93416fc0833
+#[repr(u32)]
+#[derive(Debug, PartialEq, Eq, PartialOrd, Ord, IntoPrimitive)]
+#[non_exhaustive]
+pub enum FamilyVariant {
+    /// A family variant value for the compact font family variant.
+    /// The compact font family has Latin-based vertical metrics.
+    Compact = ffi::AFAMILY_VARIANT_COMPACT,
+    /// A family variant value for the system default variant.
+    Default = ffi::AFAMILY_VARIANT_DEFAULT,
+    /// A family variant value for the elegant font family variant.
+    /// The elegant font family may have larger vertical metrics than Latin font.
+    Elegant = ffi::AFAMILY_VARIANT_ELEGANT,
+
+    #[doc(hidden)]
+    #[num_enum(catch_all)]
+    __Unknown(u32),
+}
+
+/// A native [`AFontMatcher *`]
+///
+/// [`AFontMatcher *`]: https://developer.android.com/ndk/reference/group/font#afontmatcher_create
+#[derive(Debug)]
+pub struct FontMatcher {
+    ptr: NonNull<ffi::AFontMatcher>,
+}
+
+impl FontMatcher {
+    /// Assumes ownership of `ptr`.
+    ///
+    /// # Safety
+    /// `ptr` must be a valid owning pointer to an Android [`ffi::AFontMatcher`].
+    pub unsafe fn from_ptr(ptr: NonNull<ffi::AFontMatcher>) -> Self {
+        Self { ptr }
+    }
+
+    /// Returns s the pointer to the native [`ffi::AFontMatcher`].
+    pub fn ptr(&self) -> NonNull<ffi::AFontMatcher> {
+        self.ptr
+    }
+
+    /// Creates a new [`FontMatcher`] object. [`FontMatcher`] selects the best font from the
+    /// parameters set by the user.
+    pub fn new() -> Self {
+        let ptr = NonNull::new(unsafe { ffi::AFontMatcher_create() })
+            .expect("AFontMatcher_create returned NULL");
+        unsafe { FontMatcher::from_ptr(ptr) }
+    }
+
+    /// Performs the matching from the generic font family for the text and select one font.
+    ///
+    /// For more information about generic font families, please read the
+    /// [W3C spec](https://www.w3.org/TR/css-fonts-4/#generic-font-families).
+    ///
+    /// Even if no font can render the given text, this function will return a non-null result for
+    /// drawing Tofu character.
+    ///
+    /// # Parameters
+    ///
+    /// - `family_name`: A font family name.
+    /// - `text`: A UTF-16 encoded text buffer to be rendered. If an empty string is given, this
+    ///   function will panic.
+    /// - `run_length_out`: Set this to [`Some`] if you want to get the length of the text run with
+    ///   the font returned.
+    pub fn match_font(
+        &mut self,
+        family_name: &CStr,
+        text: &[u16],
+        run_length_out: Option<&mut u32>,
+    ) -> Font {
+        if text.is_empty() {
+            panic!("text is empty");
+        }
+        unsafe {
+            Font::from_ptr(
+                NonNull::new(ffi::AFontMatcher_match(
+                    self.ptr.as_ptr(),
+                    family_name.as_ptr(),
+                    text.as_ptr(),
+                    text.len() as _,
+                    run_length_out.map_or(std::ptr::null_mut(), |u| u),
+                ))
+                .expect("AFontMatcher_match returned NULL"),
+            )
+        }
+    }
+
+    /// Sets the family variant of the font to be matched.
+    ///
+    /// If this function is not called, the match is performed with [`FamilyVariant::Default`].
+    pub fn set_family_variant(&mut self, family_variant: FamilyVariant) {
+        unsafe { ffi::AFontMatcher_setFamilyVariant(self.ptr.as_ptr(), family_variant.into()) }
+    }
+
+    /// Sets the locale of the font to be matched.
+    ///
+    /// If this function is not called, the match is performed with an empty locale list.
+    ///
+    /// # Parameters
+    ///
+    /// - `language_tags`: comma separated IETF BCP47 compliant language tags.
+    pub fn set_locales(&mut self, language_tags: &CStr) {
+        unsafe { ffi::AFontMatcher_setLocales(self.ptr.as_ptr(), language_tags.as_ptr()) }
+    }
+
+    /// Sets the style of the font to be matched.
+    ///
+    /// If this function is not called, the match is performed with [`FontWeight::NORMAL`] with non-italic style.
+    pub fn set_style(&mut self, weight: FontWeight, italic: bool) {
+        unsafe { ffi::AFontMatcher_setStyle(self.ptr.as_ptr(), weight.to_u16(), italic) }
+    }
+}
+
+impl Drop for FontMatcher {
+    fn drop(&mut self) {
+        unsafe { ffi::AFontMatcher_destroy(self.ptr.as_ptr()) }
+    }
+}
+
+/// A native [`ASystemFontIterator *`]
+///
+/// [`ASystemFontIterator *`]: https://developer.android.com/ndk/reference/group/font#asystemfontiterator_open
+#[derive(Debug)]
+pub struct SystemFontIterator {
+    ptr: NonNull<ffi::ASystemFontIterator>,
+}
+
+impl SystemFontIterator {
+    /// Assumes ownership of `ptr`.
+    ///
+    /// # Safety
+    /// `ptr` must be a valid owning pointer to an Android [`ffi::ASystemFontIterator`].
+    pub unsafe fn from_ptr(ptr: NonNull<ffi::ASystemFontIterator>) -> Self {
+        Self { ptr }
+    }
+
+    /// Returns the pointer to the native [`ffi::ASystemFontIterator`].
+    pub fn ptr(&self) -> NonNull<ffi::ASystemFontIterator> {
+        self.ptr
+    }
+
+    /// Creates a system font iterator.
+    pub fn new() -> Option<Self> {
+        NonNull::new(unsafe { ffi::ASystemFontIterator_open() })
+            .map(|p| unsafe { SystemFontIterator::from_ptr(p) })
+    }
+}
+
+impl Iterator for SystemFontIterator {
+    type Item = Font;
+
+    fn next(&mut self) -> Option<Self::Item> {
+        NonNull::new(unsafe { ffi::ASystemFontIterator_next(self.ptr.as_ptr()) })
+            .map(|p| unsafe { Font::from_ptr(p) })
+    }
+}
+
+impl Drop for SystemFontIterator {
+    fn drop(&mut self) {
+        unsafe { ffi::ASystemFontIterator_close(self.ptr.as_ptr()) }
+    }
+}

clients/android/native/vendor/ndk/src/hardware_buffer.rs

@@ -0,0 +1,640 @@
+//! Bindings for [`AHardwareBuffer`]
+//!
+//! [`AHardwareBuffer`]: https://developer.android.com/ndk/reference/group/a-hardware-buffer#ahardwarebuffer
+
+#![cfg(feature = "api-level-26")]
+
+use std::{
+    io::Result,
+    mem::MaybeUninit,
+    ops::Deref,
+    os::{
+        fd::{AsRawFd, BorrowedFd, FromRawFd, IntoRawFd, OwnedFd},
+        raw::c_void,
+    },
+    ptr::NonNull,
+};
+
+use jni_sys::{jobject, JNIEnv};
+
+use super::{hardware_buffer_format::HardwareBufferFormat, utils::status_to_io_result};
+
+bitflags::bitflags! {
+    /// Buffer usage flags, specifying how the buffer will be accessed.
+    #[derive(Clone, Copy, Debug, Hash, PartialEq, Eq)]
+    #[doc(alias = "AHardwareBuffer_UsageFlags")]
+    pub struct HardwareBufferUsage : u64 {
+        /// The buffer will never be locked for direct CPU reads using the
+        /// [`HardwareBuffer::lock()`] function. Note that reading the buffer using OpenGL or Vulkan
+        /// functions or memory mappings is still allowed.
+        #[doc(alias = "AHARDWAREBUFFER_USAGE_CPU_READ_NEVER")]
+        const CPU_READ_NEVER = ffi::AHardwareBuffer_UsageFlags::AHARDWAREBUFFER_USAGE_CPU_READ_NEVER.0;
+        /// The buffer will sometimes be locked for direct CPU reads using the
+        /// [`HardwareBuffer::lock()`] function. Note that reading the buffer using OpenGL or Vulkan
+        /// functions or memory mappings does not require the presence of this flag.
+        #[doc(alias = "AHARDWAREBUFFER_USAGE_CPU_READ_RARELY")]
+        const CPU_READ_RARELY = ffi::AHardwareBuffer_UsageFlags::AHARDWAREBUFFER_USAGE_CPU_READ_RARELY.0;
+        /// The buffer will often be locked for direct CPU reads using the
+        /// [`HardwareBuffer::lock()`] function. Note that reading the buffer using OpenGL or Vulkan
+        /// functions or memory mappings does not require the presence of this flag.
+        #[doc(alias = "AHARDWAREBUFFER_USAGE_CPU_READ_OFTEN")]
+        const CPU_READ_OFTEN = ffi::AHardwareBuffer_UsageFlags::AHARDWAREBUFFER_USAGE_CPU_READ_OFTEN.0;
+        /// CPU read value mask.
+        #[doc(alias = "AHARDWAREBUFFER_USAGE_CPU_READ_MASK")]
+        const CPU_READ_MASK = ffi::AHardwareBuffer_UsageFlags::AHARDWAREBUFFER_USAGE_CPU_READ_MASK.0;
+
+        /// The buffer will never be locked for direct CPU writes using the
+        /// [`HardwareBuffer::lock()`] function. Note that writing the buffer using OpenGL or Vulkan
+        /// functions or memory mappings is still allowed.
+        #[doc(alias = "AHARDWAREBUFFER_USAGE_CPU_WRITE_NEVER")]
+        const CPU_WRITE_NEVER = ffi::AHardwareBuffer_UsageFlags::AHARDWAREBUFFER_USAGE_CPU_WRITE_NEVER.0;
+        /// The buffer will sometimes be locked for direct CPU writes using the
+        /// [`HardwareBuffer::lock()`] function. Note that writing the buffer using OpenGL or Vulkan
+        /// functions or memory mappings does not require the presence of this flag.
+        #[doc(alias = "AHARDWAREBUFFER_USAGE_CPU_WRITE_RARELY")]
+        const CPU_WRITE_RARELY = ffi::AHardwareBuffer_UsageFlags::AHARDWAREBUFFER_USAGE_CPU_WRITE_RARELY.0;
+        /// The buffer will often be locked for direct CPU writes using the
+        /// [`HardwareBuffer::lock()`] function. Note that writing the buffer using OpenGL or Vulkan
+        /// functions or memory mappings does not require the presence of this flag.
+        #[doc(alias = "AHARDWAREBUFFER_USAGE_CPU_WRITE_OFTEN")]
+        const CPU_WRITE_OFTEN = ffi::AHardwareBuffer_UsageFlags::AHARDWAREBUFFER_USAGE_CPU_WRITE_OFTEN.0;
+        /// CPU write value mask.
+        #[doc(alias = "AHARDWAREBUFFER_USAGE_CPU_WRITE_MASK")]
+        const CPU_WRITE_MASK = ffi::AHardwareBuffer_UsageFlags::AHARDWAREBUFFER_USAGE_CPU_WRITE_MASK.0;
+
+        /// The buffer will be read from by the GPU as a texture.
+        #[doc(alias = "AHARDWAREBUFFER_USAGE_GPU_SAMPLED_IMAGE")]
+        const GPU_SAMPLED_IMAGE = ffi::AHardwareBuffer_UsageFlags::AHARDWAREBUFFER_USAGE_GPU_SAMPLED_IMAGE.0;
+        /// The buffer will be written to by the GPU as a framebuffer attachment.
+        #[doc(alias = "AHARDWAREBUFFER_USAGE_GPU_FRAMEBUFFER")]
+        const GPU_FRAMEBUFFER = ffi::AHardwareBuffer_UsageFlags::AHARDWAREBUFFER_USAGE_GPU_FRAMEBUFFER.0;
+        /// The buffer will be written to by the GPU as a framebuffer attachment.
+        ///
+        /// Note that the name of this flag is somewhat misleading: it does not imply that the
+        /// buffer contains a color format. A buffer with depth or stencil format that will be
+        /// used as a framebuffer attachment should also have this flag. Use the equivalent flag
+        /// [`HardwareBufferusage::GPU_FRAMEBUFFER`] to avoid this confusion.
+        #[doc(alias = "AHARDWAREBUFFER_USAGE_GPU_COLOR_OUTPUT")]
+        const GPU_COLOR_OUTPUT = ffi::AHardwareBuffer_UsageFlags::AHARDWAREBUFFER_USAGE_GPU_COLOR_OUTPUT.0;
+        /// The buffer will be used as a composer HAL overlay layer.
+        ///
+        /// This flag is currently only needed when using [`SurfaceTransaction::set_buffer()`] to
+        /// set a buffer. In all other cases, the framework adds this flag internally to buffers
+        /// that could be presented in a composer overlay. [`SurfaceTransaction::set_buffer()`]
+        /// is special because it uses buffers allocated directly through
+        /// [`HardwareBuffer::allocate()`] instead of buffers allocated by the framework.
+        #[doc(alias = "AHARDWAREBUFFER_USAGE_COMPOSER_OVERLAY")]
+        const COMPOSER_OVERLAY = ffi::AHardwareBuffer_UsageFlags::AHARDWAREBUFFER_USAGE_COMPOSER_OVERLAY.0;
+        /// The buffer is protected from direct CPU access or being read by non-secure hardware,
+        /// such as video encoders.
+        ///
+        /// This flag is incompatible with CPU read and write flags. It is mainly used when handling
+        /// DRM video. Refer to the EGL extension [`EGL_EXT_protected_content`] and GL extension
+        /// [`GL_EXT_protected_textures`] for more information on how these buffers are expected
+        /// to behave.
+        ///
+        /// [`EGL_EXT_protected_content`]: https://registry.khronos.org/EGL/extensions/EXT/EGL_EXT_protected_content.txt
+        /// [`GL_EXT_protected_textures`]: https://registry.khronos.org/OpenGL/extensions/EXT/EXT_protected_textures.txt
+        #[doc(alias = "AHARDWAREBUFFER_USAGE_PROTECTED_CONTENT")]
+        const PROTECTED_CONTENT = ffi::AHardwareBuffer_UsageFlags::AHARDWAREBUFFER_USAGE_PROTECTED_CONTENT.0;
+        /// The buffer will be read by a hardware video encoder.
+        #[doc(alias = "AHARDWAREBUFFER_USAGE_VIDEO_ENCODE")]
+        const VIDEO_ENCODE = ffi::AHardwareBuffer_UsageFlags::AHARDWAREBUFFER_USAGE_VIDEO_ENCODE.0;
+        /// The buffer will be used for direct writes from sensors. When this flag is present, the
+        /// format must be [`HardwareBufferFormat::Blob`].
+        #[doc(alias = "AHARDWAREBUFFER_USAGE_SENSOR_DIRECT_DATA")]
+        const SENSOR_DIRECT_DATA = ffi::AHardwareBuffer_UsageFlags::AHARDWAREBUFFER_USAGE_SENSOR_DIRECT_DATA.0;
+        /// The buffer will be used as a shader storage or uniform buffer object. When this flag is
+        /// present, the format must be [`HardwareBufferFormat::Blob`].
+        #[doc(alias = "AHARDWAREBUFFER_USAGE_GPU_DATA_BUFFER")]
+        const GPU_DATA_BUFFER = ffi::AHardwareBuffer_UsageFlags::AHARDWAREBUFFER_USAGE_GPU_DATA_BUFFER.0;
+        /// The buffer will be used as a cube map texture. When this flag is present, the buffer
+        /// must have a layer count that is a multiple of 6. Note that buffers with this flag must
+        /// be bound to OpenGL textures using the extension [`GL_EXT_EGL_image_storage`] instead
+        /// of [`GL_KHR_EGL_image`].
+        ///
+        /// [`GL_EXT_EGL_image_storage`]: https://registry.khronos.org/OpenGL/extensions/EXT/EXT_EGL_image_storage.txt
+        // TODO: This extension only exists for VG. Reported at https://issuetracker.google.com/issues/300602767#comment16
+        /// [`GL_KHR_EGL_image`]: https://registry.khronos.org/OpenVG/extensions/KHR/VG_KHR_EGL_image.txt
+        #[doc(alias = "AHARDWAREBUFFER_USAGE_GPU_CUBE_MAP")]
+        const GPU_CUBE_MAP = ffi::AHardwareBuffer_UsageFlags::AHARDWAREBUFFER_USAGE_GPU_CUBE_MAP.0;
+        /// The buffer contains a complete mipmap hierarchy. Note that buffers with this flag must
+        /// be bound to OpenGL textures using the extension [`GL_EXT_EGL_image_storage`] instead
+        /// of [`GL_KHR_EGL_image`].
+        ///
+        /// [`GL_EXT_EGL_image_storage`]: https://registry.khronos.org/OpenGL/extensions/EXT/EXT_EGL_image_storage.txt
+        // TODO: This extension only exists for VG. Reported at https://issuetracker.google.com/issues/300602767#comment16
+        /// [`GL_KHR_EGL_image`]: https://registry.khronos.org/OpenVG/extensions/KHR/VG_KHR_EGL_image.txt
+        #[doc(alias = "AHARDWAREBUFFER_USAGE_GPU_MIPMAP_COMPLETE")]
+        const GPU_MIPMAP_COMPLETE = ffi::AHardwareBuffer_UsageFlags::AHARDWAREBUFFER_USAGE_GPU_MIPMAP_COMPLETE.0;
+
+        // TODO: Only available in a newer NDK
+        // /// Usage: The buffer is used for front-buffer rendering. When front-buffering rendering
+        // /// is specified, different usages may adjust their behavior as a result. For example, when
+        // /// used as [`HardwareBufferFormat::GPU_COLOR_OUTPUT`] the buffer will behave similar to a
+        // /// single-buffered window. When used with [`HardwareBufferFormat::COMPOSER_OVERLAY`], the
+        // /// system will try to prioritize the buffer receiving an overlay plane & avoid caching it
+        // /// in intermediate composition buffers.
+        // #[doc(alias = "AHARDWAREBUFFER_USAGE_FRONT_BUFFER")]
+        // const USAGE_FRONT_BUFFER = ffi::AHardwareBuffer_UsageFlags::AHARDWAREBUFFER_USAGE_FRONT_BUFFER.0;
+
+        #[doc(alias = "AHARDWAREBUFFER_USAGE_VENDOR_0")]
+        const VENDOR_0 = ffi::AHardwareBuffer_UsageFlags::AHARDWAREBUFFER_USAGE_VENDOR_0.0;
+        #[doc(alias = "AHARDWAREBUFFER_USAGE_VENDOR_1")]
+        const VENDOR_1 = ffi::AHardwareBuffer_UsageFlags::AHARDWAREBUFFER_USAGE_VENDOR_1.0;
+        #[doc(alias = "AHARDWAREBUFFER_USAGE_VENDOR_2")]
+        const VENDOR_2 = ffi::AHardwareBuffer_UsageFlags::AHARDWAREBUFFER_USAGE_VENDOR_2.0;
+        #[doc(alias = "AHARDWAREBUFFER_USAGE_VENDOR_3")]
+        const VENDOR_3 = ffi::AHardwareBuffer_UsageFlags::AHARDWAREBUFFER_USAGE_VENDOR_3.0;
+        #[doc(alias = "AHARDWAREBUFFER_USAGE_VENDOR_4")]
+        const VENDOR_4 = ffi::AHardwareBuffer_UsageFlags::AHARDWAREBUFFER_USAGE_VENDOR_4.0;
+        #[doc(alias = "AHARDWAREBUFFER_USAGE_VENDOR_5")]
+        const VENDOR_5 = ffi::AHardwareBuffer_UsageFlags::AHARDWAREBUFFER_USAGE_VENDOR_5.0;
+        #[doc(alias = "AHARDWAREBUFFER_USAGE_VENDOR_6")]
+        const VENDOR_6 = ffi::AHardwareBuffer_UsageFlags::AHARDWAREBUFFER_USAGE_VENDOR_6.0;
+        #[doc(alias = "AHARDWAREBUFFER_USAGE_VENDOR_7")]
+        const VENDOR_7 = ffi::AHardwareBuffer_UsageFlags::AHARDWAREBUFFER_USAGE_VENDOR_7.0;
+        #[doc(alias = "AHARDWAREBUFFER_USAGE_VENDOR_8")]
+        const VENDOR_8 = ffi::AHardwareBuffer_UsageFlags::AHARDWAREBUFFER_USAGE_VENDOR_8.0;
+        #[doc(alias = "AHARDWAREBUFFER_USAGE_VENDOR_9")]
+        const VENDOR_9 = ffi::AHardwareBuffer_UsageFlags::AHARDWAREBUFFER_USAGE_VENDOR_9.0;
+        #[doc(alias = "AHARDWAREBUFFER_USAGE_VENDOR_10")]
+        const VENDOR_10 = ffi::AHardwareBuffer_UsageFlags::AHARDWAREBUFFER_USAGE_VENDOR_10.0;
+        #[doc(alias = "AHARDWAREBUFFER_USAGE_VENDOR_11")]
+        const VENDOR_11 = ffi::AHardwareBuffer_UsageFlags::AHARDWAREBUFFER_USAGE_VENDOR_11.0;
+        #[doc(alias = "AHARDWAREBUFFER_USAGE_VENDOR_12")]
+        const VENDOR_12 = ffi::AHardwareBuffer_UsageFlags::AHARDWAREBUFFER_USAGE_VENDOR_12.0;
+        #[doc(alias = "AHARDWAREBUFFER_USAGE_VENDOR_13")]
+        const VENDOR_13 = ffi::AHardwareBuffer_UsageFlags::AHARDWAREBUFFER_USAGE_VENDOR_13.0;
+        #[doc(alias = "AHARDWAREBUFFER_USAGE_VENDOR_14")]
+        const VENDOR_14 = ffi::AHardwareBuffer_UsageFlags::AHARDWAREBUFFER_USAGE_VENDOR_14.0;
+        #[doc(alias = "AHARDWAREBUFFER_USAGE_VENDOR_15")]
+        const VENDOR_15 = ffi::AHardwareBuffer_UsageFlags::AHARDWAREBUFFER_USAGE_VENDOR_15.0;
+        #[doc(alias = "AHARDWAREBUFFER_USAGE_VENDOR_16")]
+        const VENDOR_16 = ffi::AHardwareBuffer_UsageFlags::AHARDWAREBUFFER_USAGE_VENDOR_16.0;
+        #[doc(alias = "AHARDWAREBUFFER_USAGE_VENDOR_17")]
+        const VENDOR_17 = ffi::AHardwareBuffer_UsageFlags::AHARDWAREBUFFER_USAGE_VENDOR_17.0;
+        #[doc(alias = "AHARDWAREBUFFER_USAGE_VENDOR_18")]
+        const VENDOR_18 = ffi::AHardwareBuffer_UsageFlags::AHARDWAREBUFFER_USAGE_VENDOR_18.0;
+        #[doc(alias = "AHARDWAREBUFFER_USAGE_VENDOR_19")]
+        const VENDOR_19 = ffi::AHardwareBuffer_UsageFlags::AHARDWAREBUFFER_USAGE_VENDOR_19.0;
+    }
+}
+
+impl HardwareBufferUsage {
+    /// Helper to read [`HardwareBufferUsage::CPU_READ_MASK`] values.
+    #[doc(alias = "AHARDWAREBUFFER_USAGE_CPU_READ_MASK")]
+    pub fn cpu_read(self) -> HardwareBufferUsage {
+        self.intersection(Self::CPU_READ_MASK)
+    }
+
+    /// Helper to read [`HardwareBufferUsage::CPU_WRITE_MASK`] values.
+    #[doc(alias = "AHARDWAREBUFFER_USAGE_CPU_WRITE_MASK")]
+    pub fn cpu_write(self) -> HardwareBufferUsage {
+        self.intersection(Self::CPU_WRITE_MASK)
+    }
+}
+
+pub type Rect = ffi::ARect;
+
+fn construct<T>(with_ptr: impl FnOnce(*mut T) -> i32) -> Result<T> {
+    let mut result = MaybeUninit::uninit();
+    let status = with_ptr(result.as_mut_ptr());
+    status_to_io_result(status).map(|()| unsafe { result.assume_init() })
+}
+
+/// A native [`AHardwareBuffer *`]
+///
+/// [`HardwareBuffer`] objects represent chunks of memory that can be accessed by various hardware
+/// components in the system.
+///
+/// It can be easily converted to the Java counterpart [`android.hardware.HardwareBuffer`] and
+/// passed between processes using Binder. All operations involving [`HardwareBuffer`] and
+/// [`android.hardware.HardwareBuffer`] are zero-copy, i.e., passing [`HardwareBuffer`] to another
+/// process creates a shared view of the same region of memory.
+///
+/// [`HardwareBuffer`] can be bound to EGL/OpenGL and Vulkan primitives. For EGL, use the extension
+/// function [`eglGetNativeClientBufferANDROID`] to obtain an `EGLClientBuffer` and pass it
+/// directly to [`eglCreateImageKHR`]. Refer to the EGL extensions
+/// [`EGL_ANDROID_get_native_client_buffer`] and [`EGL_ANDROID_image_native_buffer`] for more
+/// information. In Vulkan, the contents of the [`HardwareBuffer`] can be accessed as [external
+/// memory]. See the [`VK_ANDROID_external_memory_android_hardware_buffer`] extension for details.
+///
+/// [`AHardwareBuffer *`]: https://developer.android.com/ndk/reference/group/a-hardware-buffer#ahardwarebuffer
+/// [`android.hardware.HardwareBuffer`]: https://developer.android.com/reference/android/hardware/HardwareBuffer
+/// [`eglGetNativeClientBufferANDROID`]: https://www.khronos.org/registry/EGL/extensions/ANDROID/EGL_ANDROID_get_native_client_buffer.txt
+/// [`eglCreateImageKHR`]: https://www.khronos.org/registry/EGL/extensions/KHR/EGL_KHR_image_base.txt
+/// [`EGL_ANDROID_get_native_client_buffer`]: https://www.khronos.org/registry/EGL/extensions/ANDROID/EGL_ANDROID_get_native_client_buffer.txt
+/// [`EGL_ANDROID_image_native_buffer`]: https://www.khronos.org/registry/EGL/extensions/ANDROID/EGL_ANDROID_image_native_buffer.txt
+/// [external memory]: https://www.khronos.org/registry/vulkan/specs/1.3-extensions/man/html/VK_KHR_external_memory.html
+/// [`VK_ANDROID_external_memory_android_hardware_buffer`]: https://www.khronos.org/registry/vulkan/specs/1.3-extensions/man/html/VK_ANDROID_external_memory_android_hardware_buffer.html
+#[derive(Debug)]
+pub struct HardwareBuffer {
+    inner: NonNull<ffi::AHardwareBuffer>,
+}
+
+impl HardwareBuffer {
+    /// Create an _unowned_ [`HardwareBuffer`] from a native pointer
+    ///
+    /// To wrap a strong reference (that is `release`d on [`Drop`]), call
+    /// [`HardwareBufferRef::from_ptr()`] instead.
+    ///
+    /// # Safety
+    /// By calling this function, you assert that it is a valid pointer to an NDK
+    /// [`ffi::AHardwareBuffer`] that is kept alive externally, or retrieve a strong reference
+    /// using [`HardwareBuffer::acquire()`].
+    pub unsafe fn from_ptr(ptr: NonNull<ffi::AHardwareBuffer>) -> Self {
+        Self { inner: ptr }
+    }
+
+    /// Returns the underlying [`ffi::AHardwareBuffer`] pointer
+    ///
+    /// See the top-level [`HardwareBuffer`] struct documentation for (graphics) APIs that accept
+    /// this pointer.
+    pub fn as_ptr(&self) -> *mut ffi::AHardwareBuffer {
+        self.inner.as_ptr()
+    }
+
+    /// Allocates a buffer that matches the passed [`HardwareBufferDesc`].
+    ///
+    /// If allocation succeeds, the buffer can be used according to the usage flags specified in
+    /// its description. If a buffer is used in ways not compatible with its usage flags, the
+    /// results are undefined and may include program termination.
+    pub fn allocate(desc: HardwareBufferDesc) -> Result<HardwareBufferRef> {
+        unsafe {
+            let ptr = construct(|res| ffi::AHardwareBuffer_allocate(&desc.into_native(), res))?;
+
+            Ok(HardwareBufferRef::from_ptr(NonNull::new_unchecked(ptr)))
+        }
+    }
+
+    /// Create a [`HardwareBuffer`] from JNI pointers
+    ///
+    /// # Safety
+    /// By calling this function, you assert that these are valid pointers to JNI objects.
+    ///
+    /// This method does not acquire any additional reference to the AHardwareBuffer that is
+    /// returned. To keep the [`HardwareBuffer`] alive after the [Java `HardwareBuffer`] object
+    /// is closed, explicitly or by the garbage collector, be sure to retrieve a strong reference
+    /// using [`HardwareBuffer::acquire()`].
+    ///
+    /// [Java `HardwareBuffer`]: https://developer.android.com/reference/android/hardware/HardwareBuffer
+    pub unsafe fn from_jni(env: *mut JNIEnv, hardware_buffer: jobject) -> Self {
+        let ptr = ffi::AHardwareBuffer_fromHardwareBuffer(env, hardware_buffer);
+
+        Self::from_ptr(NonNull::new_unchecked(ptr))
+    }
+
+    /// # Safety
+    /// By calling this function, you assert that `env` is a valid pointer to a [`JNIEnv`].
+    pub unsafe fn to_jni(&self, env: *mut JNIEnv) -> jobject {
+        ffi::AHardwareBuffer_toHardwareBuffer(env, self.as_ptr())
+    }
+
+    /// Return a description of the [`HardwareBuffer`] in the passed [`HardwareBufferDesc`] struct.
+    pub fn describe(&self) -> HardwareBufferDesc {
+        let desc = unsafe {
+            let mut result = MaybeUninit::uninit();
+            ffi::AHardwareBuffer_describe(self.as_ptr(), result.as_mut_ptr());
+            result.assume_init()
+        };
+
+        HardwareBufferDesc {
+            width: desc.width,
+            height: desc.height,
+            layers: desc.layers,
+            format: i32::try_from(desc.format)
+                .expect("i32->u32 overflow in HardwareBuffer::describe()")
+                .into(),
+            usage: HardwareBufferUsage::from_bits_retain(desc.usage),
+            stride: desc.stride,
+        }
+    }
+
+    /// Test whether the given format and usage flag combination is allocatable.
+    ///
+    /// If this function returns [`true`], it means that a buffer with the given description can
+    /// be allocated on this implementation, unless resource exhaustion occurs. If this function
+    /// returns [`false`], it means that the allocation of the given description will never
+    /// succeed.
+    ///
+    /// The return value of this function may depend on all fields in the description, except
+    /// [`HardwareBufferDesc::stride`], which is always ignored. For example, some implementations
+    /// have implementation-defined limits on texture size and layer count.
+    #[cfg(feature = "api-level-29")]
+    pub fn is_supported(desc: HardwareBufferDesc) -> bool {
+        let res = unsafe { ffi::AHardwareBuffer_isSupported(&desc.into_native()) };
+        res == 1
+    }
+
+    /// Get the system-wide unique id for this [`HardwareBuffer`].
+    #[cfg(feature = "api-level-31")]
+    #[doc(alias = "AHardwareBuffer_getId")]
+    pub fn id(&self) -> Result<u64> {
+        construct(|res| unsafe { ffi::AHardwareBuffer_getId(self.as_ptr(), res) })
+    }
+
+    /// Lock the [`HardwareBuffer`] for direct CPU access.
+    ///
+    /// This function can lock the buffer for either reading or writing. It may block if the
+    /// hardware needs to finish rendering, if CPU caches need to be synchronized, or possibly for
+    /// other implementation-specific reasons.
+    ///
+    /// The [`HardwareBuffer`] must have one layer, otherwise the call will fail.
+    ///
+    /// If `fence` is not [`None`], it specifies a fence file descriptor on which to wait before
+    /// locking the buffer. If it's [`None`], the caller is responsible for ensuring that writes
+    /// to the buffer have completed before calling this function. Using this parameter is more
+    /// efficient than waiting on the fence and then calling this function.
+    ///
+    /// The `usage` parameter may only specify `HardwareBufferUsage::CPU_*`. If set, then the
+    /// address of the buffer in virtual memory is returned. The flags must also be compatible with
+    /// usage flags specified at buffer creation: if a read flag is passed, the buffer must have
+    /// been created with [`HardwareBufferUsage::CPU_READ_RARELY`] or
+    /// [`HardwareBufferUsage::CPU_READ_OFTEN`]. If a write flag is passed, it must have been
+    /// created with [`HardwareBufferUsage::CPU_WRITE_RARELY`] or
+    /// [`HardwareBufferUsage::CPU_WRITE_OFTEN`].
+    ///
+    /// If `rect` is not [`None`], the caller promises to modify only data in the area specified by
+    /// `rect`. If rect is [`None`], the caller may modify the contents of the entire buffer. The
+    /// content of the buffer outside of the specified rect is NOT modified by this call.
+    ///
+    /// It is legal for several different threads to lock a buffer for read access; none of the
+    /// threads are blocked.
+    ///
+    /// Locking a buffer simultaneously for write or read/write is undefined, but will neither
+    /// terminate the process nor block the caller. This function may return an error or leave the
+    /// buffer's content in an indeterminate state.
+    ///
+    /// If the buffer has [`HardwareBufferFormat::BLOB`], it is legal lock it for reading and
+    /// writing in multiple threads and/or processes simultaneously, and the contents of the buffer
+    /// behave like shared memory.
+    pub fn lock(
+        &self,
+        usage: HardwareBufferUsage,
+        fence: Option<OwnedFd>,
+        rect: Option<Rect>,
+    ) -> Result<*mut c_void> {
+        let fence = fence.map_or(-1, IntoRawFd::into_raw_fd);
+        let rect = match rect {
+            Some(rect) => &rect,
+            None => std::ptr::null(),
+        };
+        construct(|res| unsafe {
+            ffi::AHardwareBuffer_lock(self.as_ptr(), usage.bits(), fence, rect, res)
+        })
+    }
+
+    /// Lock a [`HardwareBuffer`] for direct CPU access.
+    ///
+    /// This function is the same as the above [`lock()`][Self::lock()] function, but passes back
+    /// additional information about the bytes per pixel and the bytes per stride of the locked
+    /// buffer. If the bytes per pixel or bytes per stride are unknown or variable, or if the
+    /// underlying mapper implementation does not support returning additional information, then
+    /// this call will fail with [`std::io::Error::kind()`] = [`std::io::ErrorKind::Unsupported`].
+    #[cfg(feature = "api-level-29")]
+    pub fn lock_and_get_info(
+        &self,
+        usage: HardwareBufferUsage,
+        fence: Option<OwnedFd>,
+        rect: Option<Rect>,
+    ) -> Result<LockedPlaneInfo> {
+        let fence = fence.map_or(-1, IntoRawFd::into_raw_fd);
+        let rect = match rect {
+            Some(rect) => &rect,
+            None => std::ptr::null(),
+        };
+        let mut virtual_address = MaybeUninit::uninit();
+        let mut bytes_per_pixel = MaybeUninit::uninit();
+        let mut bytes_per_stride = MaybeUninit::uninit();
+        let status = unsafe {
+            ffi::AHardwareBuffer_lockAndGetInfo(
+                self.as_ptr(),
+                usage.bits(),
+                fence,
+                rect,
+                virtual_address.as_mut_ptr(),
+                bytes_per_pixel.as_mut_ptr(),
+                bytes_per_stride.as_mut_ptr(),
+            )
+        };
+        status_to_io_result(status).map(|()| unsafe {
+            LockedPlaneInfo {
+                virtual_address: virtual_address.assume_init(),
+                bytes_per_pixel: bytes_per_pixel.assume_init() as u32,
+                bytes_per_stride: bytes_per_stride.assume_init() as u32,
+            }
+        })
+    }
+
+    /// Lock a potentially multi-planar [`HardwareBuffer`] for direct CPU access.
+    ///
+    /// This function is similar to [`lock()`][Self::lock()], but can lock multi-planar formats.
+    /// Note, that multi-planar should not be confused with multi-layer images, which this locking
+    /// function does not support.
+    ///
+    /// YUV formats are always represented by three separate planes of data, one for each color
+    /// plane. The order of planes in the array is guaranteed such that plane #0 is always `Y`,
+    /// plane #1 is always `U` (`Cb`), and plane #2 is always `V` (`Cr`). All other formats are
+    /// represented by a single plane.
+    ///
+    /// Additional information always accompanies the buffers, describing the row stride and the
+    /// pixel stride for each plane.
+    ///
+    /// In case the buffer cannot be locked, this will return zero planes.
+    ///
+    /// See the [`lock()`][Self::lock()] documentation for all other locking semantics.
+    #[cfg(feature = "api-level-29")]
+    pub fn lock_planes(
+        &self,
+        usage: HardwareBufferUsage,
+        fence: Option<OwnedFd>,
+        rect: Option<Rect>,
+    ) -> Result<HardwareBufferPlanes> {
+        let fence = fence.map_or(-1, IntoRawFd::into_raw_fd);
+        let rect = match rect {
+            Some(rect) => &rect,
+            None => std::ptr::null(),
+        };
+        let planes = construct(|res| unsafe {
+            ffi::AHardwareBuffer_lockPlanes(self.as_ptr(), usage.bits(), fence, rect, res)
+        })?;
+
+        Ok(HardwareBufferPlanes {
+            inner: planes,
+            index: 0,
+        })
+    }
+
+    /// Unlock the [`HardwareBuffer`] from direct CPU access.
+    ///
+    /// Must be called after all changes to the buffer are completed by the caller. The function
+    /// will block until all work is completed. See [`unlock_async()`][Self::unlock_async()] for
+    /// a non-blocking variant that returns a file descriptor to be signaled on unlocking instead.
+    pub fn unlock(&self) -> Result<()> {
+        let status = unsafe { ffi::AHardwareBuffer_unlock(self.as_ptr(), std::ptr::null_mut()) };
+        status_to_io_result(status)
+    }
+
+    /// Unlock the [`HardwareBuffer`] from direct CPU access.
+    ///
+    /// Returns a fence file descriptor that will become signaled when unlocking is completed, or
+    /// [`None`] if unlocking is already finished. The caller is responsible for closing the file
+    /// descriptor once it's no longer needed. See [`unlock()`][Self::unlock()] for a variant that
+    /// blocks instead.
+    pub fn unlock_async(&self) -> Result<Option<OwnedFd>> {
+        let fence = construct(|res| unsafe { ffi::AHardwareBuffer_unlock(self.as_ptr(), res) })?;
+        Ok(match fence {
+            -1 => None,
+            fence => Some(unsafe { OwnedFd::from_raw_fd(fence) }),
+        })
+    }
+
+    /// Receive a [`HardwareBuffer`] from an `AF_UNIX` socket.
+    ///
+    /// `AF_UNIX` sockets are wrapped by [`std::os::unix::net::UnixListener`] and
+    /// [`std::os::unix::net::UnixStream`] in Rust and have a corresponding
+    /// [`std::os::unix::io::AsFd::as_fd()`] implementation.
+    pub fn recv_handle_from_unix_socket(socket_fd: BorrowedFd<'_>) -> Result<Self> {
+        unsafe {
+            let ptr = construct(|res| {
+                ffi::AHardwareBuffer_recvHandleFromUnixSocket(socket_fd.as_raw_fd(), res)
+            })?;
+
+            Ok(Self::from_ptr(NonNull::new_unchecked(ptr)))
+        }
+    }
+
+    /// Send the [`HardwareBuffer`] to an `AF_UNIX` socket.
+    ///
+    /// `AF_UNIX` sockets are wrapped by [`std::os::unix::net::UnixListener`] and
+    /// [`std::os::unix::net::UnixStream`] in Rust and have a corresponding
+    /// [`std::os::unix::io::AsFd::as_fd()`] implementation.
+    pub fn send_handle_to_unix_socket(&self, socket_fd: BorrowedFd<'_>) -> Result<()> {
+        let status = unsafe {
+            ffi::AHardwareBuffer_sendHandleToUnixSocket(self.as_ptr(), socket_fd.as_raw_fd())
+        };
+        status_to_io_result(status)
+    }
+
+    /// Acquire a reference on the given [`HardwareBuffer`] object.
+    ///
+    /// This prevents the object from being deleted until the last strong reference, represented
+    /// by [`HardwareBufferRef`], is [`drop()`]ped.
+    pub fn acquire(&self) -> HardwareBufferRef {
+        unsafe {
+            ffi::AHardwareBuffer_acquire(self.as_ptr());
+            HardwareBufferRef::from_ptr(self.inner)
+        }
+    }
+}
+
+/// A [`HardwareBuffer`] with an owned reference, that is released when dropped.
+/// It behaves much like a strong [`std::rc::Rc`] reference.
+#[derive(Debug)]
+pub struct HardwareBufferRef {
+    inner: HardwareBuffer,
+}
+
+impl HardwareBufferRef {
+    /// Create an _owned_ [`HardwareBuffer`] from a native pointer
+    ///
+    /// To wrap a weak reference (that is **not** `release`d on [`Drop`]), call
+    /// [`HardwareBuffer::from_ptr()`] instead.
+    ///
+    /// # Safety
+    /// By calling this function, you assert that it is a valid pointer to an NDK
+    /// [`ffi::AHardwareBuffer`].
+    pub unsafe fn from_ptr(ptr: NonNull<ffi::AHardwareBuffer>) -> Self {
+        Self {
+            inner: HardwareBuffer { inner: ptr },
+        }
+    }
+}
+
+impl Deref for HardwareBufferRef {
+    type Target = HardwareBuffer;
+
+    fn deref(&self) -> &Self::Target {
+        &self.inner
+    }
+}
+
+impl Drop for HardwareBufferRef {
+    fn drop(&mut self) {
+        unsafe { ffi::AHardwareBuffer_release(self.inner.as_ptr()) }
+    }
+}
+
+impl Clone for HardwareBufferRef {
+    fn clone(&self) -> Self {
+        self.acquire()
+    }
+}
+
+/// Buffer description.
+///
+/// Used for allocating new buffers and querying parameters of existing ones.
+#[derive(Copy, Clone, Debug, PartialEq, Eq)]
+pub struct HardwareBufferDesc {
+    pub width: u32,
+    pub height: u32,
+    pub layers: u32,
+    pub format: HardwareBufferFormat,
+    pub usage: HardwareBufferUsage,
+    pub stride: u32,
+}
+
+impl HardwareBufferDesc {
+    fn into_native(self) -> ffi::AHardwareBuffer_Desc {
+        ffi::AHardwareBuffer_Desc {
+            width: self.width,
+            height: self.height,
+            layers: self.layers,
+            format: i32::from(self.format)
+                .try_into()
+                .expect("i32->u32 overflow in HardwareBufferDesc::into_native()"),
+            usage: self.usage.bits(),
+            stride: self.stride,
+            rfu0: 0,
+            rfu1: 0,
+        }
+    }
+}
+
+/// A native [`AHardwareBuffer_Plane`]
+///
+/// Contains the same fields as [`ffi::AHardwareBuffer_Plane`].
+///
+/// [`AHardwareBuffer_Plane`]: https://developer.android.com/ndk/reference/group/a-hardware-buffer#ahardwarebuffer_plane
+#[derive(Copy, Clone, Debug, PartialEq, Eq)]
+pub struct LockedPlaneInfo {
+    pub virtual_address: *mut c_void,
+    pub bytes_per_pixel: u32,
+    pub bytes_per_stride: u32,
+}
+
+/// Iterator over [`ffi::AHardwareBuffer_Planes`], containing a list of [`LockedPlaneInfo`].
+#[derive(Debug)]
+pub struct HardwareBufferPlanes {
+    inner: ffi::AHardwareBuffer_Planes,
+    index: u32,
+}
+
+impl Iterator for HardwareBufferPlanes {
+    type Item = LockedPlaneInfo;
+
+    fn next(&mut self) -> Option<LockedPlaneInfo> {
+        if self.index == self.inner.planeCount {
+            None
+        } else {
+            let plane = self.inner.planes[self.index as usize];
+            self.index += 1;
+            Some(LockedPlaneInfo {
+                virtual_address: plane.data,
+                bytes_per_pixel: plane.pixelStride,
+                bytes_per_stride: plane.rowStride,
+            })
+        }
+    }
+}

clients/android/native/vendor/ndk/src/hardware_buffer_format.rs

@@ -0,0 +1,106 @@
+//! Bindings for [`AHardwareBuffer_Format`]
+//!
+//! [`AHardwareBuffer_Format`]: https://developer.android.com/ndk/reference/group/a-hardware-buffer#ahardwarebuffer_format
+
+use num_enum::{FromPrimitive, IntoPrimitive};
+
+/// Buffer pixel formats.
+#[repr(i32)]
+#[derive(Copy, Clone, Debug, PartialEq, Eq, FromPrimitive, IntoPrimitive)]
+#[allow(non_camel_case_types)]
+#[non_exhaustive]
+pub enum HardwareBufferFormat {
+    /// Matches deprecated [`ffi::ANativeWindow_LegacyFormat::WINDOW_FORMAT_RGBA_8888`].0.
+    #[doc(alias = "AHARDWAREBUFFER_FORMAT_R8G8B8A8_UNORM")]
+    R8G8B8A8_UNORM = ffi::AHardwareBuffer_Format::AHARDWAREBUFFER_FORMAT_R8G8B8A8_UNORM.0 as i32,
+    /// Matches deprecated [`ffi::ANativeWindow_LegacyFormat::WINDOW_FORMAT_RGBX_8888`].0.
+    #[doc(alias = "AHARDWAREBUFFER_FORMAT_R8G8B8X8_UNORM")]
+    R8G8B8X8_UNORM = ffi::AHardwareBuffer_Format::AHARDWAREBUFFER_FORMAT_R8G8B8X8_UNORM.0 as i32,
+    #[cfg(feature = "api-level-26")]
+    #[doc(alias = "AHARDWAREBUFFER_FORMAT_R8G8B8_UNORM")]
+    R8G8B8_UNORM = ffi::AHardwareBuffer_Format::AHARDWAREBUFFER_FORMAT_R8G8B8_UNORM.0 as i32,
+    /// Matches deprecated [`ffi::ANativeWindow_LegacyFormat::WINDOW_FORMAT_RGB_565`].0.
+    #[doc(alias = "AHARDWAREBUFFER_FORMAT_R5G6B5_UNORM")]
+    R5G6B5_UNORM = ffi::AHardwareBuffer_Format::AHARDWAREBUFFER_FORMAT_R5G6B5_UNORM.0 as i32,
+    #[cfg(feature = "api-level-26")]
+    #[doc(alias = "AHARDWAREBUFFER_FORMAT_R16G16B16A16_FLOAT")]
+    R16G16B16A16_FLOAT =
+        ffi::AHardwareBuffer_Format::AHARDWAREBUFFER_FORMAT_R16G16B16A16_FLOAT.0 as i32,
+    #[cfg(feature = "api-level-26")]
+    #[doc(alias = "AHARDWAREBUFFER_FORMAT_R10G10B10A2_UNORM")]
+    R10G10B10A2_UNORM =
+        ffi::AHardwareBuffer_Format::AHARDWAREBUFFER_FORMAT_R10G10B10A2_UNORM.0 as i32,
+    #[cfg(feature = "api-level-26")]
+    #[doc(alias = "AHARDWAREBUFFER_FORMAT_BLOB")]
+    BLOB = ffi::AHardwareBuffer_Format::AHARDWAREBUFFER_FORMAT_BLOB.0 as i32,
+    #[cfg(feature = "api-level-26")]
+    #[doc(alias = "AHARDWAREBUFFER_FORMAT_D16_UNORM")]
+    D16_UNORM = ffi::AHardwareBuffer_Format::AHARDWAREBUFFER_FORMAT_D16_UNORM.0 as i32,
+    #[cfg(feature = "api-level-26")]
+    #[doc(alias = "AHARDWAREBUFFER_FORMAT_D24_UNORM")]
+    D24_UNORM = ffi::AHardwareBuffer_Format::AHARDWAREBUFFER_FORMAT_D24_UNORM.0 as i32,
+    #[cfg(feature = "api-level-26")]
+    #[doc(alias = "AHARDWAREBUFFER_FORMAT_D24_UNORM_S8_UINT")]
+    D24_UNORM_S8_UINT =
+        ffi::AHardwareBuffer_Format::AHARDWAREBUFFER_FORMAT_D24_UNORM_S8_UINT.0 as i32,
+    #[cfg(feature = "api-level-26")]
+    #[doc(alias = "AHARDWAREBUFFER_FORMAT_D32_FLOAT")]
+    D32_FLOAT = ffi::AHardwareBuffer_Format::AHARDWAREBUFFER_FORMAT_D32_FLOAT.0 as i32,
+    #[cfg(feature = "api-level-26")]
+    #[doc(alias = "AHARDWAREBUFFER_FORMAT_D32_FLOAT_S8_UINT")]
+    D32_FLOAT_S8_UINT =
+        ffi::AHardwareBuffer_Format::AHARDWAREBUFFER_FORMAT_D32_FLOAT_S8_UINT.0 as i32,
+    #[cfg(feature = "api-level-26")]
+    #[doc(alias = "AHARDWAREBUFFER_FORMAT_S8_UINT")]
+    S8_UINT = ffi::AHardwareBuffer_Format::AHARDWAREBUFFER_FORMAT_S8_UINT.0 as i32,
+    #[cfg(feature = "api-level-26")]
+    #[doc(alias = "AHARDWAREBUFFER_FORMAT_Y8Cb8Cr8_420")]
+    Y8Cb8Cr8_420 = ffi::AHardwareBuffer_Format::AHARDWAREBUFFER_FORMAT_Y8Cb8Cr8_420.0 as i32,
+    #[cfg(feature = "api-level-26")]
+    #[doc(alias = "AHARDWAREBUFFER_FORMAT_YCbCr_P010")]
+    YCbCr_P010 = ffi::AHardwareBuffer_Format::AHARDWAREBUFFER_FORMAT_YCbCr_P010.0 as i32,
+    #[cfg(feature = "api-level-26")]
+    R8_UNORM = ffi::AHardwareBuffer_Format::AHARDWAREBUFFER_FORMAT_R8_UNORM.0 as i32,
+
+    #[doc(hidden)]
+    #[num_enum(catch_all)]
+    __Unknown(i32),
+}
+
+impl HardwareBufferFormat {
+    /// Returns [`None`] when there is no immediate byte size available for this format, for
+    /// example on planar buffer formats.
+    pub fn bytes_per_pixel(self) -> Option<usize> {
+        Some(match self {
+            Self::R8G8B8A8_UNORM | Self::R8G8B8X8_UNORM => 4,
+            #[cfg(feature = "api-level-26")]
+            Self::R8G8B8_UNORM => 3,
+            Self::R5G6B5_UNORM => 2,
+            #[cfg(feature = "api-level-26")]
+            Self::R16G16B16A16_FLOAT => 8,
+            #[cfg(feature = "api-level-26")]
+            Self::R10G10B10A2_UNORM => 4,
+            #[cfg(feature = "api-level-26")]
+            Self::BLOB => 1,
+            #[cfg(feature = "api-level-26")]
+            Self::D16_UNORM => 2,
+            #[cfg(feature = "api-level-26")]
+            Self::D24_UNORM => 3,
+            #[cfg(feature = "api-level-26")]
+            Self::D24_UNORM_S8_UINT => 4,
+            #[cfg(feature = "api-level-26")]
+            Self::D32_FLOAT => 4,
+            #[cfg(feature = "api-level-26")]
+            Self::D32_FLOAT_S8_UINT => 5,
+            #[cfg(feature = "api-level-26")]
+            Self::S8_UINT => 1,
+            #[cfg(feature = "api-level-26")]
+            Self::Y8Cb8Cr8_420 => 3,
+            #[cfg(feature = "api-level-26")]
+            Self::YCbCr_P010 => return None,
+            #[cfg(feature = "api-level-26")]
+            Self::R8_UNORM => 1,
+            Self::__Unknown(_) => return None,
+        })
+    }
+}

clients/android/native/vendor/ndk/src/input_queue.rs

@@ -0,0 +1,143 @@
+//! Bindings for [`AInputQueue`]
+//!
+//! [`AInputQueue`]: https://developer.android.com/ndk/reference/group/input#ainputqueue
+
+use std::io::Result;
+use std::os::raw::c_int;
+use std::ptr::{self, NonNull};
+
+#[cfg(feature = "api-level-33")]
+use jni_sys::{jobject, JNIEnv};
+
+use crate::event::InputEvent;
+#[cfg(doc)]
+use crate::event::KeyEvent;
+use crate::looper::ForeignLooper;
+use crate::utils::status_to_io_result;
+
+/// A native [`AInputQueue *`]
+///
+/// An input queue is the facility through which you retrieve input events.
+///
+/// [`AInputQueue *`]: https://developer.android.com/ndk/reference/group/input#ainputqueue
+#[derive(Debug)]
+pub struct InputQueue {
+    ptr: NonNull<ffi::AInputQueue>,
+}
+
+// It gets shared between threads in `ndk-glue`
+unsafe impl Send for InputQueue {}
+unsafe impl Sync for InputQueue {}
+
+impl InputQueue {
+    /// Construct an [`InputQueue`] from the native pointer.
+    ///
+    /// # Safety
+    /// By calling this function, you assert that the pointer is a valid pointer to an NDK [`ffi::AInputQueue`].
+    pub unsafe fn from_ptr(ptr: NonNull<ffi::AInputQueue>) -> Self {
+        Self { ptr }
+    }
+
+    /// Returns the [`InputQueue`] object associated with the supplied
+    /// [Java `InputQueue`][`android.view.InputQueue`] object.
+    ///
+    /// # Safety
+    ///
+    /// This function should be called with a healthy JVM pointer and with a non-null
+    /// [`android.view.InputQueue`], which must be kept alive on the Java/Kotlin side.
+    ///
+    /// The returned native object holds a weak reference to the Java object, and is only valid as
+    /// long as the Java object has not yet been disposed. You should ensure that there is a strong
+    /// reference to the Java object and that it has not been disposed before using the returned
+    /// object.
+    ///
+    /// [`android.view.InputQueue`]: https://developer.android.com/reference/android/view/InputQueue
+    #[cfg(feature = "api-level-33")]
+    #[doc(alias = "AInputQueue_fromJava")]
+    pub unsafe fn from_java(env: *mut JNIEnv, input_queue: jobject) -> Option<Self> {
+        let ptr = unsafe { ffi::AInputQueue_fromJava(env, input_queue) };
+        Some(Self::from_ptr(NonNull::new(ptr)?))
+    }
+
+    pub fn ptr(&self) -> NonNull<ffi::AInputQueue> {
+        self.ptr
+    }
+
+    /// Returns the next available [`InputEvent`] from the queue.
+    ///
+    /// Returns [`None`] if no event is available.
+    #[doc(alias = "AInputQueue_getEvent")]
+    pub fn event(&self) -> Result<Option<InputEvent>> {
+        let mut out_event = ptr::null_mut();
+        let status = unsafe { ffi::AInputQueue_getEvent(self.ptr.as_ptr(), &mut out_event) };
+        match status_to_io_result(status) {
+            Ok(()) => {
+                debug_assert!(!out_event.is_null());
+                Ok(Some(unsafe {
+                    InputEvent::from_ptr(NonNull::new_unchecked(out_event))
+                }))
+            }
+            Err(e) if e.kind() == std::io::ErrorKind::WouldBlock => Ok(None),
+            Err(e) => Err(e),
+        }
+    }
+
+    /// Returns [`true`] if there are one or more events available in the input queue.
+    #[doc(alias = "AInputQueue_hasEvents")]
+    pub fn has_events(&self) -> bool {
+        match unsafe { ffi::AInputQueue_hasEvents(self.ptr.as_ptr()) } {
+            0 => false,
+            1 => true,
+            r => unreachable!("AInputQueue_hasEvents returned non-boolean {}", r),
+        }
+    }
+
+    /// Sends the key for standard pre-dispatching that is, possibly deliver it to the current IME
+    /// to be consumed before the app.
+    ///
+    /// Returns [`Some`] if it was not pre-dispatched, meaning you can process it right now. If
+    /// [`None`] is returned, you must abandon the current event processing and allow the event to
+    /// appear again in the event queue (if it does not get consumed during pre-dispatching).
+    ///
+    /// Also returns [`None`] if `event` is not a [`KeyEvent`].
+    #[doc(alias = "AInputQueue_preDispatchEvent")]
+    pub fn pre_dispatch(&self, event: InputEvent) -> Option<InputEvent> {
+        match unsafe { ffi::AInputQueue_preDispatchEvent(self.ptr.as_ptr(), event.ptr().as_ptr()) }
+        {
+            0 => Some(event),
+            _ => None,
+        }
+    }
+
+    /// Report that dispatching has finished with the given [`InputEvent`].
+    ///
+    /// This must be called after receiving an event with [`InputQueue::event()`].
+    #[doc(alias = "AInputQueue_finishEvent")]
+    pub fn finish_event(&self, event: InputEvent, handled: bool) {
+        unsafe {
+            ffi::AInputQueue_finishEvent(self.ptr.as_ptr(), event.ptr().as_ptr(), handled as c_int)
+        }
+    }
+
+    /// Add this input queue to a [`ForeignLooper`] for processing.
+    ///
+    /// See [`ForeignLooper::add_fd()`] for information on the `ident`, `callback`, and `data` params.
+    #[doc(alias = "AInputQueue_attachLooper")]
+    pub fn attach_looper(&self, looper: &ForeignLooper, id: i32) {
+        unsafe {
+            ffi::AInputQueue_attachLooper(
+                self.ptr.as_ptr(),
+                looper.ptr().as_ptr(),
+                id,
+                None,
+                ptr::null_mut(),
+            )
+        }
+    }
+
+    /// Remove this input queue from the [`ForeignLooper`] it is currently attached to.
+    #[doc(alias = "AInputQueue_detachLooper")]
+    pub fn detach_looper(&self) {
+        unsafe { ffi::AInputQueue_detachLooper(self.ptr.as_ptr()) }
+    }
+}

clients/android/native/vendor/ndk/src/lib.rs

@@ -0,0 +1,33 @@
+//! # Android NDK
+//!
+//! Bindings to the [Android NDK].
+//!
+//! [Android NDK]: https://developer.android.com/ndk/reference
+#![warn(
+    missing_debug_implementations,
+    rust_2018_idioms,
+    trivial_casts,
+    unused_qualifications
+)]
+#![cfg_attr(docsrs, feature(doc_cfg, doc_auto_cfg))]
+
+pub mod asset;
+pub mod audio;
+pub mod bitmap;
+pub mod configuration;
+pub mod data_space;
+pub mod event;
+pub mod font;
+pub mod hardware_buffer;
+pub mod hardware_buffer_format;
+pub mod input_queue;
+pub mod looper;
+pub mod media;
+pub mod media_error;
+pub mod native_activity;
+pub mod native_window;
+pub mod shared_memory;
+pub mod surface_texture;
+pub mod sync;
+pub mod trace;
+mod utils;

clients/android/native/vendor/ndk/src/looper.rs

@@ -0,0 +1,459 @@
+//! Bindings for [`ALooper`]
+//!
+//! In Android, [`ALooper`]s are inherently thread-local.  Due to this, there are two different
+//! [`ALooper`] interfaces exposed in this module:
+//!
+//! * [`ThreadLooper`], which has methods for the operations performable with a looper in one's own
+//!   thread; and
+//! * [`ForeignLooper`], which has methods for the operations performable with any thread's looper.
+//!
+//! [`ALooper`]: https://developer.android.com/ndk/reference/group/looper#alooper
+
+use std::mem::ManuallyDrop;
+use std::os::{
+    fd::{AsRawFd, BorrowedFd, RawFd},
+    raw::c_void,
+};
+use std::ptr;
+use std::time::Duration;
+use thiserror::Error;
+
+use crate::utils::abort_on_panic;
+
+/// A thread-local native [`ALooper *`].  This promises that there is a looper associated with the
+/// current thread.
+///
+/// [`ALooper *`]: https://developer.android.com/ndk/reference/group/looper#alooper
+#[derive(Debug)]
+pub struct ThreadLooper {
+    _marker: std::marker::PhantomData<*mut ()>, // Not send or sync
+    foreign: ForeignLooper,
+}
+
+bitflags::bitflags! {
+    /// Flags for file descriptor events that a looper can monitor.
+    ///
+    /// These flag bits can be combined to monitor multiple events at once.
+    #[derive(Clone, Copy, Debug, Hash, PartialEq, Eq, PartialOrd, Ord)]
+    pub struct FdEvent : u32 {
+        /// The file descriptor is available for read operations.
+        #[doc(alias = "ALOOPER_EVENT_INPUT")]
+        const INPUT = ffi::ALOOPER_EVENT_INPUT;
+        /// The file descriptor is available for write operations.
+        #[doc(alias = "ALOOPER_EVENT_OUTPUT")]
+        const OUTPUT = ffi::ALOOPER_EVENT_OUTPUT;
+        /// The file descriptor has encountered an error condition.
+        ///
+        /// The looper always sends notifications about errors; it is not necessary to specify this
+        /// event flag in the requested event set.
+        #[doc(alias = "ALOOPER_EVENT_ERROR")]
+        const ERROR = ffi::ALOOPER_EVENT_ERROR;
+        /// The file descriptor was hung up.
+        ///
+        /// For example, indicates that the remote end of a pipe or socket was closed.
+        ///
+        /// The looper always sends notifications about hangups; it is not necessary to specify this
+        /// event flag in the requested event set.
+        #[doc(alias = "ALOOPER_EVENT_HANGUP")]
+        const HANGUP = ffi::ALOOPER_EVENT_HANGUP;
+        /// The file descriptor is invalid.
+        ///
+        /// For example, the file descriptor was closed prematurely.
+        ///
+        /// The looper always sends notifications about invalid file descriptors; it is not
+        /// necessary to specify this event flag in the requested event set.
+        #[doc(alias = "ALOOPER_EVENT_INVALID")]
+        const INVALID = ffi::ALOOPER_EVENT_INVALID;
+
+        // https://docs.rs/bitflags/latest/bitflags/#externally-defined-flags
+        const _ = !0;
+    }
+}
+
+/// The poll result from a [`ThreadLooper`].
+#[derive(Debug)]
+pub enum Poll<'fd> {
+    /// This looper was woken using [`ForeignLooper::wake()`]
+    Wake,
+    /// For [`ThreadLooper::poll_once*()`][ThreadLooper::poll_once()], an event was received and processed using a callback.
+    Callback,
+    /// For [`ThreadLooper::poll_*_timeout()`][ThreadLooper::poll_once_timeout()], the requested timeout was reached before any events.
+    Timeout,
+    /// An event was received
+    Event {
+        ident: i32,
+        /// # Safety
+        /// The caller should guarantee that this file descriptor remains open after it was added
+        /// via [`ForeignLooper::add_fd()`] or [`ForeignLooper::add_fd_with_callback()`].
+        fd: BorrowedFd<'fd>,
+        events: FdEvent,
+        data: *mut c_void,
+    },
+}
+
+#[derive(Debug, Copy, Clone, Error)]
+#[error("Android Looper error")]
+pub struct LooperError;
+
+impl ThreadLooper {
+    /// Prepares a looper for the current thread and returns it
+    pub fn prepare() -> Self {
+        unsafe {
+            let ptr = ffi::ALooper_prepare(ffi::ALOOPER_PREPARE_ALLOW_NON_CALLBACKS as _);
+            let foreign = ForeignLooper::from_ptr(ptr::NonNull::new(ptr).expect("looper non null"));
+            Self {
+                _marker: std::marker::PhantomData,
+                foreign,
+            }
+        }
+    }
+
+    /// Returns the looper associated with the current thread, if any.
+    pub fn for_thread() -> Option<Self> {
+        Some(Self {
+            _marker: std::marker::PhantomData,
+            foreign: ForeignLooper::for_thread()?,
+        })
+    }
+
+    /// Polls the looper, blocking on processing an event, but with a timeout in milliseconds.
+    /// Give a timeout of `0` to make this non-blocking.
+    fn poll_once_ms(&self, ms: i32) -> Result<Poll<'_>, LooperError> {
+        let mut fd = -1;
+        let mut events = -1;
+        let mut data: *mut c_void = ptr::null_mut();
+        match unsafe { ffi::ALooper_pollOnce(ms, &mut fd, &mut events, &mut data) } {
+            ffi::ALOOPER_POLL_WAKE => Ok(Poll::Wake),
+            ffi::ALOOPER_POLL_CALLBACK => Ok(Poll::Callback),
+            ffi::ALOOPER_POLL_TIMEOUT => Ok(Poll::Timeout),
+            ffi::ALOOPER_POLL_ERROR => Err(LooperError),
+            ident if ident >= 0 => Ok(Poll::Event {
+                ident,
+                // SAFETY: Even though this FD at least shouldn't outlive self, a user could have
+                // closed it after calling add_fd or add_fd_with_callback.
+                fd: unsafe { BorrowedFd::borrow_raw(fd) },
+                events: FdEvent::from_bits(events as u32)
+                    .expect("poll event contains unknown bits"),
+                data,
+            }),
+            _ => unreachable!(),
+        }
+    }
+
+    /// Polls the looper, blocking on processing an event.
+    #[inline]
+    pub fn poll_once(&self) -> Result<Poll<'_>, LooperError> {
+        self.poll_once_ms(-1)
+    }
+
+    /// Polls the looper, blocking on processing an event, but with a timeout.  Give a timeout of
+    /// [`Duration::ZERO`] to make this non-blocking.
+    ///
+    /// It panics if the timeout is larger than expressible as an [`i32`] of milliseconds (roughly 25
+    /// days).
+    #[inline]
+    pub fn poll_once_timeout(&self, timeout: Duration) -> Result<Poll<'_>, LooperError> {
+        self.poll_once_ms(
+            timeout
+                .as_millis()
+                .try_into()
+                .expect("Supplied timeout is too large"),
+        )
+    }
+
+    /// Repeatedly polls the looper, blocking on processing an event, but with a timeout in
+    /// milliseconds.  Give a timeout of `0` to make this non-blocking.
+    ///
+    /// This function will never return [`Poll::Callback`].
+    fn poll_all_ms(&self, ms: i32) -> Result<Poll<'_>, LooperError> {
+        let mut fd = -1;
+        let mut events = -1;
+        let mut data: *mut c_void = ptr::null_mut();
+        match unsafe { ffi::ALooper_pollAll(ms, &mut fd, &mut events, &mut data) } {
+            ffi::ALOOPER_POLL_WAKE => Ok(Poll::Wake),
+            ffi::ALOOPER_POLL_TIMEOUT => Ok(Poll::Timeout),
+            ffi::ALOOPER_POLL_ERROR => Err(LooperError),
+            ident if ident >= 0 => Ok(Poll::Event {
+                ident,
+                // SAFETY: Even though this FD at least shouldn't outlive self, a user could have
+                // closed it after calling add_fd or add_fd_with_callback.
+                fd: unsafe { BorrowedFd::borrow_raw(fd) },
+                events: FdEvent::from_bits(events as u32)
+                    .expect("poll event contains unknown bits"),
+                data,
+            }),
+            _ => unreachable!(),
+        }
+    }
+
+    /// Repeatedly polls the looper, blocking on processing an event.
+    ///
+    /// This function will never return [`Poll::Callback`].
+    #[inline]
+    pub fn poll_all(&self) -> Result<Poll<'_>, LooperError> {
+        self.poll_all_ms(-1)
+    }
+
+    /// Repeatedly polls the looper, blocking on processing an event, but with a timeout.  Give a
+    /// timeout of [`Duration::ZERO`] to make this non-blocking.
+    ///
+    /// This function will never return [`Poll::Callback`].
+    ///
+    /// It panics if the timeout is larger than expressible as an [`i32`] of milliseconds (roughly 25
+    /// days).
+    #[inline]
+    pub fn poll_all_timeout(&self, timeout: Duration) -> Result<Poll<'_>, LooperError> {
+        self.poll_all_ms(
+            timeout
+                .as_millis()
+                .try_into()
+                .expect("Supplied timeout is too large"),
+        )
+    }
+
+    /// Adds a file descriptor to be polled, with a callback that is invoked when any of the
+    /// [`FdEvent`]s described in `events` is triggered.
+    ///
+    /// The callback receives the file descriptor it is associated with and a bitmask of the poll
+    /// events that were triggered (typically [`FdEvent::INPUT`]).  It should return [`true`] to
+    /// continue receiving callbacks, or [`false`] to have the callback unregistered.
+    ///
+    /// See also [the NDK
+    /// docs](https://developer.android.com/ndk/reference/group/looper.html#alooper_addfd).
+    ///
+    /// Note that this will leak a [`Box`] unless the callback returns [`false`] to unregister
+    /// itself.
+    ///
+    /// # Threading
+    /// This function will be called on the current thread when this [`ThreadLooper`] is
+    /// polled. A callback can also be registered from other threads via the equivalent
+    /// [`ForeignLooper::add_fd_with_callback()`] function, which requires a [`Send`] bound.
+    ///
+    /// # Safety
+    /// The caller should guarantee that this file descriptor stays open until it is removed via
+    /// [`remove_fd()`][ForeignLooper::remove_fd()] or by returning [`false`] from the callback,
+    /// and for however long the caller wishes to use this file descriptor inside and after the
+    /// callback.
+    #[doc(alias = "ALooper_addFd")]
+    pub fn add_fd_with_callback<F: FnMut(BorrowedFd<'_>, FdEvent) -> bool>(
+        &self,
+        fd: BorrowedFd<'_>,
+        events: FdEvent,
+        callback: F,
+    ) -> Result<(), LooperError> {
+        unsafe {
+            self.foreign
+                .add_fd_with_callback_assume_send(fd, events, callback)
+        }
+    }
+
+    /// Returns a reference to the [`ForeignLooper`] that is associated with the current thread.
+    pub fn as_foreign(&self) -> &ForeignLooper {
+        &self.foreign
+    }
+
+    pub fn into_foreign(self) -> ForeignLooper {
+        self.foreign
+    }
+}
+
+/// A native [`ALooper *`], not necessarily allocated with the current thread.
+///
+/// [`ALooper *`]: https://developer.android.com/ndk/reference/group/looper#alooper
+#[derive(Debug)]
+pub struct ForeignLooper {
+    ptr: ptr::NonNull<ffi::ALooper>,
+}
+
+unsafe impl Send for ForeignLooper {}
+unsafe impl Sync for ForeignLooper {}
+
+impl Drop for ForeignLooper {
+    fn drop(&mut self) {
+        unsafe { ffi::ALooper_release(self.ptr.as_ptr()) }
+    }
+}
+
+impl Clone for ForeignLooper {
+    fn clone(&self) -> Self {
+        unsafe {
+            ffi::ALooper_acquire(self.ptr.as_ptr());
+            Self { ptr: self.ptr }
+        }
+    }
+}
+
+impl ForeignLooper {
+    /// Returns the looper associated with the current thread, if any.
+    #[inline]
+    pub fn for_thread() -> Option<Self> {
+        ptr::NonNull::new(unsafe { ffi::ALooper_forThread() })
+            .map(|ptr| unsafe { Self::from_ptr(ptr) })
+    }
+
+    /// Construct a [`ForeignLooper`] object from the given pointer.
+    ///
+    /// # Safety
+    /// By calling this function, you guarantee that the pointer is a valid, non-null pointer to an
+    /// NDK [`ffi::ALooper`].
+    #[inline]
+    pub unsafe fn from_ptr(ptr: ptr::NonNull<ffi::ALooper>) -> Self {
+        ffi::ALooper_acquire(ptr.as_ptr());
+        Self { ptr }
+    }
+
+    /// Returns a pointer to the NDK `ALooper` object.
+    #[inline]
+    pub fn ptr(&self) -> ptr::NonNull<ffi::ALooper> {
+        self.ptr
+    }
+
+    /// Wakes the looper.  An event of [`Poll::Wake`] will be sent.
+    pub fn wake(&self) {
+        unsafe { ffi::ALooper_wake(self.ptr.as_ptr()) }
+    }
+
+    /// Adds a file descriptor to be polled, without a callback.
+    ///
+    /// See also [the NDK
+    /// docs](https://developer.android.com/ndk/reference/group/looper.html#alooper_addfd).
+    ///
+    /// # Safety
+    /// The caller should guarantee that this file descriptor stays open until it is removed via
+    /// [`remove_fd()`][Self::remove_fd()], and for however long the caller wishes to use this file
+    /// descriptor when it is returned in [`Poll::Event::fd`].
+
+    // `ALooper_addFd` won't dereference `data`; it will only pass it on to the event.
+    // Optionally dereferencing it there already enforces `unsafe` context.
+    #[allow(clippy::not_unsafe_ptr_arg_deref)]
+    pub fn add_fd(
+        &self,
+        fd: BorrowedFd<'_>,
+        ident: i32,
+        events: FdEvent,
+        data: *mut c_void,
+    ) -> Result<(), LooperError> {
+        match unsafe {
+            ffi::ALooper_addFd(
+                self.ptr.as_ptr(),
+                fd.as_raw_fd(),
+                ident,
+                events.bits() as i32,
+                None,
+                data,
+            )
+        } {
+            1 => Ok(()),
+            -1 => Err(LooperError),
+            _ => unreachable!(),
+        }
+    }
+
+    /// Adds a file descriptor to be polled, with a callback that is invoked when any of the
+    /// [`FdEvent`]s described in `events` is triggered.
+    ///
+    /// The callback receives the file descriptor it is associated with and a bitmask of the poll
+    /// events that were triggered (typically [`FdEvent::INPUT`]).  It should return [`true`] to
+    /// continue receiving callbacks, or [`false`] to have the callback unregistered.
+    ///
+    /// See also [the NDK
+    /// docs](https://developer.android.com/ndk/reference/group/looper.html#alooper_addfd).
+    ///
+    /// Note that this will leak a [`Box`] unless the callback returns [`false`] to unregister
+    /// itself.
+    ///
+    /// # Threading
+    /// This function will be called on the looper thread where and when it is polled.
+    /// For registering callbacks without [`Send`] requirement, call the equivalent
+    /// [`ThreadLooper::add_fd_with_callback()`] function on the Looper thread.
+    ///
+    /// # Safety
+    /// The caller should guarantee that this file descriptor stays open until it is removed via
+    /// [`remove_fd()`][Self::remove_fd()] or by returning [`false`] from the callback, and for
+    /// however long the caller wishes to use this file descriptor inside and after the callback.
+    #[doc(alias = "ALooper_addFd")]
+    pub fn add_fd_with_callback<F: FnMut(BorrowedFd<'_>, FdEvent) -> bool + Send>(
+        &self,
+        fd: BorrowedFd<'_>,
+        events: FdEvent,
+        callback: F,
+    ) -> Result<(), LooperError> {
+        unsafe { self.add_fd_with_callback_assume_send(fd, events, callback) }
+    }
+
+    /// Private helper to deduplicate/commonize the implementation behind
+    /// [`ForeignLooper::add_fd_with_callback()`] and [`ThreadLooper::add_fd_with_callback()`],
+    /// as both have their own way of guaranteeing thread-safety.  The former, [`ForeignLooper`],
+    /// requires the closure to be [`Send`]. The latter, [`ThreadLooper`], can only exist on the
+    /// thread where polling happens and where the closure will end up being invoked, and does not
+    /// require [`Send`].
+    ///
+    /// # Safety
+    /// The caller must guarantee that `F` is [`Send`] or that `F` will only run on the current
+    /// thread.  See the explanation above about why this function exists.
+    unsafe fn add_fd_with_callback_assume_send<F: FnMut(BorrowedFd<'_>, FdEvent) -> bool>(
+        &self,
+        fd: BorrowedFd<'_>,
+        events: FdEvent,
+        callback: F,
+    ) -> Result<(), LooperError> {
+        extern "C" fn cb_handler<F: FnMut(BorrowedFd<'_>, FdEvent) -> bool>(
+            fd: RawFd,
+            events: i32,
+            data: *mut c_void,
+        ) -> i32 {
+            abort_on_panic(|| unsafe {
+                let mut cb = ManuallyDrop::new(Box::<F>::from_raw(data as *mut _));
+                let events = FdEvent::from_bits_retain(
+                    events.try_into().expect("Unexpected sign bit in `events`"),
+                );
+                let keep_registered = cb(BorrowedFd::borrow_raw(fd), events);
+                if !keep_registered {
+                    ManuallyDrop::into_inner(cb);
+                }
+                keep_registered as i32
+            })
+        }
+        let data = Box::into_raw(Box::new(callback)) as *mut _;
+        match unsafe {
+            ffi::ALooper_addFd(
+                self.ptr.as_ptr(),
+                fd.as_raw_fd(),
+                ffi::ALOOPER_POLL_CALLBACK,
+                events.bits() as i32,
+                Some(cb_handler::<F>),
+                data,
+            )
+        } {
+            1 => Ok(()),
+            -1 => Err(LooperError),
+            _ => unreachable!(),
+        }
+    }
+
+    /// Removes a previously added file descriptor from the looper.
+    ///
+    /// Returns [`true`] if the file descriptor was removed, [`false`] if it was not previously
+    /// registered.
+    ///
+    /// # Safety
+    /// When this method returns, it is safe to close the file descriptor since the looper will no
+    /// longer have a reference to it. However, it is possible for the callback to already be
+    /// running or for it to run one last time if the file descriptor was already signalled.
+    /// Calling code is responsible for ensuring that this case is safely handled. For example, if
+    /// the callback takes care of removing itself during its own execution either by returning `0`
+    /// or by calling this method, then it can be guaranteed to not be invoked again at any later
+    /// time unless registered anew.
+    ///
+    /// Note that unregistering a file descriptor with callback will leak a [`Box`] created in
+    /// [`add_fd_with_callback()`][Self::add_fd_with_callback()]. Consider returning [`false`]
+    /// from the callback instead to drop it.
+    pub fn remove_fd(&self, fd: BorrowedFd<'_>) -> Result<bool, LooperError> {
+        match unsafe { ffi::ALooper_removeFd(self.ptr.as_ptr(), fd.as_raw_fd()) } {
+            1 => Ok(true),
+            0 => Ok(false),
+            -1 => Err(LooperError),
+            _ => unreachable!(),
+        }
+    }
+}

clients/android/native/vendor/ndk/src/media/image_reader.rs

@@ -0,0 +1,459 @@
+//! Bindings for [`AImageReader`] and [`AImage`]
+//!
+//! [`AImageReader`]: https://developer.android.com/ndk/reference/group/media#aimagereader
+//! [`AImage`]: https://developer.android.com/ndk/reference/group/media#aimage
+#![cfg(feature = "api-level-24")]
+
+use crate::media_error::{construct, construct_never_null, MediaError, Result};
+use crate::native_window::NativeWindow;
+use crate::utils::abort_on_panic;
+use num_enum::{FromPrimitive, IntoPrimitive};
+use std::{
+    ffi::c_void,
+    fmt::{self, Debug, Formatter},
+    mem::MaybeUninit,
+    ptr::NonNull,
+};
+
+#[cfg(feature = "api-level-26")]
+use std::os::fd::{FromRawFd, IntoRawFd, OwnedFd};
+
+#[cfg(feature = "api-level-26")]
+use crate::hardware_buffer::{HardwareBuffer, HardwareBufferUsage};
+
+#[repr(i32)]
+#[derive(Copy, Clone, Debug, PartialEq, Eq, FromPrimitive, IntoPrimitive)]
+#[allow(non_camel_case_types)]
+#[non_exhaustive]
+pub enum ImageFormat {
+    RGBA_8888 = ffi::AIMAGE_FORMATS::AIMAGE_FORMAT_RGBA_8888.0 as i32,
+    RGBX_8888 = ffi::AIMAGE_FORMATS::AIMAGE_FORMAT_RGBX_8888.0 as i32,
+    RGB_888 = ffi::AIMAGE_FORMATS::AIMAGE_FORMAT_RGB_888.0 as i32,
+    RGB_565 = ffi::AIMAGE_FORMATS::AIMAGE_FORMAT_RGB_565.0 as i32,
+    RGBA_FP16 = ffi::AIMAGE_FORMATS::AIMAGE_FORMAT_RGBA_FP16.0 as i32,
+    YUV_420_888 = ffi::AIMAGE_FORMATS::AIMAGE_FORMAT_YUV_420_888.0 as i32,
+    JPEG = ffi::AIMAGE_FORMATS::AIMAGE_FORMAT_JPEG.0 as i32,
+    RAW16 = ffi::AIMAGE_FORMATS::AIMAGE_FORMAT_RAW16.0 as i32,
+    RAW_PRIVATE = ffi::AIMAGE_FORMATS::AIMAGE_FORMAT_RAW_PRIVATE.0 as i32,
+    RAW10 = ffi::AIMAGE_FORMATS::AIMAGE_FORMAT_RAW10.0 as i32,
+    RAW12 = ffi::AIMAGE_FORMATS::AIMAGE_FORMAT_RAW12.0 as i32,
+    DEPTH16 = ffi::AIMAGE_FORMATS::AIMAGE_FORMAT_DEPTH16.0 as i32,
+    DEPTH_POINT_CLOUD = ffi::AIMAGE_FORMATS::AIMAGE_FORMAT_DEPTH_POINT_CLOUD.0 as i32,
+    PRIVATE = ffi::AIMAGE_FORMATS::AIMAGE_FORMAT_PRIVATE.0 as i32,
+    Y8 = ffi::AIMAGE_FORMATS::AIMAGE_FORMAT_Y8.0 as i32,
+    HEIC = ffi::AIMAGE_FORMATS::AIMAGE_FORMAT_HEIC.0 as i32,
+    DEPTH_JPEG = ffi::AIMAGE_FORMATS::AIMAGE_FORMAT_DEPTH_JPEG.0 as i32,
+
+    #[doc(hidden)]
+    #[num_enum(catch_all)]
+    __Unknown(i32),
+}
+
+pub type ImageListener = Box<dyn FnMut(&ImageReader) + Send>;
+
+#[cfg(feature = "api-level-26")]
+pub type BufferRemovedListener = Box<dyn FnMut(&ImageReader, &HardwareBuffer) + Send>;
+
+/// Result returned by:
+/// - [`ImageReader::acquire_next_image()`]`
+/// - [`ImageReader::acquire_next_image_async()`]`
+/// - [`ImageReader::acquire_latest_image()`]`
+/// - [`ImageReader::acquire_latest_image_async()`]`
+#[derive(Copy, Clone, Debug, PartialEq, Eq)]
+pub enum AcquireResult<T> {
+    /// Returned if there is no buffers currently available in the reader queue.
+    #[doc(alias = "AMEDIA_IMGREADER_NO_BUFFER_AVAILABLE")]
+    NoBufferAvailable,
+    /// Returned if the number of concurrently acquired images has reached the limit.
+    #[doc(alias = "AMEDIA_IMGREADER_MAX_IMAGES_ACQUIRED")]
+    MaxImagesAcquired,
+
+    /// Returned if an [`Image`] (optionally with fence) was successfully acquired.
+    Image(T),
+}
+
+impl<T> AcquireResult<T> {
+    fn map<U>(self, f: impl FnOnce(T) -> U) -> AcquireResult<U> {
+        match self {
+            AcquireResult::Image(img) => AcquireResult::Image(f(img)),
+            AcquireResult::NoBufferAvailable => AcquireResult::NoBufferAvailable,
+            AcquireResult::MaxImagesAcquired => AcquireResult::MaxImagesAcquired,
+        }
+    }
+}
+
+impl AcquireResult<Image> {
+    /// Inlined version of [`construct_never_null()`] with IMGREADER-specific result mapping.
+    fn construct_never_null(
+        with_ptr: impl FnOnce(*mut *mut ffi::AImage) -> ffi::media_status_t,
+    ) -> Result<Self> {
+        let mut result = MaybeUninit::uninit();
+        let status = with_ptr(result.as_mut_ptr());
+        match status {
+            ffi::media_status_t::AMEDIA_IMGREADER_NO_BUFFER_AVAILABLE => {
+                Ok(Self::NoBufferAvailable)
+            }
+            ffi::media_status_t::AMEDIA_IMGREADER_MAX_IMAGES_ACQUIRED => {
+                Ok(Self::MaxImagesAcquired)
+            }
+            status => MediaError::from_status(status).map(|()| {
+                let result = unsafe { result.assume_init() };
+                Self::Image(Image {
+                    inner: if cfg!(debug_assertions) {
+                        NonNull::new(result).expect("result should never be null")
+                    } else {
+                        unsafe { NonNull::new_unchecked(result) }
+                    },
+                })
+            }),
+        }
+    }
+}
+
+/// A native [`AImageReader *`]
+///
+/// [`AImageReader *`]: https://developer.android.com/ndk/reference/group/media#aimagereader
+pub struct ImageReader {
+    inner: NonNull<ffi::AImageReader>,
+    image_cb: Option<Box<ImageListener>>,
+    #[cfg(feature = "api-level-26")]
+    buffer_removed_cb: Option<Box<BufferRemovedListener>>,
+}
+
+impl Debug for ImageReader {
+    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
+        f.debug_struct("ImageReader")
+            .field("inner", &self.inner)
+            .field(
+                "image_cb",
+                match &self.image_cb {
+                    Some(_) => &"Some(_)",
+                    None => &"None",
+                },
+            )
+            .finish()
+    }
+}
+
+impl ImageReader {
+    fn from_ptr(inner: NonNull<ffi::AImageReader>) -> Self {
+        Self {
+            inner,
+            image_cb: None,
+            #[cfg(feature = "api-level-26")]
+            buffer_removed_cb: None,
+        }
+    }
+
+    fn as_ptr(&self) -> *mut ffi::AImageReader {
+        self.inner.as_ptr()
+    }
+
+    pub fn new(width: i32, height: i32, format: ImageFormat, max_images: i32) -> Result<Self> {
+        let inner = construct_never_null(|res| unsafe {
+            ffi::AImageReader_new(width, height, format.into(), max_images, res)
+        })?;
+
+        Ok(Self::from_ptr(inner))
+    }
+
+    #[cfg(feature = "api-level-26")]
+    pub fn new_with_usage(
+        width: i32,
+        height: i32,
+        format: ImageFormat,
+        usage: HardwareBufferUsage,
+        max_images: i32,
+    ) -> Result<Self> {
+        let inner = construct_never_null(|res| unsafe {
+            ffi::AImageReader_newWithUsage(
+                width,
+                height,
+                format.into(),
+                usage.bits(),
+                max_images,
+                res,
+            )
+        })?;
+
+        Ok(Self::from_ptr(inner))
+    }
+
+    #[doc(alias = "AImageReader_setImageListener")]
+    pub fn set_image_listener(&mut self, listener: ImageListener) -> Result<()> {
+        let mut boxed = Box::new(listener);
+        let ptr: *mut ImageListener = &mut *boxed;
+
+        unsafe extern "C" fn on_image_available(
+            context: *mut c_void,
+            reader: *mut ffi::AImageReader,
+        ) {
+            abort_on_panic(|| {
+                let reader = ImageReader::from_ptr(NonNull::new_unchecked(reader));
+                let listener: *mut ImageListener = context.cast();
+                (*listener)(&reader);
+                std::mem::forget(reader);
+            })
+        }
+
+        let mut listener = ffi::AImageReader_ImageListener {
+            context: ptr as _,
+            onImageAvailable: Some(on_image_available),
+        };
+        let status = unsafe { ffi::AImageReader_setImageListener(self.as_ptr(), &mut listener) };
+
+        // keep listener alive until Drop or new listener is assigned
+        self.image_cb = Some(boxed);
+
+        MediaError::from_status(status)
+    }
+
+    #[cfg(feature = "api-level-26")]
+    #[doc(alias = "AImageReader_setBufferRemovedListener")]
+    pub fn set_buffer_removed_listener(&mut self, listener: BufferRemovedListener) -> Result<()> {
+        let mut boxed = Box::new(listener);
+        let ptr: *mut BufferRemovedListener = &mut *boxed;
+
+        unsafe extern "C" fn on_buffer_removed(
+            context: *mut c_void,
+            reader: *mut ffi::AImageReader,
+            buffer: *mut ffi::AHardwareBuffer,
+        ) {
+            abort_on_panic(|| {
+                let reader = ImageReader::from_ptr(NonNull::new_unchecked(reader));
+                let buffer = HardwareBuffer::from_ptr(NonNull::new_unchecked(buffer));
+                let listener: *mut BufferRemovedListener = context.cast();
+                (*listener)(&reader, &buffer);
+                std::mem::forget(reader);
+            })
+        }
+
+        let mut listener = ffi::AImageReader_BufferRemovedListener {
+            context: ptr as _,
+            onBufferRemoved: Some(on_buffer_removed),
+        };
+        let status =
+            unsafe { ffi::AImageReader_setBufferRemovedListener(self.as_ptr(), &mut listener) };
+
+        // keep listener alive until Drop or new listener is assigned
+        self.buffer_removed_cb = Some(boxed);
+
+        MediaError::from_status(status)
+    }
+
+    /// Get a [`NativeWindow`] that can be used to produce [`Image`]s for this [`ImageReader`].
+    ///
+    /// <https://developer.android.com/ndk/reference/group/media#aimagereader_getwindow>
+    #[doc(alias = "AImageReader_getWindow")]
+    pub fn window(&self) -> Result<NativeWindow> {
+        unsafe {
+            let ptr = construct_never_null(|res| ffi::AImageReader_getWindow(self.as_ptr(), res))?;
+            Ok(NativeWindow::clone_from_ptr(ptr))
+        }
+    }
+
+    #[doc(alias = "AImageReader_getWidth")]
+    pub fn width(&self) -> Result<i32> {
+        construct(|res| unsafe { ffi::AImageReader_getWidth(self.as_ptr(), res) })
+    }
+
+    #[doc(alias = "AImageReader_getHeight")]
+    pub fn height(&self) -> Result<i32> {
+        construct(|res| unsafe { ffi::AImageReader_getHeight(self.as_ptr(), res) })
+    }
+
+    #[doc(alias = "AImageReader_getFormat")]
+    pub fn format(&self) -> Result<ImageFormat> {
+        let format = construct(|res| unsafe { ffi::AImageReader_getFormat(self.as_ptr(), res) })?;
+        Ok(format.into())
+    }
+
+    #[doc(alias = "AImageReader_getMaxImages")]
+    pub fn max_images(&self) -> Result<i32> {
+        construct(|res| unsafe { ffi::AImageReader_getMaxImages(self.as_ptr(), res) })
+    }
+
+    #[doc(alias = "AImageReader_acquireNextImage")]
+    pub fn acquire_next_image(&self) -> Result<AcquireResult<Image>> {
+        AcquireResult::construct_never_null(|res| unsafe {
+            ffi::AImageReader_acquireNextImage(self.as_ptr(), res)
+        })
+    }
+
+    /// Acquire the next [`Image`] from the image reader's queue asynchronously.
+    ///
+    /// # Safety
+    /// If the returned file descriptor is not [`None`], it must be awaited before attempting to
+    /// access the [`Image`] returned.
+    ///
+    /// <https://developer.android.com/ndk/reference/group/media#aimagereader_acquirenextimageasync>
+    #[cfg(feature = "api-level-26")]
+    #[doc(alias = "AImageReader_acquireNextImageAsync")]
+    pub unsafe fn acquire_next_image_async(
+        &self,
+    ) -> Result<AcquireResult<(Image, Option<OwnedFd>)>> {
+        let mut fence = MaybeUninit::uninit();
+        AcquireResult::construct_never_null(|res| {
+            ffi::AImageReader_acquireNextImageAsync(self.as_ptr(), res, fence.as_mut_ptr())
+        })
+        .map(|result| {
+            result.map(|image| match fence.assume_init() {
+                -1 => (image, None),
+                fence => (image, Some(unsafe { OwnedFd::from_raw_fd(fence) })),
+            })
+        })
+    }
+
+    #[doc(alias = "AImageReader_acquireLatestImage")]
+    pub fn acquire_latest_image(&self) -> Result<AcquireResult<Image>> {
+        AcquireResult::construct_never_null(|res| unsafe {
+            ffi::AImageReader_acquireLatestImage(self.as_ptr(), res)
+        })
+    }
+
+    /// Acquire the latest [`Image`] from the image reader's queue asynchronously, dropping older images.
+    ///
+    /// # Safety
+    /// If the returned file descriptor is not [`None`], it must be awaited before attempting to
+    /// access the [`Image`] returned.
+    ///
+    /// <https://developer.android.com/ndk/reference/group/media#aimagereader_acquirelatestimageasync>
+    #[cfg(feature = "api-level-26")]
+    #[doc(alias = "AImageReader_acquireLatestImageAsync")]
+    pub unsafe fn acquire_latest_image_async(
+        &self,
+    ) -> Result<AcquireResult<(Image, Option<OwnedFd>)>> {
+        let mut fence = MaybeUninit::uninit();
+        AcquireResult::construct_never_null(|res| {
+            ffi::AImageReader_acquireLatestImageAsync(self.as_ptr(), res, fence.as_mut_ptr())
+        })
+        .map(|result| {
+            result.map(|image| match fence.assume_init() {
+                -1 => (image, None),
+                fence => (image, Some(unsafe { OwnedFd::from_raw_fd(fence) })),
+            })
+        })
+    }
+}
+
+impl Drop for ImageReader {
+    #[doc(alias = "AImageReader_delete")]
+    fn drop(&mut self) {
+        unsafe { ffi::AImageReader_delete(self.as_ptr()) };
+    }
+}
+
+/// A native [`AImage *`]
+///
+/// [`AImage *`]: https://developer.android.com/ndk/reference/group/media#aimage
+#[derive(Debug)]
+#[doc(alias = "AImage")]
+pub struct Image {
+    inner: NonNull<ffi::AImage>,
+}
+
+#[doc(alias = "AImageCropRect")]
+pub type CropRect = ffi::AImageCropRect;
+
+impl Image {
+    fn as_ptr(&self) -> *mut ffi::AImage {
+        self.inner.as_ptr()
+    }
+
+    #[doc(alias = "AImage_getPlaneData")]
+    pub fn plane_data(&self, plane_idx: i32) -> Result<&[u8]> {
+        let mut result_ptr = MaybeUninit::uninit();
+        let mut result_len = MaybeUninit::uninit();
+        let status = unsafe {
+            ffi::AImage_getPlaneData(
+                self.as_ptr(),
+                plane_idx,
+                result_ptr.as_mut_ptr(),
+                result_len.as_mut_ptr(),
+            )
+        };
+
+        MediaError::from_status(status).map(|()| unsafe {
+            std::slice::from_raw_parts(result_ptr.assume_init(), result_len.assume_init() as _)
+        })
+    }
+
+    #[doc(alias = "AImage_getPlanePixelStride")]
+    pub fn plane_pixel_stride(&self, plane_idx: i32) -> Result<i32> {
+        construct(|res| unsafe { ffi::AImage_getPlanePixelStride(self.as_ptr(), plane_idx, res) })
+    }
+
+    #[doc(alias = "AImage_getPlaneRowStride")]
+    pub fn plane_row_stride(&self, plane_idx: i32) -> Result<i32> {
+        construct(|res| unsafe { ffi::AImage_getPlaneRowStride(self.as_ptr(), plane_idx, res) })
+    }
+
+    #[doc(alias = "AImage_getCropRect")]
+    pub fn crop_rect(&self) -> Result<CropRect> {
+        construct(|res| unsafe { ffi::AImage_getCropRect(self.as_ptr(), res) })
+    }
+
+    #[doc(alias = "AImage_getWidth")]
+    pub fn width(&self) -> Result<i32> {
+        construct(|res| unsafe { ffi::AImage_getWidth(self.as_ptr(), res) })
+    }
+
+    #[doc(alias = "AImage_getHeight")]
+    pub fn height(&self) -> Result<i32> {
+        construct(|res| unsafe { ffi::AImage_getHeight(self.as_ptr(), res) })
+    }
+
+    #[doc(alias = "AImage_getFormat")]
+    pub fn format(&self) -> Result<ImageFormat> {
+        let format = construct(|res| unsafe { ffi::AImage_getFormat(self.as_ptr(), res) })?;
+        Ok(format.into())
+    }
+
+    #[doc(alias = "AImage_getTimestamp")]
+    pub fn timestamp(&self) -> Result<i64> {
+        construct(|res| unsafe { ffi::AImage_getTimestamp(self.as_ptr(), res) })
+    }
+
+    #[doc(alias = "AImage_getNumberOfPlanes")]
+    pub fn number_of_planes(&self) -> Result<i32> {
+        construct(|res| unsafe { ffi::AImage_getNumberOfPlanes(self.as_ptr(), res) })
+    }
+
+    /// Get the hardware buffer handle of the input image intended for GPU and/or hardware access.
+    ///
+    /// Note that no reference on the returned [`HardwareBuffer`] handle is acquired automatically.
+    /// Once the [`Image`] or the parent [`ImageReader`] is deleted, the [`HardwareBuffer`] handle
+    /// from previous [`Image::hardware_buffer()`] becomes invalid.
+    ///
+    /// If the caller ever needs to hold on a reference to the [`HardwareBuffer`] handle after the
+    /// [`Image`] or the parent [`ImageReader`] is deleted, it must call
+    /// [`HardwareBuffer::acquire()`] to acquire an extra reference, and [`drop()`] it when
+    /// finished using it in order to properly deallocate the underlying memory managed by
+    /// [`HardwareBuffer`]. If the caller has acquired an extra reference on a [`HardwareBuffer`]
+    /// returned from this function, it must also register a listener using
+    /// [`ImageReader::set_buffer_removed_listener()`] to be notified when the buffer is no longer
+    /// used by [`ImageReader`].
+    #[cfg(feature = "api-level-26")]
+    #[doc(alias = "AImage_getHardwareBuffer")]
+    pub fn hardware_buffer(&self) -> Result<HardwareBuffer> {
+        unsafe {
+            let ptr =
+                construct_never_null(|res| ffi::AImage_getHardwareBuffer(self.as_ptr(), res))?;
+            Ok(HardwareBuffer::from_ptr(ptr))
+        }
+    }
+
+    #[cfg(feature = "api-level-26")]
+    #[doc(alias = "AImage_deleteAsync")]
+    pub fn delete_async(self, release_fence_fd: OwnedFd) {
+        unsafe { ffi::AImage_deleteAsync(self.as_ptr(), release_fence_fd.into_raw_fd()) };
+        std::mem::forget(self);
+    }
+}
+
+impl Drop for Image {
+    #[doc(alias = "AImage_delete")]
+    fn drop(&mut self) {
+        unsafe { ffi::AImage_delete(self.as_ptr()) };
+    }
+}

clients/android/native/vendor/ndk/src/media/media_codec.rs

@@ -0,0 +1,634 @@
+//! Bindings for [`AMediaCodec`]
+//!
+//! [`AMediaCodec`]: https://developer.android.com/ndk/reference/group/media#amediacodec
+
+#[deprecated = "MediaFormat should be referenced directly from the media_format module"]
+pub use super::media_format::MediaFormat;
+use crate::media_error::{MediaError, Result};
+use crate::native_window::NativeWindow;
+use crate::utils::abort_on_panic;
+use std::{
+    ffi::{c_char, c_void, CStr, CString},
+    fmt,
+    mem::MaybeUninit,
+    pin::Pin,
+    ptr::{self, NonNull},
+    slice,
+    time::Duration,
+};
+
+#[derive(Debug, PartialEq, Eq)]
+pub enum MediaCodecDirection {
+    Decoder,
+    Encoder,
+}
+
+/// A native [`AMediaCodec *`]
+///
+/// [`AMediaCodec *`]: https://developer.android.com/ndk/reference/group/media#amediacodec
+#[derive(Debug)]
+pub struct MediaCodec {
+    inner: NonNull<ffi::AMediaCodec>,
+    async_notify_callback: Option<Pin<Box<AsyncNotifyCallback>>>,
+}
+
+pub struct AsyncNotifyCallback {
+    /// Called when an input buffer becomes available.
+    ///
+    /// The specified index is the index of the available input buffer.
+    pub on_input_available: Option<InputAvailableCallback>,
+
+    /// Called when an output buffer becomes available.
+    ///
+    /// The specified index is the index of the available output buffer. The specified
+    /// [`BufferInfo`] contains information regarding the available output buffer.
+    pub on_output_available: Option<OutputAvailableCallback>,
+
+    /// Called when the output format has changed.
+    ///
+    /// The specified format contains the new output format.
+    pub on_format_changed: Option<FormatChangedCallback>,
+
+    /// Called when the [`MediaCodec`] encountered an error.
+    ///
+    /// The specified [`ActionCode`] indicates the possible actions that client can take, and it can
+    /// be checked by calling [`ActionCode::is_recoverable`] or [`ActionCode::is_transient`]. If
+    /// both [`ActionCode::is_recoverable`] and [`ActionCode::is_transient`] return [`false`], then
+    /// the codec error is fatal and the codec must be deleted. The specified detail string may
+    /// contain more detailed messages about this error.
+    pub on_error: Option<ErrorCallback>,
+}
+
+impl fmt::Debug for AsyncNotifyCallback {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.debug_struct("AsyncNotifyCallback")
+            .field(
+                "on_input_available",
+                match &self.on_input_available {
+                    Some(_) => &"Some(_)",
+                    None => &"None",
+                },
+            )
+            .field(
+                "on_output_available",
+                match &self.on_output_available {
+                    Some(_) => &"Some(_)",
+                    None => &"None",
+                },
+            )
+            .field(
+                "on_format_changed",
+                match &self.on_format_changed {
+                    Some(_) => &"Some(_)",
+                    None => &"None",
+                },
+            )
+            .field(
+                "on_error",
+                match &self.on_error {
+                    Some(_) => &"Some(_)",
+                    None => &"None",
+                },
+            )
+            .finish()
+    }
+}
+
+pub type InputAvailableCallback = Box<dyn FnMut(usize) + Send>;
+pub type OutputAvailableCallback = Box<dyn FnMut(usize, &BufferInfo) + Send>;
+pub type FormatChangedCallback = Box<dyn FnMut(&MediaFormat) + Send>;
+pub type ErrorCallback = Box<dyn FnMut(MediaError, ActionCode, &CStr) + Send>;
+
+impl MediaCodec {
+    /// [punktfunk vendored patch — the ONLY change to this crate] Public so callers can bind
+    /// `AMediaCodec_*` entry points the wrapper doesn't expose yet (here:
+    /// `AMediaCodec_setOnFrameRenderedCallback` for the HUD's display stage). The pointer is valid
+    /// for `&self`'s lifetime; callers must not delete or re-configure the codec through it.
+    pub fn as_ptr(&self) -> *mut ffi::AMediaCodec {
+        self.inner.as_ptr()
+    }
+
+    pub fn from_codec_name(name: &str) -> Option<Self> {
+        let c_string = CString::new(name).unwrap();
+        Some(Self {
+            inner: NonNull::new(unsafe { ffi::AMediaCodec_createCodecByName(c_string.as_ptr()) })?,
+            async_notify_callback: None,
+        })
+    }
+
+    pub fn from_decoder_type(mime_type: &str) -> Option<Self> {
+        let c_string = CString::new(mime_type).unwrap();
+        Some(Self {
+            inner: NonNull::new(unsafe {
+                ffi::AMediaCodec_createDecoderByType(c_string.as_ptr())
+            })?,
+            async_notify_callback: None,
+        })
+    }
+
+    pub fn from_encoder_type(mime_type: &str) -> Option<Self> {
+        let c_string = CString::new(mime_type).unwrap();
+        Some(Self {
+            inner: NonNull::new(unsafe {
+                ffi::AMediaCodec_createEncoderByType(c_string.as_ptr())
+            })?,
+            async_notify_callback: None,
+        })
+    }
+
+    /// Set an asynchronous callback for actionable [`MediaCodec`] events.
+    ///
+    /// When asynchronous callback is enabled, it is an error for the client to call
+    /// [`MediaCodec::dequeue_input_buffer()`] or [`MediaCodec::dequeue_output_buffer()`].
+    ///
+    /// [`MediaCodec::flush()`] behaves differently in asynchronous mode. After calling
+    /// [`MediaCodec::flush()`], the client must call [`MediaCodec::start()`] to "resume" receiving
+    /// input buffers. Even if the client does not receive
+    /// [`AsyncNotifyCallback::on_input_available`] callbacks from video encoders configured with an
+    /// input surface, the client still needs to call [`MediaCodec::start()`] to resume the input
+    /// surface to send buffers to the encoders.
+    ///
+    /// When called with [`None`] callback, this method unregisters any previously set callback.
+    ///
+    /// Refer to the definition of [`AsyncNotifyCallback`] on how each callback function is called
+    /// and what are specified.
+    ///
+    /// Once the callback is unregistered or the codec is reset / released, the previously
+    /// registered callback will not be called.
+    ///
+    /// All callbacks are fired on one NDK internal thread.
+    /// [`MediaCodec::set_async_notify_callback()`] should not be called on the callback thread. No
+    /// heavy duty task should be performed on callback thread.
+    #[cfg(feature = "api-level-28")]
+    pub fn set_async_notify_callback(
+        &mut self,
+        callback: Option<AsyncNotifyCallback>,
+    ) -> Result<()> {
+        unsafe extern "C" fn ffi_on_input_available(
+            _codec: *mut ffi::AMediaCodec,
+            user_data: *mut c_void,
+            index: i32,
+        ) {
+            abort_on_panic(|| {
+                let callback = &mut *(user_data as *mut AsyncNotifyCallback);
+                if let Some(f) = callback.on_input_available.as_mut() {
+                    f(index as usize);
+                }
+            })
+        }
+
+        unsafe extern "C" fn ffi_on_output_available(
+            _codec: *mut ffi::AMediaCodec,
+            user_data: *mut c_void,
+            index: i32,
+            buffer_info: *mut ffi::AMediaCodecBufferInfo,
+        ) {
+            abort_on_panic(|| {
+                let callback = &mut *(user_data as *mut AsyncNotifyCallback);
+                if let Some(f) = callback.on_output_available.as_mut() {
+                    let buffer_info = BufferInfo {
+                        inner: *buffer_info,
+                    };
+                    f(index as usize, &buffer_info);
+                }
+            })
+        }
+
+        unsafe extern "C" fn ffi_on_format_changed(
+            _codec: *mut ffi::AMediaCodec,
+            user_data: *mut c_void,
+            format: *mut ffi::AMediaFormat,
+        ) {
+            abort_on_panic(|| {
+                // Ownership of the format is not documented, but the implementation allocates a new instance and does
+                // not free it, so assume it is ok for us to do so
+                // https://cs.android.com/android/platform/superproject/main/+/refs/heads/main:frameworks/av/media/ndk/NdkMediaCodec.cpp;l=248-254;drc=5e15c3e22f3fa32d64e57302201123ce41589adf
+                let format = MediaFormat::from_ptr(NonNull::new_unchecked(format));
+
+                let callback = &mut *(user_data as *mut AsyncNotifyCallback);
+                if let Some(f) = callback.on_format_changed.as_mut() {
+                    f(&format);
+                }
+            })
+        }
+
+        unsafe extern "C" fn ffi_on_error(
+            _codec: *mut ffi::AMediaCodec,
+            user_data: *mut c_void,
+            error: ffi::media_status_t,
+            action_code: i32,
+            detail: *const c_char,
+        ) {
+            abort_on_panic(|| {
+                let callback = &mut *(user_data as *mut AsyncNotifyCallback);
+                if let Some(f) = callback.on_error.as_mut() {
+                    f(
+                        MediaError::from_status(error).unwrap_err(),
+                        ActionCode(action_code),
+                        CStr::from_ptr(detail),
+                    );
+                }
+            })
+        }
+
+        let (callback, ffi_callback, user_data) = if let Some(callback) = callback {
+            // On Android 12 and earlier, due to faulty null checks, if a callback is not set, but at least one other
+            // callback *is* set, then it will segfault in when trying to invoke the unset callback. See for example:
+            // https://cs.android.com/android/platform/superproject/+/android-12.0.0_r34:frameworks/av/media/ndk/NdkMediaCodec.cpp;l=161-162;drc=ef058464777739e2d9ffad5f00d0e57b186d9a13
+            // To work around this we just enable all callbacks and do nothing if the corresponding callback is not set
+            // in AsyncNotifyCallback
+            let ffi_callback = ffi::AMediaCodecOnAsyncNotifyCallback {
+                onAsyncInputAvailable: Some(ffi_on_input_available),
+                onAsyncOutputAvailable: Some(ffi_on_output_available),
+                onAsyncFormatChanged: Some(ffi_on_format_changed),
+                onAsyncError: Some(ffi_on_error),
+            };
+
+            let mut boxed = Box::pin(callback);
+            let ptr: *mut AsyncNotifyCallback = &mut *boxed;
+
+            (Some(boxed), ffi_callback, ptr as *mut c_void)
+        } else {
+            let ffi_callback = ffi::AMediaCodecOnAsyncNotifyCallback {
+                onAsyncInputAvailable: None,
+                onAsyncOutputAvailable: None,
+                onAsyncFormatChanged: None,
+                onAsyncError: None,
+            };
+
+            (None, ffi_callback, ptr::null_mut())
+        };
+
+        let status = unsafe {
+            ffi::AMediaCodec_setAsyncNotifyCallback(self.as_ptr(), ffi_callback, user_data)
+        };
+        let result = MediaError::from_status(status);
+
+        // This behavior is not documented, but the implementation always clears the callback on failure, so we must
+        // clear any callback that may have been previously registered
+        // https://cs.android.com/android/platform/superproject/main/+/main:frameworks/av/media/ndk/NdkMediaCodec.cpp;l=581-584;drc=8c4e619c7461ac1a8c20c55364643662e9185e4d
+        if result.is_ok() {
+            self.async_notify_callback = callback;
+        } else {
+            self.async_notify_callback = None;
+        }
+
+        result
+    }
+
+    pub fn configure(
+        &self,
+        format: &MediaFormat,
+        surface: Option<&NativeWindow>,
+        direction: MediaCodecDirection,
+    ) -> Result<()> {
+        let status = unsafe {
+            ffi::AMediaCodec_configure(
+                self.as_ptr(),
+                format.as_ptr(),
+                surface.map_or(ptr::null_mut(), |s| s.ptr().as_ptr()),
+                ptr::null_mut(),
+                if direction == MediaCodecDirection::Encoder {
+                    ffi::AMEDIACODEC_CONFIGURE_FLAG_ENCODE as u32
+                } else {
+                    0
+                },
+            )
+        };
+        MediaError::from_status(status)
+    }
+
+    #[cfg(feature = "api-level-26")]
+    pub fn create_input_surface(&self) -> Result<NativeWindow> {
+        use crate::media_error::construct_never_null;
+        unsafe {
+            let ptr = construct_never_null(|res| {
+                ffi::AMediaCodec_createInputSurface(self.as_ptr(), res)
+            })?;
+            Ok(NativeWindow::from_ptr(ptr))
+        }
+    }
+
+    #[cfg(feature = "api-level-26")]
+    pub fn create_persistent_input_surface() -> Result<NativeWindow> {
+        use crate::media_error::construct_never_null;
+        unsafe {
+            let ptr =
+                construct_never_null(|res| ffi::AMediaCodec_createPersistentInputSurface(res))?;
+            Ok(NativeWindow::from_ptr(ptr))
+        }
+    }
+
+    pub fn dequeue_input_buffer(&self, timeout: Duration) -> Result<DequeuedInputBufferResult<'_>> {
+        let result = unsafe {
+            ffi::AMediaCodec_dequeueInputBuffer(
+                self.as_ptr(),
+                timeout
+                    .as_micros()
+                    .try_into()
+                    .expect("Supplied timeout is too large"),
+            )
+        };
+
+        if result == ffi::AMEDIACODEC_INFO_TRY_AGAIN_LATER as isize {
+            Ok(DequeuedInputBufferResult::TryAgainLater)
+        } else {
+            let index = MediaError::from_status_if_negative(result)? as usize;
+            Ok(DequeuedInputBufferResult::Buffer(InputBuffer {
+                codec: self,
+                index,
+            }))
+        }
+    }
+
+    pub fn dequeue_output_buffer(
+        &self,
+        timeout: Duration,
+    ) -> Result<DequeuedOutputBufferInfoResult<'_>> {
+        let mut info = MaybeUninit::uninit();
+
+        let result = unsafe {
+            ffi::AMediaCodec_dequeueOutputBuffer(
+                self.as_ptr(),
+                info.as_mut_ptr(),
+                timeout
+                    .as_micros()
+                    .try_into()
+                    .expect("Supplied timeout is too large"),
+            )
+        };
+
+        if result == ffi::AMEDIACODEC_INFO_TRY_AGAIN_LATER as isize {
+            Ok(DequeuedOutputBufferInfoResult::TryAgainLater)
+        } else if result == ffi::AMEDIACODEC_INFO_OUTPUT_FORMAT_CHANGED as isize {
+            Ok(DequeuedOutputBufferInfoResult::OutputFormatChanged)
+        } else if result == ffi::AMEDIACODEC_INFO_OUTPUT_BUFFERS_CHANGED as isize {
+            Ok(DequeuedOutputBufferInfoResult::OutputBuffersChanged)
+        } else {
+            let index = MediaError::from_status_if_negative(result)? as usize;
+            Ok(DequeuedOutputBufferInfoResult::Buffer(OutputBuffer {
+                codec: self,
+                index,
+                info: BufferInfo {
+                    inner: unsafe { info.assume_init() },
+                },
+            }))
+        }
+    }
+
+    pub fn flush(&self) -> Result<()> {
+        let status = unsafe { ffi::AMediaCodec_flush(self.as_ptr()) };
+        MediaError::from_status(status)
+    }
+
+    pub fn input_buffer(&self, index: usize) -> Option<&mut [MaybeUninit<u8>]> {
+        unsafe {
+            let mut out_size = 0;
+            let buffer_ptr = ffi::AMediaCodec_getInputBuffer(self.as_ptr(), index, &mut out_size);
+            if buffer_ptr.is_null() {
+                return None;
+            }
+            Some(slice::from_raw_parts_mut(buffer_ptr.cast(), out_size))
+        }
+    }
+
+    pub fn output_buffer(&self, index: usize) -> Option<&[u8]> {
+        unsafe {
+            let mut out_size = 0;
+            let buffer_ptr = ffi::AMediaCodec_getOutputBuffer(self.as_ptr(), index, &mut out_size);
+            if buffer_ptr.is_null() {
+                return None;
+            }
+            Some(slice::from_raw_parts(buffer_ptr, out_size))
+        }
+    }
+
+    #[cfg(feature = "api-level-28")]
+    pub fn input_format(&self) -> MediaFormat {
+        let inner = NonNull::new(unsafe { ffi::AMediaCodec_getInputFormat(self.as_ptr()) })
+            .expect("AMediaCodec_getInputFormat returned NULL");
+        unsafe { MediaFormat::from_ptr(inner) }
+    }
+
+    pub fn output_format(&self) -> MediaFormat {
+        let inner = NonNull::new(unsafe { ffi::AMediaCodec_getOutputFormat(self.as_ptr()) })
+            .expect("AMediaCodec_getOutputFormat returned NULL");
+        unsafe { MediaFormat::from_ptr(inner) }
+    }
+
+    #[cfg(feature = "api-level-28")]
+    pub fn name(&self) -> Result<String> {
+        use crate::media_error::construct;
+        unsafe {
+            let name_ptr = construct(|name| ffi::AMediaCodec_getName(self.as_ptr(), name))?;
+            let name = CStr::from_ptr(name_ptr).to_str().unwrap().to_owned();
+            ffi::AMediaCodec_releaseName(self.as_ptr(), name_ptr);
+
+            Ok(name)
+        }
+    }
+
+    pub fn queue_input_buffer(
+        &self,
+        buffer: InputBuffer<'_>,
+        offset: usize,
+        size: usize,
+        time: u64,
+        flags: u32,
+    ) -> Result<()> {
+        debug_assert!(ptr::eq(self, buffer.codec));
+        self.queue_input_buffer_by_index(buffer.index, offset, size, time, flags)
+    }
+
+    pub fn queue_input_buffer_by_index(
+        &self,
+        buffer_index: usize,
+        offset: usize,
+        size: usize,
+        time: u64,
+        flags: u32,
+    ) -> Result<()> {
+        let status = unsafe {
+            ffi::AMediaCodec_queueInputBuffer(
+                self.as_ptr(),
+                buffer_index,
+                offset as ffi::off_t,
+                size,
+                time,
+                flags,
+            )
+        };
+        MediaError::from_status(status)
+    }
+
+    pub fn release_output_buffer(&self, buffer: OutputBuffer<'_>, render: bool) -> Result<()> {
+        debug_assert!(ptr::eq(self, buffer.codec));
+        self.release_output_buffer_by_index(buffer.index, render)
+    }
+
+    pub fn release_output_buffer_by_index(&self, buffer_index: usize, render: bool) -> Result<()> {
+        let status =
+            unsafe { ffi::AMediaCodec_releaseOutputBuffer(self.as_ptr(), buffer_index, render) };
+        MediaError::from_status(status)
+    }
+
+    pub fn release_output_buffer_at_time(
+        &self,
+        buffer: OutputBuffer<'_>,
+        timestamp_ns: i64,
+    ) -> Result<()> {
+        debug_assert!(ptr::eq(self, buffer.codec));
+        self.release_output_buffer_at_time_by_index(buffer.index, timestamp_ns)
+    }
+
+    pub fn release_output_buffer_at_time_by_index(
+        &self,
+        buffer_index: usize,
+        timestamp_ns: i64,
+    ) -> Result<()> {
+        let status = unsafe {
+            ffi::AMediaCodec_releaseOutputBufferAtTime(self.as_ptr(), buffer_index, timestamp_ns)
+        };
+        MediaError::from_status(status)
+    }
+
+    #[cfg(feature = "api-level-26")]
+    pub fn set_input_surface(&self, surface: &NativeWindow) -> Result<()> {
+        let status =
+            unsafe { ffi::AMediaCodec_setInputSurface(self.as_ptr(), surface.ptr().as_ptr()) };
+        MediaError::from_status(status)
+    }
+
+    pub fn set_output_surface(&self, surface: &NativeWindow) -> Result<()> {
+        let status =
+            unsafe { ffi::AMediaCodec_setOutputSurface(self.as_ptr(), surface.ptr().as_ptr()) };
+        MediaError::from_status(status)
+    }
+
+    #[cfg(feature = "api-level-26")]
+    pub fn set_parameters(&self, params: MediaFormat) -> Result<()> {
+        let status = unsafe { ffi::AMediaCodec_setParameters(self.as_ptr(), params.as_ptr()) };
+        MediaError::from_status(status)
+    }
+
+    #[cfg(feature = "api-level-26")]
+    pub fn set_signal_end_of_input_stream(&self) -> Result<()> {
+        let status = unsafe { ffi::AMediaCodec_signalEndOfInputStream(self.as_ptr()) };
+        MediaError::from_status(status)
+    }
+
+    pub fn start(&self) -> Result<()> {
+        let status = unsafe { ffi::AMediaCodec_start(self.as_ptr()) };
+        MediaError::from_status(status)
+    }
+
+    pub fn stop(&self) -> Result<()> {
+        let status = unsafe { ffi::AMediaCodec_stop(self.as_ptr()) };
+        MediaError::from_status(status)
+    }
+}
+
+impl Drop for MediaCodec {
+    fn drop(&mut self) {
+        let status = unsafe { ffi::AMediaCodec_delete(self.as_ptr()) };
+        MediaError::from_status(status).unwrap();
+    }
+}
+
+#[derive(Debug)]
+pub struct InputBuffer<'a> {
+    codec: &'a MediaCodec,
+    index: usize,
+}
+
+impl InputBuffer<'_> {
+    pub fn buffer_mut(&mut self) -> &mut [MaybeUninit<u8>] {
+        self.codec.input_buffer(self.index).unwrap_or_else(|| {
+            panic!(
+                "AMediaCodec_getInputBuffer returned NULL for index {}",
+                self.index
+            )
+        })
+    }
+}
+
+#[derive(Debug)]
+pub enum DequeuedInputBufferResult<'a> {
+    Buffer(InputBuffer<'a>),
+    TryAgainLater,
+}
+
+#[derive(Debug)]
+pub struct OutputBuffer<'a> {
+    codec: &'a MediaCodec,
+    index: usize,
+    info: BufferInfo,
+}
+
+impl OutputBuffer<'_> {
+    pub fn buffer(&self) -> &[u8] {
+        self.codec.output_buffer(self.index).unwrap_or_else(|| {
+            panic!(
+                "AMediaCodec_getOutputBuffer returned NULL for index {}",
+                self.index
+            )
+        })
+    }
+
+    #[cfg(feature = "api-level-28")]
+    pub fn format(&self) -> MediaFormat {
+        let inner = NonNull::new(unsafe {
+            ffi::AMediaCodec_getBufferFormat(self.codec.as_ptr(), self.index)
+        })
+        .expect("AMediaCodec_getBufferFormat returned NULL");
+        unsafe { MediaFormat::from_ptr(inner) }
+    }
+
+    pub fn info(&self) -> &BufferInfo {
+        &self.info
+    }
+}
+
+#[derive(Debug)]
+pub enum DequeuedOutputBufferInfoResult<'a> {
+    Buffer(OutputBuffer<'a>),
+    TryAgainLater,
+    OutputFormatChanged,
+    OutputBuffersChanged,
+}
+
+#[derive(Copy, Clone, Debug)]
+pub struct BufferInfo {
+    inner: ffi::AMediaCodecBufferInfo,
+}
+
+impl BufferInfo {
+    pub fn offset(&self) -> i32 {
+        self.inner.offset
+    }
+
+    pub fn size(&self) -> i32 {
+        self.inner.size
+    }
+
+    pub fn presentation_time_us(&self) -> i64 {
+        self.inner.presentationTimeUs
+    }
+
+    pub fn flags(&self) -> u32 {
+        self.inner.flags
+    }
+}
+
+#[derive(Copy, Clone, Debug)]
+pub struct ActionCode(pub i32);
+
+impl ActionCode {
+    pub fn is_recoverable(self) -> bool {
+        unsafe { ffi::AMediaCodecActionCode_isRecoverable(self.0) }
+    }
+
+    pub fn is_transient(self) -> bool {
+        unsafe { ffi::AMediaCodecActionCode_isTransient(self.0) }
+    }
+}

clients/android/native/vendor/ndk/src/media/media_format.rs

@@ -0,0 +1,268 @@
+//! Bindings for [`AMediaFormat`]
+//!
+//! [`AMediaFormat`]: https://developer.android.com/ndk/reference/group/media#amediaformat
+
+use std::{
+    ffi::{CStr, CString},
+    fmt,
+    ptr::{self, NonNull},
+    slice,
+};
+
+use crate::media_error::MediaError;
+// `Result` is only referenced by the api-level-29 methods below; an ungated import warns
+// (unused_imports) on every default-feature build.
+#[cfg(feature = "api-level-29")]
+use crate::media_error::Result;
+
+/// A native [`AMediaFormat *`]
+///
+/// [`AMediaFormat *`]: https://developer.android.com/ndk/reference/group/media#amediaformat
+#[doc(alias = "AMediaFormat")]
+pub struct MediaFormat {
+    inner: NonNull<ffi::AMediaFormat>,
+}
+
+impl fmt::Display for MediaFormat {
+    /// Human readable representation of the format.
+    #[doc(alias = "AMediaFormat_toString")]
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        let c_str = unsafe { CStr::from_ptr(ffi::AMediaFormat_toString(self.as_ptr())) };
+        f.write_str(c_str.to_str().unwrap())
+    }
+}
+
+impl fmt::Debug for MediaFormat {
+    #[doc(alias = "AMediaFormat_toString")]
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(f, "MediaFormat({:?}: {})", self.inner, self)
+    }
+}
+
+impl Default for MediaFormat {
+    #[doc(alias = "AMediaFormat_new")]
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl MediaFormat {
+    /// Assumes ownership of `ptr`
+    ///
+    /// # Safety
+    /// `ptr` must be a valid pointer to an Android [`ffi::AMediaFormat`].
+    pub unsafe fn from_ptr(ptr: NonNull<ffi::AMediaFormat>) -> Self {
+        Self { inner: ptr }
+    }
+
+    pub fn as_ptr(&self) -> *mut ffi::AMediaFormat {
+        self.inner.as_ptr()
+    }
+
+    #[doc(alias = "AMediaFormat_new")]
+    pub fn new() -> Self {
+        Self {
+            inner: NonNull::new(unsafe { ffi::AMediaFormat_new() }).unwrap(),
+        }
+    }
+
+    #[doc(alias = "AMediaFormat_getInt32")]
+    pub fn i32(&self, key: &str) -> Option<i32> {
+        let name = CString::new(key).unwrap();
+        let mut out = 0;
+        if unsafe { ffi::AMediaFormat_getInt32(self.as_ptr(), name.as_ptr(), &mut out) } {
+            Some(out)
+        } else {
+            None
+        }
+    }
+
+    #[doc(alias = "AMediaFormat_getInt64")]
+    pub fn i64(&self, key: &str) -> Option<i64> {
+        let name = CString::new(key).unwrap();
+        let mut out = 0;
+        if unsafe { ffi::AMediaFormat_getInt64(self.as_ptr(), name.as_ptr(), &mut out) } {
+            Some(out)
+        } else {
+            None
+        }
+    }
+
+    #[doc(alias = "AMediaFormat_getFloat")]
+    pub fn f32(&self, key: &str) -> Option<f32> {
+        let name = CString::new(key).unwrap();
+        let mut out = 0.0;
+        if unsafe { ffi::AMediaFormat_getFloat(self.as_ptr(), name.as_ptr(), &mut out) } {
+            Some(out)
+        } else {
+            None
+        }
+    }
+
+    #[doc(alias = "AMediaFormat_getSize")]
+    pub fn usize(&self, key: &str) -> Option<usize> {
+        let name = CString::new(key).unwrap();
+        let mut out = 0;
+        if unsafe { ffi::AMediaFormat_getSize(self.as_ptr(), name.as_ptr(), &mut out) } {
+            Some(out)
+        } else {
+            None
+        }
+    }
+
+    #[doc(alias = "AMediaFormat_getBuffer")]
+    pub fn buffer(&self, key: &str) -> Option<&[u8]> {
+        let name = CString::new(key).unwrap();
+        let mut out_buffer = ptr::null_mut();
+        let mut out_size = 0;
+        unsafe {
+            ffi::AMediaFormat_getBuffer(
+                self.as_ptr(),
+                name.as_ptr(),
+                &mut out_buffer,
+                &mut out_size,
+            )
+        }
+        .then(|| unsafe { slice::from_raw_parts(out_buffer.cast(), out_size) })
+    }
+
+    /// The returned `&str` borrow is only valid until the next call to [`MediaFormat::str()`] for
+    /// the same key.
+    #[doc(alias = "AMediaFormat_getString")]
+    pub fn str(&mut self, key: &str) -> Option<&str> {
+        let name = CString::new(key).unwrap();
+        let mut out = ptr::null();
+        unsafe { ffi::AMediaFormat_getString(self.as_ptr(), name.as_ptr(), &mut out) }
+            .then(|| unsafe { CStr::from_ptr(out) }.to_str().unwrap())
+    }
+
+    #[doc(alias = "AMediaFormat_setInt32")]
+    pub fn set_i32(&mut self, key: &str, value: i32) {
+        let name = CString::new(key).unwrap();
+        unsafe { ffi::AMediaFormat_setInt32(self.as_ptr(), name.as_ptr(), value) }
+    }
+
+    #[doc(alias = "AMediaFormat_setInt64")]
+    pub fn set_i64(&mut self, key: &str, value: i64) {
+        let name = CString::new(key).unwrap();
+        unsafe { ffi::AMediaFormat_setInt64(self.as_ptr(), name.as_ptr(), value) }
+    }
+
+    #[doc(alias = "AMediaFormat_setFloat")]
+    pub fn set_f32(&mut self, key: &str, value: f32) {
+        let name = CString::new(key).unwrap();
+        unsafe { ffi::AMediaFormat_setFloat(self.as_ptr(), name.as_ptr(), value) }
+    }
+
+    #[doc(alias = "AMediaFormat_setString")]
+    pub fn set_str(&mut self, key: &str, value: &str) {
+        let name = CString::new(key).unwrap();
+        let c_string = CString::new(value).unwrap();
+        unsafe { ffi::AMediaFormat_setString(self.as_ptr(), name.as_ptr(), c_string.as_ptr()) }
+    }
+
+    #[doc(alias = "AMediaFormat_setBuffer")]
+    pub fn set_buffer(&mut self, key: &str, value: &[u8]) {
+        let name = CString::new(key).unwrap();
+        unsafe {
+            ffi::AMediaFormat_setBuffer(
+                self.as_ptr(),
+                name.as_ptr(),
+                value.as_ptr().cast(),
+                value.len(),
+            )
+        }
+    }
+
+    #[cfg(feature = "api-level-28")]
+    #[doc(alias = "AMediaFormat_getDouble")]
+    pub fn f64(&self, key: &str) -> Option<f64> {
+        let name = CString::new(key).unwrap();
+        let mut out = 0.0;
+        if unsafe { ffi::AMediaFormat_getDouble(self.as_ptr(), name.as_ptr(), &mut out) } {
+            Some(out)
+        } else {
+            None
+        }
+    }
+
+    /// Returns (left, top, right, bottom)
+    #[cfg(feature = "api-level-28")]
+    #[doc(alias = "AMediaFormat_getRect")]
+    pub fn rect(&self, key: &str) -> Option<(i32, i32, i32, i32)> {
+        let name = CString::new(key).unwrap();
+        let mut left = 0;
+        let mut top = 0;
+        let mut right = 0;
+        let mut bottom = 0;
+        if unsafe {
+            ffi::AMediaFormat_getRect(
+                self.as_ptr(),
+                name.as_ptr(),
+                &mut left,
+                &mut top,
+                &mut right,
+                &mut bottom,
+            )
+        } {
+            Some((left, top, right, bottom))
+        } else {
+            None
+        }
+    }
+
+    #[cfg(feature = "api-level-28")]
+    #[doc(alias = "AMediaFormat_setDouble")]
+    pub fn set_f64(&mut self, key: &str, value: f64) {
+        let name = CString::new(key).unwrap();
+        unsafe { ffi::AMediaFormat_setDouble(self.as_ptr(), name.as_ptr(), value) }
+    }
+
+    #[cfg(feature = "api-level-28")]
+    #[doc(alias = "AMediaFormat_setRect")]
+    pub fn set_rect(&mut self, key: &str, left: i32, top: i32, right: i32, bottom: i32) {
+        let name = CString::new(key).unwrap();
+        unsafe { ffi::AMediaFormat_setRect(self.as_ptr(), name.as_ptr(), left, top, right, bottom) }
+    }
+
+    #[cfg(feature = "api-level-28")]
+    #[doc(alias = "AMediaFormat_setSize")]
+    pub fn set_usize(&mut self, key: &str, value: usize) {
+        let name = CString::new(key).unwrap();
+        unsafe { ffi::AMediaFormat_setSize(self.as_ptr(), name.as_ptr(), value) }
+    }
+
+    /// Copy one [`MediaFormat`] to another.
+    #[cfg(feature = "api-level-29")]
+    #[doc(alias = "AMediaFormat_copy")]
+    pub fn copy(&self, to: &mut Self) -> Result<()> {
+        let status = unsafe { ffi::AMediaFormat_copy(to.as_ptr(), self.as_ptr()) };
+        MediaError::from_status(status)
+    }
+
+    /// Clones this [`MediaFormat`] into a [`MediaFormat::new()`] object using
+    /// [`MediaFormat::copy()`].
+    #[cfg(feature = "api-level-29")]
+    #[doc(alias = "AMediaFormat_new")]
+    #[doc(alias = "AMediaFormat_copy")]
+    pub fn try_clone(&self) -> Result<Self> {
+        let mut copy = Self::new();
+        self.copy(&mut copy)?;
+        Ok(copy)
+    }
+
+    /// Remove all key/value pairs from this [`MediaFormat`].
+    #[cfg(feature = "api-level-29")]
+    #[doc(alias = "AMediaFormat_clear")]
+    pub fn clear(&mut self) {
+        unsafe { ffi::AMediaFormat_clear(self.as_ptr()) }
+    }
+}
+
+impl Drop for MediaFormat {
+    #[doc(alias = "AMediaFormat_delete")]
+    fn drop(&mut self) {
+        let status = unsafe { ffi::AMediaFormat_delete(self.as_ptr()) };
+        MediaError::from_status(status).unwrap()
+    }
+}

clients/android/native/vendor/ndk/src/media/mod.rs

@@ -0,0 +1,8 @@
+//! Bindings for the NDK media classes.
+//!
+//! See also [the NDK docs](https://developer.android.com/ndk/reference/group/media)
+#![cfg(feature = "media")]
+
+pub mod image_reader;
+pub mod media_codec;
+pub mod media_format;

clients/android/native/vendor/ndk/src/media_error.rs

@@ -0,0 +1,140 @@
+//! Bindings for NDK media status codes.
+//!
+//! Also used outside of `libmediandk.so` in `libamidi.so` for example.
+#![cfg(feature = "media")]
+// The cfg(feature) bounds for some pub(crate) fn uses are non-trivial and will become even more
+// complex going forward.  Allow them to be unused when compiling with certain feature combinations.
+#![allow(dead_code)]
+
+use std::{fmt, mem::MaybeUninit, ptr::NonNull};
+
+use num_enum::{FromPrimitive, IntoPrimitive};
+
+pub type Result<T, E = MediaError> = std::result::Result<T, E>;
+
+/// Media Status codes for [`media_status_t`](https://developer.android.com/ndk/reference/group/media#group___media_1ga009a49041fe39f7bdc6d8b5cddbe760c)
+#[repr(i32)]
+#[derive(Copy, Clone, Debug, PartialEq, Eq, FromPrimitive, IntoPrimitive)]
+#[doc(alias = "media_status_t")]
+#[non_exhaustive]
+pub enum MediaError {
+    #[doc(alias = "AMEDIACODEC_ERROR_INSUFFICIENT_RESOURCE")]
+    CodecErrorInsufficientResource = ffi::media_status_t::AMEDIACODEC_ERROR_INSUFFICIENT_RESOURCE.0,
+    #[doc(alias = "AMEDIACODEC_ERROR_RECLAIMED")]
+    CodecErrorReclaimed = ffi::media_status_t::AMEDIACODEC_ERROR_RECLAIMED.0,
+    #[doc(alias = "AMEDIA_ERROR_UNKNOWN")]
+    ErrorUnknown = ffi::media_status_t::AMEDIA_ERROR_UNKNOWN.0,
+    #[doc(alias = "AMEDIA_ERROR_MALFORMED")]
+    ErrorMalformed = ffi::media_status_t::AMEDIA_ERROR_MALFORMED.0,
+    #[doc(alias = "AMEDIA_ERROR_UNSUPPORTED")]
+    ErrorUnsupported = ffi::media_status_t::AMEDIA_ERROR_UNSUPPORTED.0,
+    #[doc(alias = "AMEDIA_ERROR_INVALID_OBJECT")]
+    ErrorInvalidObject = ffi::media_status_t::AMEDIA_ERROR_INVALID_OBJECT.0,
+    #[doc(alias = "AMEDIA_ERROR_INVALID_PARAMETER")]
+    ErrorInvalidParameter = ffi::media_status_t::AMEDIA_ERROR_INVALID_PARAMETER.0,
+    #[doc(alias = "AMEDIA_ERROR_INVALID_OPERATION")]
+    ErrorInvalidOperation = ffi::media_status_t::AMEDIA_ERROR_INVALID_OPERATION.0,
+    #[doc(alias = "AMEDIA_ERROR_END_OF_STREAM")]
+    ErrorEndOfStream = ffi::media_status_t::AMEDIA_ERROR_END_OF_STREAM.0,
+    #[doc(alias = "AMEDIA_ERROR_IO")]
+    ErrorIo = ffi::media_status_t::AMEDIA_ERROR_IO.0,
+    #[doc(alias = "AMEDIA_ERROR_WOULD_BLOCK")]
+    ErrorWouldBlock = ffi::media_status_t::AMEDIA_ERROR_WOULD_BLOCK.0,
+    #[doc(alias = "AMEDIA_DRM_ERROR_BASE")]
+    DrmErrorBase = ffi::media_status_t::AMEDIA_DRM_ERROR_BASE.0,
+    #[doc(alias = "AMEDIA_DRM_NOT_PROVISIONED")]
+    DrmNotProvisioned = ffi::media_status_t::AMEDIA_DRM_NOT_PROVISIONED.0,
+    #[doc(alias = "AMEDIA_DRM_RESOURCE_BUSY")]
+    DrmResourceBusy = ffi::media_status_t::AMEDIA_DRM_RESOURCE_BUSY.0,
+    #[doc(alias = "AMEDIA_DRM_DEVICE_REVOKED")]
+    DrmDeviceRevoked = ffi::media_status_t::AMEDIA_DRM_DEVICE_REVOKED.0,
+    #[doc(alias = "AMEDIA_DRM_SHORT_BUFFER")]
+    DrmShortBuffer = ffi::media_status_t::AMEDIA_DRM_SHORT_BUFFER.0,
+    #[doc(alias = "AMEDIA_DRM_SESSION_NOT_OPENED")]
+    DrmSessionNotOpened = ffi::media_status_t::AMEDIA_DRM_SESSION_NOT_OPENED.0,
+    #[doc(alias = "AMEDIA_DRM_TAMPER_DETECTED")]
+    DrmTamperDetected = ffi::media_status_t::AMEDIA_DRM_TAMPER_DETECTED.0,
+    #[doc(alias = "AMEDIA_DRM_VERIFY_FAILED")]
+    DrmVerifyFailed = ffi::media_status_t::AMEDIA_DRM_VERIFY_FAILED.0,
+    #[doc(alias = "AMEDIA_DRM_NEED_KEY")]
+    DrmNeedKey = ffi::media_status_t::AMEDIA_DRM_NEED_KEY.0,
+    #[doc(alias = "AMEDIA_DRM_LICENSE_EXPIRED")]
+    DrmLicenseExpired = ffi::media_status_t::AMEDIA_DRM_LICENSE_EXPIRED.0,
+    #[doc(alias = "AMEDIA_IMGREADER_ERROR_BASE")]
+    ImgreaderErrorBase = ffi::media_status_t::AMEDIA_IMGREADER_ERROR_BASE.0,
+    #[doc(alias = "AMEDIA_IMGREADER_CANNOT_LOCK_IMAGE")]
+    ImgreaderCannotLockImage = ffi::media_status_t::AMEDIA_IMGREADER_CANNOT_LOCK_IMAGE.0,
+    #[doc(alias = "AMEDIA_IMGREADER_CANNOT_UNLOCK_IMAGE")]
+    ImgreaderCannotUnlockImage = ffi::media_status_t::AMEDIA_IMGREADER_CANNOT_UNLOCK_IMAGE.0,
+    #[doc(alias = "AMEDIA_IMGREADER_IMAGE_NOT_LOCKED")]
+    ImgreaderImageNotLocked = ffi::media_status_t::AMEDIA_IMGREADER_IMAGE_NOT_LOCKED.0,
+
+    /// This error code is unknown to the [`ndk`][crate] crate.  Please report an issue if you
+    /// believe this code needs to be added to our mapping.
+    // Use the OK discriminant, as no-one will be able to call `as i32` and only has access to the
+    // constants via `From` provided by `IntoPrimitive` which reads the contained value.
+    // An autogenerated `<previous variant> + 1` discriminant is normally fine, except that the
+    // previous variant is negative and `+1` would match the variant before that.
+    #[doc(hidden)]
+    #[num_enum(catch_all)]
+    __Unknown(i32) = ffi::media_status_t::AMEDIA_OK.0,
+}
+
+impl fmt::Display for MediaError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(f, "{:?}", self)
+    }
+}
+
+impl std::error::Error for MediaError {}
+
+impl MediaError {
+    /// Returns [`Ok`] on [`ffi::media_status_t::AMEDIA_OK`], [`Err`] otherwise (including positive
+    /// values).
+    ///
+    /// Note that some known error codes (currently only for `AMediaCodec`) are positive.
+    pub(crate) fn from_status(status: ffi::media_status_t) -> Result<()> {
+        match status {
+            ffi::media_status_t::AMEDIA_OK => Ok(()),
+            x => Err(Self::from(x.0)),
+        }
+    }
+
+    /// Returns the original value in [`Ok`] if it is not negative, [`Err`] otherwise.
+    ///
+    /// Note that some [`ffi::media_status_t`] codes are positive but will never be returned as
+    /// [`Err`] from this function. As of writing these codes are specific to the `AMediaCodec` API
+    /// and should not be handled generically.
+    pub(crate) fn from_status_if_negative<T: Into<isize> + Copy>(value: T) -> Result<T> {
+        let v = value.into();
+        if v >= 0 {
+            Ok(value)
+        } else {
+            Err(Self::from(
+                i32::try_from(v).expect("Error code out of bounds"),
+            ))
+        }
+    }
+}
+
+/// Calls the `with_ptr` construction function with a pointer to uninitialized stack memory,
+/// expecting `with_ptr` to initialize it or otherwise return an error code.
+pub(crate) fn construct<T>(with_ptr: impl FnOnce(*mut T) -> ffi::media_status_t) -> Result<T> {
+    let mut result = MaybeUninit::uninit();
+    let status = with_ptr(result.as_mut_ptr());
+    MediaError::from_status(status).map(|()| unsafe { result.assume_init() })
+}
+
+/// Calls the `with_ptr` construction function with a pointer to a pointer, and expects `with_ptr`
+/// to initialize the second pointer to a valid address.  That address is returned in the form of a
+/// [`NonNull`] object.
+pub(crate) fn construct_never_null<T>(
+    with_ptr: impl FnOnce(*mut *mut T) -> ffi::media_status_t,
+) -> Result<NonNull<T>> {
+    let result = construct(with_ptr)?;
+    Ok(if cfg!(debug_assertions) {
+        NonNull::new(result).expect("result should never be null")
+    } else {
+        unsafe { NonNull::new_unchecked(result) }
+    })
+}

clients/android/native/vendor/ndk/src/native_activity.rs

@@ -0,0 +1,241 @@
+//! Bindings for [`ANativeActivity`]
+//!
+//! [`ANativeActivity`]: https://developer.android.com/ndk/reference/group/native-activity#anativeactivity
+
+use super::hardware_buffer_format::HardwareBufferFormat;
+use std::{
+    ffi::{CStr, OsStr},
+    os::{raw::c_void, unix::prelude::OsStrExt},
+    path::Path,
+    ptr::NonNull,
+};
+
+bitflags::bitflags! {
+    /// Window flags, as per the Java API at [`android.view.WindowManager.LayoutParams`].
+    ///
+    /// <https://developer.android.com/ndk/reference/group/native-activity#group___native_activity_1ga2f1398dba5e4a5616b83437528bdb28e>
+    ///
+    /// [`android.view.WindowManager.LayoutParams`]: https://developer.android.com/reference/android/view/WindowManager.LayoutParams
+    #[derive(Clone, Copy, Debug, Hash, PartialEq, Eq, PartialOrd, Ord)]
+    pub struct WindowFlags : u32 {
+        const ALLOW_LOCK_WHILE_SCREEN_ON = ffi::AWINDOW_FLAG_ALLOW_LOCK_WHILE_SCREEN_ON;
+        const DIM_BEHIND = ffi::AWINDOW_FLAG_DIM_BEHIND;
+        #[deprecated = "Deprecated. Blurring is no longer supported."]
+        const BLUR_BEHIND = ffi::AWINDOW_FLAG_BLUR_BEHIND;
+        const NOT_FOCUSABLE = ffi::AWINDOW_FLAG_NOT_FOCUSABLE;
+        const NOT_TOUCHABLE = ffi::AWINDOW_FLAG_NOT_TOUCHABLE;
+        const NOT_TOUCH_MODAL = ffi::AWINDOW_FLAG_NOT_TOUCH_MODAL;
+        #[deprecated = "This constant was deprecated in API level 20. This flag has no effect."]
+        const TOUCHABLE_WHEN_WAKING = ffi::AWINDOW_FLAG_TOUCHABLE_WHEN_WAKING;
+        const KEEP_SCREEN_ON = ffi::AWINDOW_FLAG_KEEP_SCREEN_ON;
+        const LAYOUT_IN_SCREEN = ffi::AWINDOW_FLAG_LAYOUT_IN_SCREEN;
+        const LAYOUT_NO_LIMITS = ffi::AWINDOW_FLAG_LAYOUT_NO_LIMITS;
+        const FULLSCREEN = ffi::AWINDOW_FLAG_FULLSCREEN;
+        #[cfg_attr(feature = "api-level-30", deprecated = "This constant was deprecated in API level 30. This value became API \"by accident\", and shouldn't be used by 3rd party applications.")]
+        const FORCE_NOT_FULLSCREEN = ffi::AWINDOW_FLAG_FORCE_NOT_FULLSCREEN;
+        #[deprecated = "This constant was deprecated in API level 17. This flag is no longer used."]
+        const DITHER = ffi::AWINDOW_FLAG_DITHER;
+        const SECURE = ffi::AWINDOW_FLAG_SECURE;
+        const SCALED = ffi::AWINDOW_FLAG_SCALED;
+        const IGNORE_CHEEK_PRESSES = ffi::AWINDOW_FLAG_IGNORE_CHEEK_PRESSES;
+        const LAYOUT_INSET_DECOR = ffi::AWINDOW_FLAG_LAYOUT_INSET_DECOR;
+        const ALT_FOCUSABLE_IM = ffi::AWINDOW_FLAG_ALT_FOCUSABLE_IM;
+        const WATCH_OUTSIDE_TOUCH = ffi::AWINDOW_FLAG_WATCH_OUTSIDE_TOUCH;
+        const SHOW_WHEN_LOCKED = ffi::AWINDOW_FLAG_SHOW_WHEN_LOCKED;
+        const SHOW_WALLPAPER = ffi::AWINDOW_FLAG_SHOW_WALLPAPER;
+        const TURN_SCREEN_ON = ffi::AWINDOW_FLAG_TURN_SCREEN_ON;
+        #[cfg_attr(feature = "api-level-26", deprecated = "This constant was deprecated in API level 26. Use `SHOW_WHEN_LOCKED` instead.")]
+        const DISMISS_KEYGUARD = ffi::AWINDOW_FLAG_DISMISS_KEYGUARD;
+        const ATTACHED_IN_DECOR = 0x40000000;
+
+        // https://docs.rs/bitflags/latest/bitflags/#externally-defined-flags
+        const _ = !0;
+    }
+}
+
+/// A native [`ANativeActivity *`]
+///
+/// This is either provided in [`ffi::ANativeActivity_onCreate()`], or accessible through
+/// `ndk_glue::native_activity()`.
+///
+/// [`ANativeActivity *`]: https://developer.android.com/ndk/reference/struct/a-native-activity
+#[derive(Debug)]
+pub struct NativeActivity {
+    ptr: NonNull<ffi::ANativeActivity>,
+}
+
+// It gets shared between threads in `ndk-glue`
+unsafe impl Send for NativeActivity {}
+unsafe impl Sync for NativeActivity {}
+
+impl NativeActivity {
+    /// Create a [`NativeActivity`] from a pointer
+    ///
+    /// # Safety
+    /// By calling this function, you assert that it is a valid pointer to a native
+    /// [`ffi::ANativeActivity`].
+    pub unsafe fn from_ptr(ptr: NonNull<ffi::ANativeActivity>) -> Self {
+        Self { ptr }
+    }
+
+    /// The pointer to the native `ANativeActivity`
+    pub fn ptr(&self) -> NonNull<ffi::ANativeActivity> {
+        self.ptr
+    }
+}
+
+/// Methods that relate to fields of the struct itself
+///
+/// The relevant NDK docs can be found
+/// [here](https://developer.android.com/ndk/reference/struct/a-native-activity).
+impl NativeActivity {
+    /// The platform's SDK version code
+    pub fn sdk_version(&self) -> i32 {
+        unsafe { self.ptr.as_ref().sdkVersion }
+    }
+
+    /// Path to this application's internal data directory
+    pub fn internal_data_path(&self) -> &Path {
+        OsStr::from_bytes(unsafe { CStr::from_ptr(self.ptr.as_ref().internalDataPath) }.to_bytes())
+            .as_ref()
+    }
+
+    /// Path to this application's external (removable, mountable) data directory
+    pub fn external_data_path(&self) -> &Path {
+        OsStr::from_bytes(unsafe { CStr::from_ptr(self.ptr.as_ref().externalDataPath) }.to_bytes())
+            .as_ref()
+    }
+
+    /// This app's asset manager, which can be used to access assets from the `.apk` file.
+    pub fn asset_manager(&self) -> crate::asset::AssetManager {
+        unsafe {
+            crate::asset::AssetManager::from_ptr(
+                NonNull::new(self.ptr.as_ref().assetManager).unwrap(),
+            )
+        }
+    }
+
+    /// Instance data associated with the activity
+    pub fn instance(&self) -> *mut c_void {
+        unsafe { self.ptr.as_ref().instance }
+    }
+
+    /// Set the instance data associated with the activity
+    ///
+    /// # Safety
+    /// This can invalidate assumptions held by `ndk-glue`, as well as cause data
+    /// races with concurrent access to the instance data.
+    pub unsafe fn set_instance(&mut self, data: *mut c_void) {
+        // FIXME Does this create undefined behavior by creating a mutable reference to what could
+        // also be accessed immutably at the same time?
+        //
+        // I think that as long as we warn the users to avoid concurrent access, and we pass along
+        // the `unsafe` burden, it's OK.
+        self.ptr.as_mut().instance = data;
+    }
+
+    /// This process's `JavaVM` object.
+    ///
+    /// Usage with [__jni__](https://crates.io/crates/jni) crate:
+    /// ```no_run
+    /// # use ndk::native_activity::NativeActivity;
+    /// # let native_activity: NativeActivity = unimplemented!();
+    /// let vm_ptr = native_activity.vm();
+    /// let vm = unsafe { jni::JavaVM::from_raw(vm_ptr) }.unwrap();
+    /// let env = vm.attach_current_thread();
+    /// // Do JNI with env ...
+    /// ```
+    pub fn vm(&self) -> *mut jni_sys::JavaVM {
+        unsafe { self.ptr.as_ref() }.vm
+    }
+
+    /// The [`android.app.NativeActivity`] instance
+    ///
+    /// In the JNI, this is named `clazz`; however, as the docs say, "it should really be named
+    /// 'activity' instead of 'clazz', since it's a reference to the NativeActivity instance".
+    ///
+    /// [`android.app.NativeActivity`]: https://developer.android.com/reference/android/app/NativeActivity
+    pub fn activity(&self) -> jni_sys::jobject {
+        unsafe { self.ptr.as_ref() }.clazz
+    }
+
+    /// Path to the directory with the application's OBB files.
+    ///
+    /// # Safety
+    /// Only available as of Honeycomb (Android 3.0+, API level 11+)
+    pub unsafe fn obb_path(&self) -> &Path {
+        OsStr::from_bytes(CStr::from_ptr(self.ptr.as_ref().obbPath).to_bytes()).as_ref()
+    }
+}
+
+/// Methods that relate to `ANativeActivity_*` functions.
+///
+/// The relevant NDK docs can be found
+/// [here](https://developer.android.com/ndk/reference/group/native-activity).
+impl NativeActivity {
+    /// Sends a destroy event to the activity and stops it.
+    pub fn finish(&self) {
+        unsafe { ffi::ANativeActivity_finish(self.ptr.as_ptr()) }
+    }
+
+    /// Shows the IME (the on-screen keyboard).
+    ///
+    /// If `force` is true, the `SHOW_FORCED` flag is used; otherwise, the `SHOW_IMPLICIT` flag is
+    /// used.  Depending on the value of this flag, the `hide_soft_input` method with behave
+    /// differently.  See [the relevant
+    /// javadoc](https://developer.android.com/reference/android/view/inputmethod/InputMethodManager#constants_2)
+    /// for more information.
+    pub fn show_soft_input(&self, force: bool) {
+        let flag = if force {
+            ffi::ANATIVEACTIVITY_SHOW_SOFT_INPUT_FORCED
+        } else {
+            ffi::ANATIVEACTIVITY_SHOW_SOFT_INPUT_IMPLICIT
+        };
+        unsafe { ffi::ANativeActivity_showSoftInput(self.ptr.as_ptr(), flag) }
+    }
+
+    /// Hides the IME (the on-screen keyboard).
+    ///
+    /// If `not_always` is true, the `HIDE_NOT_ALWAYS` flag is used; otherwise, the
+    /// `HIDE_IMPLICIT_ONLY` flag is used.  Depending on the value of this flag and the way the IME
+    /// was shown, it may or may not be hidden.  See [the relevant
+    /// javadoc](https://developer.android.com/reference/android/view/inputmethod/InputMethodManager#constants_2)
+    /// for more information.
+    pub fn hide_soft_input(&self, not_always: bool) {
+        let flag = if not_always {
+            ffi::ANATIVEACTIVITY_HIDE_SOFT_INPUT_NOT_ALWAYS
+        } else {
+            ffi::ANATIVEACTIVITY_HIDE_SOFT_INPUT_IMPLICIT_ONLY
+        };
+        unsafe { ffi::ANativeActivity_hideSoftInput(self.ptr.as_ptr(), flag) }
+    }
+
+    /// Change the window format of the given activity.
+    ///
+    /// Calls [`getWindow().setFormat()`] of the given activity. Note that this method can be
+    /// called from any thread; it will send a message to the main thread of the process where the
+    /// Java finish call will take place.
+    ///
+    /// [`getWindow().setFormat()`]: https://developer.android.com/reference/android/view/Window#setFormat(int)
+    pub fn set_window_format(&self, format: HardwareBufferFormat) {
+        unsafe { ffi::ANativeActivity_setWindowFormat(self.ptr.as_ptr(), format.into()) }
+    }
+
+    /// Change the window flags of the given activity.
+    ///
+    /// Calls [`getWindow().setFlags()`] of the given activity.
+    ///
+    /// Note that this method can be called from any thread; it will send a message to the main
+    /// thread of the process where the Java finish call will take place.
+    ///
+    /// [`getWindow().setFlags()`]: https://developer.android.com/reference/android/view/Window#setFlags(int,%20int)
+    pub fn set_window_flags(&self, add_flags: WindowFlags, remove_flags: WindowFlags) {
+        unsafe {
+            ffi::ANativeActivity_setWindowFlags(
+                self.ptr.as_ptr(),
+                add_flags.bits(),
+                remove_flags.bits(),
+            )
+        }
+    }
+}

clients/android/native/vendor/ndk/src/native_window.rs

@@ -0,0 +1,459 @@
+//! Bindings for [`ANativeWindow`]
+//!
+//! [`ANativeWindow`]: https://developer.android.com/ndk/reference/group/a-native-window#anativewindow
+
+use std::{ffi::c_void, io, mem::MaybeUninit, ptr::NonNull};
+
+use jni_sys::{jobject, JNIEnv};
+
+use super::{hardware_buffer_format::HardwareBufferFormat, utils::status_to_io_result};
+#[cfg(all(feature = "nativewindow", feature = "api-level-28"))]
+use crate::data_space::DataSpace;
+
+pub type Rect = ffi::ARect;
+
+// [`NativeWindow`] represents the producer end of an image queue
+///
+/// It is the C counterpart of the [`android.view.Surface`] object in Java, and can be converted
+/// both ways. Depending on the consumer, images submitted to [`NativeWindow`] can be shown on the
+/// display or sent to other consumers, such as video encoders.
+///
+/// [`android.view.Surface`]: https://developer.android.com/reference/android/view/Surface
+#[derive(Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
+pub struct NativeWindow {
+    ptr: NonNull<ffi::ANativeWindow>,
+}
+
+unsafe impl Send for NativeWindow {}
+unsafe impl Sync for NativeWindow {}
+
+impl Drop for NativeWindow {
+    fn drop(&mut self) {
+        unsafe { ffi::ANativeWindow_release(self.ptr.as_ptr()) }
+    }
+}
+
+impl Clone for NativeWindow {
+    fn clone(&self) -> Self {
+        unsafe { ffi::ANativeWindow_acquire(self.ptr.as_ptr()) }
+        Self { ptr: self.ptr }
+    }
+}
+
+#[cfg(feature = "rwh_04")]
+unsafe impl rwh_04::HasRawWindowHandle for NativeWindow {
+    fn raw_window_handle(&self) -> rwh_04::RawWindowHandle {
+        let mut handle = rwh_04::AndroidNdkHandle::empty();
+        handle.a_native_window = self.ptr.as_ptr().cast();
+        rwh_04::RawWindowHandle::AndroidNdk(handle)
+    }
+}
+
+#[cfg(feature = "rwh_05")]
+unsafe impl rwh_05::HasRawWindowHandle for NativeWindow {
+    fn raw_window_handle(&self) -> rwh_05::RawWindowHandle {
+        let mut handle = rwh_05::AndroidNdkWindowHandle::empty();
+        handle.a_native_window = self.ptr.as_ptr().cast();
+        rwh_05::RawWindowHandle::AndroidNdk(handle)
+    }
+}
+
+#[cfg(feature = "rwh_06")]
+impl rwh_06::HasWindowHandle for NativeWindow {
+    fn window_handle(&self) -> Result<rwh_06::WindowHandle<'_>, rwh_06::HandleError> {
+        let handle = rwh_06::AndroidNdkWindowHandle::new(self.ptr.cast());
+        let handle = rwh_06::RawWindowHandle::AndroidNdk(handle);
+        // SAFETY: All fields of the "raw" `AndroidNdkWindowHandle` struct are filled out.  The
+        // returned pointer is also kept valid by `NativeWindow` (until `Drop`), which is lifetime-
+        // borrowed in the returned `WindowHandle<'_>` and cannot be outlived.  Its value won't
+        // change throughout the lifetime of this `NativeWindow`.
+        Ok(unsafe { rwh_06::WindowHandle::borrow_raw(handle) })
+    }
+}
+
+impl NativeWindow {
+    /// Assumes ownership of `ptr`
+    ///
+    /// # Safety
+    /// `ptr` must be a valid pointer to an Android [`ffi::ANativeWindow`].
+    pub unsafe fn from_ptr(ptr: NonNull<ffi::ANativeWindow>) -> Self {
+        Self { ptr }
+    }
+
+    /// Acquires ownership of `ptr`
+    ///
+    /// # Safety
+    /// `ptr` must be a valid pointer to an Android [`ffi::ANativeWindow`].
+    pub unsafe fn clone_from_ptr(ptr: NonNull<ffi::ANativeWindow>) -> Self {
+        ffi::ANativeWindow_acquire(ptr.as_ptr());
+        Self::from_ptr(ptr)
+    }
+
+    pub fn ptr(&self) -> NonNull<ffi::ANativeWindow> {
+        self.ptr
+    }
+
+    pub fn height(&self) -> i32 {
+        unsafe { ffi::ANativeWindow_getHeight(self.ptr.as_ptr()) }
+    }
+
+    pub fn width(&self) -> i32 {
+        unsafe { ffi::ANativeWindow_getWidth(self.ptr.as_ptr()) }
+    }
+
+    /// Return the current pixel format ([`HardwareBufferFormat`]) of the window surface.
+    pub fn format(&self) -> HardwareBufferFormat {
+        let value = unsafe { ffi::ANativeWindow_getFormat(self.ptr.as_ptr()) };
+        value.into()
+    }
+
+    /// Change the format and size of the window buffers.
+    ///
+    /// The width and height control the number of pixels in the buffers, not the dimensions of the
+    /// window on screen. If these are different than the window's physical size, then its buffer
+    /// will be scaled to match that size when compositing it to the screen. The width and height
+    /// must be either both zero or both non-zero.
+    ///
+    /// For all of these parameters, if `0` or [`None`] is supplied then the window's base value
+    /// will come back in force.
+    pub fn set_buffers_geometry(
+        &self,
+        width: i32,
+        height: i32,
+        format: Option<HardwareBufferFormat>,
+    ) -> io::Result<()> {
+        let format = format.map_or(0i32, |f| f.into());
+        let status = unsafe {
+            ffi::ANativeWindow_setBuffersGeometry(self.ptr.as_ptr(), width, height, format)
+        };
+        status_to_io_result(status)
+    }
+
+    /// Set a transform that will be applied to future buffers posted to the window.
+    #[cfg(all(feature = "nativewindow", feature = "api-level-26"))]
+    #[doc(alias = "ANativeWindow_setBuffersTransform")]
+    pub fn set_buffers_transform(&self, transform: NativeWindowTransform) -> io::Result<()> {
+        let status =
+            unsafe { ffi::ANativeWindow_setBuffersTransform(self.ptr.as_ptr(), transform.bits()) };
+        status_to_io_result(status)
+    }
+
+    /// All buffers queued after this call will be associated with the dataSpace parameter
+    /// specified.
+    ///
+    /// `data_space` specifies additional information about the buffer. For example, it can be used
+    /// to convey the color space of the image data in the buffer, or it can be used to indicate
+    /// that the buffers contain depth measurement data instead of color images. The default
+    /// dataSpace is `0`, [`DataSpace::Unknown`], unless it has been overridden by the producer.
+    #[cfg(all(feature = "nativewindow", feature = "api-level-28"))]
+    #[doc(alias = "ANativeWindow_setBuffersDataSpace")]
+    pub fn set_buffers_data_space(&self, data_space: DataSpace) -> io::Result<()> {
+        let status =
+            unsafe { ffi::ANativeWindow_setBuffersDataSpace(self.ptr.as_ptr(), data_space.into()) };
+        status_to_io_result(status)
+    }
+
+    /// Get the dataspace of the buffers in this [`NativeWindow`].
+    #[cfg(all(feature = "nativewindow", feature = "api-level-28"))]
+    #[doc(alias = "ANativeWindow_getBuffersDataSpace")]
+    pub fn buffers_data_space(&self) -> io::Result<DataSpace> {
+        let status = unsafe { ffi::ANativeWindow_getBuffersDataSpace(self.ptr.as_ptr()) };
+        if status >= 0 {
+            Ok(status.into())
+        } else {
+            Err(status_to_io_result(status).unwrap_err())
+        }
+    }
+
+    /// Sets the intended frame rate for this window.
+    ///
+    /// Same as [`set_frame_rate_with_change_strategy(window, frame_rate, compatibility, ChangeFrameRateStrategy::OnlyIfSeamless)`][`NativeWindow::set_frame_rate_with_change_strategy()`].
+    ///
+    #[cfg_attr(
+        not(feature = "api-level-31"),
+        doc = "[`NativeWindow::set_frame_rate_with_change_strategy()`]: https://developer.android.com/ndk/reference/group/a-native-window#anativewindow_setframeratewithchangestrategy"
+    )]
+    #[cfg(all(feature = "nativewindow", feature = "api-level-30"))]
+    #[doc(alias = "ANativeWindow_setFrameRate")]
+    pub fn set_frame_rate(
+        &self,
+        frame_rate: f32,
+        compatibility: FrameRateCompatibility,
+    ) -> io::Result<()> {
+        let status = unsafe {
+            ffi::ANativeWindow_setFrameRate(self.ptr.as_ptr(), frame_rate, compatibility as i8)
+        };
+        status_to_io_result(status)
+    }
+
+    /// Sets the intended frame rate for this window.
+    ///
+    /// On devices that are capable of running the display at different refresh rates, the system
+    /// may choose a display refresh rate to better match this window's frame rate. Usage of this
+    /// API won't introduce frame rate throttling, or affect other aspects of the application's
+    /// frame production pipeline. However, because the system may change the display refresh rate,
+    /// calls to this function may result in changes to Choreographer callback timings, and changes
+    /// to the time interval at which the system releases buffers back to the application.
+    ///
+    /// Note that this only has an effect for windows presented on the display. If this
+    /// [`NativeWindow`] is consumed by something other than the system compositor, e.g. a media
+    /// codec, this call has no effect.
+    ///
+    /// You can register for changes in the refresh rate using
+    /// [`ffi::AChoreographer_registerRefreshRateCallback()`].
+    ///
+    /// # Parameters
+    ///
+    /// - `frame_rate`: The intended frame rate of this window, in frames per second. `0` is a
+    ///   special value that indicates the app will accept the system's choice for the display
+    ///   frame rate, which is the default behavior if this function isn't called. The `frame_rate`
+    ///   param does not need to be a valid refresh rate for this device's display - e.g., it's
+    ///   fine to pass `30`fps to a device that can only run the display at `60`fps.
+    /// - `compatibility`: The frame rate compatibility of this window. The compatibility value may
+    ///   influence the system's choice of display refresh rate. See the [`FrameRateCompatibility`]
+    ///   values for more info. This parameter is ignored when `frame_rate` is `0`.
+    /// - `change_frame_rate_strategy`: Whether display refresh rate transitions caused by this
+    ///   window should be seamless. A seamless transition is one that doesn't have any visual
+    ///   interruptions, such as a black screen for a second or two. See the
+    ///   [`ChangeFrameRateStrategy`] values. This parameter is ignored when `frame_rate` is `0`.
+    #[cfg(all(feature = "nativewindow", feature = "api-level-31"))]
+    #[doc(alias = "ANativeWindow_setFrameRateWithChangeStrategy")]
+    pub fn set_frame_rate_with_change_strategy(
+        &self,
+        frame_rate: f32,
+        compatibility: FrameRateCompatibility,
+        change_frame_rate_strategy: ChangeFrameRateStrategy,
+    ) -> io::Result<()> {
+        let status = unsafe {
+            ffi::ANativeWindow_setFrameRateWithChangeStrategy(
+                self.ptr.as_ptr(),
+                frame_rate,
+                compatibility as i8,
+                change_frame_rate_strategy as i8,
+            )
+        };
+        status_to_io_result(status)
+    }
+
+    /// Provides a hint to the window that buffers should be preallocated ahead of time.
+    ///
+    /// Note that the window implementation is not guaranteed to preallocate any buffers, for
+    /// instance if an implementation disallows allocation of new buffers, or if there is
+    /// insufficient memory in the system to preallocate additional buffers
+    #[cfg(all(feature = "nativewindow", feature = "api-level-30"))]
+    pub fn try_allocate_buffers(&self) {
+        unsafe { ffi::ANativeWindow_tryAllocateBuffers(self.ptr.as_ptr()) }
+    }
+
+    /// Return the [`NativeWindow`] associated with a JNI [`android.view.Surface`] pointer.
+    ///
+    /// # Safety
+    /// By calling this function, you assert that `env` is a valid pointer to a [`JNIEnv`] and
+    /// `surface` is a valid pointer to an [`android.view.Surface`].
+    ///
+    /// [`android.view.Surface`]: https://developer.android.com/reference/android/view/Surface
+    pub unsafe fn from_surface(env: *mut JNIEnv, surface: jobject) -> Option<Self> {
+        let ptr = ffi::ANativeWindow_fromSurface(env, surface);
+        Some(Self::from_ptr(NonNull::new(ptr)?))
+    }
+
+    /// Return a JNI [`android.view.Surface`] pointer derived from this [`NativeWindow`].
+    ///
+    /// # Safety
+    /// By calling this function, you assert that `env` is a valid pointer to a [`JNIEnv`].
+    ///
+    /// [`android.view.Surface`]: https://developer.android.com/reference/android/view/Surface
+    #[cfg(feature = "api-level-26")]
+    pub unsafe fn to_surface(&self, env: *mut JNIEnv) -> jobject {
+        ffi::ANativeWindow_toSurface(env, self.ptr().as_ptr())
+    }
+
+    /// Lock the window's next drawing surface for writing.
+    ///
+    /// Optionally pass the region you intend to draw into `dirty_bounds`.  When this function
+    /// returns it is updated (commonly enlarged) with the actual area the caller needs to redraw.
+    pub fn lock(
+        &self,
+        dirty_bounds: Option<&mut Rect>,
+    ) -> io::Result<NativeWindowBufferLockGuard<'_>> {
+        let dirty_bounds = match dirty_bounds {
+            Some(dirty_bounds) => dirty_bounds,
+            None => std::ptr::null_mut(),
+        };
+        let mut buffer = MaybeUninit::uninit();
+        let status = unsafe {
+            ffi::ANativeWindow_lock(self.ptr.as_ptr(), buffer.as_mut_ptr(), dirty_bounds)
+        };
+        status_to_io_result(status)?;
+
+        Ok(NativeWindowBufferLockGuard {
+            window: self,
+            buffer: unsafe { buffer.assume_init() },
+        })
+    }
+}
+
+/// Lock holding the next drawing surface for writing.  It is unlocked and posted on [`drop()`].
+#[derive(Debug)]
+pub struct NativeWindowBufferLockGuard<'a> {
+    window: &'a NativeWindow,
+    buffer: ffi::ANativeWindow_Buffer,
+}
+
+impl<'a> NativeWindowBufferLockGuard<'a> {
+    /// The number of pixels that are shown horizontally.
+    pub fn width(&self) -> usize {
+        usize::try_from(self.buffer.width).unwrap()
+    }
+
+    // The number of pixels that are shown vertically.
+    pub fn height(&self) -> usize {
+        usize::try_from(self.buffer.height).unwrap()
+    }
+
+    /// The number of _pixels_ that a line in the buffer takes in memory.
+    ///
+    /// This may be `>= width`.
+    pub fn stride(&self) -> usize {
+        usize::try_from(self.buffer.stride).unwrap()
+    }
+
+    /// The format of the buffer. One of [`HardwareBufferFormat`].
+    pub fn format(&self) -> HardwareBufferFormat {
+        self.buffer.format.into()
+    }
+
+    /// The actual bits.
+    ///
+    /// This points to a memory segment of [`stride()`][Self::stride()] *
+    /// [`height()`][Self::height()] * [`HardwareBufferFormat::bytes_per_pixel()`] bytes.
+    ///
+    /// Only [`width()`][Self::width()] pixels are visible for each [`stride()`][Self::stride()]
+    /// line of pixels in the buffer.
+    ///
+    /// See [`bytes()`][Self::bytes()] for safe access to these bytes.
+    pub fn bits(&mut self) -> *mut c_void {
+        self.buffer.bits
+    }
+
+    /// Safe write access to likely uninitialized pixel buffer data.
+    ///
+    /// Returns [`None`] when there is no [`HardwareBufferFormat::bytes_per_pixel()`] size
+    /// available for this [`format()`][Self::format()].
+    ///
+    /// The returned slice consists of [`stride()`][Self::stride()] * [`height()`][Self::height()]
+    /// \* [`HardwareBufferFormat::bytes_per_pixel()`] bytes.
+    ///
+    /// Only [`width()`][Self::width()] pixels are visible for each [`stride()`][Self::stride()]
+    /// line of pixels in the buffer.
+    pub fn bytes(&mut self) -> Option<&mut [MaybeUninit<u8>]> {
+        let num_pixels = self.stride() * self.height();
+        let num_bytes = num_pixels * self.format().bytes_per_pixel()?;
+        Some(unsafe { std::slice::from_raw_parts_mut(self.bits().cast(), num_bytes) })
+    }
+
+    /// Returns a slice of bytes for each line of visible pixels in the buffer, ignoring any
+    /// padding pixels incurred by the stride.
+    ///
+    /// See [`bits()`][Self::bits()] and [`bytes()`][Self::bytes()] for contiguous access to the
+    /// underlying buffer.
+    pub fn lines(&mut self) -> Option<impl Iterator<Item = &mut [MaybeUninit<u8>]>> {
+        let bpp = self.format().bytes_per_pixel()?;
+        let scanline_bytes = bpp * self.stride();
+        let width_bytes = bpp * self.width();
+        let bytes = self.bytes()?;
+
+        Some(
+            bytes
+                .chunks_exact_mut(scanline_bytes)
+                .map(move |scanline| &mut scanline[..width_bytes]),
+        )
+    }
+}
+
+impl<'a> Drop for NativeWindowBufferLockGuard<'a> {
+    fn drop(&mut self) {
+        let ret = unsafe { ffi::ANativeWindow_unlockAndPost(self.window.ptr.as_ptr()) };
+        assert_eq!(ret, 0);
+    }
+}
+
+#[cfg(all(feature = "nativewindow", feature = "api-level-26"))]
+bitflags::bitflags! {
+    /// Transforms that can be applied to buffers as they are displayed to a window.
+    ///
+    /// Supported transforms are any combination of horizontal mirror, vertical mirror, and
+    /// clockwise 90 degree rotation, in that order. Rotations of 180 and 270 degrees are made up
+    /// of those basic transforms.
+    #[derive(Clone, Copy, Debug, Hash, PartialEq, Eq)]
+    #[doc(alias = "ANativeWindowTransform")]
+    pub struct NativeWindowTransform : i32 {
+        #[doc(alias = "ANATIVEWINDOW_TRANSFORM_IDENTITY")]
+        const IDENTITY = ffi::ANativeWindowTransform::ANATIVEWINDOW_TRANSFORM_IDENTITY.0 as i32;
+        #[doc(alias = "ANATIVEWINDOW_TRANSFORM_MIRROR_HORIZONTAL")]
+        const MIRROR_HORIZONTAL = ffi::ANativeWindowTransform::ANATIVEWINDOW_TRANSFORM_MIRROR_HORIZONTAL.0 as i32;
+        #[doc(alias = "ANATIVEWINDOW_TRANSFORM_MIRROR_VERTICAL")]
+        const MIRROR_VERTICAL = ffi::ANativeWindowTransform::ANATIVEWINDOW_TRANSFORM_MIRROR_VERTICAL.0 as i32;
+        #[doc(alias = "ANATIVEWINDOW_TRANSFORM_ROTATE_90")]
+        const ROTATE_90 = ffi::ANativeWindowTransform::ANATIVEWINDOW_TRANSFORM_ROTATE_90.0 as i32;
+        /// Defined as [`Self::MIRROR_HORIZONTAL`] `|` [`Self::MIRROR_VERTICAL`].
+        #[doc(alias = "ANATIVEWINDOW_TRANSFORM_ROTATE_180")]
+        const ROTATE_180 = ffi::ANativeWindowTransform::ANATIVEWINDOW_TRANSFORM_ROTATE_180.0 as i32;
+        /// Defined as [`Self::ROTATE_180`] `|` [`Self::ROTATE_90`].
+        #[doc(alias = "ANATIVEWINDOW_TRANSFORM_ROTATE_270")]
+        const ROTATE_270 = ffi::ANativeWindowTransform::ANATIVEWINDOW_TRANSFORM_ROTATE_270.0 as i32;
+
+        // https://docs.rs/bitflags/latest/bitflags/#externally-defined-flags
+        const _ = !0;
+    }
+}
+
+/// Compatibility value for [`NativeWindow::set_frame_rate()`]
+#[cfg_attr(
+    feature = "api-level-31",
+    doc = " and [`NativeWindow::set_frame_rate_with_change_strategy()`]"
+)]
+/// .
+#[cfg(all(feature = "nativewindow", feature = "api-level-30"))]
+#[repr(i8)]
+#[derive(Clone, Copy, Debug, Hash, PartialEq, Eq)]
+#[doc(alias = "ANativeWindow_FrameRateCompatibility")]
+#[non_exhaustive]
+pub enum FrameRateCompatibility {
+    /// There are no inherent restrictions on the frame rate of this window.
+    ///
+    /// When the system selects a frame rate other than what the app requested, the app will be
+    /// able to run at the system frame rate without requiring pull down. This value should be used
+    /// when displaying game content, UIs, and anything that isn't video.
+    #[doc(alias = "ANATIVEWINDOW_FRAME_RATE_COMPATIBILITY_DEFAULT")]
+    Default =
+        ffi::ANativeWindow_FrameRateCompatibility::ANATIVEWINDOW_FRAME_RATE_COMPATIBILITY_DEFAULT.0 as i8,
+    /// This window is being used to display content with an inherently fixed frame rate, e.g. a
+    /// video that has a specific frame rate.
+    ///
+    /// When the system selects a frame rate other than what the app requested, the app will need
+    /// to do pull down or use some other technique to adapt to the system's frame rate. The user
+    /// experience is likely to be worse (e.g. more frame stuttering) than it would be if the
+    /// system had chosen the app's requested frame rate. This value should be used for video
+    /// content.
+    #[doc(alias = "ANATIVEWINDOW_FRAME_RATE_COMPATIBILITY_FIXED_SOURCE")]
+    FixedSource = ffi::ANativeWindow_FrameRateCompatibility::ANATIVEWINDOW_FRAME_RATE_COMPATIBILITY_FIXED_SOURCE.0 as i8,
+}
+
+/// Change frame rate strategy value for [`NativeWindow::set_frame_rate_with_change_strategy()`].
+#[cfg(all(feature = "nativewindow", feature = "api-level-31"))]
+#[repr(i8)]
+#[derive(Clone, Copy, Debug, Hash, PartialEq, Eq)]
+#[doc(alias = "ANativeWindow_ChangeFrameRateStrategy")]
+#[non_exhaustive]
+pub enum ChangeFrameRateStrategy {
+    /// Change the frame rate only if the transition is going to be seamless.
+    #[doc(alias = "ANATIVEWINDOW_CHANGE_FRAME_RATE_ONLY_IF_SEAMLESS")]
+    OnlyIfSeamless =
+        ffi::ANativeWindow_ChangeFrameRateStrategy::ANATIVEWINDOW_CHANGE_FRAME_RATE_ONLY_IF_SEAMLESS
+            .0 as i8,
+    /// Change the frame rate even if the transition is going to be non-seamless, i.e. with visual interruptions for the user.
+    #[doc(alias = "ANATIVEWINDOW_CHANGE_FRAME_RATE_ALWAYS")]
+    Always =
+        ffi::ANativeWindow_ChangeFrameRateStrategy::ANATIVEWINDOW_CHANGE_FRAME_RATE_ALWAYS.0 as i8,
+}

clients/android/native/vendor/ndk/src/shared_memory.rs

@@ -0,0 +1,153 @@
+//! Bindings for [`ASharedMemory`]
+//!
+//! [`ASharedMemory`]: https://developer.android.com/ndk/reference/group/memory
+#![cfg(feature = "api-level-26")]
+
+use std::{
+    ffi::CStr,
+    io::{Error, Result},
+    // TODO: Import from std::os::fd::{} since Rust 1.66
+    os::unix::io::{AsFd, AsRawFd, BorrowedFd, FromRawFd, IntoRawFd, OwnedFd, RawFd},
+    ptr,
+};
+
+#[cfg(feature = "api-level-27")]
+use jni_sys::{jobject, JNIEnv};
+
+/// Enables the creation, mapping, and protection control over anonymous shared memory.
+#[derive(Debug)]
+#[doc(alias = "ASharedMemory")]
+pub struct SharedMemory(OwnedFd);
+
+impl SharedMemory {
+    /// Create a shared memory region.
+    ///
+    /// Creates shared memory region and returns a file descriptor. The resulting file descriptor
+    /// can be `mmap`'ed to process memory space with `PROT_READ | PROT_WRITE | PROT_EXEC`. Access
+    /// to this shared memory region can be restricted with [`set_prot()`][Self::set_prot()].
+    ///
+    /// Use [`android.os.ParcelFileDescriptor`] to pass the file descriptor to another process.
+    /// File descriptors may also be sent to other processes over a Unix domain socket with
+    /// `sendmsg` and `SCM_RIGHTS`. See `sendmsg(3)` and `cmsg(3)` man pages for more information.
+    ///
+    /// If you intend to share this file descriptor with a child process after calling `exec(3)`,
+    /// note that you will need to use `fcntl(2)` with `F_SETFD` to clear the `FD_CLOEXEC` flag for
+    /// this to work on all versions of Android.
+    ///
+    /// [`android.os.ParcelFileDescriptor`]: https://developer.android.com/reference/android/os/ParcelFileDescriptor
+    #[doc(alias = "ASharedMemory_create")]
+    pub fn create(name: Option<&CStr>, size: usize) -> Result<Self> {
+        let fd =
+            unsafe { ffi::ASharedMemory_create(name.map_or(ptr::null(), |p| p.as_ptr()), size) };
+        if fd < 0 {
+            Err(Error::last_os_error())
+        } else {
+            Ok(unsafe { Self::from_raw_fd(fd) })
+        }
+    }
+
+    /// Returns a `dup`'d FD from the given Java [`android.os.SharedMemory`] object.
+    ///
+    /// The returned file descriptor has all the same properties & capabilities as the FD returned
+    /// from [`create()`][Self::create()], however the protection flags will be the same as those
+    /// of the [`android.os.SharedMemory`] object.
+    ///
+    /// [`android.os.SharedMemory`]: https://developer.android.com/reference/android/os/SharedMemory
+    #[cfg(feature = "api-level-27")]
+    #[doc(alias = "ASharedMemory_dupFromJava")]
+    #[allow(clippy::not_unsafe_ptr_arg_deref)]
+    pub fn dup_from_java(env: *mut JNIEnv, shared_memory: jobject) -> Result<Self> {
+        let fd = unsafe { ffi::ASharedMemory_dupFromJava(env, shared_memory) };
+        if fd < 0 {
+            Err(Error::last_os_error())
+        } else {
+            Ok(unsafe { Self::from_raw_fd(fd) })
+        }
+    }
+
+    /// Get the size of the shared memory region.
+    #[doc(alias = "ASharedMemory_getSize")]
+    pub fn size(&self) -> usize {
+        unsafe { ffi::ASharedMemory_getSize(self.as_raw_fd()) }
+    }
+
+    /// Restrict access of shared memory region.
+    ///
+    /// This function restricts access of a shared memory region. Access can only be removed. The
+    /// effect applies globally to all file descriptors in all processes across the system that
+    /// refer to this shared memory region. Existing memory mapped regions are not affected.
+    ///
+    /// It is a common use case to create a shared memory region, map it read/write locally to
+    /// initialize content, and then send the shared memory to another process with read only
+    /// access. Code example as below:
+    ///
+    /// ```no_run
+    /// # use ndk::shared_memory::SharedMemory;
+    /// # // TODO: Import from std::os::fd::{} since Rust 1.66
+    /// # use std::os::unix::io::AsRawFd;
+    /// # use std::ffi::CStr;
+    /// # unsafe {
+    /// let mem = SharedMemory::create(Some(CStr::from_bytes_with_nul_unchecked(b"memory\0")), 127).unwrap();
+    /// // By default it has PROT_READ | PROT_WRITE | PROT_EXEC.
+    /// let size = mem.size();
+    /// let buffer = libc::mmap(
+    ///     std::ptr::null_mut(),
+    ///     size,
+    ///     libc::PROT_READ | libc::PROT_WRITE,
+    ///     libc::MAP_SHARED,
+    ///     mem.as_raw_fd(),
+    ///     0,
+    /// );
+    /// let buffer_slice = std::slice::from_raw_parts_mut(buffer.cast(), size);
+    ///
+    /// // trivially initialize content
+    /// buffer_slice[..7].copy_from_slice(b"hello!\0");
+    ///
+    /// // Existing mappings will retain their protection flags (PROT_WRITE here) after set_prod()
+    /// // unless it is unmapped:
+    /// libc::munmap(buffer, size);
+    ///
+    /// // limit access to read only
+    /// mem.set_prot(libc::PROT_READ);
+    ///
+    /// // share fd with another process here and the other process can only map with PROT_READ.
+    /// # }
+    /// ```
+    #[doc(alias = "ASharedMemory_setProt")]
+    pub fn set_prot(&self, prot: i32) -> Result<()> {
+        let status = unsafe { ffi::ASharedMemory_setProt(self.as_raw_fd(), prot) };
+        if status < 0 {
+            Err(Error::last_os_error())
+        } else {
+            Ok(())
+        }
+    }
+}
+
+impl AsFd for SharedMemory {
+    fn as_fd(&self) -> BorrowedFd<'_> {
+        self.0.as_fd()
+    }
+}
+
+impl AsRawFd for SharedMemory {
+    fn as_raw_fd(&self) -> RawFd {
+        self.0.as_raw_fd()
+    }
+}
+
+impl IntoRawFd for SharedMemory {
+    fn into_raw_fd(self) -> RawFd {
+        self.0.into_raw_fd()
+    }
+}
+
+impl FromRawFd for SharedMemory {
+    /// # Safety
+    ///
+    /// The resource pointed to by `fd` must be open and suitable for assuming
+    /// ownership. The resource must not require any cleanup other than `close`.
+    unsafe fn from_raw_fd(fd: RawFd) -> Self {
+        Self(OwnedFd::from_raw_fd(fd))
+    }
+}

clients/android/native/vendor/ndk/src/surface_texture.rs

@@ -0,0 +1,159 @@
+//! Bindings for [`ASurfaceTexture`]
+//!
+//! See <https://source.android.com/devices/graphics/arch-st> for an architectural overview of
+//! [`SurfaceTexture`] internals.
+//!
+//! [`ASurfaceTexture`]: https://developer.android.com/ndk/reference/group/surface-texture
+#![cfg(feature = "api-level-28")]
+
+use crate::{native_window::NativeWindow, utils::status_to_io_result};
+use jni_sys::{jobject, JNIEnv};
+use std::{io::Result, ptr::NonNull, time::Duration};
+
+/// An opaque type to manage [`android.graphics.SurfaceTexture`] from native code
+///
+/// [`android.graphics.SurfaceTexture`]: https://developer.android.com/reference/android/graphics/SurfaceTexture
+#[derive(Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
+pub struct SurfaceTexture {
+    ptr: NonNull<ffi::ASurfaceTexture>,
+}
+
+unsafe impl Send for SurfaceTexture {}
+
+impl Drop for SurfaceTexture {
+    fn drop(&mut self) {
+        unsafe { ffi::ASurfaceTexture_release(self.ptr.as_ptr()) }
+    }
+}
+
+impl SurfaceTexture {
+    /// Assumes ownership of `ptr`
+    ///
+    /// # Safety
+    /// `ptr` must be a valid pointer to an Android [`ffi::ASurfaceTexture`].
+    pub unsafe fn from_ptr(ptr: NonNull<ffi::ASurfaceTexture>) -> Self {
+        Self { ptr }
+    }
+
+    /// Get a reference to the native [`SurfaceTexture`] from the corresponding Java object.
+    ///
+    /// # Safety
+    ///
+    /// This function should be called with a healthy JVM pointer and with a non-null
+    /// [`android.graphics.SurfaceTexture`], which must be kept alive on the Java/Kotlin side.
+    ///
+    /// The caller must keep a reference to the Java [`android.graphics.SurfaceTexture`] during the
+    /// lifetime of the returned [`SurfaceTexture`]. Failing to do so could result in the
+    /// [`SurfaceTexture`] to stop functioning properly once the Java object gets finalized.
+    /// However, this will not result in program termination.
+    ///
+    /// [`android.graphics.SurfaceTexture`]: https://developer.android.com/reference/android/graphics/SurfaceTexture
+    pub unsafe fn from_surface_texture(env: *mut JNIEnv, surface_texture: jobject) -> Option<Self> {
+        let a_surface_texture_ptr = ffi::ASurfaceTexture_fromSurfaceTexture(env, surface_texture);
+        let s = NonNull::new(a_surface_texture_ptr)?;
+        Some(SurfaceTexture::from_ptr(s))
+    }
+
+    /// Returns a pointer to the native [`ffi::ASurfaceTexture`].
+    pub fn ptr(&self) -> NonNull<ffi::ASurfaceTexture> {
+        self.ptr
+    }
+
+    /// Returns a reference to a [`NativeWindow`] (i.e. the Producer) for this [`SurfaceTexture`].
+    ///
+    /// This is equivalent to Java's:
+    /// ```java
+    /// Surface sur = new Surface(surfaceTexture);
+    /// ```
+    pub fn acquire_native_window(&self) -> Option<NativeWindow> {
+        let native_window = unsafe { ffi::ASurfaceTexture_acquireANativeWindow(self.ptr.as_ptr()) };
+        let n = NonNull::new(native_window)?;
+        Some(unsafe { NativeWindow::from_ptr(n) })
+    }
+
+    /// Attach the [`SurfaceTexture`] to the OpenGL ES context that is current on the calling
+    /// thread.
+    ///
+    /// A new OpenGL ES texture object is created and populated with the [`SurfaceTexture`] image
+    /// frame that was current at the time of the last call to
+    /// [`detach_from_gl_context()`][Self::detach_from_gl_context()]. This new texture is bound to
+    /// the `GL_TEXTURE_EXTERNAL_OES` texture target.
+    ///
+    /// This can be used to access the [`SurfaceTexture`] image contents from multiple OpenGL ES
+    /// contexts. Note, however, that the image contents are only accessible from one OpenGL ES
+    /// context at a time.
+    pub fn attach_to_gl_context(&self, tex_name: u32) -> Result<()> {
+        let status = unsafe { ffi::ASurfaceTexture_attachToGLContext(self.ptr.as_ptr(), tex_name) };
+        status_to_io_result(status)
+    }
+
+    /// Detach the [`SurfaceTexture`] from the OpenGL ES context that owns the OpenGL ES texture
+    /// object.
+    ///
+    /// This call must be made with the OpenGL ES context current on the calling thread. The OpenGL
+    /// ES texture object will be deleted as a result of this call. After calling this method all
+    /// calls to [`update_tex_image()`][Self::update_tex_image()] will fail until a successful call
+    /// to [`attach_to_gl_context()`][Self::attach_to_gl_context()] is made.
+    ///
+    /// This can be used to access the [`SurfaceTexture`] image contents from multiple OpenGL ES
+    /// contexts. Note, however, that the image contents are only accessible from one OpenGL ES
+    /// context at a time.
+    pub fn detach_from_gl_context(&self) -> Result<()> {
+        let status = unsafe { ffi::ASurfaceTexture_detachFromGLContext(self.ptr.as_ptr()) };
+        status_to_io_result(status)
+    }
+
+    /// Retrieve the 4x4 texture coordinate transform matrix associated with the texture image set
+    /// by the most recent call to [`update_tex_image()`][Self::update_tex_image()].
+    ///
+    /// This transform matrix maps 2D homogeneous texture coordinates of the form `(s, t, 0, 1)`
+    /// with `s` and `t` in the inclusive range `[0, 1]` to the texture coordinate that should be
+    /// used to sample that location from the texture. Sampling the texture outside of the range of
+    /// this transform is undefined.
+    ///
+    /// The matrix is stored in column-major order so that it may be passed directly to OpenGL ES
+    /// via the [`glLoadMatrixf()`] or [`glUniformMatrix4fv()`] functions.
+    ///
+    /// [`glLoadMatrixf()`]: https://www.khronos.org/registry/OpenGL-Refpages/gl2.1/xhtml/glLoadMatrix.xml
+    /// [`gluniformmatrix4fv()`]: https://www.khronos.org/registry/OpenGL-Refpages/es3.1/html/glUniform.xhtml
+    pub fn transform_matrix(&self) -> [f32; 16] {
+        let mut r = [0f32; 16];
+        unsafe { ffi::ASurfaceTexture_getTransformMatrix(self.ptr.as_ptr(), r.as_mut_ptr()) };
+        r
+    }
+
+    /// Retrieve the timestamp associated with the texture image set by the most recent call to
+    /// [`update_tex_image()`][Self::update_tex_image()].
+    ///
+    /// This timestamp is in nanoseconds, and is normally monotonically increasing. The timestamp
+    /// should be unaffected by time-of-day adjustments, and for a camera should be strictly
+    /// monotonic but for a [`MediaPlayer`] may be reset when the position is set. The specific
+    /// meaning and zero point of the timestamp depends on the source providing images to the
+    /// [`SurfaceTexture`]. Unless otherwise specified by the image source, timestamps cannot
+    /// generally be compared across [`SurfaceTexture`] instances, or across multiple program
+    /// invocations. It is mostly useful for determining time offsets between subsequent frames.
+    ///
+    /// For EGL/Vulkan producers, this timestamp is the desired present time set with the
+    /// [`EGL_ANDROID_presentation_time`] or [`VK_GOOGLE_display_timing`] extensions.
+    ///
+    /// [`MediaPlayer`]: https://developer.android.com/reference/android/media/MediaPlayer
+    /// [`EGL_ANDROID_presentation_time`]: https://www.khronos.org/registry/EGL/extensions/ANDROID/EGL_ANDROID_presentation_time.txt
+    /// [`VK_GOOGLE_display_timing`]: https://www.khronos.org/registry/vulkan/specs/1.3-extensions/man/html/VK_GOOGLE_display_timing.html
+    pub fn timestamp(&self) -> Duration {
+        Duration::from_nanos(
+            unsafe { ffi::ASurfaceTexture_getTimestamp(self.ptr.as_ptr()) }
+                .try_into()
+                .unwrap(),
+        )
+    }
+
+    /// Update the texture image to the most recent frame from the image stream.
+    ///
+    /// This may only be called while the OpenGL ES context that owns the texture is current on the
+    /// calling thread. It will implicitly bind its texture to the `GL_TEXTURE_EXTERNAL_OES`
+    /// texture target.
+    pub fn update_tex_image(&self) -> Result<()> {
+        let status = unsafe { ffi::ASurfaceTexture_updateTexImage(self.ptr.as_ptr()) };
+        status_to_io_result(status)
+    }
+}

clients/android/native/vendor/ndk/src/sync.rs

@@ -0,0 +1,143 @@
+//! Bindings for [sync functions]
+//!
+//! [sync functions]: https://developer.android.com/ndk/reference/group/sync
+#![cfg(feature = "sync")]
+
+use std::{
+    ffi::CStr,
+    fmt::Debug,
+    // TODO: Import from std::os::fd::{} since Rust 1.66
+    os::unix::io::{AsRawFd, BorrowedFd, FromRawFd, OwnedFd},
+    ptr::NonNull,
+};
+
+#[doc(alias = "sync_file_info")]
+#[repr(transparent)]
+pub struct SyncFileInfo {
+    inner: NonNull<ffi::sync_file_info>,
+}
+
+impl Debug for SyncFileInfo {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("SyncFileInfo")
+            .field("name", &self.name())
+            .field("status", &self.status())
+            .field("flags", &self.flags())
+            .field("num_fences", &self.num_fences())
+            .field("fence_info", &self.fence_info())
+            .finish()
+    }
+}
+
+impl SyncFileInfo {
+    /// Retrieve detailed information about a sync file and its fences.
+    #[doc(alias = "sync_file_info")]
+    pub fn new(fd: BorrowedFd<'_>) -> Option<Self> {
+        let inner = NonNull::new(unsafe { ffi::sync_file_info(fd.as_raw_fd()) })?;
+        Some(Self { inner })
+    }
+
+    pub fn name(&self) -> &CStr {
+        let inner = unsafe { self.inner.as_ref() };
+        // TODO: Switch to CStr::from_bytes_until_nul (with c_char -> u8 transmute) since MSRV 1.69
+        // https://github.com/ash-rs/ash/pull/746
+        unsafe { CStr::from_ptr(inner.name.as_ptr()) }
+    }
+
+    pub fn status(&self) -> i32 {
+        let inner = unsafe { self.inner.as_ref() };
+        inner.status
+    }
+
+    pub fn flags(&self) -> u32 {
+        let inner = unsafe { self.inner.as_ref() };
+        inner.flags
+    }
+
+    pub fn num_fences(&self) -> usize {
+        let inner = unsafe { self.inner.as_ref() };
+        inner.num_fences as usize
+    }
+
+    /// Get the array of fence infos from the sync file's info.
+    #[doc(alias = "sync_get_fence_info")]
+    pub fn fence_info(&self) -> &[SyncFenceInfo] {
+        let inner = unsafe { self.inner.as_ref() };
+
+        if inner.num_fences == 0 {
+            &[]
+        } else {
+            let sync_fence_info = NonNull::new(inner.sync_fence_info as *mut _)
+                .expect("sync_fence_info cannot be null if num_fences > 0");
+            unsafe {
+                std::slice::from_raw_parts(sync_fence_info.as_ptr(), inner.num_fences as usize)
+            }
+        }
+    }
+}
+
+impl Drop for SyncFileInfo {
+    /// Free a [`struct@ffi::sync_file_info`] structure.
+    #[doc(alias = "sync_file_info_free")]
+    fn drop(&mut self) {
+        unsafe { ffi::sync_file_info_free(self.inner.as_ptr()) }
+    }
+}
+
+#[doc(alias = "sync_fence_info")]
+#[repr(transparent)]
+pub struct SyncFenceInfo(ffi::sync_fence_info);
+
+impl Debug for SyncFenceInfo {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("SyncFenceInfo")
+            .field("obj_name", &self.obj_name())
+            .field("driver_name", &self.driver_name())
+            .field("status", &self.status())
+            .field("flags", &self.flags())
+            .field("timestamp_ns", &self.timestamp_ns())
+            .finish()
+    }
+}
+
+impl SyncFenceInfo {
+    pub fn obj_name(&self) -> &CStr {
+        // TODO: Switch to CStr::from_bytes_until_nul (with c_char -> u8 transmute) since MSRV 1.69
+        unsafe { CStr::from_ptr(self.0.obj_name.as_ptr()) }
+    }
+
+    pub fn driver_name(&self) -> &CStr {
+        // TODO: Switch to CStr::from_bytes_until_nul (with c_char -> u8 transmute) since MSRV 1.69
+        unsafe { CStr::from_ptr(self.0.driver_name.as_ptr()) }
+    }
+
+    pub fn status(&self) -> i32 {
+        self.0.status
+    }
+
+    pub fn flags(&self) -> u32 {
+        self.0.flags
+    }
+
+    pub fn timestamp_ns(&self) -> u64 {
+        self.0.timestamp_ns
+    }
+}
+
+/// Merge two sync files.
+///
+/// This produces a new sync file with the given name which has the union of the two original sync
+/// file's fences; redundant fences may be removed.
+///
+/// If one of the input sync files is signaled or invalid, then this function may behave like
+/// `dup()`: the new file descriptor refers to the valid/unsignaled sync file with its original
+/// name, rather than a new sync file.
+pub fn sync_merge(name: &CStr, fd1: BorrowedFd<'_>, fd2: BorrowedFd<'_>) -> OwnedFd {
+    unsafe {
+        OwnedFd::from_raw_fd(ffi::sync_merge(
+            name.as_ptr(),
+            fd1.as_raw_fd(),
+            fd2.as_raw_fd(),
+        ))
+    }
+}

clients/android/native/vendor/ndk/src/trace.rs

@@ -0,0 +1,92 @@
+//! Bindings for the NDK tracing API.
+//!
+//! See also [the NDK docs](https://developer.android.com/ndk/reference/group/tracing)
+#![cfg(feature = "api-level-23")]
+use std::ffi::{CString, NulError};
+use std::marker::PhantomData;
+
+pub fn is_trace_enabled() -> bool {
+    unsafe { ffi::ATrace_isEnabled() }
+}
+
+#[derive(Debug)]
+pub struct Section {
+    // Section is !Sync and !Send
+    _pd: PhantomData<*mut ()>,
+}
+
+impl Section {
+    pub fn new(name: &str) -> Result<Self, NulError> {
+        let section_name = CString::new(name)?;
+        unsafe { ffi::ATrace_beginSection(section_name.as_ptr()) };
+
+        Ok(Self { _pd: PhantomData })
+    }
+
+    pub fn end(self) {
+        drop(self)
+    }
+}
+
+impl Drop for Section {
+    fn drop(&mut self) {
+        unsafe { ffi::ATrace_endSection() };
+    }
+}
+
+/// Unique identifier for distinguishing simultaneous events
+#[derive(Debug)]
+#[cfg(feature = "api-level-29")]
+pub struct Cookie(pub i32);
+
+#[derive(Debug)]
+#[cfg(feature = "api-level-29")]
+pub struct AsyncSection {
+    section_name: CString,
+    cookie: Cookie,
+    // AsyncSection is !Sync
+    _pd: PhantomData<&'static ()>,
+}
+
+#[cfg(feature = "api-level-29")]
+impl AsyncSection {
+    pub fn new(name: &str, cookie: Cookie) -> Result<Self, NulError> {
+        let section_name = CString::new(name)?;
+        unsafe { ffi::ATrace_beginAsyncSection(section_name.as_ptr(), cookie.0) };
+
+        Ok(Self {
+            section_name,
+            cookie,
+            _pd: PhantomData,
+        })
+    }
+
+    pub fn end(self) {
+        drop(self)
+    }
+}
+
+#[cfg(feature = "api-level-29")]
+impl Drop for AsyncSection {
+    fn drop(&mut self) {
+        unsafe { ffi::ATrace_endAsyncSection(self.section_name.as_ptr(), self.cookie.0) };
+    }
+}
+
+#[cfg(feature = "api-level-29")]
+#[derive(Debug)]
+pub struct Counter {
+    name: CString,
+}
+
+#[cfg(feature = "api-level-29")]
+impl Counter {
+    pub fn new(name: &str) -> Result<Self, NulError> {
+        let name = CString::new(name)?;
+        Ok(Self { name })
+    }
+
+    pub fn set_value(&self, value: i64) {
+        unsafe { ffi::ATrace_setCounter(self.name.as_ptr(), value) }
+    }
+}

clients/android/native/vendor/ndk/src/utils.rs

@@ -0,0 +1,70 @@
+//! Internal utilities
+use log::{error, log_enabled, Level};
+use std::ffi::{c_int, CStr, CString};
+use std::io::{Error, Result};
+
+/// Turns standard `<errno.h>` status codes - typically rewrapped by Android's [`Errors.h`] - into
+/// Rust's [`std::io::Error`].
+///
+/// [`Errors.h`]: https://cs.android.com/android/platform/superproject/+/master:system/core/libutils/include/utils/Errors.h
+pub(crate) fn status_to_io_result(status: i32) -> Result<()> {
+    match status {
+        0 => Ok(()),
+        r if r < 0 => Err(Error::from_raw_os_error(-r)),
+        r => unreachable!("Status is positive integer {}", r),
+    }
+}
+
+pub(crate) fn android_log(level: Level, tag: &CStr, msg: &CStr) {
+    let prio = match level {
+        Level::Error => ffi::android_LogPriority::ANDROID_LOG_ERROR,
+        Level::Warn => ffi::android_LogPriority::ANDROID_LOG_WARN,
+        Level::Info => ffi::android_LogPriority::ANDROID_LOG_INFO,
+        Level::Debug => ffi::android_LogPriority::ANDROID_LOG_DEBUG,
+        Level::Trace => ffi::android_LogPriority::ANDROID_LOG_VERBOSE,
+    };
+    unsafe {
+        ffi::__android_log_write(prio.0 as c_int, tag.as_ptr(), msg.as_ptr());
+    }
+}
+
+pub(crate) fn log_panic(panic: Box<dyn std::any::Any + Send>) {
+    fn log_panic(panic_str: &str) {
+        const RUST_PANIC_TAG: &CStr =
+            unsafe { CStr::from_bytes_with_nul_unchecked(b"RustPanic\0") };
+
+        let panic_str = CString::new(panic_str).unwrap_or_default();
+
+        // Use the Rust logger if installed and enabled, otherwise fall back to the Android system
+        // logger so there is at least some record of the panic
+        if log_enabled!(Level::Error) {
+            error!("RustPanic: {}", panic_str.to_string_lossy());
+            log::logger().flush();
+        } else {
+            android_log(Level::Error, RUST_PANIC_TAG, &panic_str);
+        }
+    }
+
+    match panic.downcast::<String>() {
+        Ok(panic_string) => log_panic(&panic_string),
+        Err(panic) => match panic.downcast::<&str>() {
+            Ok(panic_str) => log_panic(&panic_str),
+            Err(_) => log_panic("Unknown panic message type"),
+        },
+    }
+}
+
+/// Run a closure and abort the program if it panics.
+///
+/// This is generally used to ensure Rust callbacks won't unwind past the FFI boundary, which leads
+/// to undefined behaviour.
+pub(crate) fn abort_on_panic<R>(f: impl FnOnce() -> R) -> R {
+    std::panic::catch_unwind(std::panic::AssertUnwindSafe(f)).unwrap_or_else(|panic| {
+        // Try logging the panic before aborting
+        //
+        // Just in case our attempt to log a panic could itself cause a panic we use a
+        // second catch_unwind here.
+        let _ = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| log_panic(panic)));
+        std::process::abort();
+    })
+}

clients/apple/Punktfunk.xcodeproj/project.pbxproj

@@ -366,7 +366,8 @@
 				INFOPLIST_FILE = Config/Info.plist;
 				INFOPLIST_KEY_CFBundleDisplayName = Punktfunk;
 				INFOPLIST_KEY_GCSupportsControllerUserInteraction = YES;
-				INFOPLIST_KEY_LSApplicationCategoryType = "public.app-category.utilities";
+				INFOPLIST_KEY_GCSupportsGameMode = YES;
+				INFOPLIST_KEY_LSApplicationCategoryType = "public.app-category.games";
 				INFOPLIST_KEY_NSHumanReadableCopyright = "";
 				INFOPLIST_KEY_NSLocalNetworkUsageDescription = "Punktfunk connects directly to your punktfunk host on the local network to stream video, audio, and input.";
 				INFOPLIST_KEY_NSMicrophoneUsageDescription = "Your microphone is streamed to the connected punktfunk host, where it appears as a virtual microphone.";
@@ -375,7 +376,7 @@
 					"$(inherited)",
 					"@executable_path/../Frameworks",
 				);
-				MARKETING_VERSION = 0.1;
+				MARKETING_VERSION = 0.9.1;
 				PRODUCT_BUNDLE_IDENTIFIER = io.unom.punktfunk;
 				PRODUCT_NAME = "$(TARGET_NAME)";
 				SUPPORTED_PLATFORMS = macosx;
@@ -401,7 +402,8 @@
 				INFOPLIST_FILE = Config/Info.plist;
 				INFOPLIST_KEY_CFBundleDisplayName = Punktfunk;
 				INFOPLIST_KEY_GCSupportsControllerUserInteraction = YES;
-				INFOPLIST_KEY_LSApplicationCategoryType = "public.app-category.utilities";
+				INFOPLIST_KEY_GCSupportsGameMode = YES;
+				INFOPLIST_KEY_LSApplicationCategoryType = "public.app-category.games";
 				INFOPLIST_KEY_NSHumanReadableCopyright = "";
 				INFOPLIST_KEY_NSLocalNetworkUsageDescription = "Punktfunk connects directly to your punktfunk host on the local network to stream video, audio, and input.";
 				INFOPLIST_KEY_NSMicrophoneUsageDescription = "Your microphone is streamed to the connected punktfunk host, where it appears as a virtual microphone.";
@@ -410,7 +412,7 @@
 					"$(inherited)",
 					"@executable_path/../Frameworks",
 				);
-				MARKETING_VERSION = 0.1;
+				MARKETING_VERSION = 0.9.1;
 				PRODUCT_BUNDLE_IDENTIFIER = io.unom.punktfunk;
 				PRODUCT_NAME = "$(TARGET_NAME)";
 				SUPPORTED_PLATFORMS = macosx;
@@ -433,7 +435,8 @@
 				INFOPLIST_FILE = Config/Info.plist;
 				INFOPLIST_KEY_CFBundleDisplayName = Punktfunk;
 				INFOPLIST_KEY_GCSupportsControllerUserInteraction = YES;
-				INFOPLIST_KEY_LSApplicationCategoryType = "public.app-category.utilities";
+				INFOPLIST_KEY_GCSupportsGameMode = YES;
+				INFOPLIST_KEY_LSApplicationCategoryType = "public.app-category.games";
 				INFOPLIST_KEY_NSLocalNetworkUsageDescription = "Punktfunk connects directly to your punktfunk host on the local network to stream video, audio, and input.";
 				INFOPLIST_KEY_NSMicrophoneUsageDescription = "Your microphone is streamed to the connected punktfunk host, where it appears as a virtual microphone.";
 				INFOPLIST_KEY_UIApplicationSceneManifest_Generation = YES;
@@ -446,7 +449,7 @@
 					"$(inherited)",
 					"@executable_path/Frameworks",
 				);
-				MARKETING_VERSION = 0.1;
+				MARKETING_VERSION = 0.9.1;
 				PRODUCT_BUNDLE_IDENTIFIER = io.unom.punktfunk;
 				PRODUCT_NAME = "$(TARGET_NAME)";
 				SDKROOT = iphoneos;
@@ -473,7 +476,8 @@
 				INFOPLIST_FILE = Config/Info.plist;
 				INFOPLIST_KEY_CFBundleDisplayName = Punktfunk;
 				INFOPLIST_KEY_GCSupportsControllerUserInteraction = YES;
-				INFOPLIST_KEY_LSApplicationCategoryType = "public.app-category.utilities";
+				INFOPLIST_KEY_GCSupportsGameMode = YES;
+				INFOPLIST_KEY_LSApplicationCategoryType = "public.app-category.games";
 				INFOPLIST_KEY_NSLocalNetworkUsageDescription = "Punktfunk connects directly to your punktfunk host on the local network to stream video, audio, and input.";
 				INFOPLIST_KEY_NSMicrophoneUsageDescription = "Your microphone is streamed to the connected punktfunk host, where it appears as a virtual microphone.";
 				INFOPLIST_KEY_UIApplicationSceneManifest_Generation = YES;
@@ -486,7 +490,7 @@
 					"$(inherited)",
 					"@executable_path/Frameworks",
 				);
-				MARKETING_VERSION = 0.1;
+				MARKETING_VERSION = 0.9.1;
 				PRODUCT_BUNDLE_IDENTIFIER = io.unom.punktfunk;
 				PRODUCT_NAME = "$(TARGET_NAME)";
 				SDKROOT = iphoneos;
@@ -511,14 +515,14 @@
 				GENERATE_INFOPLIST_FILE = YES;
 				INFOPLIST_FILE = Config/Info.plist;
 				INFOPLIST_KEY_CFBundleDisplayName = Punktfunk;
-				INFOPLIST_KEY_LSApplicationCategoryType = "public.app-category.utilities";
+				INFOPLIST_KEY_LSApplicationCategoryType = "public.app-category.games";
 				INFOPLIST_KEY_NSLocalNetworkUsageDescription = "Punktfunk connects directly to your punktfunk host on the local network to stream video, audio, and input.";
 				INFOPLIST_KEY_UIApplicationSceneManifest_Generation = YES;
 				LD_RUNPATH_SEARCH_PATHS = (
 					"$(inherited)",
 					"@executable_path/Frameworks",
 				);
-				MARKETING_VERSION = 0.1;
+				MARKETING_VERSION = 0.9.1;
 				PRODUCT_BUNDLE_IDENTIFIER = io.unom.punktfunk;
 				PRODUCT_NAME = "$(TARGET_NAME)";
 				SDKROOT = appletvos;
@@ -541,14 +545,14 @@
 				GENERATE_INFOPLIST_FILE = YES;
 				INFOPLIST_FILE = Config/Info.plist;
 				INFOPLIST_KEY_CFBundleDisplayName = Punktfunk;
-				INFOPLIST_KEY_LSApplicationCategoryType = "public.app-category.utilities";
+				INFOPLIST_KEY_LSApplicationCategoryType = "public.app-category.games";
 				INFOPLIST_KEY_NSLocalNetworkUsageDescription = "Punktfunk connects directly to your punktfunk host on the local network to stream video, audio, and input.";
 				INFOPLIST_KEY_UIApplicationSceneManifest_Generation = YES;
 				LD_RUNPATH_SEARCH_PATHS = (
 					"$(inherited)",
 					"@executable_path/Frameworks",
 				);
-				MARKETING_VERSION = 0.1;
+				MARKETING_VERSION = 0.9.1;
 				PRODUCT_BUNDLE_IDENTIFIER = io.unom.punktfunk;
 				PRODUCT_NAME = "$(TARGET_NAME)";
 				SDKROOT = appletvos;

clients/apple/README.md

@@ -10,7 +10,8 @@ Opus audio, cert pinning — lives in the shared Rust **`punktfunk-core`** (stat
 
 ## Features
 
-- **Hardware decode** — VideoToolbox HEVC, with a low-latency **stage-2 presenter**
+- **Hardware decode** — VideoToolbox H.264/HEVC (plus **AV1** on devices with an AV1 hardware
+  decoder — M3-class Macs, A17 Pro-class iPhones), with a low-latency **stage-2 presenter**
   (`VTDecompressionSession` → `CAMetalLayer`, presented off a `CADisplayLink`, ~11 ms p50) as the
   default and an `AVSampleBufferDisplayLayer` fallback.
 - **HDR & 4:4:4** — PQ passthrough with a correct reference-white anchor, mid-session SDR↔HDR
@@ -22,8 +23,9 @@ Opus audio, cert pinning — lives in the shared Rust **`punktfunk-core`** (stat
 - **Full controller support** — one selected controller forwarded as pad 0, including **DualSense**
   feedback (rumble → CoreHaptics, lightbar, player LEDs, adaptive triggers) and touchpad/motion. The
   virtual pad type auto-resolves from your physical controller.
-- **Mouse & keyboard** — `GCMouse`/`GCKeyboard` capture with click-to-capture and a ⌘⎋ release, plus
-  iPad pointer lock and touch input.
+- **Mouse & keyboard** — `GCMouse`/`GCKeyboard` capture with click-to-capture and a ⌃⌥⇧Q release
+  (the cross-client Ctrl+Alt+Shift+Q; ⌘⎋ still works as the macOS/iPad toggle), plus iPad pointer
+  lock and touch input.
 - **Find hosts automatically** — mDNS discovery (`NWBrowser` over `_punktfunk._udp`); first connect
   does a one-time **SPAKE2 PIN pairing** (or TOFU on trusted LANs), then reconnects on a pinned,
   Keychain-stored identity.
@@ -83,7 +85,9 @@ PUNKTFUNK_AUTOCONNECT=<box-ip> PUNKTFUNK_MODE=1280x720x60 swift run PunktfunkCli
 - **`PunktfunkClient`** (the app) — hosts grid with an *On this network* section, add-host sheet,
   the two trust flows (TOFU prompt + SPAKE2 `PairSheet`), the stream view with the HUD, a
   tabbed Settings pane (General / Display / Audio / Controllers / Advanced), and the network speed
-  test. A Scene-level **Stream** menu carries Disconnect (⌘D) and the HUD toggle (⌘⇧S).
+  test. A Scene-level **Stream** menu carries the cross-client shortcut set: Release Mouse (⌃⌥⇧Q),
+  Disconnect (⌃⌥⇧D) and the HUD toggle (⌃⌥⇧S) — the same Ctrl+Alt+Shift combos the Windows and
+  Linux clients reserve, also shown on a 6-second banner at stream start.
   On iOS/iPadOS **and macOS** a connected controller swaps the whole home for the **gamepad UI**
   (`Home/Gamepad*`, `Settings/GamepadSettingsView`): a console-style host carousel (A connect · Y
   library · X settings), a controller-navigable settings screen, an add-host flow with an
@@ -118,7 +122,8 @@ PUNKTFUNK_AUTOCONNECT=<box-ip> PUNKTFUNK_MODE=1280x720x60 swift run PunktfunkCli
 - **App Store screenshots** are automated — `tools/screenshots.sh all` renders the real UI at the
   required pixel sizes via a DEBUG-only shot mode; the `apple` CI workflow captures the iOS sizes on
   every main push. See the script header for details.
-- Deeper design notes live in [`design/apple-stage2-presenter.md`](../../design/apple-stage2-presenter.md).
+- Deeper design notes live in the internal planning repo (punktfunk-planning:
+  `apple-stage2-presenter.md`).
 
 ## Related
 

clients/apple/Sources/PunktfunkClient/ContentView.swift

@@ -31,8 +31,15 @@ struct ContentView: View {
     @AppStorage(DefaultsKey.codec) private var codec = "auto"
     @AppStorage(DefaultsKey.hdrEnabled) private var hdrEnabled = true
     @AppStorage(DefaultsKey.fullscreenWhileStreaming) private var fullscreenWhileStreaming = true
-    @AppStorage(DefaultsKey.hudEnabled) private var hudEnabled = true
+    // The raw string is what @AppStorage observes (so cycles from any surface re-render this
+    // view); the absent-key default runs the legacy-hudEnabled migration once per init.
+    @AppStorage(DefaultsKey.statsVerbosity) private var statsVerbosityRaw
+        = StatsVerbosity.current.rawValue
     @AppStorage(DefaultsKey.hudPlacement) private var hudPlacement = HUDPlacement.topTrailing.rawValue
+    /// The persisted overlay tier (unknown raw falls back to .normal, like the migration).
+    private var statsVerbosity: StatsVerbosity {
+        StatsVerbosity(rawValue: statsVerbosityRaw) ?? .normal
+    }
     /// The `codec` setting as a `PUNKTFUNK_CODEC_*` soft-preference byte (`0` = auto).
     private var preferredCodecByte: UInt8 {
         switch codec {
@@ -55,19 +62,34 @@ struct ContentView: View {
     /// Wakes a sleeping host and waits for it to come back online before connecting (drives the
     /// "Waking…" overlay). macOS-only in practice — WoL is gated off on iOS/tvOS.
     @StateObject private var waker = HostWaker()
+    #if os(macOS)
+    /// Whether the hosting window is native-fullscreen right now (reported by
+    /// FullscreenController). Drives the session view's safe-area choice: fullscreen goes
+    /// edge-to-edge (behind the notch); windowed respects the top inset so the title bar
+    /// never covers the video.
+    @State private var isFullscreen = false
+    #endif
+    #if os(macOS) || os(tvOS)
+    /// Shows the start-of-stream shortcut banner (the Windows client's discoverability
+    /// pattern): raised on every transition to `.streaming`, dropped by the banner's own
+    /// 6-second task. Independent of the stats HUD so the keys are discoverable even with
+    /// statistics off. On tvOS it carries the ONLY exits (hold Back / the pad chord) plus
+    /// the remote-as-pointer controls, so it must be seen at least once per session.
+    @State private var showShortcutHint = false
+    #endif
     #if !os(macOS)
     @State private var showSettings = false
     #endif
-    #if os(iOS) || os(macOS)
     // A connected controller (+ the Settings toggle) swaps the whole home screen for
     // GamepadHomeView instead of retrofitting HomeView's touch/desktop UI — see `home` below.
+    // On tvOS the same screens are focus-engine-driven, so the Siri Remote keeps working;
+    // with no (extended) controller attached tvOS falls back to HomeView as before.
     @ObservedObject private var gamepadManager = GamepadManager.shared
     @AppStorage(DefaultsKey.gamepadUIEnabled) private var gamepadUIEnabled = true
     private var gamepadUIActive: Bool {
         GamepadUIEnvironment.isActive(
             gamepadConnected: gamepadManager.active != nil, enabledSetting: gamepadUIEnabled)
     }
-    #endif
 
     var body: some View {
         Group {
@@ -89,6 +111,9 @@ struct ContentView: View {
         .onChange(of: model.phase) { _, phase in
             switch phase {
             case .streaming:
+                #if os(macOS) || os(tvOS)
+                showShortcutHint = true // the 6 s shortcut banner, per session start
+                #endif
                 // A session actually started — remember it on the card ("Connected … ago"
                 // plus the accent ring on the most recent host).
                 guard let host = model.activeHost else { break }
@@ -115,7 +140,7 @@ struct ContentView: View {
             }
         }
         .onDisappear { model.disconnect() } // window closed mid-session (Cmd+N spawns more)
-        // Expose the session to the Scene-level Stream menu (Disconnect ⌘D works even when
+        // Expose the session to the Scene-level Stream menu (Disconnect ⌃⌥⇧D works even when
         // the HUD is hidden). tvOS has no such menu.
         #if !os(tvOS)
         .focusedSceneValue(\.sessionFocus, SessionFocus(
@@ -125,7 +150,12 @@ struct ContentView: View {
         #if os(macOS)
         // Fullscreen only while a session is up (incl. the trust prompt over the blurred stream),
         // windowed on the host list — so the picker isn't forced fullscreen. Opt-out in Settings.
-        .background(FullscreenController(active: fullscreenWhileStreaming && model.connection != nil))
+        // The controller also reports the window's ACTUAL fullscreen state back into
+        // `isFullscreen` (the user can toggle it manually), which drives the session view's
+        // safe-area handling below.
+        .background(FullscreenController(
+            active: fullscreenWhileStreaming && model.connection != nil,
+            isFullscreen: $isFullscreen))
         #endif
         // On the outer Group so the sheet survives the trust-prompt → home transition
         // (the "Pair with PIN instead" path disconnects first — the host's accept loop
@@ -188,7 +218,21 @@ struct ContentView: View {
         .alert(
             "Connection failed",
             isPresented: Binding(
-                get: { model.errorMessage != nil },
+                get: {
+                    guard model.errorMessage != nil else { return false }
+                    #if os(macOS)
+                    // Defer the alert while a forced-fullscreen exit is still pending: a sheet
+                    // attached to a fullscreen window makes AppKit drop `-toggleFullScreen:`, so
+                    // presenting it now strands the window fullscreen on the home screen after a
+                    // session error (a deliberate disconnect sets no `errorMessage`, which is why
+                    // it never stuck). Tearing the session down already flipped `active`→false;
+                    // once the window leaves fullscreen and `isFullscreen` flips, the alert shows
+                    // over the windowed home UI. Not gated when fullscreen is the user's own manual
+                    // choice (opt-out setting) — nothing is auto-exiting there to conflict with.
+                    if fullscreenWhileStreaming && isFullscreen { return false }
+                    #endif
+                    return true
+                },
                 set: { if !$0 { model.errorMessage = nil } })
         ) {
             Button("OK", role: .cancel) {}
@@ -237,13 +281,30 @@ struct ContentView: View {
                     onPaired: handlePaired, onLaunchTitle: launchTitle, wake: { wakeOnly($0) })
             }
         }
-        #elseif os(iOS)
+        #else
         Group {
             if gamepadUIActive {
                 GamepadHomeView(
                     store: store, model: model, discovery: discovery,
                     libraryTarget: $libraryTarget, waker: waker,
                     connect: { connect($0) }, connectDiscovered: connectDiscovered)
+                // On tvOS pairing/library normally present from HomeView's navigationDestinations
+                // — which aren't mounted while the gamepad launcher is up. Give the launcher its
+                // own presenters (exactly one of the two homes is mounted at a time, so these can
+                // never double-present against HomeView's routes). Menu closes a cover the same
+                // way B backs out elsewhere; PairSheet's own onDisappear cancels a live ceremony.
+                #if os(tvOS)
+                .fullScreenCover(item: $pairingTarget) { host in
+                    PairSheet(host: host) { fingerprint in handlePaired(host, fingerprint: fingerprint) }
+                        .onExitCommand { pairingTarget = nil }
+                }
+                .fullScreenCover(item: $libraryTarget) { host in
+                    NavigationStack {
+                        LibraryView(store: store, host: host, onLaunch: { launchTitle(host, $0) })
+                    }
+                    .onExitCommand { libraryTarget = nil }
+                }
+                #endif
             } else {
                 HomeView(
                     store: store, model: model, discovery: discovery,
@@ -254,14 +315,6 @@ struct ContentView: View {
                     onPaired: handlePaired, onLaunchTitle: launchTitle, wake: { wakeOnly($0) })
             }
         }
-        #else
-        HomeView(
-            store: store, model: model, discovery: discovery,
-            showAddHost: $showAddHost, pairingTarget: $pairingTarget,
-            speedTestTarget: $speedTestTarget, libraryTarget: $libraryTarget,
-            showSettings: $showSettings,
-            connect: { connect($0) }, connectDiscovered: connectDiscovered,
-            onPaired: handlePaired, onLaunchTitle: launchTitle, wake: { wakeOnly($0) })
         #endif
     }
 
@@ -274,12 +327,25 @@ struct ContentView: View {
         }()
         return ZStack {
             stream(captureEnabled: pendingFingerprint == nil)
-                .blur(radius: pendingFingerprint != nil ? 32 : 0)
+                // Blur the live stream during the trust prompt (heavy) and during a resize (lighter
+                // — the deliberate "hold on" while the host rebuilds its pipeline and the decoder
+                // re-inits on the new-mode IDR). Only the resize blur animates; the trust blur snaps
+                // as before (its own overlay handles the transition).
+                .blur(radius: pendingFingerprint != nil ? 32 : (model.resizing ? 16 : 0))
+                .animation(.easeInOut(duration: 0.22), value: model.resizing)
                 .overlay {
                     if pendingFingerprint != nil {
                         Color.black.opacity(0.45)
                     }
                 }
+                // The resize spinner rides over the (blurred) stream; suppressed under the trust
+                // prompt, which owns the screen. It never hit-tests, so window-drag resizes keep
+                // steering and the next click still reaches the stream.
+                .overlay {
+                    if pendingFingerprint == nil {
+                        ResizeIndicatorView(active: model.resizing)
+                    }
+                }
             if let fp = pendingFingerprint {
                 TrustCardView(
                     fingerprint: fp,
@@ -300,13 +366,17 @@ struct ContentView: View {
         #if os(macOS)
         .frame(minWidth: 640, minHeight: 360)
         .background(Color.black)
-        // Fill the whole display in fullscreen, INCLUDING behind the camera housing (notch).
+        // FULLSCREEN fills the whole display, INCLUDING behind the camera housing (notch).
         // Without this the stream is laid out in the safe area below the notch, so an
         // aspect-fit video at the display's native mode scales down and leaves black borders.
         // A fullscreen video behind the notch (a thin top-center strip occluded) is the
-        // expected behavior — same edge-to-edge intent as the iOS/tvOS branches below. Inert
-        // in windowed mode (no notch safe-area inset on a titled window).
-        .ignoresSafeArea()
+        // expected behavior — same edge-to-edge intent as the iOS/tvOS branches below.
+        // WINDOWED keeps the TOP inset: macOS 26 windows extend content under the (glass)
+        // title bar and report its height as top safe area — ignoring it there put the top of
+        // the video (and the HUD) underneath the title bar. The black `.background` above is a
+        // ShapeStyle background, which always extends under every inset, so the strip behind
+        // the title bar stays black rather than showing the video.
+        .ignoresSafeArea(edges: isFullscreen ? .all : [.horizontal, .bottom])
         #elseif os(iOS)
         // Streaming is immersive: edge-to-edge under the status bar and home
         // indicator, both hidden for the session (they return with the hosts grid).
@@ -317,11 +387,14 @@ struct ContentView: View {
         #else
         .background(Color.black)
         .ignoresSafeArea()
-        // Siri Remote MENU = disconnect (the idiomatic tvOS "back"). With no focusable
-        // disconnect control during play, the controller's buttons flow to the host instead of
-        // driving the focus engine. NOTE: a game controller's Menu is also forwarded to the
-        // host as Start — the Siri Remote is the intended disconnect path.
-        .onExitCommand { model.disconnect() }
+        // SWALLOW Menu/B during a session — a game controller's B button ALSO surfaces as this
+        // UIKit menu press, so the old instant-disconnect here ended the session on every B
+        // press in gameplay. The button still reaches the host via GamepadCapture; the
+        // DELIBERATE exits are holding the remote's Back ≥ 1 s (SiriRemotePointer) and holding
+        // L1+R1+Start+Select ≥ 1.5 s on a pad (GamepadCapture's escape chord), both surfaced by
+        // the start-of-stream banner. The empty handler is what keeps the press from bubbling
+        // out and suspending the app.
+        .onExitCommand {}
         #endif
     }
 
@@ -335,6 +408,9 @@ struct ContentView: View {
                     onCaptureChange: { [weak model] captured in
                         model?.mouseCaptured = captured
                     },
+                    onDisconnectRequest: { [weak model] in
+                        model?.disconnect() // the captured-state ⌃⌥⇧D combo
+                    },
                     onFrame: { [meter = model.meter, latency = model.latency,
                                 split = model.latencySplit, offset = conn.clockOffsetNs] au in
                         meter.note(byteCount: au.data.count)
@@ -347,27 +423,77 @@ struct ContentView: View {
                     onSessionEnd: { [weak model] in
                         Task { @MainActor in model?.sessionEnded() }
                     },
+                    // Resize overlay START — the follower is main-actor, so this drives the blur
+                    // + spinner synchronously the instant the window differs from the live mode.
+                    onResizeTarget: { [weak model] w, h in
+                        model?.resizeTargeted(width: w, height: h)
+                    },
+                    // Resize overlay END — the coded dims of each new-mode IDR, reported from the
+                    // decode pump thread; hop to the main actor to clear the overlay.
+                    onDecodedSize: { [weak model] w, h in
+                        Task { @MainActor in model?.resizeDecoded(width: w, height: h) }
+                    },
                     endToEndMeter: model.endToEnd,
                     decodeMeter: model.decodeStage,
                     displayMeter: model.displayStage
                 )
                 .overlay(alignment: placement.alignment) {
-                    if captureEnabled && hudEnabled {
-                        StreamHUDView(model: model, connection: conn, placement: placement)
+                    // The stats overlay MORPHS between tiers and SCALES UP on enter. With no `.id`, a
+                    // verbosity change keeps the same StreamHUDView identity, so its one shared glass
+                    // card animates its frame/shape to the new tier (a morph) instead of cross-fading a
+                    // fresh card in. The `.transition` therefore fires only on the off↔on boundary — a
+                    // scale-up (0.8→1) from the HUD's own corner. The ZStack is the stable host the
+                    // `.animation` watches as the child enters/leaves and morphs.
+                    ZStack {
+                        if captureEnabled && statsVerbosity != .off {
+                            StreamHUDView(
+                                model: model, connection: conn, placement: placement,
+                                verbosity: statsVerbosity)
+                                .transition(
+                                    .scale(scale: 0.8, anchor: placement.unitPoint)
+                                        .combined(with: .opacity))
+                        }
+                    }
+                    .animation(.smooth(duration: 0.28), value: statsVerbosity)
+                }
+                #if os(macOS) || os(tvOS)
+                // The start-of-stream shortcut banner (Windows-client parity): the platform's
+                // reserved controls on a glass pill, bottom-centre, for the first 6 seconds of
+                // every session — independent of the stats HUD, so the keys are discoverable
+                // even with statistics off. The banner's own task drops it (cancelled cleanly
+                // if the session view goes away first). On tvOS it carries the ONLY exits —
+                // Menu/B is swallowed during a session (the `.onExitCommand {}` in the tvOS
+                // session branch), so the hold gestures must be told to the user.
+                .overlay(alignment: .bottom) {
+                    if captureEnabled && showShortcutHint {
+                        Text(Self.shortcutHintText)
+                            .font(.geist(Self.shortcutHintFont, relativeTo: .caption))
+                            .foregroundStyle(.secondary)
+                            .padding(.horizontal, 14)
+                            .padding(.vertical, 8)
+                            .glassBackground(Capsule())
+                            .padding(.bottom, 24)
+                            .transition(.opacity)
+                            .task {
+                                try? await Task.sleep(for: .seconds(6))
+                                withAnimation(.easeOut(duration: 0.6)) { showShortcutHint = false }
+                            }
                     }
                 }
+                #endif
                 #if os(iOS)
-                // Touch users have no menu / ⌘D, so when the HUD (and its Disconnect button)
-                // is hidden, keep a minimal always-reachable exit in a corner. It rides a
-                // material disc (like the HUD) so the glyph stays legible over a bright frame
-                // — this is the sole touch disconnect path when stats are off.
+                // Touch users have no menu / ⌘D, so when the HUD's Disconnect button isn't on
+                // screen — the overlay off, or the compact pill (which carries no button) —
+                // keep a minimal always-reachable exit in a corner. It rides a material disc
+                // (like the HUD) so the glyph stays legible over a bright frame — this is the
+                // sole touch disconnect path in those tiers.
                 .overlay(alignment: .topLeading) {
-                    if captureEnabled && !hudEnabled {
+                    if captureEnabled && (statsVerbosity == .off || statsVerbosity == .compact) {
                         Button { model.disconnect() } label: {
                             Image(systemName: "xmark")
                                 .font(.headline.weight(.semibold))
                                 .frame(width: 36, height: 36)
-                                // Sole touch exit when the HUD is off — a floating glass disc
+                                // Sole touch exit in the off/compact tiers — a floating glass disc
                                 // over the frame (26+, material fallback). interactive: the disc
                                 // IS the tap target, so the glass reacts to press.
                                 .glassBackground(Circle(), interactive: true)
@@ -385,6 +511,17 @@ struct ContentView: View {
         }
     }
 
+    #if os(macOS)
+    private static let shortcutHintText =
+        "Click the stream to capture · ⌃⌥⇧Q releases the mouse · ⌃⌥⇧D disconnects · ⌃⌥⇧S stats"
+    private static let shortcutHintFont: CGFloat = 12
+    #elseif os(tvOS)
+    private static let shortcutHintText =
+        "Hold the remote's Back button — or L1+R1+Start+Select on a controller — to disconnect"
+        + " · Touch surface moves the pointer · press clicks · Play/Pause right-clicks"
+    private static let shortcutHintFont: CGFloat = 22 // read from the couch
+    #endif
+
     // MARK: - Connect
 
     private func connect(_ host: StoredHost, launchID: String? = nil, allowTofu: Bool? = nil) {
@@ -422,14 +559,24 @@ struct ContentView: View {
                 host, launchID: launchID, allowTofu: allowTofu,
                 requestAccess: requestAccess, approvalReq: approvalReq)
         }
-        // Asleep (not advertising) and we can wake it? Fire the magic packet and WAIT for it to come
-        // back online — a cold box takes far longer to boot than a connect will sit — showing the
-        // "Waking…" overlay meanwhile. Then connect. Otherwise dial straight away.
+        // Not advertising and we can wake it? DIAL FIRST anyway — no mDNS advert does NOT mean
+        // unreachable: a host reached over a routed network (Tailscale/VPN/another subnet) is
+        // mDNS-blind forever, and gating the dial on presence bricked exactly those reconnects
+        // (the host log shows no connection attempt at all; the tile pip and this gate share the
+        // LAN-only `advertises` predicate). `prepareWake` inside the dial already fires the magic
+        // packet up front, so a genuinely-asleep host is waking while the connect times out; only
+        // when that dial FAILS do we fall into the visible "Waking…" wait — a cold box takes far
+        // longer to boot than a connect will sit — and redial once it's back on mDNS.
         if PunktfunkConnection.wakeOnLANAvailable, !host.wakeMacs.isEmpty, !discovery.advertises(host) {
-            discovery.start() // so we can observe it reappear
-            waker.start(
-                host: host, connectsAfter: true, macs: host.wakeMacs, lastIP: host.address,
-                isOnline: { discovery.advertises(host) }, onOnline: go)
+            discovery.start() // so the wake-wait can observe it reappear
+            startSessionDirect(
+                host, launchID: launchID, allowTofu: allowTofu,
+                requestAccess: requestAccess, approvalReq: approvalReq,
+                onUnreachable: {
+                    waker.start(
+                        host: host, connectsAfter: true, macs: host.wakeMacs, lastIP: host.address,
+                        isOnline: { discovery.advertises(host) }, onOnline: go)
+                })
         } else {
             go()
         }
@@ -437,10 +584,12 @@ struct ContentView: View {
 
     /// The actual dial — reached directly when the host is awake, or from the waker once a woken
     /// host is back online. `prepareWake` still runs here to LEARN/refresh the MAC now that the host
-    /// is advertising (and is a harmless no-op otherwise).
+    /// is advertising (and is a harmless no-op otherwise). `onUnreachable` hands a plain connect
+    /// failure back to the caller (the wake-wait fallback) instead of the error alert.
     private func startSessionDirect(
         _ host: StoredHost, launchID: String? = nil,
-        allowTofu: Bool, requestAccess: Bool = false, approvalReq: ApprovalRequest? = nil
+        allowTofu: Bool, requestAccess: Bool = false, approvalReq: ApprovalRequest? = nil,
+        onUnreachable: (@MainActor () -> Void)? = nil
     ) {
         prepareWake(for: host)
         // The delegated-approval wait prompt only makes sense once we're actually dialing — set it
@@ -461,7 +610,8 @@ struct ContentView: View {
             preferredCodec: preferredCodecByte,
             launchID: launchID,
             allowTofu: allowTofu,
-            requestAccess: requestAccess)
+            requestAccess: requestAccess,
+            onUnreachable: onUnreachable)
     }
 
     /// Learn-while-awake, wake-while-asleep — run just before every connect:
@@ -641,23 +791,62 @@ struct ContentView: View {
 }
 
 #if os(macOS)
-/// Drives the hosting window in/out of native fullscreen from SwiftUI state. Mounted invisibly in
-/// the view tree; on each `active` change it captures the window and toggles fullscreen only when
-/// the current state differs (so it never fights a toggle already in flight, and never touches a
-/// window the user fullscreened manually unless `active` says otherwise).
+/// Drives the hosting window in/out of native fullscreen from SwiftUI state, and mirrors the
+/// window's ACTUAL fullscreen state back into `isFullscreen` (the user can also toggle it with the
+/// green button / ⌃⌘F — ContentView keys the session view's safe-area handling off the real state,
+/// not the setting). Mounted invisibly in the view tree; on each `active` change it captures the
+/// window and toggles fullscreen only when the current state differs (so it never fights a toggle
+/// already in flight, and never touches a window the user fullscreened manually unless `active`
+/// says otherwise).
 private struct FullscreenController: NSViewRepresentable {
     let active: Bool
+    @Binding var isFullscreen: Bool
+
+    /// Holds the window's fullscreen-transition observers so they're rebound on a window change
+    /// and removed on dismantle.
+    final class Coordinator {
+        var observers: [NSObjectProtocol] = []
+        weak var observedWindow: NSWindow?
+        deinit { observers.forEach(NotificationCenter.default.removeObserver(_:)) }
+    }
+
+    func makeCoordinator() -> Coordinator { Coordinator() }
 
     func makeNSView(context: Context) -> NSView { NSView() }
 
     func updateNSView(_ view: NSView, context: Context) {
         let want = active
+        let isFullscreen = $isFullscreen
+        let coordinator = context.coordinator
         DispatchQueue.main.async {
             guard let window = view.window else { return }
+            observeTransitions(of: window, coordinator: coordinator)
             let isFull = window.styleMask.contains(.fullScreen)
+            if isFullscreen.wrappedValue != isFull { isFullscreen.wrappedValue = isFull }
             if want != isFull { window.toggleFullScreen(nil) }
         }
     }
+
+    /// `willEnter` (not did) so the video goes edge-to-edge while the title bar is already
+    /// animating away; `didExit` so the top inset returns only once the title bar is back —
+    /// no black gap in either direction.
+    private func observeTransitions(of window: NSWindow, coordinator: Coordinator) {
+        guard coordinator.observedWindow !== window else { return }
+        coordinator.observers.forEach(NotificationCenter.default.removeObserver(_:))
+        coordinator.observers.removeAll()
+        coordinator.observedWindow = window
+        let isFullscreen = $isFullscreen
+        for (name, value) in [
+            (NSWindow.willEnterFullScreenNotification, true),
+            (NSWindow.didExitFullScreenNotification, false),
+        ] {
+            coordinator.observers.append(NotificationCenter.default.addObserver(
+                forName: name, object: window, queue: .main
+            ) { _ in
+                isFullscreen.wrappedValue = value
+            })
+        }
+    }
 }
 #endif
 

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

@@ -1,13 +1,15 @@
-// The gamepad-driven "Add Host" screen (iOS/iPadOS/macOS) — the controller counterpart of
+// The gamepad-driven "Add Host" screen (iOS/iPadOS/macOS/tvOS) — the controller counterpart of
 // AddHostSheet, reached from the launcher's Add Host tile. Three field rows (name / address /
 // port) plus the Add action, navigated with the same vertical focus list as the gamepad settings;
 // A on a field opens GamepadKeyboard in a bottom tray, so a host can be registered end to end
 // without touching the screen. Field edits are live (the row shows every keystroke); B closes the
 // keyboard first, then cancels the screen — the same "back peels one layer" rule as a console UI.
+// tvOS swaps the custom keyboard tray for the SYSTEM fullscreen keyboard (TVTextEntry): unlike
+// iOS/macOS, tvOS HAS a first-class controller/remote-drivable text entry, so the native one wins.
 
 import PunktfunkKit
 import SwiftUI
-#if os(iOS) || os(macOS)
+#if os(iOS) || os(macOS) || os(tvOS)
 
 struct GamepadAddHostView: View {
     @Environment(\.dismiss) private var dismiss
@@ -37,22 +39,22 @@ struct GamepadAddHostView: View {
             isActive: editing == nil
         ) { row, focused in
             rowView(row, focused: focused)
-                .frame(maxWidth: 620)
+                .frame(maxWidth: GamepadFormMetrics.rowMaxWidth)
                 .padding(.horizontal, 24)
         }
         .frame(maxWidth: .infinity)
         .safeAreaInset(edge: .top, spacing: 0) {
             VStack(spacing: 4) {
                 Text("Add Host")
-                    .font(.geist(compact ? 20 : 30, .bold, relativeTo: .title))
+                    .font(.geist(gamepadTitleSize(compact: compact), .bold, relativeTo: .title))
                     .foregroundStyle(.white)
                 if !compact {
                     Text("Hosts on this network appear automatically — add one by address "
                         + "for everything else.")
-                        .font(.geist(13, relativeTo: .caption))
+                        .font(.geist(GamepadFormMetrics.detailFont, relativeTo: .caption))
                         .foregroundStyle(.white.opacity(0.55))
                         .multilineTextAlignment(.center)
-                        .frame(maxWidth: 440)
+                        .frame(maxWidth: GamepadFormMetrics.rowMaxWidth * 0.72)
                 }
             }
             .padding(.top, gamepadTitleTopPadding(compact: compact))
@@ -75,10 +77,38 @@ struct GamepadAddHostView: View {
         .onChange(of: port) { _, value in
             if value.count > 5 { port = String(value.prefix(5)) }
         }
+        #if os(tvOS)
+        // tvOS types with the SYSTEM fullscreen keyboard (TVTextEntry) instead of the custom
+        // tray — the remote and the pad both drive it natively. Same `editing` state as the
+        // tray, just a different presentation; done (or Menu, edits-stick) commits and returns.
+        .fullScreenCover(isPresented: Binding(
+            get: { editing != nil },
+            set: { if !$0 { editing = nil } })
+        ) {
+            if let field = editing {
+                TVTextEntry(
+                    title: fieldTitle(field),
+                    text: editingBinding(field).wrappedValue,
+                    keyboardType: keyboardType(field)
+                ) { value in
+                    commitEntry(field, value)
+                    editing = nil
+                }
+            }
+        }
+        #endif
     }
 
-    /// The keyboard tray while editing, the controls legend otherwise.
+    /// The keyboard tray while editing, the controls legend otherwise. (tvOS never shows the
+    /// tray — `editing` presents the system keyboard cover instead — so it's legend-only there.)
     @ViewBuilder private var bottomTray: some View {
+        #if os(tvOS)
+        GamepadHintBar(hints: [
+            .init(glyph: buttonGlyph(\.buttonA, fallback: "a.circle"), text: "Select"),
+            .init(glyph: buttonGlyph(\.buttonB, fallback: "b.circle"), text: "Cancel"),
+        ])
+        .frame(maxWidth: .infinity, alignment: .leading)
+        #else
         if let editing {
             VStack(spacing: 10) {
                 GamepadKeyboard(
@@ -104,6 +134,7 @@ struct GamepadAddHostView: View {
             ])
             .frame(maxWidth: .infinity, alignment: .leading)
         }
+        #endif
     }
 
     /// Touch/click fallback for closing — the controller path is B, a hardware keyboard's Esc
@@ -111,14 +142,16 @@ struct GamepadAddHostView: View {
     private var closeButton: some View {
         Button { dismiss() } label: {
             Image(systemName: "xmark")
-                .font(.system(size: 14, weight: .semibold))
+                .font(.system(size: GamepadFormMetrics.closeFont, weight: .semibold))
                 .foregroundStyle(.white)
-                .frame(width: 34, height: 34)
+                .frame(width: GamepadFormMetrics.closeSide, height: GamepadFormMetrics.closeSide)
                 .glassBackground(Circle(), interactive: true)
                 .contentShape(Circle())
         }
         .buttonStyle(.plain)
-        .keyboardShortcut(.cancelAction)
+        #if !os(tvOS)
+        .keyboardShortcut(.cancelAction) // unavailable on tvOS (Menu is the cancel there)
+        #endif
         .accessibilityLabel("Cancel")
     }
 
@@ -142,19 +175,20 @@ struct GamepadAddHostView: View {
     }
 
     private func rowView(_ row: Row, focused: Bool) -> some View {
-        HStack(spacing: 14) {
+        let m = GamepadFormMetrics.self
+        return HStack(spacing: 14) {
             if row.isAction {
                 Label("Add Host", systemImage: "plus.circle.fill")
-                    .font(.geist(16, .semibold, relativeTo: .body))
+                    .font(.geist(m.labelFont, .semibold, relativeTo: .body))
                     .foregroundStyle(canAdd ? Color.brand : .white.opacity(0.35))
                     .frame(maxWidth: .infinity)
             } else {
                 Text(row.label)
-                    .font(.geist(16, .semibold, relativeTo: .body))
+                    .font(.geist(m.labelFont, .semibold, relativeTo: .body))
                     .foregroundStyle(.white)
                 Spacer(minLength: 12)
                 Text(row.value.isEmpty ? row.placeholder : row.value)
-                    .font(.geistFixed(15, .medium))
+                    .font(.geistFixed(m.valueFont, .medium))
                     .foregroundStyle(row.value.isEmpty ? .white.opacity(0.35) : .white)
                     .lineLimit(1)
                     .truncationMode(.head) // keep the end of a long address visible while typing
@@ -162,20 +196,20 @@ struct GamepadAddHostView: View {
                     // The live-edit caret: this row is what the keyboard tray is typing into.
                     Rectangle()
                         .fill(Color.brand)
-                        .frame(width: 2, height: 18)
+                        .frame(width: 2, height: m.labelFont + 2)
                 }
             }
         }
-        .padding(.horizontal, 16)
-        .padding(.vertical, 13)
+        .padding(.horizontal, m.rowHPad)
+        .padding(.vertical, m.rowVPad)
         // Liquid Glass rows, matching the settings screen; the focused (or actively edited) row
         // takes the brand wash, and the edited row keeps its brand caret border.
         .consoleGlass(
-            RoundedRectangle(cornerRadius: 14, style: .continuous),
+            RoundedRectangle(cornerRadius: m.rowCorner, style: .continuous),
             tint: (focused || editing == row.id) ? Color.brand.opacity(0.30) : nil,
             interactive: focused)
         .overlay {
-            RoundedRectangle(cornerRadius: 14, style: .continuous)
+            RoundedRectangle(cornerRadius: m.rowCorner, style: .continuous)
                 .strokeBorder(
                     editing == row.id ? Color.brand.opacity(0.7) : .white.opacity(focused ? 0.28 : 0.06),
                     lineWidth: 1)
@@ -235,5 +269,41 @@ struct GamepadAddHostView: View {
         default: return nil
         }
     }
+
+    #if os(tvOS)
+    // MARK: - System keyboard plumbing (see the fullScreenCover on `body`)
+
+    private func fieldTitle(_ id: String) -> String {
+        switch id {
+        case "name": return "Name (optional)"
+        case "port": return "Port"
+        default: return "Address (IP or hostname)"
+        }
+    }
+
+    /// .URL for the address (dots on the primary layer, no autocapitalize) — the closest tvOS
+    /// keyboard to "hostname or IP".
+    private func keyboardType(_ id: String) -> UIKeyboardType {
+        switch id {
+        case "port": return .numberPad
+        case "address": return .URL
+        default: return .default
+        }
+    }
+
+    /// Apply a system-keyboard result, enforcing what `allowedCharacters` enforces per keystroke
+    /// on the other platforms (the system keyboard will type anything).
+    private func commitEntry(_ id: String, _ value: String) {
+        switch id {
+        case "port":
+            editingBinding(id).wrappedValue = String(value.filter(\.isNumber).prefix(5))
+        case "address":
+            editingBinding(id).wrappedValue = value
+                .replacingOccurrences(of: " ", with: "")
+        default:
+            editingBinding(id).wrappedValue = value
+        }
+    }
+    #endif
 }
 #endif

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

@@ -1,6 +1,11 @@
 // The one piece of gamepad-menu machinery shared by the host launcher (GamepadHomeView) and the
 // library coverflow (LibraryCoverflowView): a horizontal, center-snapping carousel driven entirely
-// by a controller (iOS/iPadOS/macOS).
+// by a controller (iOS/iPadOS/macOS) — or, on tvOS, by the NATIVE FOCUS ENGINE: every card is a
+// focusable Button, so the Siri Remote and a game controller both navigate through the system
+// (dpad/swipe moves focus, select activates, Menu backs out at the presentation level), and the
+// cursor/scroll chase the focused card instead of the poll. The poll still runs on tvOS but
+// carries ONLY the Y/X actions (library/settings) — buttons the focus engine has no concept of.
+// The iOS/macOS poll-driven behavior is untouched by the tvOS mode.
 //
 // The scrolling is pure native SwiftUI — `.scrollTargetLayout()` + `.scrollTargetBehavior(.viewAligned)`
 // snap exactly one item to center, and symmetric `.safeAreaPadding(.horizontal)` (sized off the live
@@ -24,7 +29,7 @@
 
 import PunktfunkKit
 import SwiftUI
-#if os(iOS) || os(macOS)
+#if os(iOS) || os(macOS) || os(tvOS)
 
 struct GamepadCarousel<Item: Identifiable, Card: View>: View where Item.ID: Hashable {
     let items: [Item]
@@ -54,6 +59,11 @@ struct GamepadCarousel<Item: Identifiable, Card: View>: View where Item.ID: Hash
 
     @State private var input = GamepadMenuInput(manager: .shared)
     @State private var haptics = MenuHaptics(manager: .shared)
+    #if os(tvOS)
+    /// tvOS: the focus engine is the navigation authority — `cursor`/`scrolledID` chase this,
+    /// never the other way around (mirroring the poll's cursor-first discipline).
+    @FocusState private var focusedID: Item.ID?
+    #endif
     /// Authoritative gamepad cursor (index into `items`). Never assigned from scroll read-back
     /// while the gamepad is driving — that's the whole desync fix.
     @State private var cursor = 0
@@ -81,26 +91,72 @@ struct GamepadCarousel<Item: Identifiable, Card: View>: View where Item.ID: Hash
     var body: some View {
         GeometryReader { geo in
             let inset = max(0, (geo.size.width - itemWidth) / 2)
-            ScrollView(.horizontal) {
-                HStack(spacing: spacing) {
-                    ForEach(items) { item in
-                        card(item)
-                            .frame(width: itemWidth)
-                            .contentShape(Rectangle())
-                            .onTapGesture { tap(item) }
+            ScrollViewReader { proxy in
+                ScrollView(.horizontal) {
+                    HStack(spacing: spacing) {
+                        ForEach(items) { item in
+                            #if os(tvOS)
+                            // A focusable Button per card: the focus engine does the navigating
+                            // (remote swipes and pad dpad alike), select activates. The bare style
+                            // below keeps the tile's own look — the `.scrollTransition` center pop
+                            // is the focus treatment, since focus and center track each other.
+                            Button { activate(item) } label: {
+                                card(item)
+                                    .frame(width: itemWidth)
+                            }
+                            .buttonStyle(ConsoleBareButtonStyle())
+                            .focused($focusedID, equals: item.id)
+                            .id(item.id)
+                            #else
+                            card(item)
+                                .frame(width: itemWidth)
+                                .contentShape(Rectangle())
+                                .onTapGesture { tap(item) }
+                            #endif
+                        }
+                    }
+                    .frame(height: geo.size.height) // fill so shorter cards center vertically
+                    .scrollTargetLayout()
+                }
+                // The two-way `.scrollPosition` + snap machinery serves the POLL/touch platforms.
+                // Not on tvOS: that binding DROPS a write landing mid-animation (the very desync
+                // the poll's cursor design exists to avoid — see the header), and on tvOS the
+                // focus engine's own reveal-scrolls are always in flight, so drops were routine
+                // ("navigation not reflected in the scroll view"). tvOS scrolls imperatively
+                // below instead — scrollTo RE-TARGETS mid-animation (the GamepadMenuList pattern).
+                #if !os(tvOS)
+                .scrollPosition(id: $scrolledID)
+                .scrollTargetBehavior(.viewAligned)
+                #endif
+                // .never, not .hidden — macOS's "always show scroll bars" setting overrides .hidden
+                // and paints a scroller across the console strip.
+                .scrollIndicators(.never)
+                .scrollClipDisabled() // let the focused card scale up past the strip bounds
+                .safeAreaPadding(.horizontal, inset)
+                .offset(x: bumpOffset)
+                #if os(tvOS)
+                // Land initial focus on the first card (the launcher's first host / the coverflow's
+                // first title) instead of wherever the engine guesses.
+                .defaultFocus($focusedID, items.first?.id)
+                // Focus moved (remote swipe / pad dpad) — chase it: cursor, detail selection,
+                // controller detent, and an imperative center scroll.
+                .onChange(of: focusedID) { _, newValue in
+                    guard let idx = index(of: newValue), idx != cursor else { return }
+                    cursor = idx
+                    lastNav = Date()
+                    haptics.move()
+                    selection = newValue
+                    withAnimation(.easeOut(duration: scrollAnim)) {
+                        proxy.scrollTo(newValue, anchor: .center)
                     }
                 }
-                .frame(height: geo.size.height) // fill so shorter cards center vertically
-                .scrollTargetLayout()
+                // The list changed under a stable focus (discovered hosts prepend tiles): the
+                // content shifted but no focus change fires above — re-center the focused card.
+                .onChange(of: items.map(\.id)) { _, _ in
+                    if let id = focusedID { proxy.scrollTo(id, anchor: .center) }
+                }
+                #endif
             }
-            .scrollPosition(id: $scrolledID)
-            .scrollTargetBehavior(.viewAligned)
-            // .never, not .hidden — macOS's "always show scroll bars" setting overrides .hidden
-            // and paints a scroller across the console strip.
-            .scrollIndicators(.never)
-            .scrollClipDisabled() // let the focused card scale up past the strip bounds
-            .safeAreaPadding(.horizontal, inset)
-            .offset(x: bumpOffset)
         }
         .sensoryFeedback(.selection, trigger: cursor)
         .sensoryFeedback(.impact(weight: .medium), trigger: activateTick)
@@ -128,13 +184,16 @@ struct GamepadCarousel<Item: Identifiable, Card: View>: View where Item.ID: Hash
         // A touch drag settles the scroll onto a new id: adopt it as the cursor. Ignored while a
         // programmatic scroll is animating (its own intermediate id write-backs would regress the
         // cursor) and briefly after a gamepad move (the same reason), so only a genuine touch drag
-        // — which never sets `isScrolling` — moves the cursor here.
+        // — which never sets `isScrolling` — moves the cursor here. Not on tvOS: there is no touch
+        // drag, and the focus engine's own reveal-scrolls must never steal the cursor from focus.
+        #if !os(tvOS)
         .onChange(of: scrolledID) { _, newValue in
             guard !isScrolling, Date().timeIntervalSince(lastNav) > navSettle else { return }
             guard let idx = index(of: newValue), idx != cursor else { return }
             cursor = idx
             selection = newValue
         }
+        #endif
         // Re-seed a dropped/changed selection AND re-wire the input callbacks so they capture the
         // current `items` value (a plain array — unlike an observed object it would otherwise go
         // stale in the closures stored on `input`).
@@ -147,12 +206,20 @@ struct GamepadCarousel<Item: Identifiable, Card: View>: View where Item.ID: Hash
     // MARK: - Input wiring
 
     private func wire() {
+        #if os(tvOS)
+        // The focus engine owns move/confirm/back on tvOS (that's what keeps the Siri Remote
+        // working on this screen — and what routes Menu through the system's back semantics).
+        // The poll carries only the buttons focus has no concept of: Y/X, the screen actions.
+        input.onSecondary = onSecondary
+        input.onTertiary = onTertiary
+        #else
         input.onMove = { move($0) }
         input.onConfirm = { activate() }
         input.onSecondary = onSecondary
         input.onTertiary = onTertiary
         input.onBack = onBack
         input.onShoulder = shoulderJump > 0 ? { shoulder(right: $0) } : nil
+        #endif
     }
 
     private func move(_ direction: GamepadMenuInput.Direction) {
@@ -212,9 +279,14 @@ struct GamepadCarousel<Item: Identifiable, Card: View>: View where Item.ID: Hash
 
     private func activate() {
         guard cursor >= 0, cursor < items.count else { return }
+        activate(items[cursor])
+    }
+
+    /// Shared confirm tail — the poll activates the cursor's item, a tvOS Button its own.
+    private func activate(_ item: Item) {
         activateTick &+= 1
         haptics.confirm()
-        onActivate(items[cursor])
+        onActivate(item)
     }
 
     /// Touch fallback matching the rest of the app: tapping the centered card activates it, tapping
@@ -257,6 +329,13 @@ struct GamepadCarousel<Item: Identifiable, Card: View>: View where Item.ID: Hash
             scrolledID = id
             selection = id
         }
+        #if os(tvOS)
+        // Keep real focus on the reconciled item when its old target vanished from the list —
+        // the engine would otherwise pick a neighbour by geometry and drag the cursor with it.
+        if focusedID == nil || index(of: focusedID) == nil, cursor < items.count {
+            focusedID = items[cursor].id
+        }
+        #endif
     }
 
     private func boundaryBump(forward: Bool) {

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

@@ -2,11 +2,12 @@
 // GamepadAddHostView, LibraryCoverflowView): the full-bleed console backdrop, the
 // controller-glyph hint bar, and the connected-controller status chip. One look across every
 // screen is what makes the gamepad UI read as a coherent mode rather than a set of themed pages.
-// iOS/iPadOS and macOS (the couch Mac-mini case); tvOS keeps its native focus engine instead.
+// iOS/iPadOS, macOS (the couch Mac-mini case), and tvOS — where the same screens are driven by
+// the native focus engine instead of the controller poll (see GamepadCarousel/GamepadMenuList).
 
 import PunktfunkKit
 import SwiftUI
-#if os(iOS) || os(macOS)
+#if os(iOS) || os(macOS) || os(tvOS)
 import GameController
 
 /// The active controller's real glyph for a button (Xbox "A", DualSense ✕, …) via
@@ -31,6 +32,51 @@ func gamepadTitleTopPadding(compact: Bool) -> CGFloat {
     #endif
 }
 
+/// Point size for a gamepad screen's pinned title: TV-large on tvOS (read from the couch), the
+/// in-hand compact-aware sizes elsewhere.
+func gamepadTitleSize(compact: Bool) -> CGFloat {
+    #if os(tvOS)
+    44
+    #else
+    compact ? 20 : 30
+    #endif
+}
+
+/// Metrics shared by the gamepad form screens' glass rows (GamepadSettingsView,
+/// GamepadAddHostView) — one set of numbers so the two screens read as the same surface,
+/// sized for the couch on tvOS and for the hand elsewhere.
+enum GamepadFormMetrics {
+    #if os(tvOS)
+    static let headerFont: CGFloat = 17
+    static let labelFont: CGFloat = 23
+    static let valueFont: CGFloat = 21
+    static let iconFont: CGFloat = 24
+    static let iconWidth: CGFloat = 40
+    static let chevronFont: CGFloat = 16
+    static let rowHPad: CGFloat = 24
+    static let rowVPad: CGFloat = 19
+    static let rowCorner: CGFloat = 18
+    static let rowMaxWidth: CGFloat = 920
+    static let detailFont: CGFloat = 19
+    static let closeFont: CGFloat = 20
+    static let closeSide: CGFloat = 48
+    #else
+    static let headerFont: CGFloat = 12
+    static let labelFont: CGFloat = 16
+    static let valueFont: CGFloat = 15
+    static let iconFont: CGFloat = 17
+    static let iconWidth: CGFloat = 28
+    static let chevronFont: CGFloat = 12
+    static let rowHPad: CGFloat = 16
+    static let rowVPad: CGFloat = 13
+    static let rowCorner: CGFloat = 14
+    static let rowMaxWidth: CGFloat = 620
+    static let detailFont: CGFloat = 13
+    static let closeFont: CGFloat = 14
+    static let closeSide: CGFloat = 34
+    #endif
+}
+
 /// One glyph + label cell in a hint bar.
 struct GamepadHint: Identifiable {
     let glyph: String
@@ -45,21 +91,32 @@ struct GamepadHint: Identifiable {
 struct GamepadHintBar: View {
     let hints: [GamepadHint]
 
+    // 10-foot legend on tvOS, in-hand sizes elsewhere.
+    #if os(tvOS)
+    private static let glyphFont: CGFloat = 27
+    private static let textFont: CGFloat = 20
+    private static let pad: CGFloat = 18
+    #else
+    private static let glyphFont: CGFloat = 19
+    private static let textFont: CGFloat = 14
+    private static let pad: CGFloat = 13
+    #endif
+
     var body: some View {
         HStack(spacing: 18) {
             ForEach(hints) { hint in
                 HStack(spacing: 7) {
                     Image(systemName: hint.glyph)
-                        .font(.system(size: 19))
+                        .font(.system(size: Self.glyphFont))
                         .foregroundStyle(.white)
                     Text(hint.text)
                 }
                 .fixedSize() // keep glyph + label together; never truncate a hint mid-word
             }
         }
-        .font(.geist(14, .semibold, relativeTo: .subheadline))
+        .font(.geist(Self.textFont, .semibold, relativeTo: .subheadline))
         .foregroundStyle(.white.opacity(0.85))
-        .padding(13)
+        .padding(Self.pad)
         .consoleGlass(Capsule())
         .overlay(Capsule().strokeBorder(.white.opacity(0.12), lineWidth: 1))
     }
@@ -297,30 +354,56 @@ struct GamepadFormBackground: View {
     }
 }
 
+#if os(tvOS)
+/// Bare chrome for the focusable console Buttons (carousel cards, menu-list rows) on tvOS: the
+/// tile/row draws its own look and the screen's own focus treatment marks the focused element
+/// (the carousel's `.scrollTransition` center pop, the list row's `focused` styling), so the
+/// system's lift/halo would double up on it. Press feedback is a small dip, matching the
+/// interactive-glass feel elsewhere.
+struct ConsoleBareButtonStyle: ButtonStyle {
+    func makeBody(configuration: Configuration) -> some View {
+        configuration.label
+            .scaleEffect(configuration.isPressed ? 0.97 : 1)
+            .animation(.smooth(duration: 0.15), value: configuration.isPressed)
+    }
+}
+#endif
+
 /// "Which pad is driving this UI" — the active controller's name and battery, worn as a quiet
 /// chip in the launcher's top bar. Callers observe GamepadManager already, so this re-renders
 /// when the pad or its battery state changes.
 struct ControllerStatusChip: View {
     let controller: GamepadManager.DiscoveredController
 
+    // Legible from the couch on tvOS, quiet in hand elsewhere.
+    #if os(tvOS)
+    private static let font: CGFloat = 17
+    private static let hPad: CGFloat = 16
+    private static let vPad: CGFloat = 10
+    #else
+    private static let font: CGFloat = 12
+    private static let hPad: CGFloat = 12
+    private static let vPad: CGFloat = 7
+    #endif
+
     var body: some View {
         HStack(spacing: 7) {
             Image(systemName: controller.hasTouchpadAndMotion
                 ? "playstation.logo" : "gamecontroller.fill")
-                .font(.system(size: 12))
+                .font(.system(size: Self.font))
             Text(controller.name)
                 .lineLimit(1)
             if let level = controller.batteryLevel {
                 Image(systemName: batterySymbol(level))
-                    .font(.system(size: 12))
+                    .font(.system(size: Self.font))
                     .foregroundStyle(level <= 0.2 && !controller.isCharging
                         ? AnyShapeStyle(.red) : AnyShapeStyle(.white.opacity(0.7)))
             }
         }
-        .font(.geist(12, .medium, relativeTo: .caption))
+        .font(.geist(Self.font, .medium, relativeTo: .caption))
         .foregroundStyle(.white.opacity(0.7))
-        .padding(.horizontal, 12)
-        .padding(.vertical, 7)
+        .padding(.horizontal, Self.hPad)
+        .padding(.vertical, Self.vPad)
         .background(Capsule().fill(.white.opacity(0.08)))
         .overlay(Capsule().strokeBorder(.white.opacity(0.12), lineWidth: 1))
     }

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

@@ -1,4 +1,4 @@
-// The gamepad-driven home screen (iOS/iPadOS only): a distinct, "10-foot" console-style host
+// The gamepad-driven home screen: a distinct, "10-foot" console-style host
 // launcher shown INSTEAD of HomeView while GamepadUIEnvironment is active — a separate screen built
 // around a center-snapping carousel of hosts, driven from the couch with a controller. No touch is
 // required anywhere: A connects, Y opens a saved host's library (when the flag is on), X opens the
@@ -14,11 +14,13 @@
 // `.safeAreaInset` (top / bottom-leading) — guaranteed inside the safe area and out of the carousel's
 // vertical budget — and the card is sized off the remaining height. macOS mounts it too (the
 // couch Mac-mini case) — same screen, with the settings/add-host covers presented as sheets
-// (macOS has no fullScreenCover). tvOS never mounts this view (native focus engine instead).
+// (macOS has no fullScreenCover). tvOS mounts it as well, driven by the native focus engine
+// (see GamepadCarousel's tvOS mode) so the Siri Remote works alongside the pad; Play/Pause
+// mirrors X for Settings since the focus engine has no concept of that button.
 
 import PunktfunkKit
 import SwiftUI
-#if os(iOS) || os(macOS)
+#if os(iOS) || os(macOS) || os(tvOS)
 import GameController
 
 /// One navigable tile: a saved host, a discovered-but-unsaved one, or the trailing Add Host
@@ -60,8 +62,9 @@ struct GamepadHomeView: View {
     let connect: (StoredHost) -> Void
     let connectDiscovered: (DiscoveredHost) -> Void
 
-    /// Same experimental gate the touch grid's "Browse Library…" context-menu item uses.
-    @AppStorage(DefaultsKey.libraryEnabled) private var libraryEnabled = false
+    /// Same gate the touch grid's "Browse Library…" context-menu item uses (default ON; the
+    /// Settings "Game library" toggle opts out).
+    @AppStorage(DefaultsKey.libraryEnabled) private var libraryEnabled = true
     #if os(iOS)
     /// `.compact` in a landscape phone window — drives tighter chrome so everything still fits.
     @Environment(\.verticalSizeClass) private var vSizeClass
@@ -96,6 +99,20 @@ struct GamepadHomeView: View {
         .background { GamepadScreenBackground() }
         .onAppear { discovery.start() }
         .onDisappear { discovery.stop() }
+        // Reachability sweep (mDNS-independent) so routed/VPN hosts that never advertise still show
+        // Online — the console mirror of HomeView's `.task`; cancelled on disappear.
+        .task {
+            while !Task.isCancelled {
+                await store.refreshReachability(discovery: discovery)
+                try? await Task.sleep(for: .seconds(10))
+            }
+        }
+        // The remote's Play/Pause mirrors the pad's X (Settings): the focus engine never surfaces
+        // X, and historically tvOS maps a pad's X to this same press — the poll and this command
+        // double-firing just sets the same Bool twice.
+        #if os(tvOS)
+        .onPlayPauseCommand { showSettings = true }
+        #endif
         // The settings / add-host screens take over the controller (the carousel's `isActive`
         // gate above). iOS presents them full screen — the immersive console feel; macOS has no
         // fullScreenCover, so they become generously sized sheets over the dimmed launcher.
@@ -120,11 +137,17 @@ struct GamepadHomeView: View {
     // MARK: - Hero (carousel + detail), sized to fit the space between the pinned title and hints
 
     @ViewBuilder private func hero(for size: CGSize) -> some View {
+        #if os(tvOS)
+        // 10-foot scale: the phone-sized card reads like a postage stamp from the couch.
+        let cardWidth = min(560, size.width * 0.34)
+        let cardHeight = min(350, max(240, size.height - 260))
+        #else
         let cardWidth = min(340, size.width * 0.84)
         // 48 ≈ the carousel's own vertical breathing (+40) plus a small margin; clamp so the strip
         // always fits the region the pinned title / hints safe-area insets leave. (The old detail
         // line below the strip is gone — it only re-printed what the centered card already shows.)
         let cardHeight = min(compact ? 176 : 224, max(118, size.height - 48))
+        #endif
         VStack(spacing: compact ? 8 : 10) {
             Spacer(minLength: 0)
             carousel(cardWidth: cardWidth, cardHeight: cardHeight)
@@ -137,7 +160,7 @@ struct GamepadHomeView: View {
 
     private var titleBar: some View {
         Text("Select a Host")
-            .font(.geist(compact ? 20 : 30, .bold, relativeTo: .title))
+            .font(.geist(gamepadTitleSize(compact: compact), .bold, relativeTo: .title))
             .foregroundStyle(.white)
             .frame(maxWidth: .infinity)
             .overlay(alignment: .trailing) {
@@ -150,6 +173,14 @@ struct GamepadHomeView: View {
             }
     }
 
+    private var cardSpacing: CGFloat {
+        #if os(tvOS)
+        44
+        #else
+        30
+        #endif
+    }
+
     // MARK: - Carousel
 
     private func carousel(cardWidth: CGFloat, cardHeight: CGFloat) -> some View {
@@ -157,7 +188,7 @@ struct GamepadHomeView: View {
             items: tiles,
             selection: $selection,
             itemWidth: cardWidth,
-            spacing: 30,
+            spacing: cardSpacing,
             onActivate: { $0.activate() },
             onSecondary: { openLibraryForSelected() },
             onTertiary: { showSettings = true },
@@ -218,13 +249,16 @@ struct GamepadHomeView: View {
                 id: .saved(host.id),
                 title: host.displayName,
                 subtitle: "\(host.address):\(String(host.port))",
-                isOnline: discovery.advertises(host),
+                // Online = advertising on mDNS OR proven reachable by the probe (a routed/VPN host
+                // never advertises); the wake item is offered only when neither holds.
+                isOnline: discovery.advertises(host) || store.probedOnline.contains(host.id),
                 isPaired: host.pinnedSHA256 != nil,
                 isConnecting: model.phase == .connecting && model.activeHost?.id == host.id,
                 filled: true,
                 hasLibrary: true,
                 canWake: PunktfunkConnection.wakeOnLANAvailable
-                    && !discovery.advertises(host) && !host.wakeMacs.isEmpty,
+                    && !discovery.advertises(host) && !store.probedOnline.contains(host.id)
+                    && !host.wakeMacs.isEmpty,
                 activate: { connect(host) })
         }
         let discovered = discovery.unsaved(among: store.hosts).map { d in
@@ -261,6 +295,31 @@ private struct GamepadHostTile: View {
     let tile: HomeTile
     let size: CGSize
 
+    // 10-foot metrics on tvOS, in-hand metrics elsewhere — one tile, two viewing distances.
+    #if os(tvOS)
+    private static let titleFont: CGFloat = 33
+    private static let subtitleFont: CGFloat = 19
+    private static let statusFont: CGFloat = 15
+    private static let pipSide: CGFloat = 12
+    private static let badgeSide: CGFloat = 70
+    private static let badgeCorner: CGFloat = 19
+    private static let monogramFont: CGFloat = 34
+    private static let iconFont: CGFloat = 32
+    private static let pad: CGFloat = 28
+    private static let corner: CGFloat = 30
+    #else
+    private static let titleFont: CGFloat = 23
+    private static let subtitleFont: CGFloat = 13
+    private static let statusFont: CGFloat = 11
+    private static let pipSide: CGFloat = 9
+    private static let badgeSide: CGFloat = 52
+    private static let badgeCorner: CGFloat = 15
+    private static let monogramFont: CGFloat = 25
+    private static let iconFont: CGFloat = 24
+    private static let pad: CGFloat = 20
+    private static let corner: CGFloat = 26
+    #endif
+
     var body: some View {
         VStack(alignment: .leading, spacing: 0) {
             HStack(alignment: .top, spacing: 8) {
@@ -271,38 +330,38 @@ private struct GamepadHostTile: View {
                 HStack(spacing: 7) {
                     if tile.isPaired {
                         Image(systemName: "lock.fill")
-                            .font(.system(size: 11, weight: .semibold))
+                            .font(.system(size: Self.statusFont, weight: .semibold))
                             .foregroundStyle(.white.opacity(0.5))
                     }
                     if tile.isOnline {
                         Circle()
                             .fill(Color.green)
-                            .frame(width: 9, height: 9)
+                            .frame(width: Self.pipSide, height: Self.pipSide)
                             .shadow(color: .green.opacity(0.7), radius: 5)
                     }
                 }
             }
             Spacer(minLength: 0)
             Text(tile.title)
-                .font(.geist(23, .bold, relativeTo: .title2))
+                .font(.geist(Self.titleFont, .bold, relativeTo: .title2))
                 .foregroundStyle(.white)
                 .lineLimit(1)
                 .minimumScaleFactor(0.7)
             Text(tile.subtitle)
-                .font(.geist(13, relativeTo: .caption))
+                .font(.geist(Self.subtitleFont, relativeTo: .caption))
                 .foregroundStyle(.white.opacity(0.55))
                 .lineLimit(1)
                 .padding(.top, 2)
         }
-        .padding(20)
+        .padding(Self.pad)
         .frame(width: size.width, height: size.height, alignment: .leading)
         // Liquid Glass console tile — a brand wash marks a saved host as primary; discovered /
         // Add-Host tiles stay neutral glass with a dashed edge. Glass clips to the shape itself.
         .consoleGlass(
-            RoundedRectangle(cornerRadius: 26, style: .continuous),
+            RoundedRectangle(cornerRadius: Self.corner, style: .continuous),
             tint: tile.filled ? Color.brand.opacity(0.20) : nil)
         .overlay {
-            RoundedRectangle(cornerRadius: 26, style: .continuous)
+            RoundedRectangle(cornerRadius: Self.corner, style: .continuous)
                 .strokeBorder(
                     LinearGradient(
                         colors: [.white.opacity(0.22), .white.opacity(0.04)],
@@ -313,7 +372,7 @@ private struct GamepadHostTile: View {
     }
 
     private var monogramBadge: some View {
-        let shape = RoundedRectangle(cornerRadius: 15, style: .continuous)
+        let shape = RoundedRectangle(cornerRadius: Self.badgeCorner, style: .continuous)
         return ZStack {
             shape.fill(tile.filled
                 ? AnyShapeStyle(LinearGradient(
@@ -324,15 +383,15 @@ private struct GamepadHostTile: View {
                 ProgressView().tint(.white)
             } else if let icon = tile.icon {
                 Image(systemName: icon)
-                    .font(.system(size: 24, weight: .semibold))
+                    .font(.system(size: Self.iconFont, weight: .semibold))
                     .foregroundStyle(Color.brand)
             } else {
                 Text(monogram(tile.title))
-                    .font(.geistFixed(25, .bold))
+                    .font(.geistFixed(Self.monogramFont, .bold))
                     .foregroundStyle(tile.filled ? .white : Color.brand)
             }
         }
-        .frame(width: 52, height: 52)
+        .frame(width: Self.badgeSide, height: Self.badgeSide)
         .overlay {
             if !tile.filled {
                 shape.strokeBorder(Color.brand.opacity(0.5), lineWidth: 1)

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

@@ -1,8 +1,14 @@
-// The vertical sibling of GamepadCarousel (iOS/iPadOS/macOS): a controller-driven focus list for
-// the gamepad UI's form-like screens (GamepadSettingsView, GamepadAddHostView). Up/down moves a
-// focus bar through the rows, left/right adjusts the focused row's value, A activates it, B backs
-// out. The CALLER owns each row's look (it gets the focused flag); this component owns the focus
-// cursor, controller polling, haptics, and keeping the focused row scrolled into view.
+// The vertical sibling of GamepadCarousel (iOS/iPadOS/macOS/tvOS): a controller-driven focus list
+// for the gamepad UI's form-like screens (GamepadSettingsView, GamepadAddHostView). Up/down moves
+// a focus bar through the rows, left/right adjusts the focused row's value, A activates it, B
+// backs out. The CALLER owns each row's look (it gets the focused flag); this component owns the
+// focus cursor, controller polling, haptics, and keeping the focused row scrolled into view.
+//
+// On tvOS the rows are focusable Buttons and the NATIVE FOCUS ENGINE replaces the poll entirely
+// (Siri Remote and pads both drive it: up/down moves focus, select activates, Menu — via
+// onExitCommand — backs out). Left/right value-adjust isn't wired there; select cycles a value
+// forward exactly like A does elsewhere, the standard tvOS settings interaction. The iOS/macOS
+// poll-driven behavior is untouched by the tvOS mode.
 //
 // Unlike the carousel there is no snapping and no `.scrollPosition` two-way binding to fight: the
 // cursor is plainly authoritative, the scroll view just chases it with `scrollTo`. Touch stays a
@@ -16,7 +22,7 @@
 
 import PunktfunkKit
 import SwiftUI
-#if os(iOS) || os(macOS)
+#if os(iOS) || os(macOS) || os(tvOS)
 
 struct GamepadMenuList<Item: Identifiable, Row: View>: View where Item.ID: Hashable {
     let items: [Item]
@@ -36,6 +42,15 @@ struct GamepadMenuList<Item: Identifiable, Row: View>: View where Item.ID: Hasha
 
     @State private var input = GamepadMenuInput(manager: .shared)
     @State private var haptics = MenuHaptics(manager: .shared)
+    #if os(tvOS)
+    /// tvOS: the focus engine is the navigation authority for UP/DOWN — `cursor` chases this, so
+    /// the caller's `focused` row styling always matches real system focus. LEFT/RIGHT adjust
+    /// comes from the POLL (see `wire`), never from `.onMoveCommand`: the command stream is
+    /// 4-way with no axis data (diagonal scroll wobble buckets into left/right), and its
+    /// interception of up/down proved INPUT-SOURCE-DEPENDENT on hardware — keyboard arrows were
+    /// intercepted but a pad's dpad was not, so programmatic stepping double-moved every press.
+    @FocusState private var focusedID: Item.ID?
+    #endif
     /// Authoritative focus cursor (index into `items`).
     @State private var cursor = 0
     /// A short vertical recoil when a move is refused at a list end.
@@ -51,10 +66,23 @@ struct GamepadMenuList<Item: Identifiable, Row: View>: View where Item.ID: Hasha
             ScrollView(.vertical) {
                 LazyVStack(spacing: 6) {
                     ForEach(Array(items.enumerated()), id: \.element.id) { idx, item in
+                        #if os(tvOS)
+                        // A focusable Button per row: the engine moves between them, select
+                        // activates (`tap` keeps the cursor in step before firing). The row's
+                        // own `focused` styling is the focus treatment — the bare style adds
+                        // no system chrome on top of it.
+                        Button { tap(idx) } label: {
+                            row(item, focusedID == item.id)
+                        }
+                        .buttonStyle(ConsoleBareButtonStyle())
+                        .focused($focusedID, equals: item.id)
+                        .id(item.id)
+                        #else
                         row(item, idx == cursor && isActive)
                             .contentShape(Rectangle())
                             .onTapGesture { tap(idx) }
                             .id(item.id)
+                        #endif
                     }
                 }
                 .padding(.vertical, 10)
@@ -69,6 +97,20 @@ struct GamepadMenuList<Item: Identifiable, Row: View>: View where Item.ID: Hasha
                 }
             }
         }
+        #if os(tvOS)
+        // Focus moved (remote swipe / pad dpad) — keep the cursor, the caller's focusID mirror,
+        // and the controller detent in step. Menu = the list's back action (both tvOS callers
+        // pass one; the screen behind would otherwise catch the press and peel too far).
+        .onChange(of: focusedID) { _, newValue in
+            guard let id = newValue, let idx = items.firstIndex(where: { $0.id == id }),
+                  idx != cursor else { return }
+            cursor = idx
+            focusID = id
+            haptics.move()
+        }
+        .defaultFocus($focusedID, items.first?.id)
+        .onExitCommand { onBack?() }
+        #endif
         .sensoryFeedback(.selection, trigger: cursor)
         .sensoryFeedback(.selection, trigger: adjustTick)
         .sensoryFeedback(.impact(weight: .medium), trigger: activateTick)
@@ -102,6 +144,22 @@ struct GamepadMenuList<Item: Identifiable, Row: View>: View where Item.ID: Hasha
     // MARK: - Input wiring
 
     private func wire() {
+        #if os(tvOS)
+        // The focus engine owns up/down and select (Button rows) and Menu (onExitCommand) — the
+        // poll carries ONLY the horizontal axis, where its dominant-axis deadzone + hold-repeat
+        // are exactly the adjust feel the other platforms have, and where the focus engine has
+        // nothing to move to in a vertical list. Vertical poll directions are deliberately
+        // dropped: acting on them would double the engine's own focus moves. (The Siri Remote
+        // never reaches this poll — no extended profile — so remote users cycle values with
+        // select instead, which `activate` already does.)
+        input.onMove = { direction in
+            switch direction {
+            case .left: adjust(by: -1)
+            case .right: adjust(by: 1)
+            case .up, .down: break
+            }
+        }
+        #else
         input.onMove = { direction in
             switch direction {
             case .up: step(by: -1)
@@ -112,6 +170,7 @@ struct GamepadMenuList<Item: Identifiable, Row: View>: View where Item.ID: Hasha
         }
         input.onConfirm = { activate() }
         input.onBack = onBack
+        #endif
     }
 
     private func step(by delta: Int) {
@@ -123,6 +182,7 @@ struct GamepadMenuList<Item: Identifiable, Row: View>: View where Item.ID: Hasha
         haptics.move()
     }
 
+
     private func adjust(by delta: Int) {
         guard let onAdjust, cursor >= 0, cursor < items.count else { return }
         if onAdjust(items[cursor], delta) {
@@ -165,6 +225,12 @@ struct GamepadMenuList<Item: Identifiable, Row: View>: View where Item.ID: Hasha
             cursor = min(max(cursor, 0), items.count - 1)
             focusID = items[cursor].id
         }
+        #if os(tvOS)
+        // Keep real focus on the reconciled row when its old target vanished from the list.
+        if focusedID == nil || !items.contains(where: { $0.id == focusedID }), cursor < items.count {
+            focusedID = items[cursor].id
+        }
+        #endif
     }
 
     private func boundaryBump(forward: Bool) {

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

@@ -29,8 +29,9 @@ struct HomeView: View {
     /// Explicit Wake-on-LAN of an offline host — fires the packet and waits for it to come online
     /// (the "Waking…" overlay), without connecting. Routed through ContentView's HostWaker.
     let wake: (StoredHost) -> Void
-    /// Experimental game-library browser (gated) — the host-card "Browse Library…" action.
-    @AppStorage(DefaultsKey.libraryEnabled) private var libraryEnabled = false
+    /// Game-library browser (default ON; the Settings toggle opts out) — the host-card
+    /// "Browse Library…" action.
+    @AppStorage(DefaultsKey.libraryEnabled) private var libraryEnabled = true
     /// The host being edited (name / address / port / Wake-on-LAN MAC) — drives the edit sheet.
     @State private var editTarget: StoredHost?
 
@@ -48,6 +49,13 @@ struct HomeView: View {
                                 }
                             }
                             .padding()
+                            // Mirror of the action row's focusSection below: an UPWARD move from
+                            // the centered buttons must land back in the grid even when no card
+                            // sits in the buttons' columns (a lone top-left card, say). The grid
+                            // spans the row, so the section catches every upward ray.
+                            #if os(tvOS)
+                            .focusSection()
+                            #endif
                         }
                         if !discoveredUnsaved.isEmpty {
                             discoveredSection
@@ -67,6 +75,14 @@ struct HomeView: View {
                             }
                         }
                         .padding(.top, 24)
+                        // One FULL-WIDTH focus target for any downward move out of the grid.
+                        // focusSection alone is not enough: the engine tests the section's
+                        // FRAME, and a content-hugging centered HStack only overlaps the middle
+                        // columns — a swipe down from an outer card dead-ends and the actions
+                        // are unreachable by remote. Stretching the section across the row means
+                        // every column's downward ray hits it.
+                        .frame(maxWidth: .infinity)
+                        .focusSection()
                         #endif
                     }
                 }
@@ -76,6 +92,17 @@ struct HomeView: View {
             // session. The home appears/disappears as the stream swaps in and out.
             .onAppear { discovery.start() }
             .onDisappear { discovery.stop() }
+            // Reachability sweep while the grid is up: a saved host reached only over a routed
+            // network (Tailscale/VPN) never advertises on mDNS, so `advertises` can't see it. Probe
+            // every non-advertising saved host ~every 10 s and publish the reachable set for the
+            // pips (`isOnline` above OR's it in). The `.task` is cancelled on disappear, matching
+            // `discovery.stop()`.
+            .task {
+                while !Task.isCancelled {
+                    await store.refreshReachability(discovery: discovery)
+                    try? await Task.sleep(for: .seconds(10))
+                }
+            }
             #if os(tvOS)
             // Pushed routes — the Settings-app navigation feel (push animation, Menu
             // pops) instead of modal overlays.
@@ -157,7 +184,7 @@ struct HomeView: View {
         let onBrowseLibrary: (() -> Void)? = libraryEnabled ? { libraryTarget = host } : nil
         return HostCardView(
             host: host,
-            isOnline: discovery.advertises(host),
+            isOnline: discovery.advertises(host) || store.probedOnline.contains(host.id),
             isConnecting: model.phase == .connecting && model.activeHost?.id == host.id,
             isMostRecent: host.id == mostRecentHostID,
             isBusy: model.isBusy,
@@ -187,6 +214,10 @@ struct HomeView: View {
         }
         .padding([.horizontal, .bottom])
         .padding(.top, store.hosts.isEmpty ? 0 : 8)
+        // Same reachability contract as the saved grid above — see its focusSection comment.
+        #if os(tvOS)
+        .focusSection()
+        #endif
     }
 
     /// Discovered hosts not already saved (see `HostDiscovery.unsaved` — shared with the gamepad
@@ -248,7 +279,9 @@ struct HomeView: View {
         #if os(macOS)
         [GridItem(.adaptive(minimum: 250, maximum: 320), spacing: 16)]
         #elseif os(tvOS)
-        [GridItem(.adaptive(minimum: 320), spacing: 48)]
+        // Tracks CardMetrics' 10-foot sizes — at the 30pt name a 320pt column truncates
+        // every hostname longer than ~10 characters.
+        [GridItem(.adaptive(minimum: 460), spacing: 48)]
         #else
         [GridItem(.adaptive(minimum: 280), spacing: 16)]
         #endif

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

@@ -22,8 +22,9 @@ private struct CardMetrics {
         CardMetrics(tile: 54, monogram: 26, name: 19, meta: 13, status: 11,
                     padding: 16, spacing: 14, radius: 12)
         #elseif os(tvOS)
-        CardMetrics(tile: 64, monogram: 32, name: 24, meta: 16, status: 14,
-                    padding: 18, spacing: 18, radius: 14)
+        // 10-foot sizes — the 24pt-name tier read like a phone card from the couch.
+        CardMetrics(tile: 84, monogram: 42, name: 30, meta: 20, status: 17,
+                    padding: 24, spacing: 22, radius: 18)
         #else
         CardMetrics(tile: 44, monogram: 21, name: 15, meta: 12, status: 10.5,
                     padding: 13, spacing: 12, radius: 10)

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

@@ -1,4 +1,4 @@
-// The gamepad-driven presentation of the game library (iOS/iPadOS/macOS — see LibraryView's
+// The gamepad-driven presentation of the game library (iOS/iPadOS/macOS/tvOS — see LibraryView's
 // `gamepadUIActive` branch): a classic coverflow instead of the touch grid. All the
 // scrolling/snapping/navigation/haptics live in GamepadCarousel; this file is the coverflow card
 // (poster + the 3D recede treatment via `.scrollTransition`), the "now focused" detail panel, and
@@ -15,7 +15,7 @@
 
 import PunktfunkKit
 import SwiftUI
-#if os(iOS) || os(macOS)
+#if os(iOS) || os(macOS) || os(tvOS)
 import GameController
 
 struct LibraryCoverflowView: View {

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

@@ -21,9 +21,9 @@ struct LibraryView: View {
     /// list fetch, reused across every poster in the grid). Built alongside `games` in `load()`;
     /// torn down on disappear since it isn't one-shot like `LibraryClient.fetch`'s own session.
     @State private var imageSession: URLSession?
-    #if os(iOS) || os(macOS)
-    // Gamepad-driven browsing (iOS/iPadOS/macOS) — see ContentView's identical gate. tvOS keeps
-    // its existing plain-grid presentation of this same view unchanged.
+    #if os(iOS) || os(macOS) || os(tvOS)
+    // Gamepad-driven browsing — see ContentView's identical gate. With no controller (or the
+    // setting off) every platform keeps the plain-grid presentation of this same view.
     @ObservedObject private var gamepadManager = GamepadManager.shared
     @AppStorage(DefaultsKey.gamepadUIEnabled) private var gamepadUIEnabled = true
     private var gamepadUIActive: Bool {
@@ -69,7 +69,6 @@ struct LibraryView: View {
         } else if games.isEmpty {
             emptyState
         } else {
-            #if os(iOS) || os(macOS)
             if gamepadUIActive {
                 LibraryCoverflowView(
                     games: games, imageSession: imageSession, onLaunch: onLaunch,
@@ -77,9 +76,6 @@ struct LibraryView: View {
             } else {
                 grid
             }
-            #else
-            grid
-            #endif
         }
     }
 

clients/apple/Sources/PunktfunkClient/PunktfunkClientApp.swift

@@ -38,13 +38,26 @@ struct PunktfunkClientApp: App {
                 ContentView()
                 #endif
             }
+            // NOT on tvOS: under the tvOS 26 glass button style a tinted UNFOCUSED control fills
+            // AND labels itself in the tint — every plain Button/TextField renders as a blank
+            // brand-violet pill until focused. Untinted, tvOS keeps the system glass look
+            // (visible labels, white focus lift); brand color stays on explicit Color.brand uses.
+            #if !os(tvOS)
             .tint(.brand)
+            #endif
             // Geist Sans is the app's typeface. This sets the default for unstyled text and the
             // form row labels; views that pick an explicit size/weight use `.geist(…)` directly.
+            // tvOS reads from across the room: its system body is 29pt, so pinning the phone's
+            // 17pt there shrank every unstyled control (rows, fields, buttons) to postage size.
+            #if os(tvOS)
+            .font(.geist(29, relativeTo: .body))
+            #else
             .font(.geist(17, relativeTo: .body))
+            #endif
         }
-        // The Stream menu (Disconnect ⌘D, Show/Hide Statistics ⌘⇧S) — a real menu bar on
-        // macOS, hardware-keyboard shortcuts on iPad. tvOS has neither.
+        // The Stream menu (Release Mouse ⌃⌥⇧Q, Disconnect ⌃⌥⇧D, Show/Hide Statistics ⌃⌥⇧S —
+        // the cross-client Ctrl+Alt+Shift set) — a real menu bar on macOS, hardware-keyboard
+        // shortcuts on iPad. tvOS has neither.
         #if !os(tvOS)
         .commands { StreamCommands() }
         #endif

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

@@ -23,6 +23,17 @@ enum HUDPlacement: String, CaseIterable, Identifiable {
     /// The HUD's own stack hugs the screen edge it sits against, so its text aligns outward.
     var isTrailing: Bool { self == .topTrailing || self == .bottomTrailing }
 
+    /// The corner as a `UnitPoint`, so a scale transition grows/shrinks the HUD out of its own
+    /// corner rather than its centre.
+    var unitPoint: UnitPoint {
+        switch self {
+        case .topLeading: return .topLeading
+        case .topTrailing: return .topTrailing
+        case .bottomLeading: return .bottomLeading
+        case .bottomTrailing: return .bottomTrailing
+        }
+    }
+
     /// User-facing corner label.
     var label: String {
         switch self {

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

@@ -0,0 +1,41 @@
+// The resize overlay (design/midstream-resolution-resize.md — client resize UX). A Match-window
+// resize renegotiates the host's virtual display + encoder and re-inits the local VideoToolbox
+// decoder on the first new-mode IDR — an unavoidable sub-second gap where the last frame lingers,
+// briefly freezes, or the picture pops to the new geometry. Rather than let that read as a stutter,
+// we make it DELIBERATE: the caller blurs the live stream and this centered spinner + caption
+// acknowledges the transition. It clears the instant a frame at the requested size decodes (the
+// `onDecodedSize` END signal) or on the follower's safety timeout — see `SessionModel.resizing`.
+//
+// Floating overlay, never a hit-test target: input keeps flowing to the stream underneath so a
+// resize the user triggers by dragging the window never swallows their next click.
+
+import PunktfunkKit
+import SwiftUI
+
+struct ResizeIndicatorView: View {
+    /// Mirrors `SessionModel.resizing`; the fade in/out is driven off this.
+    let active: Bool
+
+    var body: some View {
+        ZStack {
+            if active {
+                VStack(spacing: 12) {
+                    ProgressView().controlSize(.large).tint(.white)
+                    Text("Resizing…")
+                        .font(.geist(15, .medium, relativeTo: .callout))
+                        .foregroundStyle(.white.opacity(0.85))
+                }
+                .padding(.horizontal, 30)
+                .padding(.vertical, 24)
+                .glassBackground(RoundedRectangle(cornerRadius: 20, style: .continuous))
+                .overlay(
+                    RoundedRectangle(cornerRadius: 20, style: .continuous)
+                        .strokeBorder(.white.opacity(0.12), lineWidth: 1))
+                .transition(.opacity.combined(with: .scale(scale: 0.92)))
+            }
+        }
+        .environment(\.colorScheme, .dark) // the spinner + glass read over any frame
+        .animation(.easeInOut(duration: 0.22), value: active)
+        .allowsHitTesting(false) // the stream keeps receiving input the whole time
+    }
+}

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

@@ -2,6 +2,7 @@
 // handshake phase, and the pump-thread → main-actor stats relay.
 
 import Foundation
+import os
 import PunktfunkKit
 import SwiftUI
 
@@ -10,6 +11,15 @@ import SwiftUI
 #elseif canImport(UIKit)
     import UIKit
 #endif
+#if os(tvOS)
+    import AVFoundation // AVPlayer.eligibleForHDRPlayback — the TV-capability HDR gate
+#endif
+
+/// 1 Hz latency-stage line mirrored to the unified log so the stages can be read WITHOUT the
+/// on-screen HUD (Console.app, wirelessly on an iPad/Apple TV). The HUD is not a neutral
+/// instrument: any visible overlay forces the metal layer through the compositor, which costs a
+/// refresh period on the vsync-latched platforms — this is how to measure with it off.
+private let statsLog = Logger(subsystem: "io.unom.punktfunk", category: "stats")
 
 /// Pump-thread-side frame counters; a 1 Hz main-actor timer drains them into @Published
 /// values. NSLock instead of an actor — the writer is the (non-async) pump thread.
@@ -99,6 +109,16 @@ final class SessionModel: ObservableObject {
     /// Mirrors StreamView's capture state (it owns the input capture; this drives the
     /// HUD's "click to capture" / "⌘⎋ releases" hint).
     @Published var mouseCaptured = false
+    /// Resize overlay (design/midstream-resolution-resize.md — client resize UX): true from the
+    /// instant a Match-window resize starts steering toward a new size until a frame at that size
+    /// decodes (or a safety timeout). Drives the blur+spinner so the unavoidable host-rebuild delay
+    /// reads as a deliberate, acknowledged transition instead of a stutter. Pure state lives in
+    /// `ResizeIndicator`; this mirrors its `active` for SwiftUI.
+    @Published private(set) var resizing = false
+    /// START = follower steering (main actor), END = a new-mode IDR's coded dims (decode pump,
+    /// hopped to main), TIMEOUT = safety net for a rejected/capped switch that never yields a
+    /// differently-sized frame. Ticked from the 1 Hz stats timer.
+    private var resizeIndicator = ResizeIndicator()
 
     let meter = FrameMeter()
     /// Capture→received (the host+network stage), fed per AU at receipt by the stream view's
@@ -119,6 +139,12 @@ final class SessionModel: ObservableObject {
     private var audio: SessionAudio?
     private var gamepadCapture: GamepadCapture?
     private var gamepadFeedback: GamepadFeedback?
+    #if os(tvOS)
+    /// Siri Remote → host pointer while streaming (touch surface moves, press = left click,
+    /// Play/Pause = right click) + the remote's deliberate exit (hold Back ≥ 1 s). See
+    /// SiriRemotePointer — same trust gate/lifecycle as the gamepad capture above.
+    private var remotePointer: SiriRemotePointer?
+    #endif
 
     var isBusy: Bool { phase != .idle }
 
@@ -135,6 +161,10 @@ final class SessionModel: ObservableObject {
     /// successful connect streams directly (the approval IS the trust decision) — the caller pins
     /// the observed fingerprint as paired. `host.pinnedSHA256`, when set, pins the advertised cert
     /// for the wait; nil = trust-on-first-use.
+    /// `onUnreachable`, when set, replaces the "could not connect" alert for a plain connect
+    /// failure: the caller takes over recovery (the Wake-on-LAN wait for a host that stopped
+    /// advertising). It never fires for the delegated-approval path, whose failure text carries
+    /// its own instructions.
     func connect(to host: StoredHost, width: UInt32, height: UInt32, hz: UInt32,
                  compositor: PunktfunkConnection.Compositor = .auto,
                  gamepad: PunktfunkConnection.GamepadType = .auto,
@@ -145,7 +175,8 @@ final class SessionModel: ObservableObject {
                  launchID: String? = nil,
                  allowTofu: Bool = false,
                  autoTrust: Bool = false,
-                 requestAccess: Bool = false) {
+                 requestAccess: Bool = false,
+                 onUnreachable: (@MainActor () -> Void)? = nil) {
         guard phase == .idle else { return }
         phase = .connecting
         activeHost = host
@@ -158,13 +189,25 @@ final class SessionModel: ObservableObject {
         let displayHDR: Bool = {
             #if os(macOS)
                 return (NSScreen.main?.maximumExtendedDynamicRangeColorComponentValue ?? 1.0) > 1.0
+            #elseif os(tvOS)
+                // NOT the EDR headroom here: on tvOS that reflects the CURRENT output mode, and
+                // Apple's recommended setup runs an SDR home screen with Match Content — an
+                // HDR-capable TV would read 1.0 at connect time and never be advertised. The
+                // session switches the display to HDR10 itself once streaming (AVDisplayManager —
+                // see StreamViewIOS), so gate on the TV's mode-independent capability; if the
+                // switch never lands, the presenter's in-shader tone-map keeps PQ safe anyway.
+                return AVPlayer.eligibleForHDRPlayback
             #else
                 return UIScreen.main.potentialEDRHeadroom > 1.0
             #endif
         }()
         let hdrCapable = hdrEnabled && displayHDR
-        // 4:4:4 opt-out (default on); the hardware-decode probe below is the real gate.
-        let want444 = (UserDefaults.standard.object(forKey: DefaultsKey.enable444) as? Bool) ?? true
+        // 4:4:4 opt-IN (default off): full chroma is a per-client choice — a clear win for
+        // desktop/text work, but at a fixed bitrate it spends bits on chroma that game content
+        // doesn't visibly need, and the encode/decode pixel rate rises. The host allows it by
+        // default (PUNKTFUNK_444, default on), so this toggle is the one real switch; the
+        // hardware-decode probe below still gates what can actually be advertised.
+        let want444 = (UserDefaults.standard.object(forKey: DefaultsKey.enable444) as? Bool) ?? false
         Task.detached(priority: .userInitiated) {
             // PunktfunkConnection.init blocks on the QUIC handshake — keep it off the main
             // actor. The persistent identity is presented on every connect so a paired
@@ -189,10 +232,13 @@ final class SessionModel: ObservableObject {
             if want444, canDecode444 {
                 videoCaps |= PunktfunkConnection.videoCap444
             }
-            // This client's VideoToolbox path decodes H.264 and HEVC (AV1 isn't wired — hosts don't
-            // emit it on the native path yet). The host resolves the emitted codec from these + the
-            // soft `preferredCodec`; `resolvedCodec` reflects what it chose.
-            let videoCodecs = PunktfunkConnection.codecH264 | PunktfunkConnection.codecHEVC
+            // This client's VideoToolbox path decodes H.264 and HEVC everywhere, and AV1 when
+            // this device has an AV1 hardware decoder (M3-class Macs, A17 Pro-class iPhones —
+            // VideoToolbox has no software AV1 decoder, so advertising it elsewhere would invite
+            // a stream that can't decode; see AV1.swift). The host resolves the emitted codec
+            // from these + the soft `preferredCodec`; `resolvedCodec` reflects what it chose.
+            var videoCodecs = PunktfunkConnection.codecH264 | PunktfunkConnection.codecHEVC
+            if AV1.hardwareDecodeSupported { videoCodecs |= PunktfunkConnection.codecAV1 }
             let result = Result { try PunktfunkConnection(
                 host: host.address, port: host.port,
                 width: width, height: height, refreshHz: hz,
@@ -241,7 +287,11 @@ final class SessionModel: ObservableObject {
                 case .failure:
                     self.phase = .idle
                     self.activeHost = nil
-                    if requestAccess {
+                    if let onUnreachable, !requestAccess {
+                        // The caller owns recovery (wake-and-retry) — no error alert here; its
+                        // own overlay explains what's happening.
+                        onUnreachable()
+                    } else if requestAccess {
                         // The delegated-approval connect ended without being admitted: the
                         // operator didn't approve it before the host's park window elapsed (or
                         // the host was unreachable).
@@ -288,6 +338,10 @@ final class SessionModel: ObservableObject {
         // connection is still up); the feedback drain joins off-main like audio.
         gamepadCapture?.stop()
         gamepadCapture = nil
+        #if os(tvOS)
+        remotePointer?.stop() // releases any held click while the connection is still up
+        remotePointer = nil
+        #endif
         let feedback = gamepadFeedback
         gamepadFeedback = nil
         if let conn = connection {
@@ -320,6 +374,8 @@ final class SessionModel: ObservableObject {
         lostFrames = 0
         lostPct = 0
         mouseCaptured = false
+        resizing = false
+        resizeIndicator = ResizeIndicator() // no stale target/timer into the next session
     }
 
     /// Called (via the main actor) when the pump hits end-of-session.
@@ -330,6 +386,23 @@ final class SessionModel: ObservableObject {
         errorMessage = "Session ended by \(name)."
     }
 
+    /// Resize overlay START (main actor — from the Match-window follower's `onResizeTarget`): the
+    /// window began differing from the live mode, so a `Reconfigure` toward `(width, height)` is
+    /// imminent. Show the blur+spinner immediately, before the debounced request even leaves.
+    func resizeTargeted(width: UInt32, height: UInt32) {
+        resizeIndicator.steering(
+            width: width, height: height, now: Date().timeIntervalSinceReferenceDate)
+        resizing = resizeIndicator.active
+    }
+
+    /// Resize overlay END (main actor — hopped from the decode pump's `onDecodedSize`): a new-mode
+    /// IDR decoded at `(width, height)`. Clears the overlay only when that matches the size we're
+    /// steering to (a same-size loss-recovery IDR, or the initial connect IDR, is a no-op).
+    func resizeDecoded(width: Int, height: Int) {
+        resizeIndicator.decoded(width: UInt32(max(width, 0)), height: UInt32(max(height, 0)))
+        resizing = resizeIndicator.active
+    }
+
     private func beginStreaming() {
         guard let conn = connection else { return }
         // Input capture itself is owned by StreamView (engaged by the captureEnabled
@@ -351,11 +424,20 @@ final class SessionModel: ObservableObject {
         // session's virtual pad is a DualSense). Same trust gate as audio — nothing is
         // forwarded during the trust prompt.
         let capture = GamepadCapture(connection: conn, manager: .shared)
+        // The cross-client escape chord (hold L1+R1+Start+Select 1.5 s) — on tvOS the only
+        // controller way out of a stream (B/Menu is swallowed during sessions; see ContentView).
+        capture.onDisconnectRequest = { [weak self] in self?.disconnect() }
         capture.start()
         gamepadCapture = capture
         let feedback = GamepadFeedback(connection: conn, manager: .shared)
         feedback.start()
         gamepadFeedback = feedback
+        #if os(tvOS)
+        let pointer = SiriRemotePointer(connection: conn)
+        pointer.onDisconnectRequest = { [weak self] in self?.disconnect() }
+        pointer.start()
+        remotePointer = pointer
+        #endif
     }
 
     private func startStatsTimer() {
@@ -364,6 +446,11 @@ final class SessionModel: ObservableObject {
         let timer = Timer(timeInterval: 1.0, repeats: true) { [weak self] _ in
             guard let self else { return }
             Task { @MainActor in
+                // Resize-overlay safety net: clear a stuck overlay when a targeted size never
+                // decodes (a rejected/capped switch). The decoded-frame END clears it promptly on
+                // success; this only fires after the timeout.
+                self.resizeIndicator.tick(now: Date().timeIntervalSinceReferenceDate)
+                self.resizing = self.resizeIndicator.active
                 let (frames, bytes, total) = self.meter.drain()
                 self.fps = frames
                 self.mbps = Double(bytes) * 8 / 1_000_000
@@ -417,12 +504,32 @@ final class SessionModel: ObservableObject {
                 } else {
                     self.decodeValid = false
                 }
-                if let d = self.displayStage.drain() {
+                let displayWindow = self.displayStage.drain()
+                if let d = displayWindow {
                     self.displayP50Ms = d.p50Ms
                     self.displayValid = true
                 } else {
                     self.displayValid = false
                 }
+                // Mirror the window to the unified log (see statsLog) — one line per second,
+                // stages in ms, only while frames actually flowed. `fps` counts RECEIVED AUs;
+                // `presents` counts frames that reached glass (the display meter's sample count)
+                // — a presents≪fps gap is the presenter dropping/serializing, an fps deficit is
+                // upstream (host capture/encode or the network).
+                if frames > 0 {
+                    let line = String(
+                        format: "fps=%d presents=%d e2e_p50=%.1f e2e_p95=%.1f hostnet_p50=%.1f "
+                            + "decode_p50=%.1f display_p50=%.1f lost=%d",
+                        frames,
+                        displayWindow?.count ?? 0,
+                        self.endToEndValid ? self.endToEndP50Ms : -1,
+                        self.endToEndValid ? self.endToEndP95Ms : -1,
+                        self.hostNetworkValid ? self.hostNetworkP50Ms : -1,
+                        self.decodeValid ? self.decodeP50Ms : -1,
+                        self.displayValid ? self.displayP50Ms : -1,
+                        lost)
+                    statsLog.info("\(line, privacy: .public)")
+                }
             }
         }
         // .common so the HUD keeps updating during window drags / menu tracking.

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

@@ -1,7 +1,13 @@
 // The app's "Stream" menu (macOS menu bar + iPad hardware-keyboard shortcuts). These live at
-// the Scene level so they keep working when the HUD overlay is hidden — in particular ⌘D
-// disconnect, which used to be reachable only via the HUD's button. The toggle just flips the
-// shared `hudEnabled` setting; ContentView reads the same @AppStorage and reacts.
+// the Scene level so they keep working when the HUD overlay is hidden. The shortcuts are the
+// CROSS-CLIENT set every punktfunk client reserves — Ctrl+Alt+Shift+Q (release the captured
+// mouse) / +D (disconnect) / +S (stats) — and the menu is their discoverable surface on macOS
+// (the Linux client has its GTK Shortcuts window, Windows its start-of-stream banner). While
+// input is CAPTURED these key equivalents never reach the menu (the stream view swallows
+// keys); InputCapture's monitor detects the same combos there and performs the same actions —
+// the menu covers the released state and discoverability. The stats item cycles the shared
+// `statsVerbosity` tier (off → compact → normal → detailed → off); ContentView reads the same
+// @AppStorage and reacts.
 //
 // tvOS has no menu bar / hardware-keyboard command surface (disconnect there is the Siri
 // Remote's Menu button, handled by ContentView's `.onExitCommand`), so this whole file is
@@ -31,17 +37,30 @@ extension FocusedValues {
 
 struct StreamCommands: Commands {
     @FocusedValue(\.sessionFocus) private var session
-    @AppStorage(DefaultsKey.hudEnabled) private var hudEnabled = true
+    // The raw string so @AppStorage observes the shared key; the absent-key default runs the
+    // legacy-hudEnabled migration (same pattern as ContentView/SettingsView).
+    @AppStorage(DefaultsKey.statsVerbosity) private var statsVerbosityRaw
+        = StatsVerbosity.current.rawValue
 
     var body: some Commands {
         CommandMenu("Stream") {
-            Button(hudEnabled ? "Hide Statistics" : "Show Statistics") {
-                hudEnabled.toggle()
+            Button("Cycle Statistics") {
+                let current = StatsVerbosity(rawValue: statsVerbosityRaw) ?? .normal
+                statsVerbosityRaw = current.next().rawValue
             }
-            .keyboardShortcut("s", modifiers: [.command, .shift])
+            .keyboardShortcut("s", modifiers: [.control, .option, .shift])
+            // Reaches the key window's stream view via NotificationCenter — capture is view
+            // state the Scene can't touch directly. (Captured, the combo is handled by
+            // InputCapture's monitor before menus see it; this item is the released-state
+            // path and the shortcut's menu-bar documentation.)
+            Button("Release Mouse") {
+                NotificationCenter.default.post(name: .punktfunkReleaseCapture, object: nil)
+            }
+            .keyboardShortcut("q", modifiers: [.control, .option, .shift])
+            .disabled(session?.isStreaming != true)
             Divider()
             Button("Disconnect") { session?.disconnect() }
-                .keyboardShortcut("d", modifiers: .command)
+                .keyboardShortcut("d", modifiers: [.control, .option, .shift])
                 .disabled(session?.isStreaming != true)
         }
     }

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

@@ -1,17 +1,81 @@
-// The streaming overlay HUD: mode + fps/throughput, the unified latency lines
-// (design/stats-unification.md — end-to-end headline + the stage equation under stage-2, the
-// capture→received headline under the stage-1 fallback), the loss counter, the platform input
-// hint, and disconnect.
+// The streaming overlay HUD, tiered by StatsVerbosity (the Android client's 3-tier semantics):
+//  * compact — one glass-pill line: fps · end-to-end p50 · throughput (+ loss when lossy);
+//  * normal — mode + fps/throughput, the unified latency HEADLINE (design/stats-unification.md
+//    — end-to-end under stage-2, capture→received under the stage-1 fallback), the loss
+//    counter, a capture hint (shown until input is captured), and disconnect;
+//  * detailed — everything normal has plus the stage equation line(s) under the headline.
+// `.off` never reaches this view (ContentView gates the overlay on the tier).
 
 import PunktfunkKit
 import SwiftUI
+#if canImport(UIKit)
+import UIKit
+#endif
 
 struct StreamHUDView: View {
     @ObservedObject var model: SessionModel
     let connection: PunktfunkConnection
     var placement: HUDPlacement = .topTrailing
+    let verbosity: StatsVerbosity
 
     var body: some View {
+        // .off is gated upstream (ContentView only mounts the HUD when the tier is on) —
+        // render nothing if it ever slips through.
+        if verbosity != .off {
+            // ONE shared glass card wraps the tier-dependent content, so a verbosity change MORPHS
+            // this card — its frame (and, on iOS, its clamped corner) animate to the new size — rather
+            // than cross-fading a whole new card in. Only the inner content switches per tier.
+            tierContent
+                .padding(cardPadding)
+                .glassBackground(cardShape)
+                .padding(edgeInset)
+        }
+    }
+
+    /// The tier-dependent content, unwrapped (the shared card in `body` supplies the padding +
+    /// glass background). Compact is a one-line pill; normal/detailed the full stack.
+    @ViewBuilder private var tierContent: some View {
+        if verbosity == .compact {
+            compactContent
+        } else {
+            fullContent
+        }
+    }
+
+    // MARK: - Compact tier
+
+    /// One line: `{fps} fps · {e2e p50} ms · {mbps} Mb/s`. The ms segment is the best available
+    /// latency headline (stage-2 end-to-end, else the stage-1 capture→received) and is omitted until
+    /// either is valid. Loss appends in the same quiet styling the full HUD's lost line uses.
+    private var compactContent: some View {
+        HStack(spacing: 6) {
+            Circle()
+                .fill(Color.accentColor)
+                .frame(width: 7, height: 7)
+            Text(compactLine)
+                .font(.system(.caption, design: .monospaced))
+            if model.lostFrames > 0 {
+                Text("· lost \(model.lostFrames)")
+                    .font(.system(.caption2, design: .monospaced))
+                    .foregroundStyle(.secondary)
+            }
+        }
+    }
+
+    private var compactLine: String {
+        var parts = ["\(model.fps) fps"]
+        if model.endToEndValid {
+            parts.append(String(format: "%.1f ms", model.endToEndP50Ms))
+        } else if model.hostNetworkValid {
+            parts.append(String(format: "%.1f ms", model.hostNetworkP50Ms))
+        }
+        parts.append(String(format: "%.1f Mb/s", model.mbps))
+        return parts.joined(separator: " · ")
+    }
+
+    // MARK: - Normal / detailed tiers
+
+    private var fullContent: some View {
         VStack(alignment: placement.isTrailing ? .trailing : .leading, spacing: 4) {
             HStack(spacing: 6) {
                 Circle()
@@ -26,11 +90,11 @@ struct StreamHUDView: View {
                 Text("end-to-end \(model.endToEndP50Ms, specifier: "%.1f") ms p50 · \(model.endToEndP95Ms, specifier: "%.1f") p95 · capture→on-glass\(model.endToEndSkewCorrected ? "" : " (same-host clock)")")
                     .font(.system(.caption2, design: .monospaced))
                     .foregroundStyle(.secondary)
-                // The equation: the stages tiling the headline interval (per-window p50s —
-                // they only approximately sum to the directly-measured total). With a host
-                // that reports per-AU timings (0xCF) the first term splits into host + network
-                // (phase 2); an old host keeps the combined term.
-                if model.hostNetworkValid && model.decodeValid && model.displayValid {
+                // The equation (detailed tier only): the stages tiling the headline interval
+                // (per-window p50s — they only approximately sum to the directly-measured
+                // total). With a host that reports per-AU timings (0xCF) the first term splits
+                // into host + network (phase 2); an old host keeps the combined term.
+                if verbosity == .detailed && model.hostNetworkValid && model.decodeValid && model.displayValid {
                     if model.splitValid {
                         Text("= host \(model.hostP50Ms, specifier: "%.1f") + network \(model.networkP50Ms, specifier: "%.1f") + decode \(model.decodeP50Ms, specifier: "%.1f") + display \(model.displayP50Ms, specifier: "%.1f")")
                             .font(.system(.caption2, design: .monospaced))
@@ -45,11 +109,12 @@ struct StreamHUDView: View {
                 // Stage-1 fallback presenter: the layer decodes + presents internally with no
                 // per-frame stamp, so the honest headline ends at receipt. The host/network
                 // split still applies there (receipt is presenter-independent) — it becomes the
-                // only equation line; without it, host+network IS the whole measured interval.
+                // only equation line (detailed tier); without it, host+network IS the whole
+                // measured interval.
                 Text("capture→received \(model.hostNetworkP50Ms, specifier: "%.1f") ms p50 · \(model.hostNetworkP95Ms, specifier: "%.1f") p95\(model.hostNetworkSkewCorrected ? "" : " (same-host clock)")")
                     .font(.system(.caption2, design: .monospaced))
                     .foregroundStyle(.secondary)
-                if model.splitValid {
+                if verbosity == .detailed && model.splitValid {
                     Text("= host \(model.hostP50Ms, specifier: "%.1f") + network \(model.networkP50Ms, specifier: "%.1f")")
                         .font(.system(.caption2, design: .monospaced))
                         .foregroundStyle(.secondary)
@@ -63,40 +128,104 @@ struct StreamHUDView: View {
                     .font(.system(.caption2, design: .monospaced))
                     .foregroundStyle(.secondary)
             }
-            // While captured the cursor is hidden+frozen, so the button is keyboard-only
-            // (⌘⎋ or Cmd+Tab release the cursor; released, it's clickable again).
+            // Capture hint, shown only until input is captured — how to grab it. The RELEASE
+            // shortcut is intentionally not surfaced in the overlay (it lives on the Stream menu
+            // and, on macOS, the start-of-stream banner), keeping the HUD uncluttered while playing.
             #if os(macOS)
-            Text(model.mouseCaptured
-                ? "⌘⎋ releases the mouse"
-                : "Click the stream to capture input")
-                .font(.geist(11, relativeTo: .caption2))
-                .foregroundStyle(.secondary)
+            if !model.mouseCaptured {
+                Text("Click the stream to capture input")
+                    .font(.geist(11, relativeTo: .caption2))
+                    .foregroundStyle(.secondary)
+            }
             #elseif os(iOS)
-            // Touch always plays directly; ⌘⎋ (hardware keyboard) toggles kb/mouse.
-            Text(model.mouseCaptured
-                ? "⌘⎋ releases keyboard & mouse"
-                : "⌘⎋ captures keyboard & mouse")
-                .font(.geist(11, relativeTo: .caption2))
-                .foregroundStyle(.secondary)
+            // Touch always plays directly; ⌘⎋ (hardware keyboard) captures kb/mouse.
+            if !model.mouseCaptured {
+                Text("⌘⎋ captures keyboard & mouse")
+                    .font(.geist(11, relativeTo: .caption2))
+                    .foregroundStyle(.secondary)
+            }
             #endif
-            #if os(tvOS)
-            // No focusable control during play: a focusable button steals the controller's
-            // A press (the focus engine consumes it before the host sees it). Disconnect is
-            // the Siri Remote's Menu button (.onExitCommand on the stream) — just hint it.
-            Text("Press Menu to disconnect")
+            // ⌃⌥⇧D lives on the app's Stream menu (so it still works when the HUD is hidden)
+            // and in InputCapture's monitor while captured; this button is the in-overlay,
+            // click-to-disconnect affordance. tvOS deliberately gets NEITHER a button (a
+            // focusable control would steal the controller's A press from the host) NOR a hint
+            // line: the exits are the hold gestures the start-of-stream banner teaches (hold
+            // the remote's Back; hold L1+R1+Start+Select on a pad).
+            #if os(macOS)
+            Button("Disconnect (⌃⌥⇧D)") { model.disconnect() }
                 .font(.geist(12, relativeTo: .caption))
-                .foregroundStyle(.secondary)
-            #else
-            // ⌘D lives on the app's Stream menu (so it still works when the HUD is hidden);
-            // this button is the in-overlay, click-to-disconnect affordance.
-            Button("Disconnect (⌘D)") { model.disconnect() }
+            #elseif os(iOS)
+            Button("Disconnect") { model.disconnect() }
                 .font(.geist(12, relativeTo: .caption))
             #endif
         }
-        .padding(10)
-        // Floating HUD over live video — the canonical Liquid-Glass overlay surface (26+);
-        // falls back to .regularMaterial below 26 (see GlassStyle).
-        .glassBackground(RoundedRectangle(cornerRadius: 10))
-        .padding(10)
+    }
+
+    // MARK: - Card metrics
+
+    /// The card's inner content padding. Roomier on tvOS — the stat text auto-scales for the
+    /// couch (relative system styles), so the card's chrome must keep pace or it reads cramped.
+    private var cardPadding: CGFloat {
+        #if os(tvOS)
+        return 16
+        #else
+        return 10
+        #endif
+    }
+
+    /// The OUTER gap between the card and the screen edge. On iOS the card hugs a physically
+    /// rounded display corner, so it sits a little further in and pairs with a concentric corner
+    /// radius (below); tvOS floats it well clear of the TV's overscan-ish edge; macOS windows
+    /// keep the classic 10.
+    private var edgeInset: CGFloat {
+        #if os(iOS)
+        return 14
+        #elseif os(tvOS)
+        return 24
+        #else
+        return 10
+        #endif
+    }
+
+    /// The card's corner radius. On iOS it's concentric with the physical display corner —
+    /// `displayCornerRadius − edgeInset`, so the gap to the screen edge stays uniform right around the
+    /// corner instead of a small-radius card cutting into the very rounded glass. Clamped so a
+    /// flat-cornered device (or a hidden radius) still gets a sensibly rounded card.
+    private var cardCornerRadius: CGFloat {
+        #if os(iOS)
+        return max(12, DeviceMetrics.displayCornerRadius - edgeInset)
+        #elseif os(tvOS)
+        return 16 // scales with the roomier padding
+        #else
+        return 10
+        #endif
+    }
+
+    /// The card background shape — a continuous (squircle) rounded rectangle, matching the curve
+    /// Apple's hardware display corners use so the concentric inset actually reads as parallel.
+    private var cardShape: RoundedRectangle {
+        RoundedRectangle(cornerRadius: cardCornerRadius, style: .continuous)
     }
 }
+
+#if os(iOS)
+/// Device display geometry the overlay needs but UIKit doesn't expose publicly.
+enum DeviceMetrics {
+    /// The physical display's corner radius. There's no public API for it, so read the private
+    /// `_displayCornerRadius` via KVC on the active window scene's screen, guarded by a fallback that
+    /// approximates a modern rounded device — a future OS that hides the key just yields a slightly
+    /// less-perfect inset, never a crash. The key is assembled from parts so it isn't a plain literal
+    /// in the binary; note the App Store private-API consideration regardless.
+    static var displayCornerRadius: CGFloat {
+        let key = ["_display", "Corner", "Radius"].joined()
+        guard
+            let screen = UIApplication.shared.connectedScenes
+                .compactMap({ $0 as? UIWindowScene })
+                .first?.screen,
+            let radius = screen.value(forKey: key) as? NSNumber,
+            radius.doubleValue > 0
+        else { return 44 }
+        return CGFloat(radius.doubleValue)
+    }
+}
+#endif

clients/apple/Sources/PunktfunkClient/Settings/AcknowledgementsView.swift

@@ -1,13 +1,25 @@
 import PunktfunkKit
 import SwiftUI
 
-/// Open-source acknowledgements: punktfunk's own license (MIT OR Apache-2.0) followed by the
+/// Open-source acknowledgements: Punktfunk's own license (MIT OR Apache-2.0) followed by the
 /// third-party software notices. Used as a pushed view on iOS/tvOS and a preferences tab on macOS.
 struct AcknowledgementsView: View {
     private var version: String? {
         Bundle.main.infoDictionary?["CFBundleShortVersionString"] as? String
     }
 
+    // TV-legible sizes for the explicitly-sized text; the in-hand sizes elsewhere. (The license
+    // walls use relative system styles, which already scale per platform.)
+    #if os(tvOS)
+    private static let titleFont: CGFloat = 36
+    private static let headlineFont: CGFloat = 26
+    private static let captionFont: CGFloat = 20
+    #else
+    private static let titleFont: CGFloat = 22
+    private static let headlineFont: CGFloat = 17
+    private static let captionFont: CGFloat = 12
+    #endif
+
     var body: some View {
         ScrollView {
             // Top-level LazyVStack so the third-party-notices chunks (Licenses.thirdPartyNoticesChunks,
@@ -16,42 +28,40 @@ struct AcknowledgementsView: View {
             // notice chunks visually continuous; the header block carries its own spacing + bottom pad.
             LazyVStack(alignment: .leading, spacing: 0) {
                 VStack(alignment: .leading, spacing: 18) {
-                    Text("punktfunk")
-                        .font(.geist(22, .bold, relativeTo: .title2))
+                    Text("Punktfunk")
+                        .font(.geist(Self.titleFont, .bold, relativeTo: .title2))
                     if let version {
                         Text("Version \(version)")
-                            .font(.geist(12, relativeTo: .caption))
+                            .font(.geist(Self.captionFont, relativeTo: .caption))
                             .foregroundStyle(.secondary)
                     }
-                    Text(Licenses.appLicense)
+                    LicenseWall(text: Licenses.appLicense)
                         .font(.caption.monospaced())
-                        .modifier(SelectableText())
 
                     Divider()
 
                     Text("Bundled font")
-                        .font(.geist(17, .semibold, relativeTo: .headline))
-                    Text("punktfunk ships the Geist typeface (Geist Sans), "
+                        .font(.geist(Self.headlineFont, .semibold, relativeTo: .headline))
+                    Text("Punktfunk ships the Geist typeface (Geist Sans), "
                         + "© The Geist Project Authors / Vercel, used under the SIL Open Font "
                         + "License 1.1.")
-                        .font(.geist(12, relativeTo: .caption))
+                        .font(.geist(Self.captionFont, relativeTo: .caption))
                         .foregroundStyle(.secondary)
                     if !Licenses.fontLicense.isEmpty {
-                        Text(Licenses.fontLicense)
+                        LicenseWall(text: Licenses.fontLicense)
                             .font(.caption2.monospaced())
-                            .modifier(SelectableText())
                     }
 
                     Divider()
 
                     Text("Third-party software")
-                        .font(.geist(17, .semibold, relativeTo: .headline))
+                        .font(.geist(Self.headlineFont, .semibold, relativeTo: .headline))
                     Text(
-                        "punktfunk uses the open-source components below, each under its own license. "
+                        "Punktfunk uses the open-source components below, each under its own license. "
                             + "On some platforms FFmpeg is additionally bundled under the LGPL v2.1+ "
                             + "(dynamically linked, replaceable)."
                     )
-                    .font(.geist(12, relativeTo: .caption))
+                    .font(.geist(Self.captionFont, relativeTo: .caption))
                     .foregroundStyle(.secondary)
                 }
                 .frame(maxWidth: .infinity, alignment: .leading)
@@ -62,6 +72,7 @@ struct AcknowledgementsView: View {
                         .font(.caption2.monospaced())
                         .frame(maxWidth: .infinity, alignment: .leading)
                         .modifier(SelectableText())
+                        .modifier(TVFocusable())
                 }
             }
             .frame(maxWidth: 900, alignment: .leading)
@@ -85,3 +96,40 @@ private struct SelectableText: ViewModifier {
         #endif
     }
 }
+
+/// Focus IS scrolling on tvOS: with nothing focusable in this pushed screen the license wall
+/// couldn't move at all, and a Menu press had nothing inside the NavigationStack to route
+/// through — it suspended the whole app instead of popping. Plain (non-interactive) focusability
+/// on every license/notice chunk fixes both; a chunk is sized to about two thirds of a screen
+/// (see Licenses.chunked), so each focus step reads as a page turn. The chunks must be SMALL
+/// focus stops all the way down — one tall focusable block would strand focus at its top and the
+/// next stop could sit past the LazyVStack's instantiation window.
+private struct TVFocusable: ViewModifier {
+    func body(content: Content) -> some View {
+        #if os(tvOS)
+            content.focusable()
+        #else
+            content
+        #endif
+    }
+}
+
+/// One license wall: a single selectable Text on touch/desktop; on tvOS, focus-page-sized
+/// chunks (see TVFocusable). The caller's `.font` cascades into either form.
+private struct LicenseWall: View {
+    let text: String
+
+    var body: some View {
+        #if os(tvOS)
+        let chunks = Licenses.chunked(text)
+        ForEach(chunks.indices, id: \.self) { i in
+            Text(chunks[i])
+                .frame(maxWidth: .infinity, alignment: .leading)
+                .modifier(TVFocusable())
+        }
+        #else
+        Text(text)
+            .modifier(SelectableText())
+        #endif
+    }
+}