Merge pull request 'fix(plugin-kit): the SQLite reader never opened anything on Linux' (#78) from worktree-plugin-kit-sqlite-uri-fix into main

Reviewed-on: #78

.gitea/scripts/reconcile-latest.sh

@@ -0,0 +1,68 @@
+#!/usr/bin/env bash
+# Assert that a builder image's :latest is the SAME manifest as its content key, and
+# re-point it when it isn't.
+#
+# This is what we do instead of pinning consumers by @sha256: digest
+# (security-review-2026-08-05, H-6 — see the reasoning at the top of docker.yml). The
+# content key is a hash of the ci/ tree, so "which image should :latest be?" has an
+# answer derivable from the commit alone. Checking it on every run turns :latest from a
+# tag someone remembered to move into a function of the tree.
+#
+# Two different things make them diverge and neither is distinguishable from here:
+#
+#   - Someone overwrote :latest out of band. Post-fix that needs the push credential,
+#     but it is exactly the H-6 attack and it must not pass silently.
+#   - ci/ was reverted. The older key is already a cache hit, so nothing rebuilds and
+#     nothing re-points :latest — it stays on the newer build forever while every
+#     consumer pulls a builder that does not match the tree it is building. That bug
+#     predates this script.
+#
+# Both are repaired identically, so: repair, and shout. Failing the build instead would
+# turn a legitimate revert into a red main with no way forward.
+#
+# Reads go to the anonymous port, the single write to the authenticated one.
+set -euo pipefail
+
+IMAGE="${1:?usage: reconcile-latest.sh <image> <content-key>}"
+KEY="${2:?usage: reconcile-latest.sh <image> <content-key>}"
+: "${CI_REGISTRY:?CI_REGISTRY not set}"
+: "${CI_REGISTRY_PUSH:?CI_REGISTRY_PUSH not set}"
+: "${CI_REGISTRY_PASSWORD:?CI_REGISTRY_PASSWORD not set}"
+
+ACCEPT='Accept: application/vnd.docker.distribution.manifest.v2+json, application/vnd.oci.image.manifest.v1+json, application/vnd.oci.image.index.v1+json, application/vnd.docker.distribution.manifest.list.v2+json'
+
+# Digest of a tag, or empty if the tag does not exist. Never fails the script itself —
+# "missing" is a state this has to reason about, not an error to abort on.
+digest_of() {
+  curl -sfI -H "$ACCEPT" "http://$CI_REGISTRY/v2/$IMAGE/manifests/$1" 2>/dev/null \
+    | tr -d '\r' | sed -n 's/^[Dd]ocker-[Cc]ontent-[Dd]igest: //p' || true
+}
+
+key_digest=$(digest_of "$KEY")
+latest_digest=$(digest_of latest)
+
+if [ -z "$key_digest" ]; then
+  echo "::error::$IMAGE:$KEY has no manifest — the build or push above did not land"
+  exit 1
+fi
+
+if [ "$key_digest" = "$latest_digest" ]; then
+  echo "$IMAGE:latest == :$KEY ($key_digest)"
+  exit 0
+fi
+
+echo "::warning::$IMAGE:latest did not match its content key :$KEY — re-pointing it. If ci/ was not just reverted, someone overwrote this tag out of band: check the registry access log on home-ci-core."
+echo "  was:    ${latest_digest:-<no :latest tag>}"
+echo "  wanted: $key_digest  (:$KEY)"
+
+tmp=$(mktemp)
+trap 'rm -f "$tmp"' EXIT
+media_type=$(curl -sfI -H "$ACCEPT" "http://$CI_REGISTRY/v2/$IMAGE/manifests/$KEY" \
+  | tr -d '\r' | sed -n 's/^[Cc]ontent-[Tt]ype: //p')
+curl -sf -H "$ACCEPT" -o "$tmp" "http://$CI_REGISTRY/v2/$IMAGE/manifests/$KEY"
+curl -sf -u "ci:$CI_REGISTRY_PASSWORD" -X PUT -H "Content-Type: $media_type" \
+  --data-binary @"$tmp" "http://$CI_REGISTRY_PUSH/v2/$IMAGE/manifests/latest"
+
+now=$(digest_of latest)
+[ "$now" = "$key_digest" ] || { echo "::error::re-point failed: :latest is $now"; exit 1; }
+echo "$IMAGE:latest re-pointed to $key_digest"

.gitea/workflows/android.yml

@@ -160,6 +160,14 @@ jobs:
           key: gradle-${{ hashFiles('clients/android/**/*.gradle.kts', 'clients/android/gradle/wrapper/gradle-wrapper.properties') }}
           restore-keys: gradle-
 
+      # The kit's JVM unit tests — the pure parsers, migrations and feedback policies. They were
+      # running nowhere: this workflow only assembled, and android-screenshots.yml runs the :app
+      # module's tests, so nothing enforced :kit's. Cheap (a couple of seconds against an already
+      # built module) and it is the only automated cover those behaviours have.
+      - name: kit unit tests
+        working-directory: clients/android
+        run: ./gradlew :kit:testDebugUnitTest --stacktrace
+
       - name: assembleDebug (cargo-ndk → jniLibs → APK)
         working-directory: clients/android
         env:

.gitea/workflows/announce.yml

@@ -41,9 +41,23 @@ jobs:
         env:
           REGISTRY_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
           UPDATE_MANIFEST_KEY: ${{ secrets.UPDATE_MANIFEST_KEY }}
+          # Through the ENVIRONMENT, never interpolated into the script body. A `${{ }}` expansion
+          # is a raw textual substitution performed BEFORE the shell sees the line, so a
+          # workflow_dispatch input containing shell syntax executes as this step — and this is the
+          # step holding UPDATE_MANIFEST_KEY, the Ed25519 key every host pins to decide whether an
+          # update is real (2026-08-05 review H-6). As `$INPUT_TAG` it is only ever data.
+          INPUT_TAG: ${{ inputs.tag }}
         run: |
           set -euo pipefail
-          TAG="${{ inputs.tag }}"
+          TAG="$INPUT_TAG"
+          # Shape-check before the value reaches a URL or a filename: tags are `vX.Y.Z[-suffix]`.
+          case "$TAG" in
+            v[0-9]*) ;;
+            *) echo "refusing to publish for a tag that is not vX.Y.Z: $TAG" >&2; exit 1 ;;
+          esac
+          case "$TAG" in
+            *[!A-Za-z0-9.+_-]*) echo "tag has characters no release tag has: $TAG" >&2; exit 1 ;;
+          esac
           case "$TAG" in
             *-*) echo "pre-release tag $TAG — not publishing to the stable update feed"; exit 0 ;;
           esac
@@ -67,4 +81,7 @@ jobs:
           GITEA_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
           DISCORD_RELEASE_WEBHOOK: ${{ secrets.DISCORD_RELEASE_WEBHOOK }}
           ALLOW_PRERELEASE: ${{ inputs.allow_prerelease }}
-        run: bash scripts/ci/discord-announce.sh "${{ inputs.tag }}"
+          # Same reasoning as the publish step above: the input is data in the environment, never
+          # text spliced into the command line.
+          INPUT_TAG: ${{ inputs.tag }}
+        run: bash scripts/ci/discord-announce.sh "$INPUT_TAG"

.gitea/workflows/bench-gpu.yml

@@ -29,4 +29,9 @@ jobs:
     steps:
       - uses: actions/checkout@v4
       - name: Tier-3 GPU stream benchmark
-        run: bash scripts/bench/gpu-stream.sh "${{ inputs.mode || '1920x1080x120' }}" 12
+        # Through the environment, not interpolated into the command line: a `${{ }}` expansion is
+        # substituted before the shell parses the line, so an input carrying shell syntax would run
+        # as this step (2026-08-05 review H-6).
+        env:
+          BENCH_MODE: ${{ inputs.mode || '1920x1080x120' }}
+        run: bash scripts/bench/gpu-stream.sh "$BENCH_MODE" 12

.gitea/workflows/ci.yml

@@ -275,3 +275,31 @@ jobs:
         run: bun run build
       - name: Typecheck
         run: bun run lint
+
+  # web/bun.nix and sdk/bun.nix are GENERATED from their bun.lock (bun2nix) and committed; the Nix
+  # build fetches node_modules from nothing else. They regenerate only on a local `bun install` that
+  # runs lifecycle scripts — never under CI's `--ignore-scripts`, and never on a merge or rebase,
+  # which happily carries a lockfile change past a bun.nix generated before it. That is not
+  # theoretical: web/bun.nix sat stale on main for 553 commits (2026-07-27 → 2026-08-05) with
+  # `nix build .#punktfunk-web` broken, and was repaired only by accident when an advisory bump
+  # happened to rerun a real `bun install`.
+  #
+  # Deliberately UNFILTERED and in ci.yml rather than nix.yml: it needs no Nix, takes well under a
+  # minute, and the whole point is that the drift arrives through commits that look unrelated to
+  # Nix. The Nix-toolchain gates (flake eval + building the bun packages) live in nix.yml.
+  bun-nix:
+    runs-on: ubuntu-24.04
+    container:
+      image: oven/bun:1
+    timeout-minutes: 15
+    steps:
+      # oven/bun ships neither git nor a real node, and the slim base has no CA bundle —
+      # actions/checkout needs all three (see the web job).
+      - name: Install git + node + CA certs
+        run: apt-get update && apt-get install -y --no-install-recommends ca-certificates git nodejs
+      - uses: actions/checkout@v4
+      # Regenerates each bun.nix from its committed bun.lock and diffs, and checks that the
+      # bun2nix version pin agrees across flake.nix and both package.json files (bun.nix has no
+      # schema stability across bun2nix releases). Fix with: scripts/ci/check-bun-nix.sh --fix
+      - name: bun.nix drift gate
+        run: sh scripts/ci/check-bun-nix.sh

.gitea/workflows/decky.yml

@@ -46,7 +46,10 @@ env:
   REGISTRY: git.unom.io
   OWNER: unom
   PACKAGE: punktfunk-decky        # generic-registry package name
-  PLUGIN: punktfunk               # plugin.json "name" == zip top-level dir
+  # The plugin's ON-DISK dir == the zip's top-level dir. Deliberately NOT plugin.json "name"
+  # (that is the brand-cased label Decky lists, and it locates a plugin by matching it, not by
+  # the folder) — see clients/decky/scripts/package.sh.
+  PLUGIN: punktfunk
 
 jobs:
   build-publish:

.gitea/workflows/docker.yml

@@ -3,13 +3,18 @@
 # Two very different image families now:
 #
 #   BUILDER images (punktfunk-rust-ci{,-noble,-arm64cross}, punktfunk-fedora{,44}-rpm)
-#     live on the LAN registry (home-ci-core, 192.168.1.58:5010 — unom/infra
-#     runners/ci-core/) and are CONTENT-KEYED: the tag is a hash of what they are built
-#     from (the ci/ tree, + rust-toolchain.toml for the cross image), and a build only
-#     happens when that key has no manifest yet. A push that doesn't touch ci/ costs one
-#     curl per image (~seconds), pushes nothing over the WAN, and mints no per-SHA tag
-#     debris on the runners — the failure mode that filled the fleet's disks. `:latest`
-#     is re-pushed alongside every new key and is what the consuming workflows pin.
+#     live on the LAN registry (home-ci-core — unom/infra runners/ci-core/) and are
+#     CONTENT-KEYED: the tag is a hash of what they are built from (the ci/ tree, +
+#     rust-toolchain.toml for the cross image), and a build only happens when that key
+#     has no manifest yet. A push that doesn't touch ci/ costs one curl per image
+#     (~seconds), pushes nothing over the WAN, and mints no per-SHA tag debris on the
+#     runners — the failure mode that filled the fleet's disks. `:latest` is re-pushed
+#     alongside every new key and is what the consuming workflows pin.
+#
+#     READS come from :5010 and need no credential. WRITES go to :5011 and need
+#     CI_REGISTRY_PASSWORD. Same store behind both — a registry keys by repository name,
+#     not by the host:port the client used — so an image pushed to :5011 is the same
+#     image every consumer pulls from :5010.
 #
 #   APP images (punktfunk-web, punktfunk-docs) are deployables: they keep going to the
 #     Gitea registry (git.unom.io) with :latest + :sha-<8> (+ :vX.Y.Z on tags), because
@@ -17,8 +22,38 @@
 #
 # Host and clients are intentionally NOT containerized (see CLAUDE.md "What's left").
 #
-# REGISTRY_TOKEN: repo Actions secret, a PAT with write:package scope (app images only —
-# the LAN registry is unauthenticated inside the LAN).
+# REGISTRY_TOKEN: repo Actions secret, a PAT with write:package scope (app images).
+# CI_REGISTRY_PASSWORD: repo Actions secret, the LAN registry's push credential for user
+# `ci`. Generated on ci-core into /srv/ci/stack/registry-secret; rotate in both places.
+#
+# --- security-review-2026-08-05 H-6, FIXED 2026-08-05 -------------------------------
+# The registry used to accept anonymous pushes from any LAN peer, and every
+# secret-bearing job in this repo runs INSIDE an image pulled from it. Attacker
+# position #1 of the project's own threat model did not need to break any signing
+# logic: push one tag, and the next android.yml run executes their code in the same job
+# that does `echo "$RELEASE_KEYSTORE_BASE64" | base64 -d > release.jks`. Same shape for
+# rpm.yml (RPM_GPG_PRIVATE_KEY) and android-promote.yml (SERVICE_ACCOUNT_JSON).
+#
+# The infra half is done (unom/infra runners/ci-core/): :5010 serves GET/HEAD only and
+# refuses everything else with 405, :5011 demands basic auth on every request. The half
+# in this file is done below: pushes and release-tag manifest PUTs authenticate.
+#
+# ⚠ On the second half as the review originally worded it — "pin consumers by @sha256:
+# digest". We deliberately do something else, because after authentication the digest
+# pin no longer buys what it was meant to buy. The set of people who can overwrite a tag
+# is now exactly the set who can push to main and edit a pinned digest in this very
+# file: a pin defends against nobody it did not already trust, while costing a
+# two-commit dance on every ci/ change (~3x a month) during which consumers silently run
+# a builder image that predates the ci/ change they are testing.
+#
+# What actually closes the residual gap — a tag quietly overwritten out of band — is
+# making :latest a CHECKED function of the tree instead of a tag someone remembered to
+# move. The "Reconcile :latest" step below asserts on every run that :latest and
+# :ck-$KEY are the same digest, repairs it when they are not, and says so loudly. That
+# catches an out-of-band overwrite on the next push to main, needs no churn, and fixes
+# a real pre-existing bug on the side: reverting ci/ used to leave :latest pointing at
+# the newer build forever. Revisit inline digest pins if the push credential ever leaves
+# the maintainer trust set.
 #
 # Bootstrap note: consuming workflows pull <LAN>/punktfunk-rust-ci:latest, so the LAN
 # registry must hold a seeded :latest once (done 2026-07-29 from the last Gitea-registry
@@ -42,7 +77,10 @@ on:
 env:
   REGISTRY: git.unom.io
   OWNER: unom
+  # Read port (anonymous, GET/HEAD only) and write port (basic auth). Two doors onto
+  # one store; see the header.
   CI_REGISTRY: 192.168.1.58:5010
+  CI_REGISTRY_PUSH: 192.168.1.58:5011
 
 jobs:
   builders:
@@ -98,21 +136,40 @@ jobs:
             echo "hit=false" >> "$GITHUB_OUTPUT"
           fi
 
+      # Tagged for the WRITE port: :5010 refuses a push outright, so a tag that names it
+      # can only fail. Consumers still pull the identical image from :5010.
       - name: Build
         if: steps.exists.outputs.hit == 'false'
         # --pull is cheap now: base images come through the ci-core pull-through mirror.
         run: |
           docker build --pull ${{ matrix.buildargs }} \
             -f "${{ matrix.dockerfile }}" \
-            -t "$CI_REGISTRY/${{ matrix.image }}:$KEY" \
-            -t "$CI_REGISTRY/${{ matrix.image }}:latest" \
+            -t "$CI_REGISTRY_PUSH/${{ matrix.image }}:$KEY" \
+            -t "$CI_REGISTRY_PUSH/${{ matrix.image }}:latest" \
             ci
 
+      - name: Log in to the LAN registry
+        run: |
+          echo "$CI_REGISTRY_PASSWORD" | docker login "$CI_REGISTRY_PUSH" -u ci --password-stdin
+        env:
+          CI_REGISTRY_PASSWORD: ${{ secrets.CI_REGISTRY_PASSWORD }}
+
       - name: Push
         if: steps.exists.outputs.hit == 'false'
         run: |
-          docker push "$CI_REGISTRY/${{ matrix.image }}:$KEY"
-          docker push "$CI_REGISTRY/${{ matrix.image }}:latest"
+          docker push "$CI_REGISTRY_PUSH/${{ matrix.image }}:$KEY"
+          docker push "$CI_REGISTRY_PUSH/${{ matrix.image }}:latest"
+
+      # :latest must be whatever ci/ says it is, on every run — not only on the runs that
+      # happened to build. Two things break that: an out-of-band overwrite (the H-6
+      # attack, now only reachable by someone holding the push credential), and a plain
+      # revert of ci/, which leaves :latest on the newer build because the older key is
+      # already a cache hit and nothing re-points it. Both look identical from here and
+      # both are repaired the same way, so repair and shout rather than fail the build.
+      - name: Reconcile :latest with the content key
+        run: .gitea/scripts/reconcile-latest.sh "${{ matrix.image }}" "$KEY"
+        env:
+          CI_REGISTRY_PASSWORD: ${{ secrets.CI_REGISTRY_PASSWORD }}
 
       # A release pins reproducible builder images without any rebuild: copy the key's
       # manifest to a vX.Y.Z tag via the registry API (no image bytes move).
@@ -124,8 +181,19 @@ jobs:
             | tr -d '\r' | sed -n 's/^[Cc]ontent-[Tt]ype: //p')
           curl -sf -H "$ACCEPT" -o /tmp/manifest.json \
             "http://$CI_REGISTRY/v2/${{ matrix.image }}/manifests/$KEY"
-          curl -sf -X PUT -H "Content-Type: $MT" --data-binary @/tmp/manifest.json \
-            "http://$CI_REGISTRY/v2/${{ matrix.image }}/manifests/$GITHUB_REF_NAME"
+          curl -sf -u "ci:$CI_REGISTRY_PASSWORD" -X PUT -H "Content-Type: $MT" \
+            --data-binary @/tmp/manifest.json \
+            "http://$CI_REGISTRY_PUSH/v2/${{ matrix.image }}/manifests/$GITHUB_REF_NAME"
+        env:
+          CI_REGISTRY_PASSWORD: ${{ secrets.CI_REGISTRY_PASSWORD }}
+
+      # Today the job container is ephemeral (the ubuntu-24.04 label is a docker://
+      # image), so the credential docker login wrote would die with it anyway. Don't
+      # make that a load-bearing assumption about a runner label somebody may change to
+      # a host runner later.
+      - name: Log out of the LAN registry
+        if: always()
+        run: docker logout "$CI_REGISTRY_PUSH" || true
 
   # The aarch64 CROSS builder — a SEPARATE job because it is `FROM punktfunk-rust-ci:latest`
   # (the LAN copy) and so must not race the matrix entry that publishes that base. Consumed
@@ -164,15 +232,26 @@ jobs:
         run: |
           docker build --pull \
             -f ci/rust-ci-arm64cross.Dockerfile \
-            -t "$CI_REGISTRY/$IMAGE:$KEY" \
-            -t "$CI_REGISTRY/$IMAGE:latest" \
+            -t "$CI_REGISTRY_PUSH/$IMAGE:$KEY" \
+            -t "$CI_REGISTRY_PUSH/$IMAGE:latest" \
             .
 
+      - name: Log in to the LAN registry
+        run: |
+          echo "$CI_REGISTRY_PASSWORD" | docker login "$CI_REGISTRY_PUSH" -u ci --password-stdin
+        env:
+          CI_REGISTRY_PASSWORD: ${{ secrets.CI_REGISTRY_PASSWORD }}
+
       - name: Push
         if: steps.exists.outputs.hit == 'false'
         run: |
-          docker push "$CI_REGISTRY/$IMAGE:$KEY"
-          docker push "$CI_REGISTRY/$IMAGE:latest"
+          docker push "$CI_REGISTRY_PUSH/$IMAGE:$KEY"
+          docker push "$CI_REGISTRY_PUSH/$IMAGE:latest"
+
+      - name: Reconcile :latest with the content key
+        run: .gitea/scripts/reconcile-latest.sh "$IMAGE" "$KEY"
+        env:
+          CI_REGISTRY_PASSWORD: ${{ secrets.CI_REGISTRY_PASSWORD }}
 
       - name: Tag for release
         if: startsWith(github.ref, 'refs/tags/v')
@@ -182,8 +261,15 @@ jobs:
             | tr -d '\r' | sed -n 's/^[Cc]ontent-[Tt]ype: //p')
           curl -sf -H "$ACCEPT" -o /tmp/manifest.json \
             "http://$CI_REGISTRY/v2/$IMAGE/manifests/$KEY"
-          curl -sf -X PUT -H "Content-Type: $MT" --data-binary @/tmp/manifest.json \
-            "http://$CI_REGISTRY/v2/$IMAGE/manifests/$GITHUB_REF_NAME"
+          curl -sf -u "ci:$CI_REGISTRY_PASSWORD" -X PUT -H "Content-Type: $MT" \
+            --data-binary @/tmp/manifest.json \
+            "http://$CI_REGISTRY_PUSH/v2/$IMAGE/manifests/$GITHUB_REF_NAME"
+        env:
+          CI_REGISTRY_PASSWORD: ${{ secrets.CI_REGISTRY_PASSWORD }}
+
+      - name: Log out of the LAN registry
+        if: always()
+        run: docker logout "$CI_REGISTRY_PUSH" || true
 
   # Deployable app images — unchanged flow, Gitea registry, per-SHA + release tags.
   apps:

.gitea/workflows/nix.yml

@@ -0,0 +1,167 @@
+# Nix packaging gate. Until this existed, NOTHING in CI ever evaluated flake.nix: the word "nix"
+# appeared in exactly one workflow file, and only in a comment about bun2nix breaking a Windows
+# step. Every Nix regression therefore reached main invisibly and was found by hand on a Nix box —
+# `nix build .#punktfunk-web` was broken for 553 commits before anyone noticed (see the bun-nix job
+# in ci.yml for that story).
+#
+# Two tiers, because a full `nix flake check` builds the whole Rust workspace with crane and would
+# run for an hour on every push:
+#
+#   * eval  — `nix flake check --no-build`: instantiates every package, app, check, devShell and
+#             the NixOS module without building them. Catches the failures that actually happen to
+#             this flake — a renamed file, a callPackage argument that no longer exists, a syntax
+#             error, a package attribute dropped from packages.nix.
+#   * bun   — actually BUILDS punktfunk-web + punktfunk-scripting. These are the two derivations
+#             whose inputs churn constantly (every dependency bump moves a lockfile) and they cost
+#             minutes, not hours, because neither compiles Rust. This is the end-to-end proof that
+#             the generated bun.nix really does materialise a working node_modules offline — it
+#             covers what the ci.yml drift gate cannot, e.g. a tarball the registry no longer
+#             serves, or the codegen going quietly message-less (see packages.nix's inlang note).
+#
+# The Rust packages (punktfunk-host, punktfunk-client) and punktfunk-gamescope are NOT built here.
+# They are the expensive ones and their inputs are already gated by the `rust` job in ci.yml; build
+# them by hand on a Nix box, or with the `build-rust` dispatch input below.
+#
+# ⚠ pull_request is deliberately present. flatpak.yml shipped with push-only triggers and manifest
+# breakage reached main invisibly for weeks — do not "simplify" this workflow by dropping it.
+# ⚠ The two path lists are duplicated on purpose: a YAML anchor would be tidier, but Gitea's
+# workflow parser is not a place to bet on anchor support. Keep them in step by hand.
+name: nix
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "flake.nix"
+      - "flake.lock"
+      - "packaging/nix/**"
+      - "**/bun.lock"
+      - "**/bun.nix"
+      - "**/package.json"
+      - "Cargo.lock"
+      - "Cargo.toml"
+      - "rust-toolchain.toml"
+      - ".gitea/workflows/nix.yml"
+      - "scripts/ci/check-bun-nix.sh"
+  pull_request:
+    paths:
+      - "flake.nix"
+      - "flake.lock"
+      - "packaging/nix/**"
+      - "**/bun.lock"
+      - "**/bun.nix"
+      - "**/package.json"
+      - "Cargo.lock"
+      - "Cargo.toml"
+      - "rust-toolchain.toml"
+      - ".gitea/workflows/nix.yml"
+      - "scripts/ci/check-bun-nix.sh"
+  workflow_dispatch:
+    inputs:
+      build-rust:
+        description: "Also build punktfunk-host + punktfunk-client (slow: full Rust workspace)"
+        type: boolean
+        default: false
+
+jobs:
+  flake:
+    runs-on: ubuntu-24.04
+    container:
+      # NOT nixos/nix. That image contains nix and essentially nothing else — in particular no
+      # /bin/sleep, and Gitea's act_runner starts every job container with
+      # `entrypoint=["/bin/sleep","10800"]`. The container therefore never starts:
+      #   failed to create shim task: OCI runtime create failed: unable to start container
+      #   process: exec: "/bin/sleep": stat /bin/sleep: no such file or directory
+      # and — the part that makes this expensive to debug — every step is then reported as
+      # `cancelled` rather than failed, which reads exactly like a superseded run.
+      #
+      # node:22-bookworm instead: a full Debian with coreutils (so the entrypoint exists) and a
+      # real node (so actions/checkout works with no pre-checkout install dance), and audit.yml
+      # already pulls it on this fleet, so it is proven to resolve here. Nix is installed below.
+      image: node:22-bookworm
+    timeout-minutes: 90
+    env:
+      # The flake needs both experimental features. Also baked into the installer's --extra-conf
+      # below; this covers any step that shells out before that config is read.
+      NIX_CONFIG: "experimental-features = nix-command flakes"
+      # Absolute path rather than $GITHUB_PATH: one less runner behaviour to assume.
+      NIX: /nix/var/nix/profiles/default/bin/nix
+      # `--init none` installs Nix with NO daemon running, but the installer still writes a profile
+      # script that exports NIX_REMOTE=daemon. Anything that sources it (any `-l` login shell) then
+      # dies on `cannot connect to socket at '/nix/var/nix/daemon-socket/socket'` — which is exactly
+      # how the installer's own self-test fails during this step, harmlessly, and would be a
+      # confusing first thing to read in the log. The steps below never source that profile, but pin
+      # the empty value so a future step cannot reintroduce it. Empty = talk to the local store
+      # directly, which works because the job runs as root (MEASURED: "Store URL: local, Trusted: 1",
+      # and a real `nix build` of a trivial derivation succeeds).
+      NIX_REMOTE: ""
+    steps:
+      - uses: actions/checkout@v4
+
+      # The Determinate installer needs curl + xz; git so nix can read the flake from the checkout.
+      # (node:22-bookworm is the full image and already has all three — this is belt-and-braces
+      # against a future slim-image swap, and costs one cached apt call.)
+      - name: Installer prerequisites
+        run: apt-get update && apt-get install -y --no-install-recommends ca-certificates curl xz-utils git
+
+      # `--init none` is the container mode: no systemd, no daemon. Running as root, nix then talks
+      # to the store directly. Determinate Nix is also what the Nix box (.21) runs, so CI and the
+      # hand-verification box stay on the same distribution.
+      - name: Install Nix
+        run: |
+          curl -fsSL https://install.determinate.systems/nix -o /tmp/nix-installer.sh
+          sh /tmp/nix-installer.sh install linux --init none --no-confirm \
+            --extra-conf "experimental-features = nix-command flakes"
+          "$NIX" --version
+
+      # Nix reads the flake through libgit2 and refuses a checkout owned by another uid
+      # ("detected dubious ownership"), which is the normal case for a container job.
+      - name: Trust the checkout
+        run: git config --global --add safe.directory "$PWD"
+
+      # Diagnostics. This fleet ran a runner out of disk on 2026-08-06 (the ci.yml `web` job died
+      # with "no space left on device" mid-`bun install`), and a Nix build is the heaviest thing
+      # here — so record the headroom, or a future failure is a guess.
+      - name: Environment
+        run: df -h / /nix /tmp || true
+
+      # Evaluates + instantiates every flake output without building any of it.
+      - name: nix flake check (eval only)
+        run: |
+          "$NIX" flake check --no-build --show-trace
+
+      # The bun packages, built for real. This is the leg that would have caught the stale
+      # web/bun.nix end to end: the derivation's offline `bun install` runs against a store cache
+      # built strictly from bun.nix, so a lockfile that cache does not cover fails here.
+      # Path-filtered, so it runs only when the packaging or a lockfile actually moves. If it ever
+      # starts going red on runner disk rather than on real defects, demote it to the dispatch
+      # opt-in below rather than leaving an infra-red gate on the board.
+      - name: Build the bun packages
+        run: |
+          "$NIX" build --print-build-logs .#punktfunk-web .#punktfunk-scripting
+
+      # Both launchers exec pkgs.bun from the store; confirm they were produced and are real entry
+      # points rather than dangling wrappers.
+      - name: Smoke the built launchers
+        run: |
+          set -eu
+          web=$("$NIX" path-info .#punktfunk-web)
+          scripting=$("$NIX" path-info .#punktfunk-scripting)
+          test -x "$web/bin/punktfunk-web-server" || { echo "no punktfunk-web-server in $web" >&2; exit 1; }
+          test -x "$scripting/bin/punktfunk-scripting" || { echo "no punktfunk-scripting in $scripting" >&2; exit 1; }
+          # The console must be the bun bundle, not a node one — the same assertion packages.nix
+          # makes at build time, re-checked on the installed output.
+          grep -q 'Bun\.serve' "$web/share/punktfunk-web/.output/server/index.mjs" \
+            || { echo "installed console is not a bun bundle" >&2; exit 1; }
+          echo "bun packages OK: $web  $scripting"
+
+      # Opt-in only: the full Rust workspace through crane, which is the hour-long leg.
+      # `github.event.inputs.*` (string) rather than `inputs.*` — the portable spelling.
+      - name: Build the Rust packages (dispatch opt-in)
+        if: ${{ github.event.inputs.build-rust == 'true' }}
+        run: |
+          "$NIX" build --print-build-logs .#punktfunk-host .#punktfunk-client

.gitea/workflows/sbom.yml

@@ -38,10 +38,18 @@ jobs:
         with:
           fetch-depth: 0
       # Pinned syft (keep in sync with the version validated against this repo; bump deliberately).
+      #
+      # The BINARY version was pinned; the INSTALLER was not — it was fetched from `main` and piped
+      # into a shell, so whatever that branch happened to say at job time ran here, with the job's
+      # environment (2026-08-05 review H-6). Pinning the script to the same tag as the binary makes
+      # the whole step reproducible: bump the tag in both places together.
       - name: Install syft
+        env:
+          SYFT_VERSION: v1.49.0
         run: |
-          curl -sSfL https://raw.githubusercontent.com/anchore/syft/main/install.sh \
-            | sh -s -- -b /usr/local/bin v1.49.0
+          set -euo pipefail
+          curl -sSfL "https://raw.githubusercontent.com/anchore/syft/${SYFT_VERSION}/install.sh" \
+            | sh -s -- -b /usr/local/bin "$SYFT_VERSION"
       - name: Generate SBOM
         run: |
           git config --global --add safe.directory "$PWD"

Cargo.lock

@@ -2893,6 +2893,7 @@ dependencies = [
  "ureq",
  "wasapi",
  "windows 0.62.2 (git+https://github.com/microsoft/windows-rs?rev=acb5a1a7441033d9312b16842af02eb0c2b403dc)",
+ "winreg",
 ]
 
 [[package]]
@@ -3346,6 +3347,8 @@ dependencies = [
  "opus",
  "punktfunk-core",
  "tracing",
+ "uac-host",
+ "usbfs-iso",
 ]
 
 [[package]]
@@ -4985,6 +4988,14 @@ version = "1.20.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b6f5e870be6c3b371b77fe0ee0bafb859fa4964b4404c27de1d380043c4dda20"
 
+[[package]]
+name = "uac-host"
+version = "0.1.0"
+source = "git+https://github.com/unom-io/usbfs-iso?rev=f3de1fd62cec271d07f45664dc464f23e423e721#f3de1fd62cec271d07f45664dc464f23e423e721"
+dependencies = [
+ "usbfs-iso",
+]
+
 [[package]]
 name = "uds_windows"
 version = "1.2.1"
@@ -5064,6 +5075,14 @@ dependencies = [
  "serde",
 ]
 
+[[package]]
+name = "usbfs-iso"
+version = "0.1.0"
+source = "git+https://github.com/unom-io/usbfs-iso?rev=f3de1fd62cec271d07f45664dc464f23e423e721#f3de1fd62cec271d07f45664dc464f23e423e721"
+dependencies = [
+ "libc",
+]
+
 [[package]]
 name = "usbip-sim"
 version = "0.8.0"

api/openapi.json

@@ -10,7 +10,7 @@
       "name": "MIT OR Apache-2.0",
       "identifier": "MIT OR Apache-2.0"
     },
-    "version": "0.23.0"
+    "version": "0.24.0"
   },
   "paths": {
     "/api/v1/clients": {
@@ -1052,7 +1052,7 @@
           "library"
         ],
         "summary": "Fetch one cover-art image for a library entry",
-        "description": "Resolves `kind` (`portrait` | `hero` | `logo` | `header`) for the given library id and streams\nthe image bytes. For a Steam title, the host's own local Steam cache is tried first (exact —\nit's what the user's Steam client already shows for it), the public Steam CDN's flat URL\nconvention as a fallback (newer titles' CDN assets can live at a per-asset-hash path the host\ncan't predict, in which case this 404s and the client falls through to its next art candidate).\nOnly Steam ids are backed today; any other store 404s.",
+        "description": "Resolves `kind` (`portrait` | `hero` | `logo` | `header`) for the given library id and streams\nthe image bytes. Any id stored in the host's catalog (manual entries, provider-synced entries,\nand a library plugin's claimed-store entries) serves its local art file. A Steam title falls back\nto the in-host scanner's resolver: the host's own local Steam cache first (exact — it's what the\nuser's Steam client already shows for it), the public Steam CDN's flat URL convention second\n(newer titles' CDN assets can live at a per-asset-hash path the host can't predict, in which case\nthis 404s and the client falls through to its next art candidate).",
         "operationId": "getLibraryArt",
         "parameters": [
           {
@@ -1307,7 +1307,7 @@
           "library"
         ],
         "summary": "Replace a provider's library entries (declarative reconcile)",
-        "description": "Atomically replaces the full entry set owned by `{provider}` (RFC §8): the payload is the\nprovider's desired list, keyed by its own stable `external_id` — the host diffs, keeps each\nsurviving title's host id stable across reconciles, drops orphans, and never touches manual\nentries or other providers'. An empty array removes everything the provider owns. Emits\n`library.changed` with the provider as `source`.",
+        "description": "Atomically replaces the full entry set owned by `{provider}` (RFC §8): the payload is the\nprovider's desired list, keyed by its own stable `external_id` — the host diffs, keeps each\nsurviving title's host id stable across reconciles, drops orphans, and never touches manual\nentries or other providers'. An empty array removes everything the provider owns. Emits\n`library.changed` with the provider as `source`.\n\n`?store=` additionally **claims** that store for the provider: its entries then surface with\ndeterministic `<store>:<external_id>` ids and the store's own badge, instead of opaque\n`custom:<id>` ones — which is what lets a library plugin reproduce the entries an in-host scanner\nused to produce, right down to the GameStream app ids and client-side art caches. One provider\nper store; a second claimant gets 409. While a claim is held the matching built-in scanner is\nsuppressed, so the two never double-list. The claim is released by `DELETE`, not by an empty\nreconcile (a store can legitimately have zero installed titles).",
         "operationId": "reconcileProviderEntries",
         "parameters": [
           {
@@ -1318,6 +1318,15 @@
             "schema": {
               "type": "string"
             }
+          },
+          {
+            "name": "store",
+            "in": "query",
+            "description": "Claim this store for the provider ([a-z0-9_-], `custom`/`manual` reserved)",
+            "required": false,
+            "schema": {
+              "type": "string"
+            }
           }
         ],
         "requestBody": {
@@ -1348,7 +1357,7 @@
             }
           },
           "400": {
-            "description": "Invalid provider id or payload",
+            "description": "Invalid provider id, store id, or payload",
             "content": {
               "application/json": {
                 "schema": {
@@ -1367,6 +1376,16 @@
               }
             }
           },
+          "409": {
+            "description": "That store is already claimed by another provider",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiError"
+                }
+              }
+            }
+          },
           "500": {
             "description": "Could not persist the catalog",
             "content": {
@@ -4159,7 +4178,8 @@
           "tier",
           "platforms",
           "compatible",
-          "update_available"
+          "update_available",
+          "categories"
         ],
         "properties": {
           "author": {
@@ -4172,6 +4192,13 @@
             ],
             "description": "A revocation covering the catalogued version — do not offer this without shouting."
           },
+          "categories": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "What kind of plugin this is — the console filters Browse by these, and the Game sources\nsurface's \"Add a source\" rail shows exactly the `library` ones (design D5/D6)."
+          },
           "compatible": {
             "type": "boolean",
             "description": "Can this host install it?"
@@ -4179,6 +4206,13 @@
           "description": {
             "type": "string"
           },
+          "detected": {
+            "type": [
+              "boolean",
+              "null"
+            ],
+            "description": "Whether the launcher this plugin scans looks **installed on this host** (design D8), from the\nindex's own existence probes. `null` = the entry declares no probes for this platform, which\nthe console renders as \"unknown\" rather than \"not installed\"."
+          },
           "homepage": {
             "type": [
               "string",
@@ -4365,6 +4399,17 @@
                 ],
                 "description": "The external provider owning this entry (RFC §8), set ONLY by the provider reconcile\nAPI — `None` = a manual entry, which no provider operation ever touches, and which the\nmanual CRUD alone may edit (the converse holds too: manual CRUD refuses provider-owned\nentries, so ownership is never ambiguous)."
               },
+              "role": {
+                "$ref": "#/components/schemas/GameRole",
+                "description": "Whether this entry is a game or the launcher itself — see [`GameRole`]."
+              },
+              "store": {
+                "type": [
+                  "string",
+                  "null"
+                ],
+                "description": "The **store this entry was claimed under** (D2), stamped by a `?store=`-qualified reconcile.\n`None` = an unclaimed provider entry or a manual one, both of which surface as `custom`.\n\nMaterialized onto the entry rather than looked up in [`Catalog::claims`] on every read so an\nentry is self-describing: its id and its `store` badge derive from the entry alone, and stay\ncorrect even while the claim map is being rewritten."
+              },
               "title": {
                 "type": "string"
               }
@@ -4409,6 +4454,10 @@
                 },
                 "description": "Per-title prep/undo steps — commands run as the host user; operator-privileged config."
               },
+              "role": {
+                "$ref": "#/components/schemas/GameRole",
+                "description": "Whether this entry is a game or the launcher itself — see [`GameRole`]. A hand-added launcher\nentry is legal (an operator may want a \"Steam\" tile without installing the steam plugin)."
+              },
               "title": {
                 "type": "string"
               }
@@ -4467,6 +4516,17 @@
         "type": "object",
         "description": "What an operator (or a provider plugin) can tell the host about recognizing a title — the wire\nhalf of [`DetectSpec`], and the only part of it that is ever accepted from outside.\n\nDeliberately a **subset**: the store-derived signals (a Steam appid, a launcher's environment\nmarker) are things the host discovers for itself and would be meaningless — or dangerous — to take\non someone's word. What is left is what a provider genuinely knows and the host cannot guess: where\nthe title is installed, which executable is the game, what the process is called. All three are\noptional; supplying none is the same as supplying no hint at all.\n\nNever returned by the catalog API — see the module docs on why detect data does not cross the wire\noutbound.",
         "properties": {
+          "env_marker": {
+            "oneOf": [
+              {
+                "type": "null"
+              },
+              {
+                "$ref": "#/components/schemas/EnvMarker",
+                "description": "A launcher-stamped environment marker (D3) — see [`EnvMarker`]."
+              }
+            ]
+          },
           "exe": {
             "type": [
               "string",
@@ -4487,6 +4547,15 @@
               "null"
             ],
             "description": "The executable's file name (`Hades.exe`), when its location isn't fixed. Weakest of the three\n— see [`DetectSpec::process_name`]."
+          },
+          "steam_appid": {
+            "type": [
+              "integer",
+              "null"
+            ],
+            "format": "int32",
+            "description": "The Steam appid, for a title Steam itself installed (D3). On Linux this is the **sharpest**\nsignal that exists — Steam wraps every launch, native or Proton, in\n`reaper SteamLaunch AppId=<appid>`, whose lifetime is exactly the game's — so without it a\nsteam plugin's lease tracking would degrade from reaper-exact to install-dir prefix matching.",
+            "minimum": 0
           }
         }
       },
@@ -4715,6 +4784,27 @@
           }
         }
       },
+      "EnvMarker": {
+        "type": "object",
+        "description": "An environment variable a launcher stamps onto the game's process, identifying it.\n\nSerializable because it is now half of the inbound [`DetectHint`] too (D3) — a library plugin\nthat knows its launcher's marker (Heroic's `HEROIC_APP_NAME`, load-bearing under Proton) has to\nbe able to say so, since after extraction the host no longer reads that launcher's files itself.",
+        "required": [
+          "key"
+        ],
+        "properties": {
+          "key": {
+            "type": "string",
+            "description": "The variable name (e.g. `HEROIC_GAME_ID`).",
+            "example": "HEROIC_APP_NAME"
+          },
+          "value": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "The exact value to require, when the launcher's value identifies *this* title. `None` matches\nthe key's mere presence — only safe for launchers that run one game at a time."
+          }
+        }
+      },
       "EventKind": {
         "oneOf": [
           {
@@ -5165,6 +5255,10 @@
                 ],
                 "description": "The external provider owning this entry (custom-store entries synced by a provider\nplugin, RFC §8) — `None` for installed-store titles and manual custom entries. The\nconsole uses it for attribution; `GET /library?provider=` filters on it."
               },
+              "role": {
+                "$ref": "#/components/schemas/GameRole",
+                "description": "Whether this entry is a game or the launcher itself — see [`GameRole`]."
+              },
               "store": {
                 "type": "string",
                 "description": "Which store surfaced it: `\"steam\"` or `\"custom\"`.",
@@ -5296,6 +5390,14 @@
           }
         }
       },
+      "GameRole": {
+        "type": "string",
+        "description": "What a library entry *is* — an ordinary title, or the launcher application itself (Steam Big\nPicture, Heroic, Playnite fullscreen). Purely a presentation hint: a launcher entry launches,\nleases and lists exactly like a game (design D4), and clients that don't know the field render it\nas a plain tile. Serde-default `game` and skip-serialized when default, so the wire is unchanged\nfor every entry that doesn't opt in.",
+        "enum": [
+          "game",
+          "launcher"
+        ]
+      },
       "GameSession": {
         "type": "string",
         "description": "How a session that **launches a game** (a library id on the Hello / apps.json / Decky pin) is\nserved (`design/gamemode-and-dedicated-sessions.md` §5.2). Orthogonal to the preset/lifecycle axes\n— a top-level [`DisplayPolicy`] field, NOT part of [`EffectivePolicy`], so a preset never clobbers\nit. Linux-only in effect (a launching Windows session opens into the one desktop).",
@@ -6334,6 +6436,13 @@
           "title"
         ],
         "properties": {
+          "category": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "What KIND of plugin this is (`^[a-z][a-z0-9-]{0,31}$`), top-level rather than under `ui`\nbecause it describes the plugin, not its surface. The console knows one value today —\n`library` — which it filters **out of the nav**: six installed scanner plugins would otherwise\nflood the sidebar, and their real entry point is the Game sources surface (design D5). A\nlibrary plugin that genuinely wants its own page (rom-manager, which is much more than a\nscanner) simply omits the category."
+          },
           "title": {
             "type": "string",
             "description": "Human-readable title for the console nav entry (1–64 chars; control chars stripped)."
@@ -6366,6 +6475,13 @@
           "title"
         ],
         "properties": {
+          "category": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "The plugin's kind — see [`PluginRegistration::category`]."
+          },
           "id": {
             "type": "string"
           },
@@ -6604,6 +6720,10 @@
                 },
                 "description": "Per-title prep/undo steps — commands run as the host user; operator-privileged config."
               },
+              "role": {
+                "$ref": "#/components/schemas/GameRole",
+                "description": "Whether this entry is a game or the launcher itself — see [`GameRole`]. A library plugin\nemits its `launchers(cfg)` entries with `role: \"launcher\"`."
+              },
               "title": {
                 "type": "string"
               }
@@ -6780,26 +6900,46 @@
       },
       "ScannerInfo": {
         "type": "object",
-        "description": "One installed-store scanner this host build supports, with its enable state — the unit the\nconsole renders a toggle for. The list is platform-gated at compile time (the scanners are),\nso the console never shows a toggle that cannot do anything on this host.",
+        "description": "One **game source** on this host, with its enable state — the unit the console renders a toggle\nfor. A source is either a scanner compiled into this build or a plugin that reconciles entries in\n(WP2.6); the console treats them identically, which is what makes the extraction invisible.",
         "required": [
           "id",
           "label",
-          "enabled"
+          "enabled",
+          "origin"
         ],
         "properties": {
           "enabled": {
             "type": "boolean",
-            "description": "Whether this host runs the scanner (default true)."
+            "description": "Whether this host runs the source (default true)."
+          },
+          "entries": {
+            "type": [
+              "integer",
+              "null"
+            ],
+            "description": "How many entries this source currently contributes. `None` for a built-in scanner, whose\ncount would mean walking every launcher's files just to render a toggle.",
+            "minimum": 0
           },
           "id": {
             "type": "string",
-            "description": "Stable scanner id — the same string the scanner's entries carry in their `store` field.",
+            "description": "Stable source id — the same string this source's entries carry in their `store` field. For a\nplugin source it is also its provider id and its store claim: one string, by construction, so\na user's disabled state survives a built-in scanner being replaced by its plugin.",
             "example": "steam"
           },
           "label": {
             "type": "string",
             "description": "Human-facing name for the console toggle.",
             "example": "Steam"
+          },
+          "origin": {
+            "$ref": "#/components/schemas/SourceOrigin",
+            "description": "Where the source comes from: `builtin` (a scanner in this host build) or `plugin`."
+          },
+          "provider": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "The provider id backing a `plugin` source — absent for a built-in scanner."
           }
         }
       },
@@ -6962,6 +7102,14 @@
           }
         }
       },
+      "SourceOrigin": {
+        "type": "string",
+        "description": "Where a [`ScannerInfo`] comes from.",
+        "enum": [
+          "builtin",
+          "plugin"
+        ]
+      },
       "SourceView": {
         "type": "object",
         "description": "A configured catalog source and how its last refresh went.",

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

@@ -31,6 +31,7 @@ import androidx.compose.material3.Scaffold
 import androidx.compose.material3.Text
 import androidx.compose.runtime.Composable
 import androidx.compose.runtime.CompositionLocalProvider
+import androidx.compose.runtime.compositionLocalOf
 import androidx.compose.runtime.DisposableEffect
 import androidx.compose.runtime.LaunchedEffect
 import androidx.compose.runtime.getValue
@@ -47,6 +48,7 @@ import android.widget.Toast
 import io.unom.punktfunk.kit.link.DeepLinkResult
 import io.unom.punktfunk.kit.link.DeepLinks
 import io.unom.punktfunk.kit.link.HostResolution
+import io.unom.punktfunk.kit.SessionEndReason
 import io.unom.punktfunk.kit.security.KnownHostStore
 import io.unom.punktfunk.models.ActiveSession
 import io.unom.punktfunk.models.Tab
@@ -61,6 +63,11 @@ fun App(forceGamepadUi: Boolean = false) {
     // so the stream screen never re-reads the store behind its own connect's back.
     var session by remember { mutableStateOf<ActiveSession?>(null) }
     var tab by remember { mutableStateOf(Tab.Connect) }
+    // Set when a session ends because its game exited and it began as a library launch: the host
+    // whose library the console shell should come back to. Held HERE because the shell's own
+    // navigation state does not outlive the stream. Cleared once the shell has consumed it, so a
+    // later manual Back out of the library is not undone by a stale value.
+    var reopenLibraryHostId by remember { mutableStateOf<String?>(null) }
 
     // Console (gamepad) mode mirrors the Apple client: the setting AND (a pad is attached OR this is
     // a TV OR the dev force flag). Flips live as controllers connect/disconnect.
@@ -98,6 +105,15 @@ fun App(forceGamepadUi: Boolean = false) {
         }
     }
 
+    // The console backdrop's colour family, published once from the live settings rather than
+    // threaded through every screen that draws a backdrop. Because it is read from the SAME
+    // `settings` state the gamepad settings screen writes, stepping the Background row recolours
+    // the field behind that very row.
+    val palette = GamepadPalette.named(settings.uiPalette)
+    CompositionLocalProvider(
+        LocalGamepadPalette provides palette,
+        LocalGamepadInk provides GamepadInk.of(palette),
+    ) {
     AnimatedContent(
         targetState = session,
         transitionSpec = {
@@ -107,7 +123,20 @@ fun App(forceGamepadUi: Boolean = false) {
     ) { active ->
         if (active != null) {
             // Immersive: the stream takes the whole screen, no bottom bar.
-            StreamScreen(active, onDisconnect = { session = null })
+            StreamScreen(active) { reason ->
+                // A game launched from a library exiting is a normal finish, and the player is
+                // almost certainly after the next title — so send them back to that library rather
+                // than all the way out to host selection. The console shell's own screen state does
+                // not survive the stream (StreamScreen replaces it in the composition, discarding
+                // its `remember`s), so the intent is hoisted here and handed back on the way in.
+                reopenLibraryHostId =
+                    if (reason == SessionEndReason.GAME_EXITED && active.launchedFromLibrary) {
+                        active.hostId
+                    } else {
+                        null
+                    }
+                session = null
+            }
         } else if (gamepadUi) {
             GamepadShell(
                 settings = settings,
@@ -115,6 +144,8 @@ fun App(forceGamepadUi: Boolean = false) {
                 onConnected = { session = it },
                 deepLink = pendingLink,
                 onDeepLinkHandled = { activity?.pendingDeepLink = null },
+                reopenLibraryHostId = reopenLibraryHostId,
+                onReopenLibraryHandled = { reopenLibraryHostId = null },
             )
         } else {
             // Adaptive nav: a bottom bar on phones; on tablets / large windows a side NavigationRail
@@ -201,8 +232,16 @@ fun App(forceGamepadUi: Boolean = false) {
             }
         }
     }
+    }
 }
 
+/**
+ * The console backdrop's colour family for everything under [App] — provided from the live
+ * settings so a change on the gamepad settings screen recolours every backdrop at once. Defaults
+ * to the brand violet, which is also what a preview or a test composition gets.
+ */
+val LocalGamepadPalette = compositionLocalOf { GamepadPalette.named("violet") }
+
 /** Which console screen the gamepad shell is showing. */
 private enum class GamepadScreen { Home, Settings, Library }
 
@@ -218,11 +257,32 @@ fun GamepadShell(
     onConnected: (ActiveSession) -> Unit,
     deepLink: String? = null,
     onDeepLinkHandled: () -> Unit = {},
+    /**
+     * Open this saved host's library instead of Home on the way in — set when a game launched from
+     * it has just exited. Null (the default) starts on Home exactly as before.
+     */
+    reopenLibraryHostId: String? = null,
+    onReopenLibraryHandled: () -> Unit = {},
 ) {
     val context = LocalContext.current
     var screen by remember { mutableStateOf(GamepadScreen.Home) }
     var libraryHost by remember { mutableStateOf<io.unom.punktfunk.kit.security.KnownHost?>(null) }
 
+    // Consume the "come back to this library" intent once, on entry. Keyed on the id so a second
+    // game exit re-fires it; the parent clears it immediately, so a manual Back stays backed out.
+    // A host that has since been forgotten simply leaves us on Home rather than failing.
+    LaunchedEffect(reopenLibraryHostId) {
+        val id = reopenLibraryHostId ?: return@LaunchedEffect
+        // Navigate BEFORE acknowledging: acknowledging clears the parent's state, which re-keys
+        // this effect and cancels the coroutine running it. Nothing suspends in between today, so
+        // either order happens to work — but this one cannot be broken by a later edit that adds a
+        // suspending call. A host that has since been forgotten just leaves us on Home.
+        KnownHostStore(context).all()
+            .firstOrNull { it.id == id }
+            ?.let { libraryHost = it; screen = GamepadScreen.Library }
+        onReopenLibraryHandled()
+    }
+
     // On a TV, shrink the 10-foot UI so its elements aren't oversized. Density-aware: expand the
     // effective dp footprint to at least CONSOLE_TV_MIN_WIDTH_DP (→ smaller elements) ONLY when the
     // panel reports fewer dp than that; a low-density TV that's already spacious, and every phone /

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

@@ -191,6 +191,7 @@ internal fun ConnectTakeover(
     onCancel: () -> Unit,
     onRetry: () -> Unit,
 ) {
+    val ink = LocalGamepadInk.current
     val copy = connectCopy(phase)
     val timedOut = phase is ConnectPhase.WakeTimedOut
 
@@ -212,7 +213,7 @@ internal fun ConnectTakeover(
                     Icon(
                         Icons.Filled.Bedtime,
                         contentDescription = null,
-                        tint = Color.White.copy(alpha = 0.9f),
+                        tint = ink.fg(0.9f),
                         modifier = Modifier.size(46.dp),
                     )
                 }
@@ -221,14 +222,14 @@ internal fun ConnectTakeover(
             }
             Text(
                 copy.title,
-                color = Color.White,
+                color = ink.fg,
                 fontWeight = FontWeight.Bold,
                 fontSize = 24.sp,
                 textAlign = TextAlign.Center,
             )
             Text(
                 copy.subtitle,
-                color = Color.White.copy(alpha = 0.65f),
+                color = ink.fg(0.65f),
                 fontSize = 14.sp,
                 textAlign = TextAlign.Center,
                 fontFamily = if (copy.monoSubtitle) FontFamily.Monospace else FontFamily.Default,
@@ -249,6 +250,7 @@ internal fun ConnectTakeover(
  */
 @Composable
 private fun PulsingSpinner() {
+    val ink = LocalGamepadInk.current
     val transition = rememberInfiniteTransition(label = "connectPulse")
     val pulse by transition.animateFloat(
         initialValue = 0f,
@@ -262,14 +264,14 @@ private fun PulsingSpinner() {
             for (i in 0..1) {
                 val p = (pulse + i * 0.5f) % 1f
                 drawCircle(
-                    color = Color(0xFF8678F5).copy(alpha = (1f - p) * 0.35f),
+                    color = ink.accent.copy(alpha = (1f - p) * 0.35f),
                     radius = maxR * (0.42f + p * 0.58f),
                     style = Stroke(width = 2.dp.toPx()),
                 )
             }
         }
         CircularProgressIndicator(
-            color = Color.White,
+            color = ink.fg,
             strokeWidth = 3.dp,
             modifier = Modifier.size(54.dp),
         )

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

@@ -168,8 +168,7 @@ fun ConnectScreen(
             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()
+            discovery.restart()
         } else {
             lnpPrompt = true // rationale + "Open settings" (a permanently-denied request returns instantly)
         }
@@ -191,12 +190,27 @@ fun ConnectScreen(
     // or otherwise notify the app — this observer is what turns the grant into a live discovery.
     DisposableEffect(Unit) {
         val lifecycle = (context as? LifecycleOwner)?.lifecycle
+        // Whether we've actually been away. ON_RESUME also fires on first entry, right after the
+        // effect below starts the browse — restarting it there would be pure churn.
+        var wasPaused = false
         val obs = LifecycleEventObserver { _, event ->
-            if (event == Lifecycle.Event.ON_RESUME && !lnpGranted && hasLocalNetworkPermission(context)) {
-                lnpGranted = true
-                lnpPrompt = false
-                discovery.stop()
-                discovery.start()
+            when (event) {
+                Lifecycle.Event.ON_PAUSE -> wasPaused = true
+                Lifecycle.Event.ON_RESUME -> {
+                    if (!lnpGranted && hasLocalNetworkPermission(context)) {
+                        lnpGranted = true
+                        lnpPrompt = false
+                        discovery.restart()
+                    } else if (wasPaused) {
+                        // Coming back from the background: the browse may have been sitting idle
+                        // (or had its multicast socket torn out from under it) while we were away,
+                        // and its own re-query interval has kept doubling. Re-arm and ask again,
+                        // so returning to the screen is enough — no app restart.
+                        discovery.restart()
+                    }
+                    wasPaused = false
+                }
+                else -> {}
             }
         }
         lifecycle?.addObserver(obs)
@@ -1009,20 +1023,28 @@ fun ConnectScreen(
             // 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()) {
+            // Scan again is offered whether or not anything turned up: the case that sends people
+            // here is ONE expected host missing, not an empty list, and a browse that quietly went
+            // deaf (blocked when it started, or backed off to its hour-long re-query) looks
+            // exactly like a network without that host on it.
+            if (lnpGranted && !connecting) {
                 item(span = { GridItemSpan(maxLineSpan) }) {
                     Row(
                         modifier = Modifier.fillMaxWidth().padding(vertical = 12.dp),
                         horizontalArrangement = Arrangement.Center,
                         verticalAlignment = Alignment.CenterVertically,
                     ) {
-                        CircularProgressIndicator(modifier = Modifier.size(16.dp), strokeWidth = 2.dp)
-                        Spacer(Modifier.width(8.dp))
-                        Text(
-                            "Searching the local network…",
-                            style = MaterialTheme.typography.bodyMedium,
-                            color = MaterialTheme.colorScheme.onSurfaceVariant,
-                        )
+                        if (discovered.isEmpty()) {
+                            CircularProgressIndicator(modifier = Modifier.size(16.dp), strokeWidth = 2.dp)
+                            Spacer(Modifier.width(8.dp))
+                            Text(
+                                "Searching the local network…",
+                                style = MaterialTheme.typography.bodyMedium,
+                                color = MaterialTheme.colorScheme.onSurfaceVariant,
+                            )
+                            Spacer(Modifier.width(8.dp))
+                        }
+                        TextButton(onClick = { discovery.restart() }) { Text("Scan again") }
                     }
                 }
             }

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

@@ -410,17 +410,68 @@ private fun DsRow(usbDev: android.hardware.usb.UsbDevice) {
                         Text("Grant USB access")
                     }
                 }
-                else -> Text(
-                    if (model == DsDevice.Model.DUALSHOCK4) {
-                        "Ready — captured at stream start: rumble, lightbar and gyro are " +
-                            "driven directly."
-                    } else {
-                        "Ready — captured at stream start: rumble, adaptive triggers, lightbar " +
-                            "and gyro are driven directly."
-                    },
-                    style = MaterialTheme.typography.bodySmall,
-                    color = MaterialTheme.colorScheme.onSurfaceVariant,
-                )
+                else -> {
+                    Text(
+                        if (model == DsDevice.Model.DUALSHOCK4) {
+                            "Ready — captured at stream start: rumble, lightbar and gyro are " +
+                                "driven directly."
+                        } else {
+                            "Ready — captured at stream start: rumble, adaptive triggers, lightbar " +
+                                "and gyro are driven directly."
+                        },
+                        style = MaterialTheme.typography.bodySmall,
+                        color = MaterialTheme.colorScheme.onSurfaceVariant,
+                    )
+                    // Pad-audio self test. Deliberately reachable WITHOUT a stream: it exists to
+                    // answer "can this phone drive this pad's audio endpoint at all", and gating
+                    // that behind a live session would make it depend on the very thing one wants
+                    // to rule out when a session misbehaves. DualSense only — the DS4 has no
+                    // 4-channel haptics device.
+                    if (model != DsDevice.Model.DUALSHOCK4) {
+                        var testing by remember { mutableStateOf(false) }
+                        var result by remember { mutableStateOf<String?>(null) }
+                        result?.let {
+                            Text(
+                                it,
+                                style = MaterialTheme.typography.bodySmall,
+                                color = MaterialTheme.colorScheme.onSurfaceVariant,
+                            )
+                        }
+                        OutlinedButton(
+                            enabled = !testing,
+                            onClick = {
+                                testing = true
+                                result = null
+                                Thread({
+                                    // Its OWN connection: the renderer's descriptor must never be
+                                    // shared with another transfer engine, and that applies to
+                                    // this test as much as to the real path.
+                                    val conn = runCatching { usbManager.openDevice(usbDev) }.getOrNull()
+                                    val fd = conn?.fileDescriptor ?: -1
+                                    val r = if (fd >= 0) {
+                                        io.unom.punktfunk.kit.NativeBridge.nativePadAudioSelfTest(fd, 3, 60)
+                                    } else {
+                                        -1
+                                    }
+                                    conn?.close()
+                                    val msg = when {
+                                        r > 0 -> "Haptics test passed — $r frames to the pad."
+                                        r == -1 -> "Could not open the pad's audio interface. " +
+                                            "Some kernels refuse it; the pad still works normally."
+                                        r == -2 -> "The audio stream stopped part-way."
+                                        else -> "The stream opened but no audio reached the pad."
+                                    }
+                                    android.os.Handler(android.os.Looper.getMainLooper()).post {
+                                        result = msg
+                                        testing = false
+                                    }
+                                }, "pf-pad-selftest-ui").start()
+                            },
+                        ) {
+                            Text(if (testing) "Testing…" else "Test haptics")
+                        }
+                    }
+                }
             }
         }
     }

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

@@ -79,6 +79,7 @@ fun GamepadAddHostScreen(
     suggestedMacs: List<String> = emptyList(),
     onSave: ((KnownHost) -> Unit)? = null,
 ) {
+    val ink = LocalGamepadInk.current
     val context = LocalContext.current
     val isTv = remember { isTvDevice(context) }
     val isEdit = editHost != null
@@ -245,7 +246,7 @@ fun GamepadAddHostScreen(
                             Text(
                                 "Hosts on this network appear automatically — add one by address for everything else.",
                                 style = MaterialTheme.typography.bodyMedium,
-                                color = Color.White.copy(alpha = 0.55f),
+                                color = ink.fg(0.55f),
                                 modifier = Modifier.widthIn(max = 520.dp).padding(bottom = 8.dp),
                             )
                         }
@@ -306,6 +307,7 @@ private fun TvAddHostForm(
     onAdd: () -> Unit,
     onDismiss: () -> Unit,
 ) {
+    val ink = LocalGamepadInk.current
     BackHandler(onBack = onDismiss)
     val firstFocus = remember { FocusRequester() }
     Box(Modifier.fillMaxSize()) {
@@ -319,11 +321,11 @@ private fun TvAddHostForm(
                 .verticalScroll(rememberScrollState()),
             verticalArrangement = Arrangement.spacedBy(16.dp),
         ) {
-            Text(title, style = MaterialTheme.typography.headlineMedium, fontWeight = FontWeight.Bold, color = Color.White)
+            Text(title, style = MaterialTheme.typography.headlineMedium, fontWeight = FontWeight.Bold, color = ink.fg)
             Text(
                 "Hosts on this network appear automatically — add one by address for everything else.",
                 style = MaterialTheme.typography.bodyMedium,
-                color = Color.White.copy(alpha = 0.55f),
+                color = ink.fg(0.55f),
             )
             OutlinedTextField(
                 value = name, onValueChange = onName, singleLine = true,
@@ -362,6 +364,7 @@ private fun rowCols(row: Int): Int = if (row < KB_ACTIONS_ROW) KB_CHAR_ROWS[row]
 
 @Composable
 private fun FieldRow(f: Field, focused: Boolean, editing: Boolean, onClick: () -> Unit) {
+    val ink = LocalGamepadInk.current
     val visuals = animateConsoleFocus(active = focused || editing, editing = editing)
     val shape = RoundedCornerShape(14.dp)
     Row(
@@ -375,25 +378,26 @@ private fun FieldRow(f: Field, focused: Boolean, editing: Boolean, onClick: () -
             .padding(horizontal = 16.dp, vertical = 14.dp),
         verticalAlignment = Alignment.CenterVertically,
     ) {
-        Text(f.label, style = MaterialTheme.typography.bodyLarge, fontWeight = FontWeight.SemiBold, color = Color.White)
+        Text(f.label, style = MaterialTheme.typography.bodyLarge, fontWeight = FontWeight.SemiBold, color = ink.fg)
         Spacer(Modifier.weight(1f))
         Text(
             f.value.ifEmpty { f.placeholder },
             style = MaterialTheme.typography.bodyMedium.copy(fontFamily = FontFamily.Monospace),
-            color = if (f.value.isEmpty()) Color.White.copy(alpha = 0.35f) else Color.White,
+            color = if (f.value.isEmpty()) ink.fg(0.35f) else ink.fg,
             maxLines = 1,
             overflow = TextOverflow.Ellipsis,
         )
-        if (editing) Text(" |", color = Color(0xFF8678F5))
+        if (editing) Text(" |", color = ink.accent)
     }
 }
 
 @Composable
 private fun AddActionRow(label: String, enabled: Boolean, focused: Boolean, onClick: () -> Unit) {
+    val ink = LocalGamepadInk.current
     val visuals = animateConsoleFocus(active = focused)
     val shape = RoundedCornerShape(14.dp)
     val labelColor by animateColorAsState(
-        if (enabled) Color(0xFF8678F5) else Color.White.copy(alpha = 0.35f),
+        if (enabled) ink.accent else ink.fg(0.35f),
         tween(160),
         label = "addLabel",
     )
@@ -425,6 +429,7 @@ private fun KeyboardGrid(
     bottomInset: Dp = 0.dp, // empty frame at the bottom of the glass for the floating legend to sit over
     onKey: (Int, Int) -> Unit,
 ) {
+    val ink = LocalGamepadInk.current
     val shape = RoundedCornerShape(20.dp)
     val gap = if (compact) 5.dp else 7.dp
     Column(
@@ -433,7 +438,7 @@ private fun KeyboardGrid(
             .widthIn(max = 640.dp)
             .clip(shape)
             .background(Color(0x1FFFFFFF))
-            .border(1.dp, Color.White.copy(alpha = 0.12f), shape)
+            .border(1.dp, ink.fg(0.12f), shape)
             .padding(start = 12.dp, end = 12.dp, top = if (compact) 8.dp else 12.dp, bottom = 12.dp + bottomInset),
         verticalArrangement = Arrangement.spacedBy(gap),
     ) {
@@ -454,14 +459,15 @@ private fun KeyboardGrid(
 
 @Composable
 private fun Keycap(label: String, focused: Boolean, compact: Boolean, modifier: Modifier = Modifier, onClick: () -> Unit) {
+    val ink = LocalGamepadInk.current
     // Fast tweens: the keyboard cursor hops many keys per second under hold-to-repeat, so the
     // trailing key must have faded before the cursor is two keys away — quick, but no longer a snap.
     val bg by animateColorAsState(
-        if (focused) Color(0xFF8678F5) else Color(0x14FFFFFF),
+        if (focused) ink.accent else ink.glass,
         tween(90),
         label = "keyBg",
     )
-    val fg by animateColorAsState(if (focused) Color.Black else Color.White, tween(90), label = "keyFg")
+    val fg by animateColorAsState(if (focused) Color.Black else ink.fg, tween(90), label = "keyFg")
     Box(
         modifier = modifier
             .height(if (compact) 34.dp else 44.dp)

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

@@ -14,6 +14,8 @@ import androidx.compose.foundation.Canvas
 import androidx.compose.foundation.background
 import androidx.compose.foundation.border
 import androidx.compose.foundation.clickable
+import androidx.compose.foundation.horizontalScroll
+import androidx.compose.foundation.rememberScrollState
 import androidx.compose.foundation.layout.Arrangement
 import androidx.compose.foundation.layout.Box
 import androidx.compose.foundation.layout.PaddingValues
@@ -23,6 +25,9 @@ import androidx.compose.foundation.layout.offset
 import androidx.compose.foundation.layout.padding
 import androidx.compose.foundation.layout.size
 import androidx.compose.foundation.layout.width
+import androidx.compose.foundation.lazy.LazyRow
+import androidx.compose.foundation.lazy.itemsIndexed
+import androidx.compose.foundation.lazy.rememberLazyListState
 import androidx.compose.foundation.shape.CircleShape
 import androidx.compose.foundation.shape.RoundedCornerShape
 import androidx.compose.material.icons.Icons
@@ -31,7 +36,9 @@ import androidx.compose.material3.Icon
 import androidx.compose.material3.MaterialTheme
 import androidx.compose.material3.Text
 import androidx.compose.runtime.Composable
+import androidx.compose.runtime.LaunchedEffect
 import androidx.compose.runtime.getValue
+import androidx.compose.runtime.remember
 import androidx.compose.ui.Alignment
 import androidx.compose.ui.Modifier
 import androidx.compose.ui.draw.clip
@@ -65,9 +72,12 @@ import kotlin.math.sin
 // connected-controller status chip. One look across every screen is what makes the console UI read
 // as a coherent mode rather than a set of themed pages.
 
-/** One drifting colour blob of the aurora field. Integer [sx]/[sy] keep the loop seamless at wrap. */
+/**
+ * One drifting blob of the aurora field: where it sits, how far it wanders, and how fast. Integer
+ * [sx]/[sy] keep the loop seamless at wrap. The COLOUR is the palette's, taken from its ramp at
+ * draw time, so the field always shows several of that palette's tones at once.
+ */
 private class AuroraBlob(
-    val color: Color,
     val baseX: Float,
     val baseY: Float,
     val driftX: Float,
@@ -80,50 +90,80 @@ private class AuroraBlob(
 )
 
 private val auroraBlobs = listOf(
-    AuroraBlob(Color(0xFF877AF5), 0.30f, 0.26f, 0.16f, 0.10f, 1, 1, 0.0f, 0.62f, 0.55f), // brand violet
-    AuroraBlob(Color(0xFF3E33B8), 0.78f, 0.68f, 0.13f, 0.14f, 1, 2, 2.4f, 0.68f, 0.58f), // deep indigo
-    AuroraBlob(Color(0xFF9E4CCC), 0.16f, 0.82f, 0.12f, 0.09f, 2, 1, 4.1f, 0.52f, 0.42f), // plum
-    AuroraBlob(Color(0xFF3862DB), 0.72f, 0.14f, 0.10f, 0.08f, 1, 3, 1.2f, 0.48f, 0.40f), // cool blue
+    AuroraBlob(0.30f, 0.26f, 0.16f, 0.10f, 1, 1, 0.0f, 0.62f, 0.55f),
+    AuroraBlob(0.78f, 0.68f, 0.13f, 0.14f, 1, 2, 2.4f, 0.68f, 0.58f),
+    AuroraBlob(0.16f, 0.82f, 0.12f, 0.09f, 2, 1, 4.1f, 0.52f, 0.42f),
+    AuroraBlob(0.72f, 0.14f, 0.10f, 0.08f, 1, 3, 1.2f, 0.48f, 0.40f),
 )
 
 /**
- * The living console backdrop: soft violet-family blobs drifting over black on slow, seamless loops,
- * finished with a centre-pooling vignette and top/bottom legibility scrims. A Compose approximation
- * of the Apple client's MeshGradient aurora — same brand family, same "ambience, never content" role.
+ * The living console backdrop: soft blobs from the palette's ramp drifting over its ground on
+ * slow, seamless loops, finished with a centre-pooling vignette and top/bottom legibility scrims.
+ * A Compose approximation of the Apple client's MeshGradient aurora — same colour families, same
+ * "ambience, never content" role, and the same [GamepadPalette] setting recolours both.
+ *
+ * [calm] is what the FORM screens wear: the pools dim onto the ground so the glass rows keep real
+ * colour and luminance without the launcher's contrast. Motion is identical either way on purpose
+ * — only the contrast differs, so moving between screens can't make the field jump.
+ *
+ * Honours the system's "remove animations" accessibility setting by freezing at a fixed phase, the
+ * same courtesy the Apple client pays Reduce Motion.
  */
 @Composable
-fun GamepadAuroraBackground(modifier: Modifier = Modifier) {
+fun GamepadAuroraBackground(modifier: Modifier = Modifier, calm: Boolean = false) {
+    val ink = LocalGamepadInk.current
+    val palette = LocalGamepadPalette.current
+    val animated = animationsEnabled()
     val transition = rememberInfiniteTransition(label = "aurora")
-    // A full 0..2π sweep over ~96 s; integer per-blob multipliers make sin/cos continuous at the wrap
-    // so the field never visibly jumps when the animation restarts.
-    val angle by transition.animateFloat(
+    // A full 0..2π sweep over ~96 s; integer per-blob multipliers make sin/cos continuous at the
+    // wrap so the field never visibly jumps when the animation restarts.
+    val swept by transition.animateFloat(
         initialValue = 0f,
         targetValue = (2 * PI).toFloat(),
         animationSpec = infiniteRepeatable(tween(96_000, easing = LinearEasing), RepeatMode.Restart),
         label = "angle",
     )
+    val angle = if (animated) swept else 0f
+    val tones = palette.blobColors
+    val ground = palette.groundColor
+    // Where the scrims tend, and how hard. Mixing a PALE field toward white at the dark field's
+    // strength bleaches the chroma straight out of the gradient, so a pale palette gets under
+    // half — the same scrim strength the desktop console's shader carries.
+    val scrim = if (palette.light) ink.fg else Color.Black
+    val strength = if (palette.light) 0.45f else 1f
     Canvas(modifier) {
-        drawRect(Color.Black)
+        drawRect(ground)
         val span = max(size.width, size.height)
-        for (b in auroraBlobs) {
+        for ((i, b) in auroraBlobs.withIndex()) {
             val cx = (b.baseX + b.driftX * sin(angle * b.sx + b.phase)) * size.width
             val cy = (b.baseY + b.driftY * cos(angle * b.sy + b.phase)) * size.height
             val r = span * b.radiusFrac
+            // Calm scales each blob's contribution rather than dimming the whole canvas: the
+            // ground stays put and only the pools come down to meet it, which is the same "lower
+            // the contrast, keep the colour" the desktop console's `calm` uniform does.
+            val alpha = if (calm) b.alpha * 0.62f else b.alpha
             drawCircle(
                 brush = Brush.radialGradient(
-                    colors = listOf(b.color.copy(alpha = b.alpha), Color.Transparent),
+                    colors = listOf(tones[i].copy(alpha = alpha), Color.Transparent),
                     center = Offset(cx, cy),
                     radius = r,
                 ),
                 center = Offset(cx, cy),
                 radius = r,
-                blendMode = BlendMode.Plus,
+                // Additive only works over a DARK ground; over a pale one every blob
+                // saturates to white and the field turns grey. Pale palettes tint instead.
+                blendMode = if (palette.light) BlendMode.SrcOver else BlendMode.Plus,
             )
         }
-        // Cinematic vignette: pool light centre, sink the corners.
+        // Cinematic vignette: pool light centre, settle the corners toward the scrim. Halved under
+        // calm: a launcher's cards sit in the pooled centre, but a form screen's rows run out
+        // toward the edges, where crushing them just eats the list.
         drawRect(
             Brush.radialGradient(
-                colors = listOf(Color.Transparent, Color.Black.copy(alpha = 0.44f)),
+                colors = listOf(
+                    Color.Transparent,
+                    scrim.copy(alpha = (if (calm) 0.22f else 0.44f) * strength),
+                ),
                 center = Offset(size.width / 2, size.height / 2),
                 radius = span * 0.92f,
             ),
@@ -131,43 +171,108 @@ fun GamepadAuroraBackground(modifier: Modifier = Modifier) {
         // Top/bottom legibility scrim for the pinned title + hint bar.
         drawRect(
             Brush.verticalGradient(
-                0.0f to Color.Black.copy(alpha = 0.40f),
-                0.30f to Color.Black.copy(alpha = 0.05f),
-                0.70f to Color.Black.copy(alpha = 0.06f),
-                1.0f to Color.Black.copy(alpha = 0.42f),
+                0.0f to scrim.copy(alpha = 0.40f * strength),
+                0.30f to scrim.copy(alpha = 0.05f * strength),
+                0.70f to scrim.copy(alpha = 0.06f * strength),
+                1.0f to scrim.copy(alpha = 0.42f * strength),
             ),
         )
     }
 }
 
 /**
- * The calm backdrop for the console FORM screens (settings, add-host) — deliberately still and quiet
- * (unlike the launcher's drifting aurora), a deep indigo base with two soft brand glows so the glass
- * rows have some colour + luminance to sit on. Mirrors the Apple client's GamepadFormBackground.
+ * `false` when the user has turned animations off system-wide (Developer options' animator duration
+ * scale, or the accessibility "Remove animations" switch, which sets the same global). Read once
+ * per composition — it needs a settings trip to the system, and it changes about never.
+ */
+@Composable
+private fun animationsEnabled(): Boolean {
+    val context = LocalContext.current
+    return remember {
+        runCatching {
+            android.provider.Settings.Global.getFloat(
+                context.contentResolver,
+                android.provider.Settings.Global.ANIMATOR_DURATION_SCALE,
+                1f,
+            ) != 0f
+        }.getOrDefault(true)
+    }
+}
+
+/**
+ * The backdrop for the console FORM screens (settings, add-host). It used to be a STILL deep-indigo
+ * base with two soft glows; it is now the launcher's own living field at `calm`, which keeps that
+ * colour and luminance under the glass rows, honours the palette setting on every screen rather
+ * than only the launcher, and leaves nothing in the console UI backed by a static image. Mirrors
+ * the Apple client's GamepadFormBackground, which made the same substitution.
  */
 @Composable
 fun GamepadFormBackground(modifier: Modifier = Modifier) {
-    Canvas(modifier) {
-        val span = max(size.width, size.height)
-        drawRect(Color(0xFF131126))
-        drawCircle(
-            brush = Brush.radialGradient(
-                colors = listOf(Color(0xE6635AAE), Color.Transparent),
-                center = Offset(size.width * 0.24f, size.height * 0.12f),
-                radius = span * 0.7f,
-            ),
-            center = Offset(size.width * 0.24f, size.height * 0.12f),
-            radius = span * 0.7f,
-        )
-        drawCircle(
-            brush = Brush.radialGradient(
-                colors = listOf(Color(0xBF343E96), Color.Transparent),
-                center = Offset(size.width * 0.82f, size.height * 0.9f),
-                radius = span * 0.7f,
-            ),
-            center = Offset(size.width * 0.82f, size.height * 0.9f),
-            radius = span * 0.7f,
-        )
+    GamepadAuroraBackground(modifier, calm = true)
+}
+
+/**
+ * The horizontal section switcher above a console list. Purely presentational — the SCREEN owns
+ * which tab is selected and what the shoulders do. Scrollable so a narrow phone in landscape never
+ * has to squeeze the pills, and the selected one is always brought into view whether it was reached
+ * by shoulder button or tap.
+ */
+@Composable
+fun ConsoleTabStrip(
+    titles: List<String>,
+    selected: Int,
+    onSelect: (Int) -> Unit,
+    modifier: Modifier = Modifier,
+    /**
+     * The strip itself holds the cursor (the caller moved focus UP out of its list). Draws a ring
+     * on the selected pill so it's clear left/right now walks sections rather than values — the
+     * route a D-pad remote, which has no shoulder buttons, needs.
+     */
+    focused: Boolean = false,
+) {
+    val ink = LocalGamepadInk.current
+    val listState = rememberLazyListState()
+    LaunchedEffect(selected) {
+        runCatching { listState.animateScrollToItem(selected.coerceAtLeast(0)) }
+    }
+    LazyRow(
+        state = listState,
+        modifier = modifier,
+        contentPadding = PaddingValues(horizontal = ConsoleEdgeInset),
+        horizontalArrangement = Arrangement.spacedBy(6.dp),
+    ) {
+        itemsIndexed(titles) { i, title ->
+            val active = i == selected
+            val background by animateColorAsState(
+                if (active) ink.accent(0.85f) else ink.glass,
+                tween(180),
+                label = "tabBg",
+            )
+            // Not `ink` — that name is the palette's, and shadowing it here cost a compile.
+            val labelColor by animateColorAsState(
+                if (active) ink.onAccent else ink.fg(0.55f),
+                tween(180),
+                label = "tabInk",
+            )
+            val ring by animateColorAsState(
+                ink.fg(if (active && focused) 0.85f else 0f),
+                tween(180),
+                label = "tabRing",
+            )
+            Text(
+                title,
+                style = MaterialTheme.typography.labelLarge,
+                fontWeight = FontWeight.SemiBold,
+                color = labelColor,
+                maxLines = 1,
+                modifier = Modifier
+                    .clip(RoundedCornerShape(50))
+                    .background(background)
+                    .border(1.5.dp, ring, RoundedCornerShape(50))
+                    .clickable { onSelect(i) }
+                    .padding(horizontal = 14.dp, vertical = 7.dp),
+            )
+        }
     }
 }
 
@@ -176,7 +281,7 @@ fun GamepadFormBackground(modifier: Modifier = Modifier) {
  * sits in the SAME spot across Home / Settings / Add-Host and appears pinned while the content behind
  * it cross-fades between screens.
  */
-val ConsoleLegendInset = PaddingValues(start = 24.dp, bottom = 24.dp)
+val ConsoleLegendInset = PaddingValues(start = 24.dp, end = 24.dp, bottom = 24.dp)
 
 /** The shared horizontal inset for a console screen's heading (matches the legend's left edge). */
 val ConsoleEdgeInset = 24.dp
@@ -187,6 +292,7 @@ val ConsoleEdgeInset = 24.dp
  */
 @Composable
 fun ConsoleHeader(title: String, modifier: Modifier = Modifier, horizontalInset: Boolean = true) {
+    val ink = LocalGamepadInk.current
     // `horizontalInset = false` when the caller's container already pads to ConsoleEdgeInset (e.g. a
     // LazyColumn contentPadding) — so the heading lands at the SAME 24dp on every screen either way.
     val h = if (horizontalInset) ConsoleEdgeInset else 0.dp
@@ -194,7 +300,7 @@ fun ConsoleHeader(title: String, modifier: Modifier = Modifier, horizontalInset:
         title,
         style = MaterialTheme.typography.headlineMedium,
         fontWeight = FontWeight.Bold,
-        color = Color.White,
+        color = ink.fg,
         maxLines = 1,
         overflow = TextOverflow.Ellipsis,
         modifier = modifier.padding(start = h, end = h, top = 18.dp, bottom = 10.dp),
@@ -251,21 +357,22 @@ class ConsoleFocusVisuals(val scale: Float, val background: Color, val border: C
  */
 @Composable
 fun animateConsoleFocus(active: Boolean, editing: Boolean = false): ConsoleFocusVisuals {
+    val ink = LocalGamepadInk.current
     val scale by animateFloatAsState(
         targetValue = if (active) 1f else 0.98f,
         animationSpec = spring(dampingRatio = 0.7f, stiffness = Spring.StiffnessMediumLow),
         label = "consoleScale",
     )
     val background by animateColorAsState(
-        if (active) Color(0x336656F2) else Color(0x14FFFFFF),
+        if (active) ink.accent(0.20f) else ink.glass,
         tween(160),
         label = "consoleBg",
     )
     val border by animateColorAsState(
         when {
-            editing -> Color(0xB38678F5)
-            active -> Color.White.copy(alpha = 0.28f)
-            else -> Color.White.copy(alpha = 0.06f)
+            editing -> ink.accent(0.70f)
+            active -> ink.fg(0.28f)
+            else -> ink.fg(0.06f)
         },
         tween(160),
         label = "consoleBorder",
@@ -280,18 +387,19 @@ fun animateConsoleFocus(active: Boolean, editing: Boolean = false): ConsoleFocus
  */
 @Composable
 fun ConsoleSwitch(on: Boolean, focused: Boolean, modifier: Modifier = Modifier) {
+    val ink = LocalGamepadInk.current
     val travel by animateFloatAsState(
         targetValue = if (on) 1f else 0f,
         animationSpec = spring(dampingRatio = 0.8f, stiffness = 600f),
         label = "switchKnob",
     )
     val track by animateColorAsState(
-        if (on) Color(0xFF6656F2) else Color(0x26FFFFFF),
+        if (on) ink.accent else Color(0x26FFFFFF),
         tween(200),
         label = "switchTrack",
     )
     val outline by animateColorAsState(
-        Color.White.copy(alpha = if (focused) 0.45f else 0.15f),
+        ink.fg(if (focused) 0.45f else 0.15f),
         tween(160),
         label = "switchOutline",
     )
@@ -313,7 +421,7 @@ fun ConsoleSwitch(on: Boolean, focused: Boolean, modifier: Modifier = Modifier)
                 .offset { IntOffset(((trackW - knob - pad * 2).toPx() * travel).roundToInt(), 0) }
                 .size(knob)
                 .clip(CircleShape)
-                .background(Color.White),
+                .background(ink.fg),
         )
     }
 }
@@ -321,6 +429,7 @@ fun ConsoleSwitch(on: Boolean, focused: Boolean, modifier: Modifier = Modifier)
 /** A round face-button badge: a coloured disc with the button letter, like a controller's face. */
 @Composable
 fun GamepadButtonGlyph(glyph: Char, color: Color, size: androidx.compose.ui.unit.Dp = 26.dp) {
+    val ink = LocalGamepadInk.current
     Box(
         modifier = Modifier
             .size(size)
@@ -330,7 +439,7 @@ fun GamepadButtonGlyph(glyph: Char, color: Color, size: androidx.compose.ui.unit
     ) {
         Text(
             glyph.toString(),
-            color = Color.White,
+            color = ink.fg,
             fontWeight = FontWeight.Bold,
             fontSize = (size.value * 0.52f).sp,
             textAlign = TextAlign.Center,
@@ -341,11 +450,12 @@ fun GamepadButtonGlyph(glyph: Char, color: Color, size: androidx.compose.ui.unit
 /** The D-pad-centre "select" button — a green (confirm) disc with a ring; the TV-remote glyph for A. */
 @Composable
 private fun SelectGlyph(size: androidx.compose.ui.unit.Dp = 26.dp) {
+    val ink = LocalGamepadInk.current
     Box(
         modifier = Modifier.size(size).clip(CircleShape).background(PadGlyph.A),
         contentAlignment = Alignment.Center,
     ) {
-        Box(Modifier.size(size * 0.46f).clip(CircleShape).border(2.dp, Color.White, CircleShape))
+        Box(Modifier.size(size * 0.46f).clip(CircleShape).border(2.dp, ink.fg, CircleShape))
     }
 }
 
@@ -410,6 +520,7 @@ internal fun PsFaceGlyph(glyph: Char, size: androidx.compose.ui.unit.Dp = 26.dp)
  */
 @Composable
 internal fun SelectButtonGlyph(style: Gamepad.PadStyle, size: androidx.compose.ui.unit.Dp = 26.dp) {
+    val ink = LocalGamepadInk.current
     Box(
         Modifier.size(size).clip(CircleShape).background(PadButtonFace),
         contentAlignment = Alignment.Center,
@@ -421,17 +532,17 @@ internal fun SelectButtonGlyph(style: Gamepad.PadStyle, size: androidx.compose.u
                 val corner = RoundedCornerShape(2.dp)
                 Box(
                     Modifier.size(size * 0.32f).align(Alignment.TopEnd)
-                        .border(1.4.dp, Color.White.copy(alpha = 0.9f), corner),
+                        .border(1.4.dp, ink.fg(0.9f), corner),
                 )
                 Box(
                     Modifier.size(size * 0.32f).align(Alignment.BottomStart)
                         .clip(corner).background(PadButtonFace)
-                        .border(1.4.dp, Color.White.copy(alpha = 0.9f), corner),
+                        .border(1.4.dp, ink.fg(0.9f), corner),
                 )
             }
             Gamepad.PadStyle.NINTENDO -> Text(
                 "−",
-                color = Color.White,
+                color = ink.fg,
                 fontWeight = FontWeight.Bold,
                 fontSize = (size.value * 0.62f).sp,
                 textAlign = TextAlign.Center,
@@ -440,7 +551,7 @@ internal fun SelectButtonGlyph(style: Gamepad.PadStyle, size: androidx.compose.u
                 Modifier
                     .size(width = size * 0.58f, height = size * 0.30f)
                     .clip(RoundedCornerShape(50))
-                    .border(1.6.dp, Color.White.copy(alpha = 0.9f), RoundedCornerShape(50)),
+                    .border(1.6.dp, ink.fg(0.9f), RoundedCornerShape(50)),
             )
         }
     }
@@ -452,6 +563,7 @@ internal fun SelectButtonGlyph(style: Gamepad.PadStyle, size: androidx.compose.u
  */
 @Composable
 fun GamepadHintBar(hints: List<GamepadHint>, modifier: Modifier = Modifier, hazeState: HazeState? = null) {
+    val ink = LocalGamepadInk.current
     // On a TV D-pad remote (no A/B/X/Y), auto-swap the two universal pad glyphs every screen uses:
     // A (confirm) → the select ring, B (back/cancel) → a back glyph. Screen-specific glyphs like the
     // home's Up/Down handle themselves. A real pad instead picks its glyph FAMILY (Xbox letters /
@@ -464,14 +576,19 @@ fun GamepadHintBar(hints: List<GamepadHint>, modifier: Modifier = Modifier, haze
     // With a haze source, blur the content behind the pill (real backdrop blur, API 31+; a translucent
     // scrim below) + a light tint; otherwise fall back to a solid frosted fill.
     val frosted = if (hazeState != null) {
-        modifier.clip(shape).hazeEffect(hazeState).background(Color(0x4014122A))
+        modifier.clip(shape).hazeEffect(hazeState).background(ink.shade(0.25f))
     } else {
-        modifier.clip(shape).background(Color(0x8C14122A))
+        modifier.clip(shape).background(ink.shade(0.55f))
     }
     Row(
         modifier = frosted
-            .border(1.dp, Color.White.copy(alpha = 0.14f), shape)
-            .padding(horizontal = 16.dp, vertical = 10.dp),
+            .border(1.dp, ink.fg(0.14f), shape)
+            .padding(horizontal = 16.dp, vertical = 10.dp)
+            // The pill still hugs its content when it fits; when it doesn't (a narrow phone, or a
+            // screen whose legend grew a cell) it scrolls rather than running off the edge and
+            // silently eating the last hint — which is exactly what the settings screen's new
+            // Section cell did on a 360 dp phone.
+            .horizontalScroll(rememberScrollState()),
         verticalAlignment = Alignment.CenterVertically,
         horizontalArrangement = Arrangement.spacedBy(11.dp),
     ) {
@@ -497,7 +614,7 @@ fun GamepadHintBar(hints: List<GamepadHint>, modifier: Modifier = Modifier, haze
                 Text(
                     h.text,
                     style = MaterialTheme.typography.labelLarge,
-                    color = Color.White.copy(alpha = 0.9f),
+                    color = ink.fg(0.9f),
                     maxLines = 1,
                     softWrap = false, // never char-wrap a label when several hints crowd a narrow pill
                 )
@@ -509,24 +626,25 @@ fun GamepadHintBar(hints: List<GamepadHint>, modifier: Modifier = Modifier, haze
 /** "Which pad is driving this UI" — a quiet chip in the console top bar with the controller's name. */
 @Composable
 fun ControllerStatusChip(name: String, modifier: Modifier = Modifier) {
+    val ink = LocalGamepadInk.current
     Row(
         modifier = modifier
             .clip(RoundedCornerShape(50))
-            .background(Color.White.copy(alpha = 0.08f))
+            .background(ink.fg(0.08f))
             .padding(horizontal = 12.dp, vertical = 7.dp),
         verticalAlignment = Alignment.CenterVertically,
     ) {
         Icon(
             Icons.Filled.SportsEsports,
             contentDescription = null,
-            tint = Color.White.copy(alpha = 0.75f),
+            tint = ink.fg(0.75f),
             modifier = Modifier.size(16.dp),
         )
         Spacer(Modifier.width(7.dp))
         Text(
             name,
             style = MaterialTheme.typography.labelMedium,
-            color = Color.White.copy(alpha = 0.75f),
+            color = ink.fg(0.75f),
             maxLines = 1,
         )
     }

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

@@ -50,10 +50,12 @@ import androidx.compose.ui.platform.LocalConfiguration
 import androidx.compose.ui.text.font.FontFamily
 import androidx.compose.ui.text.font.FontWeight
 import androidx.compose.ui.text.style.TextAlign
+import androidx.compose.ui.text.style.TextOverflow
 import androidx.compose.ui.unit.dp
 import androidx.compose.ui.unit.sp
 import io.unom.punktfunk.kit.NativeBridge
 import io.unom.punktfunk.kit.security.ClientIdentity
+import io.unom.punktfunk.kit.security.KnownHost
 import io.unom.punktfunk.models.PendingTrust
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.launch
@@ -83,6 +85,7 @@ fun GamepadDialog(
     actions: List<DialogAction>,
     body: @Composable ColumnScope.() -> Unit,
 ) {
+    val ink = LocalGamepadInk.current
     // Focus the primary action; buttons are stacked full-width, navigated up/down (fits long labels
     // like "Request access" without the cramped-row wrapping a horizontal layout caused).
     var focus by remember { mutableIntStateOf(actions.indexOfFirst { it.primary }.coerceAtLeast(0)) }
@@ -115,11 +118,11 @@ fun GamepadDialog(
                 .heightIn(max = maxCardHeight)
                 .clip(RoundedCornerShape(24.dp))
                 .background(Color(0xF01A1730))
-                .border(1.dp, Color.White.copy(alpha = 0.12f), RoundedCornerShape(24.dp))
+                .border(1.dp, ink.fg(0.12f), RoundedCornerShape(24.dp))
                 .padding(28.dp),
             verticalArrangement = Arrangement.spacedBy(14.dp),
         ) {
-            Text(title, style = MaterialTheme.typography.headlineSmall, fontWeight = FontWeight.Bold, color = Color.White)
+            Text(title, style = MaterialTheme.typography.headlineSmall, fontWeight = FontWeight.Bold, color = ink.fg)
             Column(
                 Modifier.weight(1f, fill = false).verticalScroll(rememberScrollState()),
                 verticalArrangement = Arrangement.spacedBy(10.dp),
@@ -137,6 +140,7 @@ fun GamepadDialog(
 @OptIn(ExperimentalFoundationApi::class)
 @Composable
 private fun DialogButton(label: String, focused: Boolean, primary: Boolean, enabled: Boolean, onClick: () -> Unit) {
+    val ink = LocalGamepadInk.current
     val scale by animateFloatAsState(
         if (focused) 1.02f else 1f,
         spring(dampingRatio = 0.7f, stiffness = Spring.StiffnessMediumLow),
@@ -150,19 +154,19 @@ private fun DialogButton(label: String, focused: Boolean, primary: Boolean, enab
     // Focus sweeps up/down the stack — cross-fade the fills so it glides instead of snapping.
     val bg by animateColorAsState(
         when {
-            focused -> Color(0xFF6656F2)
-            primary -> Color(0x336656F2)
-            else -> Color(0x14FFFFFF)
+            focused -> ink.accent
+            primary -> ink.accent(0.20f)
+            else -> ink.glass
         },
         tween(160),
         label = "btnBg",
     )
     val fg by animateColorAsState(
         when {
-            !enabled -> Color.White.copy(alpha = 0.35f)
-            focused -> Color.White
-            primary -> Color(0xFF8678F5)
-            else -> Color.White.copy(alpha = 0.85f)
+            !enabled -> ink.fg(0.35f)
+            focused -> ink.fg
+            primary -> ink.accent
+            else -> ink.fg(0.85f)
         },
         tween(160),
         label = "btnFg",
@@ -196,7 +200,8 @@ private fun DialogButton(label: String, focused: Boolean, primary: Boolean, enab
 /** Body text helper — a dimmed paragraph. */
 @Composable
 private fun DialogText(text: String) {
-    Text(text, style = MaterialTheme.typography.bodyMedium, color = Color.White.copy(alpha = 0.7f))
+    val ink = LocalGamepadInk.current
+    Text(text, style = MaterialTheme.typography.bodyMedium, color = ink.fg(0.7f))
 }
 
 /**
@@ -250,6 +255,141 @@ fun GamepadHostOptionsDialog(
     }
 }
 
+/**
+ * The pin-to-hosts picker the settings screen's Profiles section opens — the Android mirror of the
+ * desktop console's PinHostsScreen (design §5.2a): one toggle row per SAVED host, D-pad up/down
+ * moves, A flips the focused pin, left/right unpins/pins (the settings-toggle semantics), B closes.
+ * A toggle is presentation only: it edits the host's pinned cards through the same store write the
+ * carousel's unpin uses, never the profile itself and never the host's default binding.
+ *
+ * Pin state is read live from [pinned] (backed by the host records), so what a switch shows is
+ * always what the store holds — the row can't disagree with the carousel it feeds.
+ */
+@OptIn(ExperimentalFoundationApi::class)
+@Composable
+fun GamepadPinHostsDialog(
+    profileName: String,
+    hosts: List<KnownHost>,
+    pinned: (KnownHost) -> Boolean,
+    onToggle: (KnownHost) -> Unit,
+    onDismiss: () -> Unit,
+) {
+    val ink = LocalGamepadInk.current
+    // 0..hosts.lastIndex = host rows, hosts.size = the Done button (with no hosts, index 0 IS
+    // Done, so it starts focused).
+    var focus by remember { mutableIntStateOf(0) }
+    BackHandler(onBack = onDismiss)
+    GamepadNavEffect2D(
+        active = true,
+        onDirection = { dir ->
+            when (dir) {
+                NavDir.UP -> if (focus > 0) focus--
+                NavDir.DOWN -> if (focus < hosts.size) focus++
+                // Directional = state-targeted (left → unpinned, right → pinned), so holding a
+                // direction can't oscillate; asking for the state it's already in is a no-op.
+                NavDir.LEFT -> hosts.getOrNull(focus)?.let { if (pinned(it)) onToggle(it) }
+                NavDir.RIGHT -> hosts.getOrNull(focus)?.let { if (!pinned(it)) onToggle(it) }
+            }
+        },
+        onActivate = {
+            val kh = hosts.getOrNull(focus)
+            if (kh != null) onToggle(kh) else onDismiss()
+        },
+    )
+    val maxCardHeight = (LocalConfiguration.current.screenHeightDp * 0.92f).dp
+    Box(
+        Modifier.fillMaxSize().background(Color.Black.copy(alpha = 0.62f)),
+        contentAlignment = Alignment.Center,
+    ) {
+        Column(
+            Modifier
+                .padding(24.dp)
+                .widthIn(max = 520.dp)
+                .heightIn(max = maxCardHeight)
+                .clip(RoundedCornerShape(24.dp))
+                .background(Color(0xF01A1730))
+                .border(1.dp, ink.fg(0.12f), RoundedCornerShape(24.dp))
+                .padding(28.dp),
+            verticalArrangement = Arrangement.spacedBy(14.dp),
+        ) {
+            Text(
+                "Pin “$profileName”",
+                style = MaterialTheme.typography.headlineSmall,
+                fontWeight = FontWeight.Bold,
+                color = ink.fg,
+                maxLines = 1,
+                overflow = TextOverflow.Ellipsis,
+            )
+            Column(
+                Modifier.weight(1f, fill = false).verticalScroll(rememberScrollState()),
+                verticalArrangement = Arrangement.spacedBy(10.dp),
+            ) {
+                if (hosts.isEmpty()) {
+                    DialogText("No saved hosts yet — pair with a host first, then pin this profile to it.")
+                } else {
+                    DialogText("A pinned profile appears as its own card on the host — one press connects with it.")
+                    hosts.forEachIndexed { i, kh ->
+                        PinHostRow(
+                            label = kh.name,
+                            on = pinned(kh),
+                            focused = i == focus,
+                            onClick = { onToggle(kh) },
+                        )
+                    }
+                }
+                Spacer(Modifier.size(4.dp))
+                DialogButton(
+                    "Done",
+                    focused = focus == hosts.size,
+                    primary = true,
+                    enabled = true,
+                    onClick = onDismiss,
+                )
+            }
+        }
+    }
+}
+
+/** One host's pin toggle: name + a [ConsoleSwitch], with the shared console focus visuals. */
+@OptIn(ExperimentalFoundationApi::class)
+@Composable
+private fun PinHostRow(label: String, on: Boolean, focused: Boolean, onClick: () -> Unit) {
+    val ink = LocalGamepadInk.current
+    val visuals = animateConsoleFocus(active = focused)
+    // Inside the dialog's scroll region, like DialogButton: a focused row scrolled out of a short
+    // landscape window pulls itself into view.
+    val intoView = remember { BringIntoViewRequester() }
+    LaunchedEffect(focused) { if (focused) intoView.bringIntoView() }
+    val shape = RoundedCornerShape(14.dp)
+    Row(
+        Modifier
+            .fillMaxWidth()
+            .bringIntoViewRequester(intoView)
+            .graphicsLayer { scaleX = visuals.scale; scaleY = visuals.scale }
+            .clip(shape)
+            .background(visuals.background)
+            .border(1.dp, visuals.border, shape)
+            .clickable(
+                interactionSource = remember { MutableInteractionSource() },
+                indication = null,
+                onClick = onClick,
+            )
+            .padding(horizontal = 16.dp, vertical = 13.dp),
+        verticalAlignment = Alignment.CenterVertically,
+    ) {
+        Text(
+            label,
+            style = MaterialTheme.typography.bodyLarge,
+            fontWeight = FontWeight.SemiBold,
+            color = ink.fg,
+            maxLines = 1,
+            overflow = TextOverflow.Ellipsis,
+        )
+        Spacer(Modifier.weight(1f))
+        ConsoleSwitch(on = on, focused = focused)
+    }
+}
+
 /**
  * Console counterpart of [SpeedTestDialog]. Same measurement, same targeting rule — a TV box on a
  * powerline adapter is exactly the machine whose link is worth measuring, so this belongs on the
@@ -383,6 +523,7 @@ fun GamepadRequestAccessDialog(pt: PendingTrust, onRequestAccess: () -> Unit, on
 
 @Composable
 fun GamepadAwaitingApprovalDialog(hostLabel: String, onCancel: () -> Unit) {
+    val ink = LocalGamepadInk.current
     GamepadDialog(
         title = "Waiting for approval",
         onDismiss = onCancel,
@@ -390,8 +531,8 @@ fun GamepadAwaitingApprovalDialog(hostLabel: String, onCancel: () -> Unit) {
     ) {
         val deviceName = Build.MODEL ?: "this device"
         Row(verticalAlignment = Alignment.CenterVertically, horizontalArrangement = Arrangement.spacedBy(12.dp)) {
-            CircularProgressIndicator(modifier = Modifier.size(20.dp), strokeWidth = 2.dp, color = Color.White)
-            Text("Approve this device on $hostLabel.", color = Color.White)
+            CircularProgressIndicator(modifier = Modifier.size(20.dp), strokeWidth = 2.dp, color = ink.fg)
+            Text("Approve this device on $hostLabel.", color = ink.fg)
         }
         DialogText(
             "Open the host's console (or web UI) and approve “$deviceName”. It connects automatically " +
@@ -407,6 +548,7 @@ fun GamepadAwaitingApprovalDialog(hostLabel: String, onCancel: () -> Unit) {
  */
 @Composable
 fun GamepadPairPinDialog(pt: PendingTrust, identity: ClientIdentity?, onPaired: (String) -> Unit, onDismiss: () -> Unit) {
+    val ink = LocalGamepadInk.current
     val scope = rememberCoroutineScope()
     val digits = remember(pt) { mutableStateListOf(0, 0, 0, 0) }
     var slot by remember(pt) { mutableIntStateOf(0) } // 0..3 = digit slots, 4 = Pair button
@@ -452,16 +594,16 @@ fun GamepadPairPinDialog(pt: PendingTrust, identity: ClientIdentity?, onPaired:
         Column(
             Modifier.padding(24.dp).widthIn(max = 460.dp).heightIn(max = maxCardHeight)
                 .clip(RoundedCornerShape(24.dp))
-                .background(Color(0xF01A1730)).border(1.dp, Color.White.copy(alpha = 0.12f), RoundedCornerShape(24.dp))
+                .background(Color(0xF01A1730)).border(1.dp, ink.fg(0.12f), RoundedCornerShape(24.dp))
                 .verticalScroll(rememberScrollState())
                 .padding(28.dp),
             horizontalAlignment = Alignment.CenterHorizontally,
             verticalArrangement = Arrangement.spacedBy(18.dp),
         ) {
-            Text("Pair with PIN", style = MaterialTheme.typography.headlineSmall, fontWeight = FontWeight.Bold, color = Color.White)
+            Text("Pair with PIN", style = MaterialTheme.typography.headlineSmall, fontWeight = FontWeight.Bold, color = ink.fg)
             Text(
                 "Enter the 4-digit PIN shown on the host — D-pad ↑↓ sets a digit, ←→ moves.",
-                style = MaterialTheme.typography.bodyMedium, color = Color.White.copy(alpha = 0.7f), textAlign = TextAlign.Center,
+                style = MaterialTheme.typography.bodyMedium, color = ink.fg(0.7f), textAlign = TextAlign.Center,
             )
             Row(horizontalArrangement = Arrangement.spacedBy(12.dp)) {
                 repeat(4) { i -> PinSlot(digits[i], focused = slot == i && !pairing) }
@@ -480,13 +622,14 @@ fun GamepadPairPinDialog(pt: PendingTrust, identity: ClientIdentity?, onPaired:
 
 @Composable
 private fun PinSlot(value: Int, focused: Boolean) {
+    val ink = LocalGamepadInk.current
     val shape = RoundedCornerShape(12.dp)
     Box(
         Modifier.size(54.dp, 66.dp).clip(shape)
-            .background(if (focused) Color(0x336656F2) else Color(0x14FFFFFF))
-            .border(if (focused) 2.dp else 1.dp, if (focused) Color(0xFF8678F5) else Color.White.copy(alpha = 0.1f), shape),
+            .background(if (focused) ink.accent(0.20f) else ink.glass)
+            .border(if (focused) 2.dp else 1.dp, if (focused) ink.accent else ink.fg(0.1f), shape),
         contentAlignment = Alignment.Center,
     ) {
-        Text(value.toString(), fontSize = 30.sp, fontWeight = FontWeight.Bold, color = Color.White, fontFamily = FontFamily.Monospace)
+        Text(value.toString(), fontSize = 30.sp, fontWeight = FontWeight.Bold, color = ink.fg, fontFamily = FontFamily.Monospace)
     }
 }

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

@@ -247,9 +247,10 @@ fun GamepadHome(
 /** One dark-glass landscape console tile — bigger and bolder than the touch grid's HostCard. */
 @Composable
 private fun GamepadHostTile(tile: HomeTile, modifier: Modifier = Modifier) {
+    val ink = LocalGamepadInk.current
     val shape = RoundedCornerShape(26.dp)
     val wash = if (tile.filled) {
-        Brush.verticalGradient(listOf(Color(0x336656F2), Color(0x14100C2A)))
+        Brush.verticalGradient(listOf(ink.accent(0.20f), Color(0x14100C2A)))
     } else {
         Brush.verticalGradient(listOf(Color(0x1AFFFFFF), Color(0x0DFFFFFF)))
     }
@@ -258,7 +259,7 @@ private fun GamepadHostTile(tile: HomeTile, modifier: Modifier = Modifier) {
             .fillMaxWidth()
             .clip(shape)
             .background(wash)
-            .border(1.dp, Color.White.copy(alpha = 0.16f), shape)
+            .border(1.dp, ink.fg(0.16f), shape)
             .padding(22.dp),
     ) {
         Row(Modifier.fillMaxWidth(), verticalAlignment = Alignment.Top) {
@@ -269,7 +270,7 @@ private fun GamepadHostTile(tile: HomeTile, modifier: Modifier = Modifier) {
                     Icon(
                         Icons.Filled.Lock,
                         contentDescription = "Paired",
-                        tint = Color.White.copy(alpha = 0.7f),
+                        tint = ink.fg(0.7f),
                         modifier = Modifier.padding(end = 6.dp).size(15.dp),
                     )
                 }
@@ -286,14 +287,14 @@ private fun GamepadHostTile(tile: HomeTile, modifier: Modifier = Modifier) {
             tile.title,
             style = MaterialTheme.typography.titleLarge,
             fontWeight = FontWeight.Bold,
-            color = Color.White,
+            color = ink.fg,
             maxLines = 1,
             overflow = TextOverflow.Ellipsis,
         )
         Text(
             tile.subtitle,
             style = MaterialTheme.typography.bodyMedium,
-            color = Color.White.copy(alpha = 0.55f),
+            color = ink.fg(0.55f),
             maxLines = 1,
             overflow = TextOverflow.Ellipsis,
         )
@@ -302,9 +303,10 @@ private fun GamepadHostTile(tile: HomeTile, modifier: Modifier = Modifier) {
 
 @Composable
 private fun MonogramBadge(tile: HomeTile) {
+    val ink = LocalGamepadInk.current
     val shape = RoundedCornerShape(15.dp)
     val fill = if (tile.filled) {
-        Brush.verticalGradient(listOf(Color(0xFF6656F2), Color(0xFF8678F5)))
+        Brush.verticalGradient(listOf(ink.accent, ink.accent))
     } else {
         Brush.verticalGradient(listOf(Color(0x296656F2), Color(0x296656F2)))
     }
@@ -316,18 +318,18 @@ private fun MonogramBadge(tile: HomeTile) {
             tile.connecting -> CircularProgressIndicator(
                 modifier = Modifier.size(24.dp),
                 strokeWidth = 2.dp,
-                color = Color.White,
+                color = ink.fg,
             )
             tile.isAdd -> Icon(
                 Icons.Filled.Add,
                 contentDescription = null,
-                tint = if (tile.filled) Color.White else Color(0xFF8678F5),
+                tint = if (tile.filled) ink.fg else ink.accent,
             )
             else -> Text(
                 tile.title.trim().firstOrNull()?.uppercaseChar()?.toString() ?: "•",
                 style = MaterialTheme.typography.titleLarge,
                 fontWeight = FontWeight.Bold,
-                color = if (tile.filled) Color.White else Color(0xFF8678F5),
+                color = if (tile.filled) ink.fg else ink.accent,
             )
         }
     }

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

@@ -0,0 +1,89 @@
+package io.unom.punktfunk
+
+import androidx.compose.runtime.compositionLocalOf
+import androidx.compose.ui.graphics.Color
+
+// The ink the console (gamepad) UI draws with under the chosen background palette.
+//
+// The console screens were white-on-dark throughout with the brand violet hardcoded as the accent.
+// Both had to become palette-derived at once: a pale field needs dark text or it is unreadable,
+// and a violet focus wash on a copper field is exactly the clash this exists to fix.
+//
+// Published as a CompositionLocal rather than passed down, so a leaf (a row, a hint pill, a card)
+// can ask for the right colour without every caller in between knowing about palettes. The Apple
+// client uses an environment value and `pf-console-ui` a thread-local for the same reason.
+
+/** Everything about the console's look that follows the chosen palette. */
+class GamepadInk(
+    /** Primary text/glyph colour. */
+    val fg: Color,
+    /** Focus wash, selected tab pill, switch track — the palette's own accent. */
+    val accent: Color,
+    /** What reads ON the accent (a filled pill's label, a switch knob). */
+    val onAccent: Color,
+    /** The base fill every glass surface starts from, at its resting opacity. */
+    val glass: Color,
+    /** What a wash laid UNDER text tends toward: black on a dark field, white on a pale one. */
+    val shade: Color,
+    /**
+     * How hard those washes go. A pale field needs far less — mixing toward white at the dark
+     * field's strength bleaches the chroma straight out of the gradient.
+     */
+    val shadeScale: Float,
+    /** True when the field is pale, for the few places that branch rather than blend. */
+    val isLight: Boolean,
+) {
+    /** The foreground at [alpha]. */
+    fun fg(alpha: Float): Color = fg.copy(alpha = alpha)
+
+    /** The accent at [alpha]. */
+    fun accent(alpha: Float): Color = accent.copy(alpha = alpha)
+
+    /** A wash under text: [alpha] is the dark-field strength, scaled for a pale one. */
+    fun shade(alpha: Float): Color = shade.copy(alpha = alpha * shadeScale)
+
+    companion object {
+        fun of(p: GamepadPalette): GamepadInk {
+            val accent = p.accentColor
+            // Chosen by luminance, not by `light`: an accent is picked for contrast against the
+            // GLASS, not against the field.
+            val accentLuma =
+                0.2126 * p.accent.first + 0.7152 * p.accent.second + 0.0722 * p.accent.third
+            val onAccent = if (accentLuma > 0.55) Color.Black else Color.White
+            if (!p.light) {
+                return GamepadInk(
+                    fg = Color.White,
+                    accent = accent,
+                    onAccent = onAccent,
+                    glass = Color.White.copy(alpha = 0.08f),
+                    shade = Color.Black,
+                    shadeScale = 1f,
+                    isLight = false,
+                )
+            }
+            val (gr, gg, gb) = p.ground
+            return GamepadInk(
+                // Tinted toward the palette's own ground so it doesn't read as a foreign grey.
+                fg = Color((gr * 0.16).toFloat(), (gg * 0.14).toFloat(), (gb * 0.20).toFloat()),
+                accent = accent,
+                onAccent = onAccent,
+                // More body than the dark glass carries: white frost over a bright gradient has
+                // far less separating it from its backdrop than dark glass over a dark one.
+                glass = Color.White.copy(alpha = 0.55f),
+                shade = Color.White,
+                shadeScale = 0.45f,
+                isLight = true,
+            )
+        }
+
+        /** The shipped dark look — what a preview or a test composition gets. */
+        val DARK = of(GamepadPalette.named("violet"))
+    }
+}
+
+/**
+ * The ink of the palette currently drawing, for everything under [App]. Provided from the live
+ * settings alongside [LocalGamepadPalette], so a change on the gamepad settings screen re-inks
+ * every console surface at once.
+ */
+val LocalGamepadInk = compositionLocalOf { GamepadInk.DARK }

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

@@ -152,8 +152,9 @@ fun GamepadNavEffect(
  * keyboard). Same hysteresis + hold-to-repeat as [GamepadNavEffect] but on both axes — the dominant
  * stick axis (or the pressed D-pad/HAT) commits a [NavDir], and it re-arms only after the stick
  * returns near centre (so a flick is one step). [onActivate] is A / center, [onTertiary] is X,
- * [onSecondary] is Y. B is left to MainActivity's BACK remap → the screen's BackHandler (so B "peels
- * one layer": close the keyboard, then the screen).
+ * [onSecondary] is Y, and [onShoulder] is L1 (-1) / R1 (+1) — a step SIDEWAYS out of the list, which
+ * the settings screen uses for its section tabs. B is left to MainActivity's BACK remap → the
+ * screen's BackHandler (so B "peels one layer": close the keyboard, then the screen).
  */
 @Composable
 fun GamepadNavEffect2D(
@@ -162,6 +163,7 @@ fun GamepadNavEffect2D(
     onActivate: () -> Unit,
     onTertiary: () -> Unit = {},
     onSecondary: () -> Unit = {},
+    onShoulder: (Int) -> Unit = {},
 ) {
     val activity = LocalContext.current as? MainActivity ?: return
     val state = remember { NavInputState() }
@@ -169,6 +171,7 @@ fun GamepadNavEffect2D(
     val currentOnActivate by rememberUpdatedState(onActivate)
     val currentOnTertiary by rememberUpdatedState(onTertiary)
     val currentOnSecondary by rememberUpdatedState(onSecondary)
+    val currentOnShoulder by rememberUpdatedState(onShoulder)
 
     DisposableEffect(active) {
         // Stable probe refs so onDispose only releases the slot if WE still own it — during a
@@ -196,7 +199,10 @@ fun GamepadNavEffect2D(
                 KeyEvent.KEYCODE_ENTER, KeyEvent.KEYCODE_NUMPAD_ENTER -> { if (edge) currentOnActivate(); true }
                 KeyEvent.KEYCODE_BUTTON_X -> { if (edge) currentOnTertiary(); true }
                 KeyEvent.KEYCODE_BUTTON_Y -> { if (edge) currentOnSecondary(); true }
-                else -> false // B / shoulders → MainActivity (B remaps to BACK → BackHandler)
+                // Edge-only, no auto-repeat: a held shoulder shouldn't spin through the tabs.
+                KeyEvent.KEYCODE_BUTTON_L1 -> { if (edge) currentOnShoulder(-1); true }
+                KeyEvent.KEYCODE_BUTTON_R1 -> { if (edge) currentOnShoulder(1); true }
+                else -> false // B → MainActivity (remapped to BACK → BackHandler)
             }
         }
         if (active) {

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

@@ -0,0 +1,218 @@
+package io.unom.punktfunk
+
+import androidx.compose.ui.graphics.Color
+
+// The console (gamepad) UI's background colour families, and the ink each one calls for.
+//
+// A palette is a short ordered ramp of DISTINCT hues, not one hue at several brightnesses. The
+// field samples that ramp so several tones show at once and pool into each other, the way a real
+// gradient poster does. An earlier version rotated ONE field's hue per palette, which is why every
+// non-default palette read flat and monotone.
+//
+// A palette also owns the UI sitting on it: [accent] is the focus wash / selected pill / switch
+// colour, and [light] flips the ink so a pale field gets dark text instead of white.
+//
+// The table, [ramp] and [CELL_RAMP] are mirrored in `pf-console-ui`'s `library.rs` (Rust) and the
+// Apple client's `GamepadPalette.swift` under the same ids, so one `ui_palette` value is one look
+// on every client. Keep the three copies in step: a palette added here without the others is a
+// value the other clients silently render as Violet.
+
+/** One background colour family. */
+class GamepadPalette(
+    /** The stored `ui_palette` value ([Settings.uiPalette]). */
+    val id: String,
+    /** What the settings row shows. */
+    val name: String,
+    /**
+     * The colour ramp, dark end first. Empty = the brand default's explicit field, kept
+     * bit-identical to what every install already sees.
+     */
+    val stops: List<Triple<Double, Double, Double>>,
+    /** The field's ground — what it settles onto and what the calm mix lifts toward. */
+    val ground: Triple<Double, Double, Double>,
+    /** The UI accent: focus wash, selected tab pill, switch track. */
+    val accent: Triple<Double, Double, Double>,
+    /** A pale field: the UI flips to dark ink and the legibility scrims go white. */
+    val light: Boolean,
+) {
+    /** Four drifting blob colours, spread across the ramp so the field shows several hues. */
+    val blobColors: List<Color> by lazy {
+        val s = stops.ifEmpty { VIOLET_BLOBS }
+        (0..3).map { color(ramp(s, 0.15 + 0.25 * it)) }
+    }
+
+    /** The field's ground as a Compose colour. */
+    val groundColor: Color by lazy { color(ground) }
+
+    /** The accent as a Compose colour. */
+    val accentColor: Color by lazy { color(accent) }
+
+    companion object {
+        /**
+         * Where each of the 16 mesh cells samples the ramp on the clients that draw a mesh. Kept
+         * here so the three ports stay one table even though this client approximates the field
+         * with blobs.
+         */
+        val CELL_RAMP = listOf(
+            0.10, -0.06, 0.04, -0.12,
+            -0.08, 0.14, -0.10, 0.06,
+            0.06, -0.12, 0.16, -0.04,
+            -0.10, 0.08, -0.06, 0.12,
+        )
+
+        /** The brand default's blob ramp — the colours the pre-palette field used. */
+        private val VIOLET_BLOBS = listOf(
+            Triple(0.53, 0.47, 0.96), Triple(0.24, 0.20, 0.72), Triple(0.62, 0.30, 0.80),
+            Triple(0.22, 0.38, 0.86), Triple(0.53, 0.47, 0.96),
+        )
+
+        /**
+         * The twelve shipped palettes: the brand default, five more dark fields, then six pale
+         * ones. Cycling order runs dark → light, so stepping the row walks the range one way.
+         */
+        val ALL = listOf(
+            // --- dark fields (white ink) ---
+            GamepadPalette(
+                "violet", "Violet", emptyList(),
+                ground = Triple(0.075, 0.060, 0.160),
+                accent = Triple(0.525, 0.471, 0.961), light = false,
+            ),
+            GamepadPalette(
+                // Deep indigo climbing through violet into a hot magenta.
+                "nebula", "Nebula",
+                listOf(
+                    Triple(0.07, 0.05, 0.20), Triple(0.26, 0.14, 0.54), Triple(0.52, 0.20, 0.72),
+                    Triple(0.82, 0.26, 0.62), Triple(0.98, 0.46, 0.68),
+                ),
+                ground = Triple(0.055, 0.040, 0.135),
+                accent = Triple(0.95, 0.42, 0.72), light = false,
+            ),
+            GamepadPalette(
+                // Ink-blue water: teal → cerulean → a violet undertow.
+                "abyss", "Abyss",
+                listOf(
+                    Triple(0.02, 0.10, 0.17), Triple(0.04, 0.28, 0.42), Triple(0.07, 0.46, 0.63),
+                    Triple(0.16, 0.38, 0.78), Triple(0.26, 0.22, 0.58),
+                ),
+                ground = Triple(0.018, 0.070, 0.130),
+                accent = Triple(0.26, 0.76, 0.92), light = false,
+            ),
+            GamepadPalette(
+                // Banked coals: plum embers → crimson → burnt orange → gold.
+                "ember", "Ember",
+                listOf(
+                    Triple(0.16, 0.03, 0.10), Triple(0.45, 0.06, 0.12), Triple(0.72, 0.18, 0.06),
+                    Triple(0.90, 0.42, 0.08), Triple(0.95, 0.68, 0.18),
+                ),
+                ground = Triple(0.090, 0.035, 0.040),
+                accent = Triple(0.98, 0.62, 0.26), light = false,
+            ),
+            GamepadPalette(
+                // Forest floor into moss and a lime break.
+                "moss", "Moss",
+                listOf(
+                    Triple(0.03, 0.11, 0.09), Triple(0.06, 0.27, 0.20), Triple(0.09, 0.45, 0.31),
+                    Triple(0.28, 0.61, 0.28), Triple(0.58, 0.77, 0.31),
+                ),
+                ground = Triple(0.025, 0.085, 0.070),
+                accent = Triple(0.48, 0.86, 0.46), light = false,
+            ),
+            GamepadPalette(
+                // Neutral, but never flat: barely-there saturation that still travels from a cool
+                // charcoal to a warm stone.
+                "graphite", "Graphite",
+                listOf(
+                    Triple(0.06, 0.07, 0.11), Triple(0.15, 0.18, 0.25), Triple(0.30, 0.31, 0.35),
+                    Triple(0.45, 0.42, 0.38), Triple(0.60, 0.56, 0.49),
+                ),
+                ground = Triple(0.055, 0.055, 0.070),
+                accent = Triple(0.78, 0.80, 0.86), light = false,
+            ),
+            // --- pale fields (dark ink) ---
+            GamepadPalette(
+                // The holographic foil: rose → lilac → periwinkle → aqua, with a white bloom.
+                "holo", "Holo",
+                listOf(
+                    Triple(0.99, 0.72, 0.90), Triple(0.80, 0.60, 0.98), Triple(0.58, 0.62, 0.99),
+                    Triple(0.55, 0.86, 0.98), Triple(0.94, 0.98, 1.00),
+                ),
+                ground = Triple(0.96, 0.92, 0.99),
+                accent = Triple(0.42, 0.28, 0.86), light = true,
+            ),
+            GamepadPalette(
+                // The poster sunset: periwinkle → magenta → scarlet → tangerine → gold.
+                "sunset", "Sunset",
+                listOf(
+                    Triple(0.55, 0.45, 0.92), Triple(0.86, 0.31, 0.66), Triple(0.97, 0.26, 0.34),
+                    Triple(0.99, 0.51, 0.18), Triple(1.00, 0.80, 0.22),
+                ),
+                ground = Triple(0.98, 0.74, 0.34),
+                accent = Triple(0.64, 0.13, 0.44), light = true,
+            ),
+            GamepadPalette(
+                // Peach into blush and lilac — the softest of the set.
+                "bloom", "Bloom",
+                listOf(
+                    Triple(1.00, 0.86, 0.72), Triple(0.99, 0.73, 0.79), Triple(0.95, 0.65, 0.89),
+                    Triple(0.82, 0.68, 0.96), Triple(0.73, 0.79, 0.99),
+                ),
+                ground = Triple(0.99, 0.90, 0.89),
+                accent = Triple(0.72, 0.24, 0.55), light = true,
+            ),
+            GamepadPalette(
+                // First light: pale gold → coral → lilac.
+                "dawn", "Dawn",
+                listOf(
+                    Triple(1.00, 0.92, 0.70), Triple(1.00, 0.80, 0.62), Triple(0.99, 0.66, 0.62),
+                    Triple(0.90, 0.62, 0.78), Triple(0.77, 0.69, 0.95),
+                ),
+                ground = Triple(1.00, 0.93, 0.82),
+                accent = Triple(0.82, 0.33, 0.28), light = true,
+            ),
+            GamepadPalette(
+                // Sea glass: mint → aqua → a pale sky.
+                "mint", "Mint",
+                listOf(
+                    Triple(0.82, 0.98, 0.90), Triple(0.62, 0.94, 0.88), Triple(0.55, 0.88, 0.95),
+                    Triple(0.63, 0.82, 0.99), Triple(0.82, 0.87, 1.00),
+                ),
+                ground = Triple(0.90, 0.98, 0.96),
+                accent = Triple(0.04, 0.42, 0.40), light = true,
+            ),
+            GamepadPalette(
+                // Near-white, but iridescent rather than flat — rose, sky, mint and cream in turn.
+                "opal", "Opal",
+                listOf(
+                    Triple(0.98, 0.92, 0.96), Triple(0.87, 0.93, 0.99), Triple(0.91, 0.99, 0.95),
+                    Triple(0.99, 0.96, 0.88), Triple(0.94, 0.90, 0.99),
+                ),
+                ground = Triple(0.97, 0.96, 0.99),
+                accent = Triple(0.36, 0.32, 0.44), light = true,
+            ),
+        )
+
+        /**
+         * The palette stored under [id], falling back to the brand default — an unknown name is a
+         * palette a newer client shipped, not a reason to draw nothing.
+         */
+        fun named(id: String): GamepadPalette = ALL.firstOrNull { it.id == id } ?: ALL[0]
+
+        /** Sample an ordered colour ramp at [t] ∈ [0, 1] (linear between neighbouring stops). */
+        fun ramp(
+            stops: List<Triple<Double, Double, Double>>,
+            t: Double,
+        ): Triple<Double, Double, Double> {
+            if (stops.isEmpty()) return Triple(0.0, 0.0, 0.0)
+            if (stops.size == 1) return stops[0]
+            val x = t.coerceIn(0.0, 1.0) * (stops.size - 1)
+            val i = x.toInt().coerceAtMost(stops.size - 2)
+            val f = x - i
+            val (ar, ag, ab) = stops[i]
+            val (br, bg, bb) = stops[i + 1]
+            return Triple(ar + (br - ar) * f, ag + (bg - ag) * f, ab + (bb - ab) * f)
+        }
+
+        fun color(c: Triple<Double, Double, Double>): Color =
+            Color(c.first.toFloat(), c.second.toFloat(), c.third.toFloat())
+    }
+}

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

@@ -39,6 +39,7 @@ import androidx.compose.material3.Text
 import androidx.compose.runtime.Composable
 import androidx.compose.runtime.getValue
 import androidx.compose.runtime.mutableIntStateOf
+import androidx.compose.runtime.mutableStateMapOf
 import androidx.compose.runtime.mutableStateOf
 import androidx.compose.runtime.remember
 import androidx.compose.runtime.setValue
@@ -57,14 +58,41 @@ import androidx.compose.ui.unit.sp
 import dev.chrisbanes.haze.HazeState
 import dev.chrisbanes.haze.hazeSource
 import io.unom.punktfunk.kit.deviceBodyVibrator
+import io.unom.punktfunk.kit.security.KnownHost
+import io.unom.punktfunk.kit.security.KnownHostStore
 
 // The gamepad-driven settings screen — the Android mirror of the Apple client's GamepadSettingsView:
 // the couch-relevant subset of the touch settings restyled as a console page and fully navigable with
 // a controller: up/down moves the focus bar, left/right steps the focused value, A cycles/toggles it,
-// B closes. Both write the same SharedPreferences, so values round-trip with the touch settings.
+// L1/R1 change SECTION, B closes. Both write the same SharedPreferences, so values round-trip with
+// the touch settings.
+//
+// The rows are split across SECTION TABS ([GpTab]) — a shoulder press on a pad, a tap on a phone.
+// They used to be one long scroll with inline `Group · Subgroup` headers, which on a TV meant
+// walking past Display and Audio to reach the controller settings. The tab names match the desktop
+// console's and the Apple client's, so a setting is found under the same word wherever you look.
 
-private class GpRow(
+/**
+ * The settings screen's sections. Order IS the strip order and the L1/R1 cycle order; the names
+ * match `pf-console-ui`'s `TABS` and the Apple client's `GpSettingsTab`.
+ */
+enum class GpTab(val title: String) {
+    STREAM("Stream"),
+    VIDEO("Video"),
+    AUDIO("Audio"),
+    CONTROLLER("Controller"),
+    INTERFACE("Interface"),
+    PROFILES("Profiles"),
+}
+
+internal class GpRow(
     val id: String,
+    val tab: GpTab,
+    /**
+     * A sub-heading above this row, for the few tabs that hold more than one group. Most rows have
+     * none: the tab pill already names the section, and repeating it would be a second label
+     * saying the same word.
+     */
     val header: String?,
     val label: String,
     val value: String,
@@ -72,8 +100,19 @@ private class GpRow(
     val adjust: (Int) -> Boolean, // left/right; returns whether the value actually changed
     val activate: () -> Unit,     // A → cycle forward (wrapping) / flip
     val toggled: Boolean? = null, // non-null = a toggle row, drawn as a ConsoleSwitch (not text)
+    val adjustable: Boolean = true, // false = the row navigates/acts instead of stepping — no chevrons
+    val enabled: Boolean = true,    // dimmed + inert when false (still focusable, for its detail)
 )
 
+/**
+ * The row at [index], or null when it is dimmed. The single place the "disabled ⇒ inert" half of
+ * [GpRow.enabled] is enforced, so the three input paths (pad left/right, A, and a tap on the
+ * already-focused row) cannot drift apart — before this, `enabled` dimmed the label and nothing
+ * else, and every dimmed row still stepped its setting.
+ */
+internal fun liveRow(rows: List<GpRow>, index: Int): GpRow? =
+    rows.getOrNull(index)?.takeIf { it.enabled }
+
 @Composable
 fun GamepadSettingsScreen(
     initial: Settings,
@@ -89,9 +128,65 @@ fun GamepadSettingsScreen(
     val hasBodyVibrator = remember { deviceBodyVibrator(context) != null }
     // Gates the AV1 codec row the same way the touch settings do (see `codecOptionsFor`).
     val av1Capable = remember { io.unom.punktfunk.kit.VideoDecoders.pickDecoder("video/av01") != null }
-    val rows = buildSettingsRows(s, hasBodyVibrator, av1Capable, ::update)
+
+    // The Profiles section's stores, constructed here the way ConnectScreen constructs its own.
+    // The catalog is read once per screen entry: this screen can't create or edit profiles
+    // (design §5.4 — the touch interface does), so the list is stable for its lifetime. The saved
+    // hosts DO change under it — every pin toggle writes one — so they live in state and refresh
+    // on each toggle, keeping the "Pinned to N hosts" counts honest.
+    val knownHostStore = remember { KnownHostStore(context) }
+    val profileStore = remember { ProfileStore(context) }
+    val profiles = remember { profileStore.all() }
+    var savedHosts by remember { mutableStateOf(knownHostStore.all()) }
+    // The profile whose pin-to-hosts picker is up, or null. While it's showing, it owns the pad
+    // (this screen's nav gates on it, the ConnectScreen-dialog pattern).
+    var pinProfile by remember { mutableStateOf<StreamProfile?>(null) }
+
+    // Toggle a host+profile pin — the same store write ConnectScreen's togglePin does. Presentation
+    // only: pin appends at the end (card order), unpin removes, and the host's default binding
+    // (profileId) is never touched.
+    fun togglePin(kh: KnownHost, profile: StreamProfile) {
+        val pins = if (profile.id in kh.pinnedProfileIds) {
+            kh.pinnedProfileIds - profile.id
+        } else {
+            kh.pinnedProfileIds + profile.id
+        }
+        knownHostStore.save(kh.copy(pinnedProfileIds = pins))
+        savedHosts = knownHostStore.all()
+    }
+
+    // On a TV "the touch interface" is confusing advice (no touch to reach it with) — the honest
+    // path there is this screen's own Controller-optimized UI toggle, which swaps in the standard
+    // interface remote-navigably. The strings branch on it.
+    val tv = remember { isTvDevice(context) }
+    val allRows = buildSettingsRows(s, hasBodyVibrator, av1Capable, ::update) +
+        buildProfileRows(profiles, savedHosts, tv) { pinProfile = it }
+    // Which section is showing, and where each one's focus was when it was last left — a detour
+    // into another tab shouldn't lose your place.
+    var tab by remember { mutableStateOf(GpTab.STREAM) }
+    // True while the STRIP holds the cursor rather than the list. Up from the first row moves
+    // here and Down goes back — the only route to the sections on a D-pad remote, which has no
+    // shoulder buttons at all (and is exactly what a TV box ships with).
+    var tabFocused by remember { mutableStateOf(false) }
+    val tabFocus = remember { mutableStateMapOf<GpTab, Int>() }
+    val rows = allRows.filter { it.tab == tab }
     var focus by remember { mutableIntStateOf(0) }
-    if (focus > rows.lastIndex) focus = rows.lastIndex
+    if (focus > rows.lastIndex) focus = rows.lastIndex.coerceAtLeast(0)
+
+    // L1/R1 — one section along, wrapping (the strip is a ring, like A's value cycle).
+    fun selectTab(next: GpTab) {
+        if (next == tab) return
+        tabFocus[tab] = focus
+        tab = next
+        // Clamp: a tab's length follows the hardware and the catalog, so a remembered index can
+        // outlive the row it pointed at.
+        focus = (tabFocus[next] ?: 0)
+            .coerceIn(0, (allRows.count { it.tab == next } - 1).coerceAtLeast(0))
+    }
+    fun stepTab(delta: Int) {
+        val all = GpTab.entries
+        selectTab(all[((all.indexOf(tab) + delta) % all.size + all.size) % all.size])
+    }
     // The direction the focused value last stepped (+1 forward / -1 back) — drives which way the
     // value text slides in its AnimatedContent, so the motion matches the button press.
     var adjustDir by remember { mutableIntStateOf(1) }
@@ -101,21 +196,33 @@ fun GamepadSettingsScreen(
 
     BackHandler(onBack = onBack)
     GamepadNavEffect2D(
-        active = navActive,
+        // The pin picker owns the pad while it's up (its own nav + BackHandler), so this screen
+        // drops its probes — the pattern ConnectScreen's dialogs use.
+        active = navActive && pinProfile == null,
         onDirection = { dir ->
             when (dir) {
-                NavDir.UP -> if (focus > 0) focus--
-                NavDir.DOWN -> if (focus < rows.lastIndex) focus++
-                NavDir.LEFT -> { adjustDir = -1; rows.getOrNull(focus)?.adjust(-1) }
-                NavDir.RIGHT -> { adjustDir = 1; rows.getOrNull(focus)?.adjust(1) }
+                NavDir.UP -> if (focus > 0) focus-- else tabFocused = true
+                NavDir.DOWN -> if (tabFocused) tabFocused = false else if (focus < rows.lastIndex) focus++
+                // On the strip, left/right walks sections; on a row it steps the value. A disabled
+                // row is INERT, not just dim — the step is refused instead of writing a setting
+                // that has nothing to act on (see `liveRow`).
+                NavDir.LEFT ->
+                    if (tabFocused) stepTab(-1) else { adjustDir = -1; liveRow(rows, focus)?.adjust(-1) }
+                NavDir.RIGHT ->
+                    if (tabFocused) stepTab(1) else { adjustDir = 1; liveRow(rows, focus)?.adjust(1) }
             }
         },
-        onActivate = { adjustDir = 1; rows.getOrNull(focus)?.activate() },
+        // A on the strip drops into the section you picked, which is what "confirm" means there.
+        onActivate = {
+            if (tabFocused) tabFocused = false else { adjustDir = 1; liveRow(rows, focus)?.activate() }
+        },
+        // The shoulders work from either place — a real pad never has to visit the strip.
+        onShoulder = { delta -> stepTab(delta) },
     )
     // Keep the focused row on screen, but only SCROLL when it's actually off-screen — so entering the
     // screen (focus on the first row) leaves the "Settings" heading visible instead of jumping past it.
     // +1 accounts for the heading being item 0.
-    LaunchedEffect(focus) {
+    LaunchedEffect(focus, tab) {
         runCatching {
             val itemIndex = focus + 1
             val info = listState.layoutInfo
@@ -134,9 +241,21 @@ fun GamepadSettingsScreen(
         // where a fixed title + a fixed detail/legend strip ate most of the (short) height.
         Box(Modifier.fillMaxSize().hazeSource(hazeState)) {
             GamepadFormBackground(Modifier.fillMaxSize())
+            Column(Modifier.fillMaxSize().systemBarsPadding()) {
+            // The strip is PINNED while the rows scroll under it: it is this screen's primary
+            // navigation now, and a switcher you have to scroll back up to find isn't one. The
+            // title stays in the scrolling list (landscape has no height to spare, and the
+            // selected pill already says which section you are in).
+            ConsoleTabStrip(
+                titles = GpTab.entries.map { it.title },
+                selected = GpTab.entries.indexOf(tab),
+                onSelect = { tabFocused = false; selectTab(GpTab.entries[it]) },
+                modifier = Modifier.fillMaxWidth().padding(top = 8.dp, bottom = 2.dp),
+                focused = tabFocused,
+            )
             LazyColumn(
                 state = listState,
-                modifier = Modifier.fillMaxSize().systemBarsPadding(),
+                modifier = Modifier.fillMaxSize(),
                 contentPadding = PaddingValues(start = 24.dp, end = 24.dp, top = 8.dp, bottom = 104.dp),
                 verticalArrangement = Arrangement.spacedBy(6.dp),
             ) {
@@ -147,9 +266,19 @@ fun GamepadSettingsScreen(
                 ConsoleHeader("Default settings", horizontalInset = false)
             }
             itemsIndexed(rows, key = { _, r -> r.id }) { index, row ->
-                SettingRowView(row, focused = index == focus, adjustDir = adjustDir, onClick = {
-                    if (focus == index) { adjustDir = 1; row.activate() } else focus = index
-                })
+                SettingRowView(
+                    row,
+                    focused = index == focus && !tabFocused,
+                    adjustDir = adjustDir,
+                    onClick = {
+                        // Same inertness as the pad path above — tapping a dimmed row focuses it
+                        // (so its detail explains itself) but never flips it.
+                        tabFocused = false
+                        if (focus != index) focus = index
+                        else if (row.enabled) { adjustDir = 1; row.activate() }
+                    },
+                )
+            }
             }
             }
         }
@@ -162,28 +291,74 @@ fun GamepadSettingsScreen(
                 .then(if (landscape) Modifier else Modifier.systemBarsPadding())
                 .padding(ConsoleLegendInset),
         ) {
+            // The legend follows the focused row (the desktop console's hints() does the same):
+            // a profile row doesn't adjust, it opens the pin picker, and the "No profiles yet"
+            // placeholder does nothing at all — advertising ↔/A on those would be a lie.
+            val focused = rows.getOrNull(focus)
+            // The shoulders always change section, so that cell leads on every row. Tappable too,
+            // like the others — a user without a working pad can still reach every tab.
+            // Advertise the shoulders only where they EXIST: a TV remote has none (its route is Up
+            // into the strip) and a touch user taps a pill, so on those the cell would be both a
+            // lie and the reason a 360 dp legend runs out of room. Defaults to the pad case off an
+            // Activity (preview/tests), like GamepadHintBar's own glyph choice.
+            val padIsGamepad = (LocalContext.current as? MainActivity)?.lastPadIsGamepad ?: true
+            val sections = listOfNotNull(
+                GamepadHint('⇄', Color(0xFF9A93C7), "Section", onClick = { stepTab(1) })
+                    .takeIf { padIsGamepad },
+            )
             GamepadHintBar(
-                listOf(
-                    GamepadHint('↔', Color(0xFF9A93C7), "Adjust"),
-                    // Tappable too (touch escape hatch): Change cycles the focused row, Done leaves.
-                    PadGlyph.hint('A', "Change") { rows.getOrNull(focus)?.activate() },
+                if (tabFocused) listOf(
+                    GamepadHint('↔', Color(0xFF9A93C7), "Section"),
+                    PadGlyph.hint('A', "Open") { tabFocused = false },
                     PadGlyph.hint('B', "Done", onClick = onBack),
-                ),
+                ) else sections + when {
+                    focused != null && !focused.enabled -> listOf(
+                        PadGlyph.hint('B', "Done", onClick = onBack),
+                    )
+                    focused != null && !focused.adjustable -> listOf(
+                        PadGlyph.hint('A', "Pin to hosts") { focused.activate() },
+                        PadGlyph.hint('B', "Done", onClick = onBack),
+                    )
+                    else -> listOf(
+                        GamepadHint('↔', Color(0xFF9A93C7), "Adjust"),
+                        // Tappable too (touch escape hatch): Change cycles the focused row, Done leaves.
+                        PadGlyph.hint('A', "Change") { rows.getOrNull(focus)?.activate() },
+                        PadGlyph.hint('B', "Done", onClick = onBack),
+                    )
+                },
                 hazeState = hazeState,
             )
         }
+
+        // The pin-to-hosts picker for the activated profile row — the console counterpart of the
+        // touch UI's per-profile pin toggles in the host edit sheet.
+        pinProfile?.let { p ->
+            GamepadPinHostsDialog(
+                profileName = p.name,
+                hosts = savedHosts,
+                pinned = { kh -> p.id in kh.pinnedProfileIds },
+                onToggle = { kh -> togglePin(kh, p) },
+                onDismiss = { pinProfile = null },
+            )
+        }
     }
 }
 
 @Composable
 private fun SettingRowView(row: GpRow, focused: Boolean, adjustDir: Int, onClick: () -> Unit) {
+    val ink = LocalGamepadInk.current
     val visuals = animateConsoleFocus(active = focused)
     val shape = RoundedCornerShape(14.dp)
     // The chevrons keep their layout slot and only fade, so the value never jumps sideways when
-    // focus arrives; the value colour cross-fades with them.
-    val chevronAlpha by animateFloatAsState(if (focused) 0.6f else 0f, tween(160), label = "chevrons")
+    // focus arrives; the value colour cross-fades with them. A non-adjustable row (a profile row
+    // navigates, the empty-catalog placeholder does nothing) never shows them at all.
+    val chevronAlpha by animateFloatAsState(
+        if (focused && row.adjustable) 0.6f else 0f,
+        tween(160),
+        label = "chevrons",
+    )
     val valueColor by animateColorAsState(
-        Color.White.copy(alpha = if (focused) 1f else 0.6f),
+        ink.fg(if (focused) 1f else 0.6f),
         tween(160),
         label = "valueColor",
     )
@@ -192,7 +367,7 @@ private fun SettingRowView(row: GpRow, focused: Boolean, adjustDir: Int, onClick
             Text(
                 row.header.uppercase(),
                 style = MaterialTheme.typography.labelMedium,
-                color = Color.White.copy(alpha = 0.45f),
+                color = ink.fg(0.45f),
                 letterSpacing = 1.4.sp,
                 modifier = Modifier.padding(start = 16.dp, top = 14.dp, bottom = 4.dp),
             )
@@ -216,7 +391,9 @@ private fun SettingRowView(row: GpRow, focused: Boolean, adjustDir: Int, onClick
                     row.label,
                     style = MaterialTheme.typography.bodyLarge,
                     fontWeight = FontWeight.SemiBold,
-                    color = Color.White,
+                    // A disabled row (the "No profiles yet" placeholder) dims but stays focusable,
+                    // so its detail line can still explain what would go here.
+                    color = ink.fg(if (row.enabled) 1f else 0.45f),
                     maxLines = 1,
                 )
                 Spacer(Modifier.weight(1f))
@@ -224,7 +401,7 @@ private fun SettingRowView(row: GpRow, focused: Boolean, adjustDir: Int, onClick
                     // A toggle is a switch, not text — the sliding knob + tinting track IS the value.
                     ConsoleSwitch(on = row.toggled, focused = focused)
                 } else {
-                    Text("‹ ", color = Color.White, modifier = Modifier.graphicsLayer { alpha = chevronAlpha })
+                    Text("‹ ", color = ink.fg, modifier = Modifier.graphicsLayer { alpha = chevronAlpha })
                     // The value slides in the direction it was stepped and its width animates, so
                     // cycling a choice reads as motion through a list rather than a text swap.
                     AnimatedContent(
@@ -245,7 +422,7 @@ private fun SettingRowView(row: GpRow, focused: Boolean, adjustDir: Int, onClick
                             overflow = TextOverflow.Ellipsis,
                         )
                     }
-                    Text(" ›", color = Color.White, modifier = Modifier.graphicsLayer { alpha = chevronAlpha })
+                    Text(" ›", color = ink.fg, modifier = Modifier.graphicsLayer { alpha = chevronAlpha })
                 }
             }
             // The focused row carries its own one-line description — no dedicated (space-eating)
@@ -258,7 +435,7 @@ private fun SettingRowView(row: GpRow, focused: Boolean, adjustDir: Int, onClick
                 Text(
                     row.detail,
                     style = MaterialTheme.typography.bodySmall,
-                    color = Color.White.copy(alpha = 0.6f),
+                    color = ink.fg(0.6f),
                     maxLines = 2,
                     modifier = Modifier.padding(top = 6.dp),
                 )
@@ -269,22 +446,24 @@ private fun SettingRowView(row: GpRow, focused: Boolean, adjustDir: Int, onClick
 
 /** Build the console settings rows from the current [Settings], writing through [update].
  * [hasBodyVibrator] gates the "Rumble on this phone" row (absent on TVs); [av1Capable] gates the
- * AV1 codec entry (see `codecOptionsFor`). */
-private fun buildSettingsRows(
+ * AV1 codec entry (see `codecOptionsFor`). Every row declares its [GpTab]; the screen shows one
+ * tab at a time. */
+internal fun buildSettingsRows(
     s: Settings,
     hasBodyVibrator: Boolean,
     av1Capable: Boolean,
     update: (Settings) -> Unit,
 ): List<GpRow> {
     fun <T> choice(
-        id: String, header: String?, label: String, detail: String,
-        options: List<Pair<T, String>>, current: T, write: (T) -> Unit,
+        id: String, tab: GpTab, header: String?, label: String, detail: String,
+        options: List<Pair<T, String>>, current: T, enabled: Boolean = true, write: (T) -> Unit,
     ): GpRow {
         val idx = options.indexOfFirst { it.first == current }
         return GpRow(
-            id, header, label,
+            id, tab, header, label,
             value = options.getOrNull(idx)?.second ?: "—",
             detail = detail,
+            enabled = enabled,
             adjust = { delta ->
                 if (idx < 0) {
                     options.firstOrNull()?.let { write(it.first) } != null
@@ -300,47 +479,25 @@ private fun buildSettingsRows(
         )
     }
     fun toggle(
-        id: String, header: String?, label: String, detail: String,
-        value: Boolean, write: (Boolean) -> Unit,
+        id: String, tab: GpTab, header: String?, label: String, detail: String,
+        value: Boolean, enabled: Boolean = true, write: (Boolean) -> Unit,
     ): GpRow = GpRow(
-        id, header, label,
+        id, tab, header, label,
         value = if (value) "On" else "Off",
         detail = detail,
+        enabled = enabled,
         adjust = { delta -> val target = delta > 0; if (value != target) { write(target); true } else false },
         activate = { write(!value) },
         toggled = value,
     )
 
-    // Grouped and ordered by the cross-client category map (General / Display / Audio /
-    // Controllers), with the same sub-section names the touch settings and the desktop clients use,
-    // so a setting sits in the same place whichever surface you found it on. The ROWS stay the
-    // couch-relevant subset: a pad can't drive a touch-input picker, and adding one for the sake of
-    // symmetry would be parity in name only.
+    // Grouped by the cross-client tab map (Stream / Video / Audio / Controller / Interface /
+    // Profiles), so a setting sits under the same word whichever client you found it on. The ROWS
+    // stay the couch-relevant subset: a pad can't drive a touch-input picker, and adding one for
+    // the sake of symmetry would be parity in name only.
     return listOf(
         choice(
-            "hud", "General · Statistics", "Statistics overlay",
-            "How much the overlay shows: Compact (one line) → Normal → Detailed (full HUD). " +
-                "A 3-finger tap cycles the tiers live.",
-            STATS_VERBOSITY_OPTIONS, s.statsVerbosity,
-        ) { update(s.copy(statsVerbosity = it)) },
-        toggle(
-            "autoWake", "General · Session", "Auto-wake on connect",
-            "Wake a saved host with Wake-on-LAN when it isn't seen on the network, then connect.",
-            s.autoWakeEnabled,
-        ) { update(s.copy(autoWakeEnabled = it)) },
-        toggle(
-            "library", "General · Library", "Game library",
-            "Browse a paired host's games with Y (experimental).",
-            s.libraryEnabled,
-        ) { update(s.copy(libraryEnabled = it)) },
-        toggle(
-            "gamepadUI", "General · Interface", "Controller-optimized UI",
-            "Turn off to use the touch interface even with a controller connected.",
-            s.gamepadUiEnabled,
-        ) { update(s.copy(gamepadUiEnabled = it)) },
-
-        choice(
-            "resolution", "Display · Resolution", "Resolution",
+            "resolution", GpTab.STREAM, null, "Resolution",
             "The host creates a virtual display at exactly this size — no scaling. " +
                 "Custom sizes are typed in the touch settings.",
             // A custom size (typed in the touch settings) leads the list so it stays visible and
@@ -354,69 +511,86 @@ private fun buildSettingsRows(
             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.",
+            "refresh", GpTab.STREAM, null, "Refresh rate",
+            "Frame rate the host renders and streams at.",
             REFRESH_OPTIONS, s.hz,
         ) { update(s.copy(hz = it)) },
-
         choice(
-            "bitrate", "Display · Quality", "Bitrate",
+            "bitrate", GpTab.STREAM, null, "Bitrate",
             "Automatic uses the host's default. A host's options (Up on its tile) can measure the " +
                 "link and set an informed value.",
             BITRATE_OPTIONS, s.bitrateKbps,
         ) { update(s.copy(bitrateKbps = it)) },
         choice(
-            "codec", null, "Video codec",
-            "A preference — the host falls back if it can't encode this one.",
-            codecOptionsFor(s.codec, av1Capable), s.codec,
-        ) { update(s.copy(codec = it)) },
-        toggle(
-            "hdr", null, "10-bit HDR",
-            "HDR10 — engages when the host sends HDR content and this display supports it.",
-            s.hdrEnabled,
-        ) { update(s.copy(hdrEnabled = it)) },
-
-        toggle(
-            "lowLatency", "Display · Decoding", "Low-latency mode",
-            "The fast pipeline (async decode + system tuning). On by default — turn off to fall back if the stream stutters or glitches.",
-            s.lowLatencyMode,
-        ) { update(s.copy(lowLatencyMode = it)) },
-
-        choice(
-            "compositor", "Display · Host output", "Compositor",
+            "compositor", GpTab.STREAM, "Host output", "Compositor",
             "Which compositor drives the virtual output — honored only if available on the host.",
             COMPOSITOR_OPTIONS.mapIndexed { i, lbl -> i to lbl }, s.compositor,
         ) { update(s.copy(compositor = it)) },
 
         choice(
-            "audio", "Audio", "Audio channels", "The speaker layout requested from the host.",
+            "codec", GpTab.VIDEO, null, "Video codec",
+            "A preference — the host falls back if it can't encode this one.",
+            codecOptionsFor(s.codec, av1Capable), s.codec,
+        ) { update(s.copy(codec = it)) },
+        toggle(
+            "hdr", GpTab.VIDEO, null, "10-bit HDR",
+            "HDR10 — engages when the host sends HDR content and this display supports it.",
+            s.hdrEnabled,
+        ) { update(s.copy(hdrEnabled = it)) },
+        toggle(
+            "lowLatency", GpTab.VIDEO, "Decoding", "Low-latency mode",
+            "The fast pipeline (async decode + system tuning). On by default — turn off to fall back if the stream stutters or glitches.",
+            s.lowLatencyMode,
+        ) { update(s.copy(lowLatencyMode = it)) },
+
+        choice(
+            "audio", GpTab.AUDIO, null, "Audio channels",
+            "The speaker layout requested from the host.",
             AUDIO_CHANNEL_OPTIONS, s.audioChannels,
         ) { update(s.copy(audioChannels = it)) },
         toggle(
-            "mic", null, "Microphone", "Send this device's microphone to the host's virtual mic.",
+            "mic", GpTab.AUDIO, null, "Microphone",
+            "Send this device's microphone to the host's virtual mic.",
             s.micEnabled,
         ) { update(s.copy(micEnabled = it)) },
         toggle(
-            "echoCancel", null, "Echo cancellation",
+            "echoCancel", GpTab.AUDIO, null, "Echo cancellation",
             "Filter the stream's own audio out of the mic pickup. Applies while the microphone is on.",
             s.echoCancel,
         ) { update(s.copy(echoCancel = it)) },
 
         toggle(
-            "padForward", "Controllers", "Forward controllers",
+            "padForward", GpTab.CONTROLLER, null, "Forward controllers",
             "Send this device's controllers to the host. Turn it off when your controller " +
                 "already reaches the host another way — USB passthrough such as VirtualHere — " +
                 "so games don't see two of them.",
             s.gamepadForwarding,
         ) { update(s.copy(gamepadForwarding = it)) },
+        // Everything below the master switch follows it — dim and inert while nothing is being
+        // forwarded, the same relationship the touch settings draw with `enabled =`. This screen
+        // had the capability (`GpRow.enabled`) and used it only for the profiles placeholder, so
+        // the pad rows kept stepping settings that had nothing to act on.
         choice(
-            "padType", null, "Controller type",
+            "padType", GpTab.CONTROLLER, null, "Controller type",
             "The virtual pad the host creates — Automatic matches this controller.",
-            GAMEPAD_OPTIONS, s.gamepad,
+            GAMEPAD_OPTIONS, s.gamepad, enabled = s.gamepadForwarding,
         ) { update(s.copy(gamepad = it)) },
+        choice(
+            "systemButtons", GpTab.CONTROLLER, null, "Guide button",
+            "Where the guide (Xbox/PS) and share presses go while streaming — Automatic " +
+                "sends them to the host whenever this device delivers them.",
+            SYSTEM_BUTTON_OPTIONS, s.systemButtons, enabled = s.gamepadForwarding,
+        ) { update(s.copy(systemButtons = it)) },
+        choice(
+            "guideGesture", GpTab.CONTROLLER, null, "Hold Select for guide",
+            "Hold Select alone to press the host's guide button — keep holding for a " +
+                "Gaming-Mode host's quick-access menu. A Select tap still goes through.",
+            GUIDE_GESTURE_OPTIONS, s.guideGesture, enabled = s.gamepadForwarding,
+        ) { update(s.copy(guideGesture = it)) },
     ) + listOfNotNull(
         if (hasBodyVibrator) {
             toggle(
-                "phoneRumble", null, "Rumble on this phone",
+                "phoneRumble", GpTab.CONTROLLER, null, "Rumble on this phone",
                 "Also play controller 1's rumble on this phone's own vibration motor — " +
                     "for clip-on pads without rumble motors.",
                 s.rumbleOnPhone,
@@ -428,10 +602,114 @@ private fun buildSettingsRows(
         // NOT gated on the vibrator (the bug A2 fixed in the touch settings): an SC2 capture has
         // nothing to do with this device's motor, and a TV box is where it matters most.
         toggle(
-            "sc2", null, "Steam Controller 2 passthrough",
+            "sc2", GpTab.CONTROLLER, "Passthrough", "Steam Controller 2 passthrough",
             "Capture a Steam Controller 2 (wired, Puck dongle, or paired Bluetooth) and stream " +
                 "it as-is — Steam on the host drives it like the physical pad.",
-            s.sc2Capture,
+            s.sc2Capture, enabled = s.gamepadForwarding,
         ) { update(s.copy(sc2Capture = it)) },
+        // The SC2 row's twin, and missing here until now: the touch settings have carried both
+        // side by side, so a couch user on a TV box — where there IS no touch interface to fall
+        // back to — could turn on SC2 passthrough but not the Sony one. Same no-vibrator-gate
+        // reasoning: this capture renders feedback on the CONTROLLER's motors, not this device's.
+        toggle(
+            "dsCapture", GpTab.CONTROLLER, null, "DualSense / DualShock passthrough (USB)",
+            "Drive a USB-connected Sony pad directly — rumble on any phone, plus adaptive " +
+                "triggers, lightbar and gyro.",
+            s.dsCapture, enabled = s.gamepadForwarding,
+        ) { update(s.copy(dsCapture = it)) },
+
+        // The palette leads Interface: it is the one row whose effect you can see while you step
+        // it (the backdrop behind this very list recolours), so it wants to be the first thing
+        // found in the section.
+        choice(
+            "palette", GpTab.INTERFACE, null, "Background",
+            "The colour family this backdrop drifts through — it changes as you step, so pick by " +
+                "looking. Appearance only.",
+            GamepadPalette.ALL.map { it.id to it.name },
+            GamepadPalette.named(s.uiPalette).id,
+        ) { update(s.copy(uiPalette = it)) },
+        choice(
+            "hud", GpTab.INTERFACE, null, "Statistics overlay",
+            "How much the overlay shows: Compact (one line) → Normal → Detailed (full HUD). " +
+                "A 3-finger tap cycles the tiers live.",
+            STATS_VERBOSITY_OPTIONS, s.statsVerbosity,
+        ) { update(s.copy(statsVerbosity = it)) },
+        toggle(
+            "autoWake", GpTab.INTERFACE, null, "Auto-wake on connect",
+            "Wake a saved host with Wake-on-LAN when it isn't seen on the network, then connect.",
+            s.autoWakeEnabled,
+        ) { update(s.copy(autoWakeEnabled = it)) },
+        toggle(
+            "library", GpTab.INTERFACE, null, "Game library",
+            "Browse a paired host's games with Y (experimental).",
+            s.libraryEnabled,
+        ) { update(s.copy(libraryEnabled = it)) },
+        toggle(
+            "gamepadUI", GpTab.INTERFACE, null, "Controller-optimized UI",
+            "Turn off to use the touch interface even with a controller connected.",
+            s.gamepadUiEnabled,
+        ) { update(s.copy(gamepadUiEnabled = it)) },
     )
 }
+
+
+/**
+ * The trailing Profiles section — the Android mirror of the desktop console's (design §5.2a, §5.4):
+ * one row per catalog profile, valued with how many saved hosts pin it, activating into the
+ * pin-to-hosts picker. Read-only beyond pinning: profiles are created and edited in the standard
+ * interface, so an empty catalog shows one dimmed placeholder explaining where they come from
+ * instead of a dead-looking empty tab. On a TV that phrasing changes: "touch interface" points
+ * nowhere useful on a touchless device, so the strings name the actual route — the
+ * Controller-optimized UI toggle a few rows up, which swaps the standard interface in
+ * (d-pad-navigable; the profile editor lives there on every device, unlike tvOS where none exists).
+ */
+private fun buildProfileRows(
+    profiles: List<StreamProfile>,
+    savedHosts: List<KnownHost>,
+    tv: Boolean,
+    openPinPicker: (StreamProfile) -> Unit,
+): List<GpRow> {
+    val createHint = if (tv) {
+        "To create or edit profiles on this device, turn off Controller-optimized UI above " +
+            "and use the standard interface."
+    } else {
+        "Profiles are created and edited in the touch interface."
+    }
+    if (profiles.isEmpty()) {
+        return listOf(
+            GpRow(
+                id = "noProfiles",
+                tab = GpTab.PROFILES,
+                header = null,
+                label = "No profiles yet",
+                value = "",
+                detail = "Profiles bundle stream settings for different uses — pinned ones become " +
+                    "one-press connect cards here. " + createHint,
+                adjust = { false },
+                activate = {},
+                adjustable = false,
+                enabled = false,
+            ),
+        )
+    }
+    return profiles.map { p ->
+        // Counted straight off the host records, so it agrees with what the carousel renders.
+        val pins = savedHosts.count { p.id in it.pinnedProfileIds }
+        GpRow(
+            id = "profile:${p.id}",
+            tab = GpTab.PROFILES,
+            header = null,
+            label = p.name,
+            value = when (pins) {
+                0 -> "Not pinned"
+                1 -> "Pinned to 1 host"
+                else -> "Pinned to $pins hosts"
+            },
+            detail = "Pin this profile to a host and it appears as its own card — one press " +
+                "connects with it. " + createHint,
+            adjust = { false },
+            activate = { openPinPicker(p) },
+            adjustable = false,
+        )
+    }
+}

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

@@ -84,6 +84,9 @@ suspend fun connectToHost(
             // The host's approval-list / trust-store label for this device — the same
             // Build.MODEL convention the pairing dialogs use for nativePair.
             Build.MODEL ?: "Android",
+            // Tier-A pad audio: ask for the 0xD1 plane only when a setting would render it, so a
+            // user with it off does not make the host provision endpoints it will never feed.
+            settings.padHaptics || settings.padSpeaker,
         )
     }
 }

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

@@ -90,6 +90,7 @@ fun LibraryScreen(
     onBack: () -> Unit,
     navActive: Boolean = true,
 ) {
+    val ink = LocalGamepadInk.current
     BackHandler(onBack = onBack)
     val context = LocalContext.current
     val scope = rememberCoroutineScope()
@@ -145,7 +146,14 @@ fun LibraryScreen(
                                     launching = false
                                     if (handle != 0L) {
                                         onLaunched(
-                                            ActiveSession(handle, settings, host.clipboardSync),
+                                            ActiveSession(
+                                                handle,
+                                                settings,
+                                                host.clipboardSync,
+                                                hostId = host.id,
+                                                // Where to come back to when this game exits.
+                                                launchedFromLibrary = true,
+                                            ),
                                         )
                                     }
                                     else Toast.makeText(
@@ -170,8 +178,8 @@ fun LibraryScreen(
                     horizontalAlignment = Alignment.CenterHorizontally,
                     verticalArrangement = Arrangement.spacedBy(14.dp),
                 ) {
-                    CircularProgressIndicator(color = Color.White)
-                    Text("Launching…", color = Color.White, style = MaterialTheme.typography.bodyLarge)
+                    CircularProgressIndicator(color = ink.fg)
+                    Text("Launching…", color = ink.fg, style = MaterialTheme.typography.bodyLarge)
                 }
             }
         }
@@ -195,17 +203,19 @@ fun LibraryScreen(
 
 @Composable
 private fun LoadingState() {
+    val ink = LocalGamepadInk.current
     Column(horizontalAlignment = Alignment.CenterHorizontally, verticalArrangement = Arrangement.spacedBy(14.dp)) {
-        CircularProgressIndicator(color = Color.White)
-        Text("Loading library…", color = Color.White.copy(alpha = 0.7f), style = MaterialTheme.typography.bodyLarge)
+        CircularProgressIndicator(color = ink.fg)
+        Text("Loading library…", color = ink.fg(0.7f), style = MaterialTheme.typography.bodyLarge)
     }
 }
 
 @Composable
 private fun MessageState(text: String) {
+    val ink = LocalGamepadInk.current
     Text(
         text,
-        color = Color.White.copy(alpha = 0.75f),
+        color = ink.fg(0.75f),
         style = MaterialTheme.typography.bodyLarge,
         textAlign = TextAlign.Center,
         modifier = Modifier.padding(horizontal = 24.dp),
@@ -219,6 +229,7 @@ private fun Coverflow(
     navActive: Boolean,
     onLaunch: (GameEntry) -> Unit,
 ) {
+    val ink = LocalGamepadInk.current
     BoxWithConstraints(Modifier.fillMaxSize()) {
         // Fit a 2:3 poster into the height the detail line leaves; clamp so it never dwarfs the screen.
         val coverHeight = (maxHeight * 0.72f).coerceAtMost(360.dp)
@@ -241,7 +252,22 @@ private fun Coverflow(
             onActivate = { games.getOrNull(navTarget)?.let(onLaunch) },
         )
 
+        // Design D4: the launcher entries lead the strip (the client groups them at parse time).
+        // A coverflow is one-dimensional, so instead of a second focus rail the heading names the
+        // group the cursor is in and changes as it crosses the boundary. Only drawn when the
+        // library actually has both groups — otherwise the screen is exactly what it was.
+        val bothGroups = games.any { it.isLauncher } && games.any { !it.isLauncher }
         Column(Modifier.fillMaxSize(), verticalArrangement = Arrangement.Center) {
+            if (bothGroups) {
+                Text(
+                    if (current?.isLauncher == true) "LAUNCHERS" else "GAMES",
+                    style = MaterialTheme.typography.labelSmall,
+                    color = Color.White.copy(alpha = 0.45f),
+                    letterSpacing = 2.sp,
+                    textAlign = TextAlign.Center,
+                    modifier = Modifier.fillMaxWidth().padding(bottom = 8.dp),
+                )
+            }
             HorizontalPager(
                 state = pagerState,
                 pageSize = PageSize.Fixed(coverWidth),
@@ -299,15 +325,16 @@ private fun Coverflow(
                     current?.title ?: " ",
                     style = MaterialTheme.typography.titleLarge,
                     fontWeight = FontWeight.Bold,
-                    color = Color.White,
+                    color = ink.fg,
                     maxLines = 1,
                     overflow = TextOverflow.Ellipsis,
                 )
                 if (current != null) {
                     Text(
-                        if (current.isCustom) "CUSTOM" else "STEAM",
+                        if (current.isLauncher) "${current.storeLabel.uppercase()} \u00B7 LAUNCHER"
+                        else current.storeLabel.uppercase(),
                         style = MaterialTheme.typography.labelMedium,
-                        color = Color.White.copy(alpha = 0.5f),
+                        color = ink.fg(0.5f),
                         letterSpacing = 2.sp,
                     )
                 }
@@ -319,6 +346,7 @@ private fun Coverflow(
 /** One cover: walks the art candidates (portrait → header → hero) then a text placeholder. */
 @Composable
 private fun Poster(game: GameEntry, loader: ImageLoader, modifier: Modifier = Modifier) {
+    val ink = LocalGamepadInk.current
     val candidates = game.art.posterCandidates
     var idx by remember(game.id) { mutableStateOf(0) }
     val shape = RoundedCornerShape(16.dp)
@@ -326,7 +354,7 @@ private fun Poster(game: GameEntry, loader: ImageLoader, modifier: Modifier = Mo
         modifier = modifier
             .clip(shape)
             .background(Color(0xFF241F3D))
-            .border(1.dp, Color.White.copy(alpha = 0.12f), shape),
+            .border(1.dp, ink.fg(0.12f), shape),
         contentAlignment = Alignment.Center,
     ) {
         if (idx < candidates.size) {
@@ -339,24 +367,29 @@ private fun Poster(game: GameEntry, loader: ImageLoader, modifier: Modifier = Mo
                 onError = { idx++ }, // this candidate failed — try the next, or fall to the placeholder
             )
         } else {
+            // A launcher rarely has poster art. Naming the launcher says "opens Steam"; the title
+            // would read as "a game whose cover failed to load".
             Text(
-                game.title,
+                if (game.isLauncher) game.storeLabel else game.title,
                 style = MaterialTheme.typography.titleMedium,
                 fontWeight = FontWeight.SemiBold,
-                color = Color.White.copy(alpha = 0.75f),
+                color = ink.fg(0.75f),
                 textAlign = TextAlign.Center,
                 modifier = Modifier.padding(12.dp),
             )
         }
-        // Store badge, top-start.
+        // Store badge, top-start — brand-filled for a launcher entry (design D4).
         Box(Modifier.fillMaxSize().padding(8.dp), contentAlignment = Alignment.TopStart) {
             Text(
-                if (game.isCustom) "Custom" else "Steam",
+                game.storeLabel,
                 style = MaterialTheme.typography.labelSmall,
-                color = Color.White,
+                color = ink.fg,
                 modifier = Modifier
                     .clip(RoundedCornerShape(50))
-                    .background(Color.Black.copy(alpha = 0.5f))
+                    .background(
+                        if (game.isLauncher) MaterialTheme.colorScheme.primary
+                        else Color.Black.copy(alpha = 0.5f),
+                    )
                     .padding(horizontal = 8.dp, vertical = 3.dp),
             )
         }

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

@@ -44,6 +44,8 @@ data class SettingsOverlay(
     val invertScroll: Boolean? = null,
     val gamepad: Int? = null,
     val gamepadForwarding: Boolean? = null,
+    val systemButtons: String? = null,
+    val guideGesture: String? = null,
     val statsVerbosity: StatsVerbosity? = null,
     /**
      * Android-only tier-P addition (design §3): the decode pipeline is a device fact everywhere
@@ -78,6 +80,8 @@ data class SettingsOverlay(
         invertScroll = invertScroll ?: base.invertScroll,
         gamepad = gamepad ?: base.gamepad,
         gamepadForwarding = gamepadForwarding ?: base.gamepadForwarding,
+        systemButtons = systemButtons ?: base.systemButtons,
+        guideGesture = guideGesture ?: base.guideGesture,
         statsVerbosity = statsVerbosity ?: base.statsVerbosity,
         lowLatencyMode = lowLatencyMode ?: base.lowLatencyMode,
         presentPriority = presentPriority ?: base.presentPriority,
@@ -115,6 +119,8 @@ data class SettingsOverlay(
         gamepadForwarding =
             if (after.gamepadForwarding != before.gamepadForwarding) after.gamepadForwarding
             else gamepadForwarding,
+        systemButtons = if (after.systemButtons != before.systemButtons) after.systemButtons else systemButtons,
+        guideGesture = if (after.guideGesture != before.guideGesture) after.guideGesture else guideGesture,
         statsVerbosity = if (after.statsVerbosity != before.statsVerbosity) after.statsVerbosity else statsVerbosity,
         lowLatencyMode = if (after.lowLatencyMode != before.lowLatencyMode) after.lowLatencyMode else lowLatencyMode,
         presentPriority = if (after.presentPriority != before.presentPriority) after.presentPriority else presentPriority,
@@ -142,6 +148,8 @@ data class SettingsOverlay(
         "invert_scroll" -> copy(invertScroll = null)
         "gamepad" -> copy(gamepad = null)
         "gamepad_forwarding" -> copy(gamepadForwarding = null)
+        "system_buttons" -> copy(systemButtons = null)
+        "guide_gesture" -> copy(guideGesture = null)
         "stats_verbosity" -> copy(statsVerbosity = null)
         "low_latency_mode" -> copy(lowLatencyMode = null)
         "present_priority" -> copy(presentPriority = null)
@@ -166,6 +174,8 @@ data class SettingsOverlay(
         if (invertScroll != null) add("invert_scroll")
         if (gamepad != null) add("gamepad")
         if (gamepadForwarding != null) add("gamepad_forwarding")
+        if (systemButtons != null) add("system_buttons")
+        if (guideGesture != null) add("guide_gesture")
         if (statsVerbosity != null) add("stats_verbosity")
         if (lowLatencyMode != null) add("low_latency_mode")
         if (presentPriority != null) add("present_priority")
@@ -198,6 +208,8 @@ data class SettingsOverlay(
         invertScroll?.let { j.put("invert_scroll", it) }
         gamepad?.let { j.put("gamepad", it) }
         gamepadForwarding?.let { j.put("gamepad_forwarding", it) }
+        systemButtons?.let { j.put("system_buttons", it) }
+        guideGesture?.let { j.put("guide_gesture", it) }
         statsVerbosity?.let { j.put("stats_verbosity", it.name) }
         lowLatencyMode?.let { j.put("low_latency_mode", it) }
         presentPriority?.let { j.put("present_priority", it) }
@@ -214,6 +226,7 @@ data class SettingsOverlay(
             "width", "height", "refresh_hz", "bitrate_kbps", "render_scale", "codec",
             "hdr_enabled", "compositor", "audio_channels", "mic_enabled", "echo_cancel",
             "touch_mode", "mouse_mode", "invert_scroll", "gamepad", "gamepad_forwarding",
+            "system_buttons", "guide_gesture",
             "stats_verbosity",
             "low_latency_mode", "present_priority", "smooth_buffer",
         )
@@ -237,6 +250,8 @@ data class SettingsOverlay(
             invertScroll = j.optBooleanOrNull("invert_scroll"),
             gamepad = j.optIntOrNull("gamepad"),
             gamepadForwarding = j.optBooleanOrNull("gamepad_forwarding"),
+            systemButtons = j.optStringOrNull("system_buttons"),
+            guideGesture = j.optStringOrNull("guide_gesture"),
             statsVerbosity = j.optStringOrNull("stats_verbosity")
                 ?.let { n -> StatsVerbosity.entries.firstOrNull { it.name == n } },
             lowLatencyMode = j.optBooleanOrNull("low_latency_mode"),

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

@@ -45,6 +45,20 @@ data class Settings(
      * bind — which is why it gates the USB capture paths, not just the wire sends.
      */
     val gamepadForwarding: Boolean = true,
+    /**
+     * Where the guide (Xbox/PS) and misc/share presses land while streaming — the
+     * cross-client `system_buttons` key: `"auto"` (forward on Android — the press reaches
+     * the app on most devices) | `"forward"` | `"local"`.
+     */
+    val systemButtons: String = "auto",
+    /**
+     * The hold-Select guide gesture — the cross-client `guide_gesture` key: `"auto"` (off
+     * on Android) | `"on"` | `"off"`. On: holding Select alone ≥350 ms sends the HOST's
+     * guide, down until release (long hold = the host's long-press → a Gaming-Mode host's
+     * QAM); a Select tap is delivered on release, slightly delayed. For devices whose
+     * shell intercepts the physical guide button.
+     */
+    val guideGesture: String = "auto",
     /** 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,
@@ -91,6 +105,16 @@ data class Settings(
      * client's `libraryEnabled`.
      */
     val libraryEnabled: Boolean = true,
+    /**
+     * Which colour family the console (gamepad) UI's living backdrop drifts through — the
+     * cross-client `ui_palette` key: `"violet"` (the brand default), `"tide"`, `"forest"`,
+     * `"ember"`, `"rose"`, `"graphite"`. See [GamepadPalette], whose table and maths mirror the
+     * desktop console's and the Apple client's under the same names. Presentation only: nothing
+     * about a stream depends on it, so it is a device preference and never part of a profile.
+     * An unknown value reads as the default rather than failing — a newer client may have shipped
+     * a palette this build doesn't know.
+     */
+    val uiPalette: String = "violet",
     /**
      * "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
@@ -156,6 +180,26 @@ data class Settings(
      */
     val dsCapture: Boolean = true,
 
+    /**
+     * Render the host's DualSense **voice-coil haptics** on a captured USB pad (tier A).
+     *
+     * The pad's own 4-channel audio device carries them, driven directly over usbfs — Android's
+     * audio framework denylists that device by VID/PID, so there is no supported route to it. The
+     * two kinds are arbitrated rather than mixed, and on evidence: wire rumble is suppressed only
+     * while haptics frames are actually arriving, so a title that drives classic rumble and sends
+     * no haptics audio keeps rumbling. Off, or on an uncaptured/Bluetooth pad, the pad stays on
+     * ordinary rumble (tier C), which on this client already drives the same actuators.
+     */
+    val padHaptics: Boolean = true,
+
+    /**
+     * Render the pad's **built-in speaker** on a captured USB pad. Independent of [padHaptics] —
+     * the host sends the two as separate streams and either can play alone. Off by default: the
+     * speaker is a small, easily-startling loudspeaker in the user's hands, and unlike haptics it
+     * duplicates audio they are already hearing.
+     */
+    val padSpeaker: Boolean = false,
+
     /**
      * How a physical mouse drives the host — the cross-client mouse model (see [MouseMode]).
      * [MouseMode.DESKTOP] (default here) points absolutely; [MouseMode.CAPTURE] locks the pointer
@@ -228,6 +272,8 @@ class SettingsStore(context: Context) {
         compositor = prefs.getInt(K_COMPOSITOR, 0),
         gamepad = prefs.getInt(K_GAMEPAD, 0),
         gamepadForwarding = prefs.getBoolean(K_GAMEPAD_FORWARDING, true),
+        systemButtons = prefs.getString(K_SYSTEM_BUTTONS, "auto") ?: "auto",
+        guideGesture = prefs.getString(K_GUIDE_GESTURE, "auto") ?: "auto",
         audioChannels = prefs.getInt(K_AUDIO_CH, 2),
         codec = prefs.getString(K_CODEC, "auto") ?: "auto",
         micEnabled = prefs.getBoolean(K_MIC, false),
@@ -248,6 +294,7 @@ class SettingsStore(context: Context) {
             ?: if (prefs.getBoolean(K_TRACKPAD, true)) TouchMode.TRACKPAD else TouchMode.POINTER,
         gamepadUiEnabled = prefs.getBoolean(K_GAMEPAD_UI, true),
         libraryEnabled = prefs.getBoolean(K_LIBRARY, true),
+        uiPalette = prefs.getString(K_UI_PALETTE, "violet") ?: "violet",
         lowLatencyMode = prefs.getBoolean(K_LOW_LATENCY, true),
         presentPriority = prefs.getString(K_PRESENT_PRIORITY, "latency") ?: "latency",
         smoothBuffer = prefs.getInt(K_SMOOTH_BUFFER, 0),
@@ -255,6 +302,8 @@ class SettingsStore(context: Context) {
         rumbleOnPhone = prefs.getBoolean(K_RUMBLE_ON_PHONE, false),
         sc2Capture = prefs.getBoolean(K_SC2_CAPTURE, true),
         dsCapture = prefs.getBoolean(K_DS_CAPTURE, true),
+        padHaptics = prefs.getBoolean(K_PAD_HAPTICS, true),
+        padSpeaker = prefs.getBoolean(K_PAD_SPEAKER, false),
         mouseMode = prefs.getString(K_MOUSE_MODE, null)
             ?.let { name -> MouseMode.entries.firstOrNull { it.storedName == name } }
             // Migration: the pre-enum Boolean "pointer_capture" (true = lock the pointer). Its
@@ -275,6 +324,8 @@ class SettingsStore(context: Context) {
             .putInt(K_COMPOSITOR, s.compositor)
             .putInt(K_GAMEPAD, s.gamepad)
             .putBoolean(K_GAMEPAD_FORWARDING, s.gamepadForwarding)
+            .putString(K_SYSTEM_BUTTONS, s.systemButtons)
+            .putString(K_GUIDE_GESTURE, s.guideGesture)
             .putInt(K_AUDIO_CH, s.audioChannels)
             .putString(K_CODEC, s.codec)
             .putBoolean(K_MIC, s.micEnabled)
@@ -283,6 +334,7 @@ class SettingsStore(context: Context) {
             .putString(K_TOUCH_MODE, s.touchMode.name)
             .putBoolean(K_GAMEPAD_UI, s.gamepadUiEnabled)
             .putBoolean(K_LIBRARY, s.libraryEnabled)
+            .putString(K_UI_PALETTE, s.uiPalette)
             .putBoolean(K_LOW_LATENCY, s.lowLatencyMode)
             .putString(K_PRESENT_PRIORITY, s.presentPriority)
             .putInt(K_SMOOTH_BUFFER, s.smoothBuffer)
@@ -290,6 +342,8 @@ class SettingsStore(context: Context) {
             .putBoolean(K_RUMBLE_ON_PHONE, s.rumbleOnPhone)
             .putBoolean(K_SC2_CAPTURE, s.sc2Capture)
             .putBoolean(K_DS_CAPTURE, s.dsCapture)
+            .putBoolean(K_PAD_HAPTICS, s.padHaptics)
+            .putBoolean(K_PAD_SPEAKER, s.padSpeaker)
             .putString(K_MOUSE_MODE, s.mouseMode.storedName)
             .putBoolean(K_INVERT_SCROLL, s.invertScroll)
             .apply()
@@ -305,6 +359,8 @@ class SettingsStore(context: Context) {
         const val K_COMPOSITOR = "compositor"
         const val K_GAMEPAD = "gamepad"
         const val K_GAMEPAD_FORWARDING = "gamepad_forwarding"
+        const val K_SYSTEM_BUTTONS = "system_buttons"
+        const val K_GUIDE_GESTURE = "guide_gesture"
         const val K_AUDIO_CH = "audio_channels"
         const val K_CODEC = "codec"
         const val K_MIC = "mic_enabled"
@@ -317,6 +373,7 @@ class SettingsStore(context: Context) {
         const val K_TOUCH_MODE = "touch_mode"
         const val K_GAMEPAD_UI = "gamepad_ui_enabled"
         const val K_LIBRARY = "library_enabled"
+        const val K_UI_PALETTE = "ui_palette"
 
         /**
          * Bumped AGAIN to restart every install at the new default (ON). History: the original
@@ -335,6 +392,8 @@ class SettingsStore(context: Context) {
         const val K_RUMBLE_ON_PHONE = "rumble_on_phone"
         const val K_SC2_CAPTURE = "sc2_capture"
         const val K_DS_CAPTURE = "ds_capture"
+        const val K_PAD_HAPTICS = "pad_haptics"
+        const val K_PAD_SPEAKER = "pad_speaker"
         const val K_MOUSE_MODE = "mouse_mode"
 
         /** Legacy Boolean the [K_MOUSE_MODE] enum replaced — read once for migration, never written. */
@@ -378,6 +437,96 @@ fun nativeDisplayMode(context: Context): Triple<Int, Int, Int> {
     return Triple(maxOf(w, h), minOf(w, h), hz)
 }
 
+/**
+ * Sentinel [Settings.width]/[Settings.height] meaning "the native mode, narrowed so the picture
+ * clears the display cutout and the rounded corners" — resolved at connect by [safeDisplayMode],
+ * exactly as `0` is resolved by [nativeDisplayMode]. Negative, so it can never collide with a real
+ * size; distinct from the UI's `-1` "Custom…" sentinel.
+ */
+const val SAFE_AREA_MODE = -2
+
+/**
+ * Safe-area stream geometry — the pure part, so it is unit-testable without a Display.
+ *
+ * The phone clips the picture in HARDWARE: the cutout (notch / punch-hole) and the four rounded
+ * corners eat whatever the stream draws under them. [StreamScreen] deliberately draws edge-to-edge
+ * (`LAYOUT_IN_DISPLAY_CUTOUT_MODE_ALWAYS`) and centres the video at its own aspect ratio
+ * (`Modifier.aspectRatio`), so which pixels survive is decided purely by the mode's aspect:
+ *
+ *  * A 16:9 mode on a 20:9 phone pillarboxes, and those black bars land exactly on the unsafe
+ *    regions — which is why the presets have always "just worked".
+ *  * The NATIVE mode has the panel's own aspect, so it fills every pixel, cutout and corners
+ *    included. That is the mode that loses its corners.
+ *
+ * So asking the host for a mode narrower by the unsafe inset is the entire fix: the existing
+ * aspect-fit centres it inside the safe region, and pointer mapping follows for free (MouseInput
+ * derives the picture rect from the live video size, not from the window).
+ */
+object SafeArea {
+    /** The host rejects odd dimensions and anything under 320 px wide (`validate_dimensions`). */
+    const val MIN_WIDTH = 320
+
+    /**
+     * [nativeWidth] reduced by [perSideInsetPx] on each side, even-floored and clamped to the
+     * host's floor. Height is deliberately untouched: under aspect-fit only one axis can bind, and
+     * on a landscape phone that axis is always the horizontal one — insetting height as well would
+     * shrink the picture without uncovering anything.
+     */
+    fun insetWidth(nativeWidth: Int, perSideInsetPx: Int): Int {
+        val inset = perSideInsetPx.coerceAtLeast(0)
+        return (nativeWidth - inset * 2).coerceAtLeast(MIN_WIDTH) / 2 * 2
+    }
+}
+
+/**
+ * The per-side inset, in pixels, that the **landscape** stream must clear on this display.
+ *
+ * Two contributions, and the larger wins:
+ *  * **The cutout.** [DisplayCutout] is rotation-aware, so in landscape the housing shows up on
+ *    `left`/`right`. The settings screen may be portrait though, where the very same housing is
+ *    reported on `top`/`bottom` and the horizontal insets read zero — which would compute "no inset
+ *    needed" for exactly the devices that need one. The stream is always landscape, so a vertical
+ *    inset now becomes a horizontal one then: fall back to it.
+ *  * **The rounded corners.** These are NOT part of the cutout insets. For a FULL-HEIGHT picture the
+ *    horizontal clearance a corner of radius `r` needs is exactly `r`: at the topmost row the
+ *    display boundary sits at `x = r`, so anything left of that is clipped. Not conservative — it is
+ *    the precise requirement for a picture that spans the full height.
+ *
+ * `0` when the display has neither, which makes the safe mode identical to the native one.
+ */
+private fun displaySideInsetPx(context: Context): Int {
+    val display = probeDisplay(context) ?: return 0
+    var inset = 0
+    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
+        display.cutout?.let { cut ->
+            val horizontal = maxOf(cut.safeInsetLeft, cut.safeInsetRight)
+            val vertical = maxOf(cut.safeInsetTop, cut.safeInsetBottom)
+            inset = maxOf(inset, if (horizontal > 0) horizontal else vertical)
+        }
+    }
+    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
+        for (position in intArrayOf(
+            android.view.RoundedCorner.POSITION_TOP_LEFT,
+            android.view.RoundedCorner.POSITION_TOP_RIGHT,
+            android.view.RoundedCorner.POSITION_BOTTOM_LEFT,
+            android.view.RoundedCorner.POSITION_BOTTOM_RIGHT,
+        )) {
+            display.getRoundedCorner(position)?.let { inset = maxOf(inset, it.radius) }
+        }
+    }
+    return inset
+}
+
+/**
+ * The native mode narrowed to clear the cutout and the rounded corners — the [SAFE_AREA_MODE]
+ * resolution, as a landscape `(width, height, hz)`. Same height and refresh as [nativeDisplayMode];
+ * only the width moves.
+ */
+fun safeDisplayMode(context: Context): Triple<Int, Int, Int> {
+    val (w, h, hz) = nativeDisplayMode(context)
+    return Triple(SafeArea.insetWidth(w, displaySideInsetPx(context)), h, hz)
+}
+
 /**
  * True when this device's display can actually present HDR10, so we should advertise HDR to the
  * host. On an SDR panel we advertise `0` instead — the host then sends a proper 8-bit BT.709 stream
@@ -412,12 +561,21 @@ fun displaySupportsHdr(context: Context): Boolean {
     return supported
 }
 
-/** Resolve [Settings] (with its 0=native placeholders) to the concrete mode to request. */
+/**
+ * Resolve [Settings] (with its `0`=native and [SAFE_AREA_MODE] placeholders) to the concrete mode to
+ * request. The safe-area sentinel is checked first because it resolves BOTH axes together — it is one
+ * mode, not an independent width and height, and mixing half of it with a native height would ask
+ * for a size neither sentinel means.
+ */
 fun Settings.effectiveMode(context: Context): Triple<Int, Int, Int> {
-    val native = nativeDisplayMode(context)
-    val w = if (width > 0) width else native.first
-    val h = if (height > 0) height else native.second
-    val hz = if (hz > 0) hz else native.third
+    val base = if (width == SAFE_AREA_MODE && height == SAFE_AREA_MODE) {
+        safeDisplayMode(context)
+    } else {
+        nativeDisplayMode(context)
+    }
+    val w = if (width > 0) width else base.first
+    val h = if (height > 0) height else base.second
+    val hz = if (hz > 0) hz else base.third
     return Triple(w, h, hz)
 }
 
@@ -471,9 +629,10 @@ val RENDER_SCALE_OPTIONS = RenderScale.PRESETS.map { it to RenderScale.label(it)
 
 // ---- UI option tables (value, label). The first entry is always the "auto/native" default. ----
 
-/** (width, height, label). `(0,0)` = native display. */
+/** (width, height, label). `(0,0)` = native display; [SAFE_AREA_MODE] = native minus the cutout. */
 val RESOLUTION_OPTIONS = listOf(
     Triple(0, 0, "Native display"),
+    Triple(SAFE_AREA_MODE, SAFE_AREA_MODE, "Native display (safe area)"),
     Triple(1280, 720, "1280 × 720"),
     Triple(1920, 1080, "1920 × 1080"),
     Triple(2560, 1440, "2560 × 1440"),
@@ -539,6 +698,15 @@ fun codecOptionsFor(stored: String, av1Capable: Boolean): List<Pair<String, Stri
         }
     }
 
+/** Resolved [Settings.systemButtons]: forward the raw guide/misc presses? Auto = forward on
+ * Android — the press reaches the app on most devices, and where the shell shows its own UI
+ * for it that's the shell's business. */
+fun Settings.systemButtonsForward(): Boolean = systemButtons != "local"
+
+/** Resolved [Settings.guideGesture]: auto = OFF on Android (the raw press already reaches the
+ * host); "on" is for devices whose shell intercepts the physical guide button. */
+fun Settings.guideGestureEnabled(): Boolean = guideGesture == "on"
+
 /** The [Settings.codec] string as a `quic::CODEC_*` preference byte (`0` = auto). H264=1, HEVC=2,
  * AV1=4, PyroWave=8 (never decodable here, but the byte is the shared contract). */
 fun Settings.preferredCodec(): Int = when (codec) {
@@ -621,3 +789,17 @@ val GAMEPAD_OPTIONS = listOf(
     io.unom.punktfunk.kit.Gamepad.PREF_DUALSHOCK4 to "DualShock 4",
     io.unom.punktfunk.kit.Gamepad.PREF_STEAMDECK to "Steam Deck",
 )
+
+/** (stored `system_buttons` value, label) — where the guide/share presses land while streaming. */
+val SYSTEM_BUTTON_OPTIONS = listOf(
+    "auto" to "Automatic",
+    "forward" to "Send to host",
+    "local" to "This device",
+)
+
+/** (stored `guide_gesture` value, label) — the hold-Select guide gesture. */
+val GUIDE_GESTURE_OPTIONS = listOf(
+    "auto" to "Automatic",
+    "on" to "On",
+    "off" to "Off",
+)

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

@@ -603,6 +603,10 @@ private fun GeneralSettings(s: Settings, update: (Settings) -> Unit) {
 @Composable
 private fun DisplaySettings(s: Settings, update: (Settings) -> Unit, context: android.content.Context) {
     val (nw, nh, nhz) = nativeDisplayMode(context)
+    // The safe-area row carries its resolved size the same way the native row does. On a display with
+    // no cutout and square corners this equals the native mode — the row stays, honestly showing that
+    // it changes nothing here, rather than silently vanishing on some devices and not others.
+    val (sw, sh, _) = safeDisplayMode(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.
@@ -611,7 +615,13 @@ private fun DisplaySettings(s: Settings, update: (Settings) -> Unit, context: an
     SettingsGroup("Resolution") {
         SettingDropdown(
             label = "Resolution",
-            options = RESOLUTION_OPTIONS.map { (w, h, lbl) -> (w to h) to (if (w == 0) "$lbl ($nw × $nh)" else lbl) } +
+            options = RESOLUTION_OPTIONS.map { (w, h, lbl) ->
+                (w to h) to when (w) {
+                    0 -> "$lbl ($nw × $nh)"
+                    SAFE_AREA_MODE -> "$lbl ($sw × $sh)"
+                    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…"),
@@ -620,7 +630,10 @@ private fun DisplaySettings(s: Settings, update: (Settings) -> Unit, context: an
             caption = "The host makes a display exactly this size — no scaling. Native follows " +
                 "this device's panel.",
         ) { (w, h) ->
-            if (w < 0) {
+            // ONLY -1 is "Custom…". The other negative value is the safe-area sentinel, which is a
+            // stored mode like any preset — a blanket `w < 0` here would open the custom fields for it
+            // and overwrite it with a concrete size.
+            if (w == -1) {
                 // Seed from the current *effective* size so the fields start from something
                 // sensible (the resolved native mode, not the 0 × 0 placeholder).
                 customPicked = true
@@ -838,6 +851,25 @@ private fun ControllerSettings(s: Settings, update: (Settings) -> Unit, onOpenCo
             caption = "The virtual pad the host creates. Automatic matches your controller; " +
                 "every connected one is forwarded as its own player.",
         ) { g -> update(s.copy(gamepad = g)) }
+        SettingDropdown(
+            label = "Guide button",
+            options = SYSTEM_BUTTON_OPTIONS,
+            selected = s.systemButtons,
+            field = "system_buttons",
+            enabled = s.gamepadForwarding,
+            caption = "Where the guide (Xbox/PS) and share presses go while streaming. " +
+                "Automatic sends them to the host whenever this device delivers them.",
+        ) { v -> update(s.copy(systemButtons = v)) }
+        SettingDropdown(
+            label = "Hold Select for guide",
+            options = GUIDE_GESTURE_OPTIONS,
+            selected = s.guideGesture,
+            field = "guide_gesture",
+            enabled = s.gamepadForwarding,
+            caption = "Hold Select alone to press the host's guide button — keep holding for a " +
+                "Gaming-Mode host's quick-access menu. A Select tap still goes through, " +
+                "slightly delayed. For devices that intercept the real guide button.",
+        ) { v -> update(s.copy(guideGesture = v)) }
         DeviceScopeOnly {
             ClickableRow(
                 title = "Connected controllers",
@@ -877,6 +909,22 @@ private fun ControllerSettings(s: Settings, update: (Settings) -> Unit, onOpenCo
                 enabled = s.gamepadForwarding,
                 onCheckedChange = { on -> update(s.copy(dsCapture = on)) },
             )
+            // Both only ever apply to a captured pad, so they follow that row and gate on it.
+            ToggleRow(
+                title = "Controller haptics",
+                subtitle = "Play the host's fine-grained DualSense haptics on the pad itself — " +
+                    "the pad keeps ordinary rumble for games that don't send them",
+                checked = s.padHaptics,
+                enabled = s.gamepadForwarding && s.dsCapture,
+                onCheckedChange = { on -> update(s.copy(padHaptics = on)) },
+            )
+            ToggleRow(
+                title = "Controller speaker",
+                subtitle = "Play audio the game sends to the controller's own speaker",
+                checked = s.padSpeaker,
+                enabled = s.gamepadForwarding && s.dsCapture,
+                onCheckedChange = { on -> update(s.copy(padSpeaker = on)) },
+            )
         }
     }
 }

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

@@ -26,13 +26,25 @@ import kotlin.math.roundToInt
  * presentsWindow, presenterActive, feedP50Ms, codecP50Ms, skippedOverflowWindow]`. Every read
  * is length-guarded, so an older native lib simply omits the lines it can't feed.
  *
+ * The shown `display` and `end-to-end` numbers EXCLUDE the OS present floor (see [osFloorMs]) at
+ * every tier, and the detailed tier names what was excluded on its own line. The principle is the
+ * Apple client's: metrics report what Punktfunk controls, so the compositor's own latch and scanout
+ * — which no client can pace under — is reported rather than charged. It also stops the HUD reading
+ * worse than it is: the usual Android streaming overlays stop measuring at decode-complete, so a
+ * headline that carried the compositor's wait was compared against numbers that never contained it.
+ *
+ * The RAW figures are not lost — the native 1 Hz `pf.present` logcat line keeps `paceMs`, `latchMs`
+ * and `e2eMs` unshaved, so a HUD-off A/B and any cross-session comparison still work off the
+ * untouched numbers.
+ *
  * [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.DETAILED] — also the decoder label, the video-feed descriptor (10–13), the
+ *   stage equation (14/15, split into `host + network` when the Phase-2 terms at 16/17 are nonzero),
+ *   and the excluded-floor line when one was measured.
  * [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).
  */
@@ -95,9 +107,15 @@ internal fun StatsOverlay(
             // 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
+            // The OS present floor this window (see [osFloorMs]) is excluded from every shown
+            // display / end-to-end number, at every tier — it is pipeline depth no client can pace
+            // under, so charging it to Punktfunk made our HUD read worse than clients that simply
+            // never measure it. 0.0 when unmeasured, which leaves the numbers exactly as raw as
+            // they were.
+            val floorMs = osFloorMs(s)
             val tag = if (skew) "" else " (same-host clock)"
             val (p50, p95, endpoint) = if (dispValid) {
-                Triple(s[24], s[25], "capture→displayed")
+                Triple(shave(s[24], floorMs), shave(s[25], floorMs), "capture→displayed")
             } else {
                 Triple(s[2], s[3], "capture→decoded")
             }
@@ -120,6 +138,11 @@ internal fun StatsOverlay(
                 // dropping/serializing, an fps deficit is upstream.
                 val split = s.size >= 30 && s[29] != 0.0 && (s[26] > 0 || s[27] > 0)
                 val displayTerm = when {
+                    // Floor excluded: what remains of the `display` term is the half Punktfunk
+                    // owns (the presenter's pace wait), and the excluded line below carries the
+                    // latch — printing the split too would report the same milliseconds twice.
+                    dispValid && floorMs > 0 ->
+                        " + display ${"%.1f".format(shave(s[23], floorMs))}"
                     dispValid && split ->
                         " + display ${"%.1f".format(s[23])} " +
                             "(pace ${"%.1f".format(s[26])} + latch ${"%.1f".format(s[27])})"
@@ -143,16 +166,14 @@ internal fun StatsOverlay(
                     "= $hostTerms + $decodeTerm$displayTerm$presents",
                     Color.White,
                 )
-                // Metric fairness: the Apple client's HUD shaves ~2 refresh periods of OS
-                // pipeline floor off its shown display/end-to-end; Android shows raw. This twin
-                // applies the same shave so iPhone↔Android HUD numbers compare directly.
-                if (dispValid && hz > 0) {
-                    val shave = 2000.0 / hz
+                // What the numbers above leave out, named — the Apple client's
+                // `os present +N excluded` line, same wording so the two HUDs read alike.
+                // (This replaces the old "≈ Apple-HUD equiv" twin: both clients now shave, and
+                // Android's shave is measured rather than assumed at 2 refresh periods.)
+                if (floorMs > 0) {
                     statLine(
-                        "≈ Apple-HUD equiv: end-to-end " +
-                            "${"%.1f".format((s[24] - shave).coerceAtLeast(0.0))} · display " +
-                            "${"%.1f".format((s[23] - shave).coerceAtLeast(0.0))} (−2 refresh)",
-                        Color(0xFFA8D8B8),
+                        "os present +${"%.1f".format(floorMs)} excluded (display pipeline minimum)",
+                        Color(0xFF9AA6B8),
                     )
                 }
             }
@@ -167,6 +188,37 @@ private fun statLine(text: String, color: Color) {
     Text(text, color = color, fontFamily = FontFamily.Monospace, fontSize = 12.sp)
 }
 
+/**
+ * The OS present floor to exclude from the shown `display` / `end-to-end` numbers, ms — the
+ * measured `latch` p50 at index 27, i.e. release→`OnFrameRendered`: SurfaceFlinger's own latch and
+ * scanout. That is compositor pipeline depth no client can pace under, so it is reported as
+ * excluded rather than charged to Punktfunk — the Apple client's policy since its presentation
+ * rebuild, where the same floor is measured from the display link's vend lead.
+ *
+ * Measured, not assumed: the previous Android treatment used a fixed `2000/hz` twin, but the latch
+ * varies with panel rate, tunnelled playback and the vendor's low-latency mode (~21 ms p50 observed
+ * where the ~2-interval model predicts less), and this term self-adapts to all three. It is also
+ * available on every render path — the presenter's and both legacy release-immediately ones — since
+ * the release stamp it starts from is parked on every render, so it does not depend on
+ * `presenterActive` (29).
+ *
+ * `0.0` means unmeasured — no display stage this window (an older native lib, API < 33, or a
+ * platform that refused the callback), or no latch sample paired — and every caller then leaves its
+ * number raw, which is the honest fallback: we exclude only what we actually measured.
+ */
+private fun osFloorMs(s: DoubleArray): Double {
+    val dispValid = s.size >= 26 && s[22] != 0.0
+    if (!dispValid || s.size < 28) return 0.0
+    return s[27].coerceAtLeast(0.0)
+}
+
+/**
+ * Subtract the excluded [floorMs] from a shown latency [ms], clamped at zero — the percentiles are
+ * drawn from different sample sets (a p50 latch against a p50/p95 end-to-end), so the difference can
+ * legitimately go slightly negative on a well-paced window without anything being wrong.
+ */
+private fun shave(ms: Double, floorMs: Double): Double = (ms - floorMs).coerceAtLeast(0.0)
+
 /**
  * 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
@@ -174,8 +226,9 @@ private fun statLine(text: String, color: Color) {
  * 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]
+    // Prefer the capture→displayed end-to-end (s[24]) when a render timestamp landed this window,
+    // less the excluded OS present floor — the same number the richer tiers headline.
+    val e2eP50 = if (s.size >= 26 && s[22] != 0.0) shave(s[24], osFloorMs(s)) else s[2]
     val parts = buildList {
         add("${s[0].roundToInt()} fps")
         if (latValid) add("${"%.1f".format(e2eP50)} ms")

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

@@ -73,6 +73,7 @@ import io.unom.punktfunk.kit.GamepadRouter
 import io.unom.punktfunk.kit.deviceBodyVibrator
 import io.unom.punktfunk.kit.NativeBridge
 import io.unom.punktfunk.kit.Sc2Capture
+import io.unom.punktfunk.kit.SessionEndReason
 import io.unom.punktfunk.kit.VideoDecoders
 import io.unom.punktfunk.models.ActiveSession
 import java.util.concurrent.atomic.AtomicBoolean
@@ -86,7 +87,7 @@ import kotlinx.coroutines.delay
  * the connect that produced this handle.
  */
 @Composable
-fun StreamScreen(session: ActiveSession, onDisconnect: () -> Unit) {
+fun StreamScreen(session: ActiveSession, onSessionEnded: (SessionEndReason) -> Unit) {
     val handle = session.handle
     val initialSettings = session.settings
     val micEnabled = initialSettings.micEnabled
@@ -200,12 +201,32 @@ fun StreamScreen(session: ActiveSession, onDisconnect: () -> Unit) {
         while (true) {
             delay(1000)
             if (NativeBridge.nativeSessionEnded(handle)) {
-                Toast.makeText(
-                    context,
-                    "Connection lost — the host may be asleep. Wake it to reconnect.",
-                    Toast.LENGTH_LONG,
-                ).show()
-                onDisconnect()
+                // WHY it ended decides what the user is told. This used to show the "host may be
+                // asleep" line for EVERY ending — including a game the player had just quit and a
+                // session the host ended on purpose — which reads as a failure report for
+                // something nobody did wrong. Only a connection that actually died says that now.
+                val reason = SessionEndReason.fromNative(NativeBridge.nativeEndReason(handle))
+                when (reason) {
+                    SessionEndReason.LOST ->
+                        Toast.makeText(
+                            context,
+                            "Connection lost — the host may be asleep. Wake it to reconnect.",
+                            Toast.LENGTH_LONG,
+                        ).show()
+                    SessionEndReason.HOST_ERROR ->
+                        Toast.makeText(
+                            context,
+                            "The host ended the session with an error.",
+                            Toast.LENGTH_LONG,
+                        ).show()
+                    // Deliberate endings — the player quit the game, the host was stopped, or we
+                    // closed it. Leaving the stream IS the feedback; a toast would only add noise.
+                    SessionEndReason.GAME_EXITED,
+                    SessionEndReason.HOST_ENDED,
+                    SessionEndReason.LOCAL,
+                    SessionEndReason.NONE -> {}
+                }
+                onSessionEnded(reason)
                 return@LaunchedEffect
             }
         }
@@ -323,13 +344,14 @@ fun StreamScreen(session: ActiveSession, onDisconnect: () -> Unit) {
         // controller (Automatic). Built here, released on dispose.
         val router = GamepadRouter(
             context, handle, initialSettings.gamepad, initialSettings.gamepadForwarding,
+            initialSettings.systemButtonsForward(), initialSettings.guideGestureEnabled(),
         )
         activity?.gamepadRouter = router
         // Select+Start+L1+R1 chord leaves the stream — a deliberate quit (signal it so the host skips
         // the keep-alive linger), unlike a host-ended / backgrounded drop. The router debounces it
         // (must be held ~1.5 s) and fires onExitChord on its main-thread timer, so leave the stream
         // the same way the Back gesture does.
-        activity?.requestStreamExit = { NativeBridge.nativeDisconnectQuit(handle); onDisconnect() }
+        activity?.requestStreamExit = { NativeBridge.nativeDisconnectQuit(handle); onSessionEnded(SessionEndReason.LOCAL) }
         router.onExitChord = { activity?.requestStreamExit?.invoke() }
         // Show a "hold to quit" hint the moment the chord completes (the router debounces the actual
         // exit); it clears when the buttons release early or the hold elapses. Runs on the main thread.
@@ -506,6 +528,28 @@ fun StreamScreen(session: ActiveSession, onDisconnect: () -> Unit) {
         var dsUsbReceiver: BroadcastReceiver? = null
         if (ds != null) {
             feedback.sink = ds
+            // Tier-A pad audio: render the host's 0xD1 streams on the pad's own 4-channel USB
+            // audio device. Bound here rather than inside DsCapture because the session handle
+            // lives at this layer; DsCapture decides WHEN (it knows the wire index and the link
+            // lifetime), this decides WHETHER.
+            if (initialSettings.padHaptics || initialSettings.padSpeaker) {
+                ds.padAudio = object : DsCapture.PadAudioHook {
+                    override fun start(pad: Int, fd: Int) {
+                        val ok = NativeBridge.nativeStartPadAudio(
+                            handle,
+                            pad,
+                            fd,
+                            initialSettings.padHaptics,
+                            initialSettings.padSpeaker,
+                        )
+                        Log.i("punktfunk", "pad audio on pad $pad: ${if (ok) "started" else "unavailable"}")
+                    }
+
+                    // Returns only once the render thread is joined — DsCapture calls this before
+                    // closing the connection whose descriptor that thread borrows.
+                    override fun stop(pad: Int) = NativeBridge.nativeStopPadAudio(handle, pad)
+                }
+            }
             val usbManager = context.getSystemService(Context.USB_SERVICE) as UsbManager
             val usbDev = ds.findUsbDevice()
             when {
@@ -594,7 +638,7 @@ fun StreamScreen(session: ActiveSession, onDisconnect: () -> Unit) {
     }
 
     // Back gesture = a deliberate exit → signal the quit so the host tears down now (no linger).
-    BackHandler { NativeBridge.nativeDisconnectQuit(handle); onDisconnect() }
+    BackHandler { NativeBridge.nativeDisconnectQuit(handle); onSessionEnded(SessionEndReason.LOCAL) }
 
     // Leaving the app (Home, task switch, screen off) MUST end the session. Android does not
     // suspend a process for going to background, so without this the native worker kept running and
@@ -602,14 +646,14 @@ fun StreamScreen(session: ActiveSession, onDisconnect: () -> Unit) {
     // host still saw a live client and held the session (and its display + encoder) open until the
     // OS eventually reclaimed the process, which on a TV box is effectively never.
     //
-    // Route it through `onDisconnect()` so the composable's `onDispose` above runs the one real
+    // Route it through `onSessionEnded()` so the composable's `onDispose` above runs the one real
     // teardown path. Deliberately NOT a `nativeDisconnectQuit`: backgrounding isn't a user "quit",
     // so the host should linger the display and make coming straight back a fast reconnect.
     DisposableEffect(handle) {
         val lifecycle = (context as? LifecycleOwner)?.lifecycle
         val obs = LifecycleEventObserver { _, event ->
             if (event == Lifecycle.Event.ON_STOP) {
-                onDisconnect()
+                onSessionEnded(SessionEndReason.LOCAL)
             }
         }
         lifecycle?.addObserver(obs)

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

@@ -61,6 +61,16 @@ data class ActiveSession(
      * from "a different host" (a notice; a URL may never preempt a live session).
      */
     val hostId: String? = null,
+    /**
+     * This session was started by launching a title from [hostId]'s library, rather than by
+     * connecting to the host's desktop.
+     *
+     * Decides where the client goes when the session ENDS: a title launched out of a library
+     * belongs back in that library when its game exits — one press from the next one — not on the
+     * host-selection screen. Only meaningful together with a
+     * [io.unom.punktfunk.kit.SessionEndReason.GAME_EXITED] ending.
+     */
+    val launchedFromLibrary: Boolean = false,
 )
 
 /** Trust state of a host, shown as a colored pill on its card. */

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

@@ -0,0 +1,158 @@
+package io.unom.punktfunk
+
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertTrue
+import org.junit.Test
+
+// The console UI's background palettes. These assertions are the CONTRACT the Rust
+// (`pf-console-ui::library`) and Swift (`GamepadPalette.swift`) ports reproduce — the same ids in
+// the same order, the same light/dark split, the same ramp — so one `ui_palette` value is one look
+// on every client.
+class GamepadPaletteTest {
+
+    private fun luma(c: Triple<Double, Double, Double>) =
+        0.2126 * c.first + 0.7152 * c.second + 0.0722 * c.third
+
+    /** Hue angle in degrees, or null for something too grey to have one. */
+    private fun hue(c: Triple<Double, Double, Double>): Double? {
+        val (r, g, b) = c
+        val max = maxOf(r, g, b)
+        val min = minOf(r, g, b)
+        val d = max - min
+        if (d < 0.04) return null
+        val h = when (max) {
+            r -> 60.0 * (((g - b) / d) % 6.0)
+            g -> 60.0 * ((b - r) / d + 2.0)
+            else -> 60.0 * ((r - g) / d + 4.0)
+        }
+        return (h + 360.0) % 360.0
+    }
+
+    /** Ids, order and the light/dark split are the cross-client contract. */
+    @Test
+    fun tableMatchesTheOtherClients() {
+        assertEquals(
+            listOf(
+                "violet", "nebula", "abyss", "ember", "moss", "graphite",
+                "holo", "sunset", "bloom", "dawn", "mint", "opal",
+            ),
+            GamepadPalette.ALL.map { it.id },
+        )
+        // Dark fields lead, pale ones follow, so stepping the row walks one direction.
+        val firstLight = GamepadPalette.ALL.indexOfFirst { it.light }
+        assertEquals(6, firstLight)
+        assertTrue(GamepadPalette.ALL.drop(firstLight).all { it.light })
+        // An unknown name is a newer client's palette, not an error.
+        assertEquals("violet", GamepadPalette.named("chartreuse").id)
+        assertEquals("violet", GamepadPalette.named("").id)
+        // The brand default keeps the shipped field rather than a generated ramp.
+        assertTrue(GamepadPalette.named("violet").stops.isEmpty())
+    }
+
+    /**
+     * A palette must read as SEVERAL hues, not one hue at several brightnesses — that was exactly
+     * the complaint about the hue-rotation model this replaced.
+     */
+    @Test
+    fun everyPaletteIsMultiTone() {
+        for (p in GamepadPalette.ALL) {
+            val stops = p.stops.ifEmpty { continue }
+            val hues = stops.mapNotNull { hue(it) }
+            assertTrue("${p.id}: too few coloured stops", hues.size >= 3)
+            var spread = 0.0
+            for (a in hues) {
+                for (b in hues) {
+                    val d = Math.abs(a - b) % 360.0
+                    spread = maxOf(spread, minOf(d, 360.0 - d))
+                }
+            }
+            // Graphite and Opal are deliberately near-neutral; the rest must travel.
+            val floor = if (p.id == "graphite" || p.id == "opal") 20.0 else 45.0
+            assertTrue("${p.id} spans only $spread° of hue", spread >= floor)
+        }
+    }
+
+    /** A pale palette really is pale — its ink flips, so a mislabelled one is unreadable. */
+    @Test
+    fun palettesAreHonestAboutLightness() {
+        for (p in GamepadPalette.ALL) {
+            if (p.light) {
+                assertTrue("${p.id}'s ground is dark", luma(p.ground) > 0.6)
+                assertTrue("${p.id}'s accent is too pale", luma(p.accent) < 0.45)
+            } else {
+                assertTrue("${p.id}'s ground is light", luma(p.ground) < 0.2)
+                assertTrue("${p.id}'s accent is too dark", luma(p.accent) > 0.25)
+            }
+        }
+    }
+
+    /** The ramp is the shared sampling rule the Rust and Swift ports reproduce. */
+    @Test
+    fun rampInterpolatesBetweenStops() {
+        val stops = listOf(
+            Triple(0.0, 0.0, 0.0), Triple(1.0, 0.0, 0.0), Triple(1.0, 1.0, 1.0),
+        )
+        assertEquals(Triple(0.0, 0.0, 0.0), GamepadPalette.ramp(stops, 0.0))
+        assertEquals(Triple(1.0, 1.0, 1.0), GamepadPalette.ramp(stops, 1.0))
+        assertEquals(Triple(1.0, 0.0, 0.0), GamepadPalette.ramp(stops, 0.5))
+        assertEquals(0.5, GamepadPalette.ramp(stops, 0.25).first, 1e-9)
+        // Out of range clamps rather than throwing.
+        assertEquals(Triple(0.0, 0.0, 0.0), GamepadPalette.ramp(stops, -3.0))
+        assertEquals(Triple(1.0, 1.0, 1.0), GamepadPalette.ramp(stops, 9.0))
+        assertEquals(Triple(0.0, 0.0, 0.0), GamepadPalette.ramp(emptyList(), 0.5))
+    }
+
+    /** The ink a palette calls for: white on a dark field, near-black on a pale one. */
+    @Test
+    fun inkFollowsTheField() {
+        val dark = GamepadInk.of(GamepadPalette.named("violet"))
+        assertTrue(!dark.isLight)
+        assertEquals(1f, dark.fg.red, 1e-6f)
+        assertEquals(1f, dark.shadeScale, 1e-6f)
+
+        val light = GamepadInk.of(GamepadPalette.named("holo"))
+        assertTrue(light.isLight)
+        assertTrue("pale fields need dark ink", light.fg.red < 0.3f)
+        // A pale field's scrims must pull far less, or they bleach the gradient.
+        assertTrue(light.shadeScale < 0.5f)
+    }
+
+    /**
+     * Every settings row lands in exactly one tab — a row missing from the tab map is a setting
+     * that became unreachable on a TV, which is precisely what this screen exists to prevent.
+     */
+    @Test
+    fun everySettingsRowHasATab() {
+        val rows = buildSettingsRows(Settings(), hasBodyVibrator = true, av1Capable = true) {}
+        assertTrue(rows.isNotEmpty())
+        assertEquals(rows.size, rows.map { it.id }.toSet().size)
+        // Profiles is built separately (from the catalog), so no settings row claims it.
+        assertTrue(rows.none { it.tab == GpTab.PROFILES })
+        for (t in listOf(GpTab.STREAM, GpTab.VIDEO, GpTab.AUDIO, GpTab.CONTROLLER, GpTab.INTERFACE)) {
+            assertTrue("$t is empty", rows.any { it.tab == t })
+        }
+    }
+
+    /** The Background row steps the shared `ui_palette` key and wraps on A, like every choice row. */
+    @Test
+    fun backgroundRowStepsTheSharedKey() {
+        var s = Settings()
+        fun rows() = buildSettingsRows(s, hasBodyVibrator = false, av1Capable = false) { s = it }
+        fun palette() = rows().first { it.id == "palette" }
+
+        assertEquals("violet", s.uiPalette)
+        assertEquals("Violet", palette().value)
+        assertTrue("already the first = thud", !palette().adjust(-1))
+        assertTrue(palette().adjust(1))
+        assertEquals(GamepadPalette.ALL[1].id, s.uiPalette)
+
+        // A from the last entry wraps home.
+        s = s.copy(uiPalette = GamepadPalette.ALL.last().id)
+        palette().activate()
+        assertEquals("violet", s.uiPalette)
+
+        // A store written by a newer client shows the palette that is actually drawing.
+        s = s.copy(uiPalette = "chartreuse")
+        assertEquals("Violet", palette().value)
+    }
+}

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

@@ -0,0 +1,97 @@
+package io.unom.punktfunk
+
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertNotNull
+import org.junit.Assert.assertNull
+import org.junit.Assert.assertTrue
+import org.junit.Test
+
+/**
+ * The controller-navigable settings rows: what the master forwarding switch governs, and that a
+ * governed row is inert rather than merely dim.
+ *
+ * The touch settings and the desktop console have carried this relationship for a while (`enabled =
+ * s.gamepadForwarding` / `RowSpec.enabled`); this screen dimmed nothing and stepped everything, so
+ * these tests pin both halves — the flag AND the refusal to write.
+ */
+class GamepadSettingsRowsTest {
+
+    /** Rows for a given forwarding state, capturing whatever a row writes back. */
+    private fun rows(
+        forwarding: Boolean,
+        sink: MutableList<Settings> = mutableListOf(),
+    ): List<GpRow> = buildSettingsRows(
+        Settings(gamepadForwarding = forwarding),
+        hasBodyVibrator = true,
+        av1Capable = true,
+    ) { sink += it }
+
+    private fun row(rows: List<GpRow>, id: String): GpRow =
+        rows.first { it.id == id }
+
+    /** Every row that only means something while a controller is actually being forwarded. */
+    private val governed = listOf("padType", "systemButtons", "guideGesture", "sc2", "dsCapture")
+
+    @Test
+    fun `forwarding off dims every row that depends on it`() {
+        val off = rows(forwarding = false)
+        for (id in governed) {
+            assertFalse("$id should be dimmed with forwarding off", row(off, id).enabled)
+        }
+        // The master switch itself stays live — otherwise it could never be turned back on.
+        assertTrue(row(off, "padForward").enabled)
+    }
+
+    @Test
+    fun `forwarding on leaves them all live`() {
+        val on = rows(forwarding = true)
+        for (id in governed) {
+            assertTrue("$id should be live with forwarding on", row(on, id).enabled)
+        }
+    }
+
+    @Test
+    fun `a dimmed row is inert - liveRow withholds it and nothing is written`() {
+        val writes = mutableListOf<Settings>()
+        val off = rows(forwarding = false, sink = writes)
+        for (id in governed) {
+            val i = off.indexOfFirst { it.id == id }
+            assertNull("$id must not be reachable while dimmed", liveRow(off, i))
+            // What the screen actually does on left/right/A — the whole point is that it no-ops.
+            liveRow(off, i)?.adjust(1)
+            liveRow(off, i)?.adjust(-1)
+            liveRow(off, i)?.activate()
+        }
+        assertEquals("a dimmed row wrote a setting", emptyList<Settings>(), writes)
+    }
+
+    @Test
+    fun `the same rows do write once forwarding is on`() {
+        val writes = mutableListOf<Settings>()
+        val on = rows(forwarding = true, sink = writes)
+        val i = on.indexOfFirst { it.id == "sc2" }
+        assertNotNull(liveRow(on, i))
+        liveRow(on, i)?.activate()
+        assertEquals(1, writes.size)
+        assertFalse("activate flips the toggle", writes[0].sc2Capture)
+    }
+
+    /**
+     * R18: the Sony passthrough toggle the touch settings have always had. It matters most exactly
+     * where this screen is the only one reachable — a TV box has no touch interface to fall back to.
+     */
+    @Test
+    fun `the DualSense passthrough toggle is present, next to its SC2 twin`() {
+        val on = rows(forwarding = true)
+        val ids = on.map { it.id }
+        assertTrue("dsCapture row is missing", "dsCapture" in ids)
+        assertEquals(
+            "the two passthrough rows belong side by side",
+            ids.indexOf("sc2") + 1,
+            ids.indexOf("dsCapture"),
+        )
+        // Drawn as a switch, and reading the persisted default.
+        assertEquals(true, row(on, "dsCapture").toggled)
+    }
+}

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

@@ -0,0 +1,48 @@
+package io.unom.punktfunk
+
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertTrue
+import org.junit.Test
+
+/**
+ * Pure JVM test of the safe-area stream geometry ([SafeArea]) and the sentinel that selects it —
+ * the width-only inset that keeps the picture clear of the cutout and the rounded corners.
+ * Run: `./gradlew :app:testDebugUnitTest`.
+ */
+class SafeAreaTest {
+    @Test
+    fun insetsBothSidesAndStaysHostValid() {
+        // A punch-hole phone: 2400 px wide, 96 px of unsafe edge per side → 2208.
+        assertEquals(2400 - 96 * 2, SafeArea.insetWidth(2400, 96))
+        // Odd results even-floor — the host rejects odd dimensions outright, and an inset
+        // subtraction lands odd about half the time.
+        assertEquals(0, SafeArea.insetWidth(2401, 95) % 2)
+        // No cutout and square corners → the native width, unchanged.
+        assertEquals(2400, SafeArea.insetWidth(2400, 0))
+    }
+
+    @Test
+    fun absurdInsetsCannotDriveTheModeUnderTheHostFloor() {
+        assertEquals(SafeArea.MIN_WIDTH, SafeArea.insetWidth(1280, 5000))
+        // A negative reading is treated as no inset rather than widening past the panel.
+        assertEquals(1280, SafeArea.insetWidth(1280, -40))
+    }
+
+    @Test
+    fun safeModeIsNarrowerThanNativeWheneverThereIsAnInset() {
+        val native = 2556
+        assertTrue(SafeArea.insetWidth(native, 60) < native)
+    }
+
+    @Test
+    fun theSentinelIsAPresetAndNeverReadsAsCustom() {
+        // The safe-area mode is a stored preset, not a typed size: `isCustomResolution` must be
+        // false for it, or the touch settings would open the custom width/height fields on it and
+        // the gamepad screen would prepend a bogus "Custom · -2 × -2" row.
+        val s = Settings(width = SAFE_AREA_MODE, height = SAFE_AREA_MODE)
+        assertTrue(!s.isCustomResolution())
+        // And it must be distinct from the UI's own "Custom…" sentinel (-1).
+        assertTrue(SAFE_AREA_MODE != -1)
+        assertTrue(RESOLUTION_OPTIONS.any { it.first == SAFE_AREA_MODE && it.second == SAFE_AREA_MODE })
+    }
+}

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

@@ -106,6 +106,14 @@ class ScreenshotTest {
     @Test
     fun connectingConsole() = shootRoot("connecting-console") { ConnectConsoleScene() }
 
+    @Test
+    fun consoleSettings() = shootRoot("console-settings") { ConsoleSettingsScene() }
+
+    /** A PALE palette: the whole UI flips to dark ink on white frost, which only a shot proves. */
+    @Test
+    fun consoleSettingsLight() =
+        shootRoot("console-settings-light") { ConsoleSettingsScene(paletteId = "holo") }
+
     @Test
     fun trust() = shootScreen("trust") {
         HostsScene()

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

@@ -31,6 +31,12 @@ import io.unom.punktfunk.BrandDark
 import io.unom.punktfunk.ConnectModal
 import io.unom.punktfunk.ConnectPhase
 import io.unom.punktfunk.ConnectTakeover
+import androidx.compose.runtime.CompositionLocalProvider
+import io.unom.punktfunk.GamepadInk
+import io.unom.punktfunk.GamepadPalette
+import io.unom.punktfunk.GamepadSettingsScreen
+import io.unom.punktfunk.LocalGamepadInk
+import io.unom.punktfunk.LocalGamepadPalette
 import io.unom.punktfunk.Settings
 import io.unom.punktfunk.TouchMode
 import io.unom.punktfunk.SettingsCategory
@@ -355,9 +361,11 @@ internal fun StreamScene(verbosity: StatsVerbosity = StatsVerbosity.DETAILED) {
         // 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
+        // directly-measured capture→displayed pair, less the excluded OS present floor (the 0.3
+        // latch p50) — 1.5/2.3 shown from 1.8/2.6 raw — and the Phase-2 stage terms
+        // (host 0.6 + network 0.3 + decode 0.4 + display 0.2) tile the shaved headline, with the
+        // `os present +0.3 excluded` line naming what came off; 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(
@@ -404,3 +412,25 @@ internal fun WakeTimedOutScene() =
 @Composable
 internal fun ConnectConsoleScene() =
     ConnectTakeover(ConnectPhase.Connecting("Living Room PC"), onCancel = {}, onRetry = {})
+
+/**
+ * The real console settings screen — the section tab strip, the glass rows, the focused row's
+ * unfolded detail, and the living (calmed) backdrop behind them. The touch [SettingsScene] can't
+ * stand in for it: this is a different screen with different navigation, and the strip is the part
+ * a layout regression would eat first.
+ */
+@Composable
+internal fun ConsoleSettingsScene(paletteId: String = "violet") {
+    // The scene calls the screen directly, so it has to publish the palette locals `App` would
+    // normally provide — without them a light palette would render with the default DARK ink and
+    // the shot would silently prove nothing.
+    val palette = GamepadPalette.named(paletteId)
+    CompositionLocalProvider(
+        LocalGamepadPalette provides palette,
+        LocalGamepadInk provides GamepadInk.of(palette),
+    ) {
+        GamepadSettingsScreen(
+            initial = SHOT_SETTINGS.copy(uiPalette = paletteId), onChange = {}, onBack = {},
+        )
+    }
+}

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

@@ -23,8 +23,9 @@ import android.view.InputDevice
  * Input: parse ([DsDevice.parseState]) → typed mirror on an [GamepadRouter.ExternalPad] (buttons
  * diffed, axes on-change — the exit chord participates like any pad) + the rich plane (touch
  * normalized to the wire's 0..65535 screen space on-change; motion forwarded per report in raw
- * device units, the wire's contract). The wire slot is claimed lazily on the FIRST parsed report
- * and freed on unplug/[stop], so indices never leak.
+ * device units, the wire's contract). The wire slot is claimed when the capture engages, with the
+ * first parsed report as the fallback for a claim that found no free index, and freed on
+ * unplug/[stop], so indices never leak.
  *
  * Feedback: implements [GamepadFeedback.PadFeedbackSink] — rumble / trigger / lightbar / player
  * LED events addressed to this pad's wire index become USB output reports on the physical pad
@@ -78,6 +79,33 @@ class DsCapture(
     @Volatile
     var onActiveChanged: ((active: Boolean) -> Unit)? = null
 
+    /**
+     * Tier-A pad audio, bound by the app layer (which owns the session handle).
+     *
+     * [start] is called once the router has assigned this pad a wire index, which the host uses to
+     * address the `0xD1` stream. [stop] is called **before** the USB link closes — on [stop] and on
+     * unplug alike — and must not return until nothing is still writing to the descriptor.
+     */
+    interface PadAudioHook {
+        fun start(pad: Int, fd: Int)
+        fun stop(pad: Int)
+    }
+
+    @Volatile
+    var padAudio: PadAudioHook? = null
+
+    /** True once [PadAudioHook.start] has run for the current capture, so it fires exactly once. */
+    @Volatile private var padAudioStarted = false
+
+    /**
+     * The renderer's OWN connection to the pad.
+     *
+     * It must not share [usb]'s descriptor: two transfer engines on one usbfs descriptor reap each
+     * other's completions (see [HidUsbLink.openAuxConnection]), which strands both the HID reader
+     * and the audio ring. Closed only after the hook's stop has returned.
+     */
+    @Volatile private var padAudioConn: android.hardware.usb.UsbDeviceConnection? = null
+
     val isActive: Boolean get() = model != null
 
     /** First attached Sony USB pad, for the permission flow. Needs no permission to enumerate. */
@@ -105,18 +133,28 @@ class DsCapture(
         // (the same init hid-playstation/SDL send on open).
         if (m != DsDevice.Model.DUALSHOCK4) usb.writeRaw(0, DsDevice.ds5InitReport(m))
         Log.i(TAG, "Sony pad captured over USB: PID=0x%04x model=%s".format(dev.productId, m))
+        ensureSlot(m)
         onActiveChanged?.invoke(true)
         return true
     }
 
     /** Stop the link and free the wire slot (host tears the virtual pad down). Idempotent. */
     fun stop() {
+        // Before anything touches the link: the pad-audio renderer borrows this connection's
+        // descriptor, and `usb.stop()` closes it. The hook does not return until its thread is
+        // joined, so ordering this first is what makes the borrow sound.
+        stopPadAudio()
         val m = model
         if (m != null) {
             // The interfaces are about to release with the kernel driver still detached — a
             // mid-rumble teardown would leave the motors running with nobody to stop them.
             // EP0-direct (the reader thread is stopping; the queue would never drain).
-            usb.writeControl(stopReport(m))
+            // Nothing can retry after this point, so a failure is worth saying out loud: it is
+            // the difference between a quiet pad and one that buzzes until it is unplugged.
+            if (!usb.writeControl(stopReport(m))) Log.w(TAG, "teardown rumble stop was not written")
+            // Motors silenced above; this hands back the lightbar, player LEDs and adaptive
+            // triggers the game was holding, which outlive the link just as stubbornly.
+            resetRichFeedback(m)
         }
         disarmBackstop()
         usb.stop()
@@ -131,20 +169,119 @@ class DsCapture(
     private fun onReport(report: ByteArray, len: Int) {
         val m = model ?: return
         if (!DsDevice.parseState(m, report, len, state)) return
-        val p = pad ?: router.openExternal(m.pref)?.also {
-            pad = it
-            Log.i(TAG, "captured $m → wire pad ${it.index}")
-        } ?: return // all 16 wire indices taken — drop until one frees
+        // Normally claimed already, at capture time; this is the retry for a capture that engaged
+        // while every wire index was taken.
+        val p = pad ?: ensureSlot(m) ?: return // all 16 taken — drop until one frees
         mirrorTyped(p)
         mirrorRich(p, m)
     }
 
+    /**
+     * Claim this capture's wire slot and start pad audio on it. Idempotent; null when all 16
+     * indices are taken.
+     *
+     * Claimed when the capture engages rather than on the first report, because a pad that reports
+     * nothing is still a pad: with the lazy claim, a captured-but-silent pad left the host with no
+     * arrival, hence no virtual pad, no pad-audio capability and so no `0xD1` — a renderer sitting
+     * at zero frames, indistinguishable from a broken pipeline (it took a physical replug to
+     * clear). Callable from the main thread (capture start) and the link thread (the fallback).
+     */
+    @Synchronized
+    private fun ensureSlot(m: DsDevice.Model): GamepadRouter.ExternalPad? {
+        pad?.let { return it }
+        val p = router.openExternal(m.pref) ?: return null
+        pad = p
+        Log.i(TAG, "captured $m → wire pad ${p.index}")
+        // The wire index exists from here on, and the host addresses pad audio by it.
+        startPadAudio(p.index)
+        return p
+    }
+
+    /** Hand the renderer its own descriptor. Caller holds the monitor; fires once per capture. */
+    private fun startPadAudio(index: Int) {
+        val hook = padAudio ?: return
+        if (padAudioStarted) return
+        // A dedicated connection, NOT usb.fileDescriptor — see padAudioConn.
+        val conn = usb.openAuxConnection()
+        val fd = conn?.fileDescriptor ?: -1
+        if (fd < 0) {
+            conn?.close()
+            Log.w(TAG, "pad audio: could not open a second USB connection")
+            return
+        }
+        padAudioConn = conn
+        padAudioStarted = true
+        // Real-world self test, opt-in: `adb shell setprop debug.punktfunk.pad_audio_selftest 3`
+        // drives the voice coils for N seconds through the actual client path before the renderer
+        // takes over — the one check that proves the descriptor, the interface claim and the write
+        // path all work on THIS device, without needing a host to be streaming. Same convention as
+        // debug.punktfunk.force_parts.
+        val secs = runCatching {
+            Class.forName("android.os.SystemProperties")
+                .getMethod("get", String::class.java, String::class.java)
+                .invoke(null, "debug.punktfunk.pad_audio_selftest", "0") as String
+        }.getOrNull()?.toIntOrNull() ?: 0
+        if (secs > 0) {
+            // Diagnostic mode: the self test OWNS this descriptor for the capture, and the renderer
+            // must not also drive it — two engines on one usbfs descriptor reap each other's
+            // completions, which is precisely the fault this test exists to expose.
+            Thread({
+                val r = NativeBridge.nativePadAudioSelfTest(fd, secs, 60)
+                Log.i(TAG, "pad audio self-test → ${if (r > 0) "PASS ($r frames)" else "FAIL ($r)"}")
+            }, "pf-pad-selftest").start()
+        } else {
+            // B6: hand the coils back before the first haptics frame. Any rumble earlier in this
+            // session asserted HAPTICS_SELECT, which firmware-mutes them, and nothing else ever
+            // clears it — so without this the stream renders into a muted actuator and looks for
+            // all the world like the host is sending nothing.
+            restoreAudioHaptics()
+            hook.start(index, fd)
+        }
+    }
+
+    /**
+     * B6: clear the rumble/haptics-select bits so the pad's voice coils answer the audio-haptics
+     * path again. EP0-direct, like the other out-of-band writes here: this has to land even when
+     * the interrupt-OUT queue is busy or draining, and it is idempotent.
+     */
+    private fun restoreAudioHaptics() {
+        val m = model ?: return
+        if (m == DsDevice.Model.DUALSHOCK4) return // no voice coils, no audio-haptics path
+        if (!usb.writeControl(DsDevice.ds5AudioHapticsReport(m))) {
+            Log.w(TAG, "pad audio: could not hand the coils back to audio haptics")
+        }
+    }
+
+    /**
+     * Stop the renderer, then close the connection whose descriptor it borrows — in that order.
+     *
+     * Runs on [stop] and on unplug alike. Skipping it on unplug left the render thread writing to a
+     * descriptor whose device was gone, leaked the connection, and — because the started flag stayed
+     * set and the native tier-A registry stayed armed for that index — cost the pad both its pad
+     * audio and its wire rumble on the way back in.
+     */
+    @Synchronized
+    private fun stopPadAudio() {
+        if (!padAudioStarted) return
+        padAudioStarted = false
+        // The hook's stop joins the render thread, so nothing is using the descriptor once it
+        // returns — only then is it safe to close the connection that owns it.
+        pad?.let { padAudio?.stop(it.index) }
+        padAudioConn?.close()
+        padAudioConn = null
+    }
+
     private fun onLinkClosed() {
         Log.i(TAG, "Sony USB link closed (unplug)")
+        // Before releaseSlot(), which forgets the wire index the renderer is addressed by.
+        stopPadAudio()
         disarmBackstop()
         val wasActive = model != null
         model = null
         releaseSlot()
+        // Release the transport too: the link only *signals* the drop, so without this an unplug
+        // left its connection open, its interfaces claimed and its detach receiver registered.
+        usb.stop()
         if (wasActive) onActiveChanged?.invoke(false)
     }
 
@@ -216,17 +353,24 @@ class DsCapture(
 
     override fun rumble(pad: Int, low: Int, high: Int, backstopMs: Long) {
         val m = model ?: return
-        if (low == 0 && high == 0) {
-            disarmBackstop()
-        } else {
-            armBackstop(backstopMs)
-        }
-        if (m == DsDevice.Model.DUALSHOCK4) {
+        val stop = low == 0 && high == 0
+        if (!stop) armBackstop(backstopMs)
+        val sent = if (m == DsDevice.Model.DUALSHOCK4) {
             ds4Low = low
             ds4High = high
             writeDs4()
         } else {
-            usb.writeRaw(0, DsDevice.ds5RumbleReport(m, low, high))
+            usb.writeRaw(0, DsDevice.ds5RumbleReport(m, low, high), OutReportQueue.KEY_RUMBLE)
+        }
+        if (stop) {
+            // Disarm only once the stop is actually on its way. Dropping the net *before* the
+            // write — as this used to — meant a discarded stop left the motors running with
+            // nothing scheduled to try again; a USB pad holds its last level until told zero.
+            if (sent) disarmBackstop() else armBackstop(STOP_RETRY_MS)
+            // B6: the stop report just re-asserted HAPTICS_SELECT on its way past, so if a
+            // haptics stream is live the coils it drives were muted by the very write that
+            // silenced the motors. Give them back.
+            if (sent && padAudioStarted) restoreAudioHaptics()
         }
     }
 
@@ -252,6 +396,9 @@ class DsCapture(
         usb.writeRaw(0, DsDevice.ds5TriggerReport(m, which, effect))
     }
 
+    // Coalescable: the DS4's write is full-state (motors AND lightbar, rebuilt from the current
+    // fields on every call), so a newer one supersedes an older one wholesale — nothing is lost by
+    // collapsing a backlog of them down to the last.
     private fun writeDs4() = usb.writeRaw(
         0,
         DsDevice.ds4Report(
@@ -261,8 +408,38 @@ class DsCapture(
             (ds4Rgb shr 8) and 0xFF,
             ds4Rgb and 0xFF,
         ),
+        OutReportQueue.KEY_RUMBLE,
     )
 
+    /**
+     * Hand the pad back neutral: adaptive triggers released, lightbar dark, player LEDs clear.
+     *
+     * Rumble stops the moment nothing renews it, but these are LATCHED in the controller's
+     * firmware — they outlive the stream, the app, and being unplugged. Ending a session while a
+     * game held a weapon's trigger resistance left the physical trigger stiff afterwards, with
+     * nothing to release it but another game that happens to set one.
+     *
+     * EP0-direct like the rumble stop above: the reader thread is stopping, so the interrupt-OUT
+     * queue would never drain. Writes are best-effort — the pad may already be gone.
+     */
+    private fun resetRichFeedback(m: DsDevice.Model) {
+        if (m == DsDevice.Model.DUALSHOCK4) {
+            // No adaptive triggers or player LEDs on a DS4, and its write is full-state, so
+            // blacking the lightbar is a single composed report.
+            ds4Rgb = 0
+            usb.writeControl(DsDevice.ds4Report(0, 0, 0, 0, 0))
+            return
+        }
+        // An all-zero effect block is mode 0x00 — no effect — which is what releases the trigger.
+        for (which in 0..1) {
+            usb.writeControl(
+                DsDevice.ds5TriggerReport(m, which, ByteArray(DsDevice.TRIGGER_EFFECT_LEN)),
+            )
+        }
+        usb.writeControl(DsDevice.ds5LightbarReport(m, 0, 0, 0))
+        usb.writeControl(DsDevice.ds5PlayerLedsReport(m, 0))
+    }
+
     /** The report that stops the motors. The DS4's is a full-state write, so it zeroes the
      *  composed motor state and carries the current lightbar rather than blacking it out. */
     private fun stopReport(m: DsDevice.Model): ByteArray = if (m == DsDevice.Model.DUALSHOCK4) {
@@ -284,7 +461,12 @@ class DsCapture(
         backstop?.let { mainHandler.removeCallbacks(it) }
         val r = Runnable {
             backstop = null
-            model?.let { usb.writeRaw(0, stopReport(it)) }
+            val m = model ?: return@Runnable
+            // The net itself can be refused (a full queue, a connection going away). Re-arm rather
+            // than give up: this is the last thing between a stalled poll thread and a pad that
+            // buzzes until it is unplugged. It stops re-arming as soon as the link closes, which
+            // clears `model` and disarms.
+            if (!usb.writeRaw(0, stopReport(m), OutReportQueue.KEY_RUMBLE)) armBackstop(STOP_RETRY_MS)
         }
         backstop = r
         mainHandler.postDelayed(r, ms.coerceAtLeast(1))
@@ -297,5 +479,9 @@ class DsCapture(
 
     private companion object {
         const val TAG = "DsCapture"
+
+        /** How soon to retry a rumble stop whose write was rejected. Short: the motors are running
+         *  and the host has already moved on, so nothing else is coming to silence them. */
+        const val STOP_RETRY_MS = 100L
     }
 }

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

@@ -276,11 +276,26 @@ object DsDevice {
      * the classic compat-vibration path AND `VIBRATION2` (firmware ≥ 2.24's full-range replot;
      * older firmware ignores the unknown flag2 bit) — the host parser accepts either.
      */
+    /**
+     * B6: hand the voice coils back to the audio-haptics path.
+     *
+     * Every [ds5RumbleReport] asserts `HAPTICS_SELECT` (flag0 bit1), which is SDL's
+     * "disable audio haptics" bit — the firmware mutes the coils the 0xD1 haptics stream drives.
+     * Until now NOTHING ever cleared it again, so a single rumble anywhere in a session left tier-A
+     * haptics silent for the rest of that pad's life, with no error and nothing in a log.
+     *
+     * The undo is a report whose flag0 has BOTH bits clear (SDL's own comment: "Leaving emulated
+     * rumble bits off will restore audio haptics"). No other valid flag is set, so nothing else
+     * about the pad's state is touched. Mirrors `Ds5Feedback::audio_haptics_packet` on the desktop
+     * client, which is the same packet one transport over.
+     */
+    fun ds5AudioHapticsReport(model: Model): ByteArray = newDs5(model)
+
     fun ds5RumbleReport(model: Model, low: Int, high: Int): ByteArray = newDs5(model).also {
         it[1] = (DS5_FLAG0_COMPAT_VIBRATION or DS5_FLAG0_HAPTICS_SELECT).toByte()
         it[39] = DS5_FLAG2_VIBRATION2.toByte()
-        it[3] = amp8(high).toByte()
-        it[4] = amp8(low).toByte()
+        it[3] = wireAmplitudeToByte(high).toByte()
+        it[4] = wireAmplitudeToByte(low).toByte()
     }
 
     /**
@@ -324,17 +339,11 @@ object DsDevice {
         ByteArray(Model.DUALSHOCK4.outputSize).also {
             it[0] = 0x05
             it[1] = (DS4_FLAG0_MOTORS or DS4_FLAG0_LED).toByte()
-            it[4] = amp8(high).toByte()
-            it[5] = amp8(low).toByte()
+            it[4] = wireAmplitudeToByte(high).toByte()
+            it[5] = wireAmplitudeToByte(low).toByte()
             it[6] = r.toByte()
             it[7] = g.toByte()
             it[8] = b.toByte()
         }
 
-    // Wire u16 amplitude → motor byte; a nonzero command never collapses to 0 (parity with the
-    // vibrator path's toAmplitude).
-    private fun amp8(v16: Int): Int {
-        val a = (v16 ushr 8) and 0xFF
-        return if (v16 != 0 && a == 0) 1 else a
-    }
 }

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

@@ -88,6 +88,9 @@ class GamepadFeedback(
         const val TAG_PLAYER_LEDS: Byte = 0x02
         const val TAG_TRIGGER: Byte = 0x03
         const val TAG_HID_RAW: Byte = 0x05
+
+        /** Sparse-log cadence for swallowed render failures — see [noteRenderFailure]. */
+        const val LOG_EVERY = 128L
     }
 
     /** One controller's rumble binding — VibratorManager (API 31+) OR the legacy single Vibrator (API 28–30). */
@@ -125,37 +128,51 @@ class GamepadFeedback(
     fun start() {
         running = true
         rumbleThread = Thread({
+            var failures = 0L
             while (running) {
                 val ev = NativeBridge.nativeNextRumble(handle)
-                if (ev < 0L) continue // timeout / closed
-                // ev bits 49..52 = wire pad index; bits 32..47 = backstop duration (ms);
-                // 16..31 = low; 0..15 = high. These are EFFECTIVE commands from the core's shared
-                // rumble policy engine — it owns every lease/staleness/close decision (uniform
-                // across all clients; the old 60 s legacy-host exposure is gone) and emits
-                // explicit zeros, so apply verbatim: (0, 0) = cancel, non-zero = one-shot for
-                // the backstop (the hardware net under a stalled poll thread).
-                val pad = ((ev ushr 49) and 0xFL).toInt()
-                val backstopMs = ((ev ushr 32) and 0xFFFF)
-                renderRumble(
-                    pad,
-                    ((ev ushr 16) and 0xFFFF).toInt(),
-                    (ev and 0xFFFF).toInt(),
-                    backstopMs,
-                )
+                // Layout + semantics live in `unpackRumbleEvent` (RumbleWire.kt), tested there
+                // against the Rust packer.
+                val cmd = unpackRumbleEvent(ev) ?: continue // timeout / closed
+                // Rendering is binder calls into the vibrator service, and every one of them can
+                // throw unchecked — DeadSystemRuntimeException when system_server goes down, and
+                // the ordinary RuntimeException a dying service wraps its RemoteException in.
+                // Unguarded, ONE of those killed this thread outright: `running` stayed true, so
+                // nothing noticed and nothing restarted it, and rumble was gone for the rest of
+                // the session. Losing a single command is recoverable; losing the loop is not.
+                runCatching {
+                    renderRumble(cmd.pad, cmd.low, cmd.high, cmd.backstopMs)
+                }.onFailure { failures = noteRenderFailure("rumble", it, failures) }
             }
         }, "pf-rumble").apply { isDaemon = true; start() }
 
         hidoutThread = Thread({
             // 128: the raw as-is passthrough events are [pad][kind tag][report kind][≤64 bytes].
             val buf = ByteBuffer.allocateDirect(128)
+            var failures = 0L
             while (running) {
                 val n = NativeBridge.nativeNextHidout(handle, buf)
                 if (n < 0) continue // timeout / closed
-                dispatchHidout(buf, n)
+                // Same hazard as the rumble loop above: lights/trigger rendering is binder and USB
+                // calls, and an unchecked throw here would silently end the rich-feedback plane.
+                runCatching { dispatchHidout(buf, n) }
+                    .onFailure { failures = noteRenderFailure("hidout", it, failures) }
             }
         }, "pf-hidout").apply { isDaemon = true; start() }
     }
 
+    /**
+     * Record a render failure the poll loop swallowed, and return the updated count. Logged on the
+     * first occurrence and sparsely after: a genuinely dead vibrator service fails on *every*
+     * command, which at a rumble plane's rate would bury the log.
+     */
+    private fun noteRenderFailure(plane: String, t: Throwable, seen: Long): Long {
+        if (seen == 0L || seen % LOG_EVERY == 0L) {
+            Log.w(TAG, "$plane render failed (#${seen + 1}) — command dropped, poll loop alive", t)
+        }
+        return seen + 1
+    }
+
     /** Idempotent. Stops + joins the poll threads (must complete before the router is released / handle freed). */
     fun stop() {
         running = false
@@ -264,12 +281,12 @@ class GamepadFeedback(
             return
         }
         val bind = rumbleBindFor(pad) ?: return
-        val lo = toAmplitude(low)
-        val hi = toAmplitude(high)
+        val lo = wireAmplitudeToByte(low)
+        val hi = wireAmplitudeToByte(high)
         val m = bind.vm
         if (m != null) {
             if (lo == 0 && hi == 0) {
-                m.cancel() // (0,0) = stop
+                runCatching { m.cancel() } // (0,0) = stop
                 return
             }
             val combo = CombinedVibration.startParallel()
@@ -294,7 +311,7 @@ class GamepadFeedback(
         // API 28–30 legacy single-motor path: blend both motors into one effect.
         val lv = bind.legacy ?: return
         if (lo == 0 && hi == 0) {
-            lv.cancel() // (0,0) = stop
+            runCatching { lv.cancel() } // (0,0) = stop
             return
         }
         val a = (lo * 0.8 + hi * 0.33).toInt().coerceIn(1, 255)
@@ -314,8 +331,8 @@ class GamepadFeedback(
      */
     private fun renderDeviceRumble(low: Int, high: Int, durationMs: Long) {
         val v = deviceVibrator ?: return
-        val lo = toAmplitude(low)
-        val hi = toAmplitude(high)
+        val lo = wireAmplitudeToByte(low)
+        val hi = wireAmplitudeToByte(high)
         if (lo == 0 && hi == 0) {
             runCatching { v.cancel() } // (0,0) = stop
             return
@@ -329,12 +346,6 @@ class GamepadFeedback(
         }
     }
 
-    // 0..0xFFFF → 1..255 (high byte); a nonzero motor never collapses to 0.
-    private fun toAmplitude(v16: Int): Int {
-        val a = (v16 ushr 8) and 0xFF
-        return if (v16 != 0 && a == 0) 1 else a
-    }
-
     // 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. Floor the duration at 1 ms: `createOneShot`
     // throws IllegalArgumentException on a non-positive duration, and a lease can carry ttl_ms==0

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

@@ -50,12 +50,35 @@ class GamepadRouter(
      * capture links, which `StreamScreen` does not start at all while this is off.
      */
     private val forwarding: Boolean = true,
+    /**
+     * Forward raw guide/QAM presses (`Settings.systemButtons` resolved — auto = forward on
+     * Android, where the press reaches the app on most devices; `local` exists for
+     * cross-client profile parity with the Gaming-Mode clients). Off keeps them entirely
+     * with this device.
+     */
+    private val systemForward: Boolean = true,
+    /**
+     * The hold-Select guide gesture (`Settings.guideGesture` resolved — auto = off on
+     * Android): holding Select ALONE ≥ [GUIDE_HOLD_MS] sends the HOST's guide button, down
+     * until release — so a long hold is the host's long-press, a Gaming-Mode host's QAM. A
+     * Select tap is delivered on release (delayed by up to the threshold); a Select pressed
+     * while other buttons are down passes through untouched, so the exit/mic chords keep
+     * working. pf-client-core's `SelectGesture`, on the main-thread handler.
+     */
+    private val guideGesture: Boolean = false,
 ) {
 
     /** One forwarded controller: its stable wire pad index, per-device axis state, and held buttons. */
     private class Slot(val index: Int, val mapper: Gamepad.AxisMapper) {
         /** Forwarded button bits currently held (Gamepad.BTN_*) — for release-on-close + chord detection. */
         var held = 0
+
+        // Hold-Select→guide gesture state ([guideGesture]): the pending Select's hold
+        // timer / a delivered tap's owed release (both on the main handler), and whether
+        // the held Select was transformed into a synthetic guide.
+        var pendingGuide: Runnable? = null
+        var pendingTapUp: Runnable? = null
+        var selectAsGuide = false
     }
 
     /** deviceId → slot. Concurrent: the feedback poll threads read it via [deviceForPad]. */
@@ -139,7 +162,24 @@ class GamepadRouter(
      * the mic-mute chord ([MIC_CHORD]).
      */
     private fun slotButton(slot: Slot, bit: Int, down: Boolean, send: Boolean) {
+        // Raw system buttons stay local under the "local" policy — no wire send and no held
+        // tracking, symmetric on both edges so nothing leaks into the chords either.
+        if (!systemForward && (bit == Gamepad.BTN_GUIDE || bit == Gamepad.BTN_MISC1)) return
         if (down) {
+            if (guideGesture && send) {
+                // A Select pressed ALONE is held back until it resolves: a tap (delivered
+                // on release), a combo member (the next button flushes it as a real
+                // press), or — past GUIDE_HOLD_MS — a synthetic guide. Held state records
+                // it either way, so the exit/mic chords read as if the gesture didn't
+                // exist (Select+Y still fires the mic toggle: the flush sends Select's
+                // down before Y's).
+                if (bit == Gamepad.BTN_BACK && slot.held == 0) {
+                    slot.held = slot.held or bit
+                    armGuide(slot)
+                    return
+                }
+                flushPendingSelect(slot)
+            }
             if (send && forwarding) {
                 NativeBridge.nativeSendGamepadButton(handle, bit, true, slot.index)
             }
@@ -155,7 +195,8 @@ class GamepadRouter(
                 onMicChord?.invoke()
             }
         } else {
-            if (send && forwarding) {
+            val owned = guideGesture && bit == Gamepad.BTN_BACK && consumeSelectRelease(slot)
+            if (!owned && send && forwarding) {
                 NativeBridge.nativeSendGamepadButton(handle, bit, false, slot.index)
             }
             slot.held = slot.held and bit.inv()
@@ -167,6 +208,61 @@ class GamepadRouter(
         }
     }
 
+    /** Start a pending Select's hold countdown ([GUIDE_HOLD_MS] → a synthetic guide, down until release). */
+    private fun armGuide(slot: Slot) {
+        val r = Runnable {
+            slot.pendingGuide = null
+            slot.selectAsGuide = true
+            if (forwarding) {
+                NativeBridge.nativeSendGamepadButton(handle, Gamepad.BTN_GUIDE, true, slot.index)
+            }
+        }
+        slot.pendingGuide = r
+        mainHandler.postDelayed(r, GUIDE_HOLD_MS)
+    }
+
+    /**
+     * A second button joined while Select was pending — it was a real Select after all; its
+     * deferred down goes out before the caller sends the new button's, preserving chronology.
+     */
+    private fun flushPendingSelect(slot: Slot) {
+        val r = slot.pendingGuide ?: return
+        mainHandler.removeCallbacks(r)
+        slot.pendingGuide = null
+        if (forwarding) {
+            NativeBridge.nativeSendGamepadButton(handle, Gamepad.BTN_BACK, true, slot.index)
+        }
+    }
+
+    /**
+     * Select released with gesture state outstanding — true when the gesture owned the
+     * release. A transformed hold lifts the synthetic guide; a pending tap delivers its
+     * held-back press now, with the release [TAP_PRESS_MS] behind it (a back-to-back pair
+     * can fold into nothing in the host's per-pad input fold).
+     */
+    private fun consumeSelectRelease(slot: Slot): Boolean {
+        if (slot.selectAsGuide) {
+            slot.selectAsGuide = false
+            if (forwarding) {
+                NativeBridge.nativeSendGamepadButton(handle, Gamepad.BTN_GUIDE, false, slot.index)
+            }
+            return true
+        }
+        val r = slot.pendingGuide ?: return false
+        mainHandler.removeCallbacks(r)
+        slot.pendingGuide = null
+        if (forwarding) {
+            NativeBridge.nativeSendGamepadButton(handle, Gamepad.BTN_BACK, true, slot.index)
+            val up = Runnable {
+                slot.pendingTapUp = null
+                NativeBridge.nativeSendGamepadButton(handle, Gamepad.BTN_BACK, false, slot.index)
+            }
+            slot.pendingTapUp = up
+            mainHandler.postDelayed(up, TAP_PRESS_MS)
+        }
+        return true
+    }
+
     /** Arm the exit-chord hold timer (once); on expiry, if the chord is still held, flush + leave. */
     private fun armExit() {
         if (pendingExit != null) return // already counting down
@@ -362,6 +458,24 @@ class GamepadRouter(
 
     /** Lift every held button + zero the axes/HAT dpad for [slot] (wire events only, all on its index). */
     private fun releaseHeld(slot: Slot) {
+        // Gesture first: a pending (never-sent) Select just drops its timer; an owed tap
+        // release goes out NOW (its down is already on the wire and the handle may not
+        // outlive this slot); a transformed guide — which is not in `held` — is lifted.
+        slot.pendingGuide?.let { mainHandler.removeCallbacks(it) }
+        slot.pendingGuide = null
+        slot.pendingTapUp?.let {
+            mainHandler.removeCallbacks(it)
+            slot.pendingTapUp = null
+            if (forwarding) {
+                NativeBridge.nativeSendGamepadButton(handle, Gamepad.BTN_BACK, false, slot.index)
+            }
+        }
+        if (slot.selectAsGuide) {
+            slot.selectAsGuide = false
+            if (forwarding) {
+                NativeBridge.nativeSendGamepadButton(handle, Gamepad.BTN_GUIDE, false, slot.index)
+            }
+        }
         var bits = slot.held
         while (bits != 0) {
             val bit = bits and -bits // lowest set bit
@@ -403,5 +517,14 @@ class GamepadRouter(
 
         /** Synthetic slot-key base for [ExternalPad]s — below every real (positive) InputDevice id. */
         const val EXTERNAL_ID_BASE = -1000
+
+        /** pf-client-core's `GUIDE_HOLD`: hold Select alone this long → the host's guide goes down. */
+        const val GUIDE_HOLD_MS = 350L
+
+        /**
+         * pf-client-core's `TAP_PRESS`: a held-back Select tap's release trails its press by
+         * this much, so the pair can't coalesce into no press at all.
+         */
+        const val TAP_PRESS_MS = 50L
     }
 }

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

@@ -14,8 +14,8 @@ import android.hardware.usb.UsbRequest
 import android.os.Build
 import android.util.Log
 import java.nio.ByteBuffer
-import java.util.concurrent.ConcurrentLinkedQueue
 import java.util.concurrent.TimeoutException
+import java.util.concurrent.atomic.AtomicBoolean
 
 /**
  * Generic USB transport for a client-captured HID controller — the device-agnostic half of what
@@ -81,17 +81,57 @@ class HidUsbLink(
 
     /** Pending OUT reports, submitted by the reader thread — only one thread may drive a
      *  connection's [UsbRequest]s ([UsbDeviceConnection.requestWait] returns ANY completed
-     *  request; a second waiter would steal the reader's completions). */
-    private val outQueue = ConcurrentLinkedQueue<ByteArray>()
+     *  request; a second waiter would steal the reader's completions). See [OutReportQueue] for
+     *  what gets discarded when it fills, and why that is not simply "the oldest". */
+    private val outQueue = OutReportQueue()
 
     private var reader: Thread? = null
     private var detachReceiver: BroadcastReceiver? = null
 
     @Volatile private var running = false
 
+    /** Latches on the first "this link is down" signal so [onClosed] fires exactly once, however
+     *  many of the racing detectors (detach broadcast, reader error streak, failed re-queue) see
+     *  it. Reset by [start]. */
+    private val down = AtomicBoolean(false)
+
     /** First attached matching device, or null. Does not need USB permission to enumerate. */
     fun findDevice(): UsbDevice? = usb.deviceList.values.firstOrNull(config.deviceMatch)
 
+    /**
+     * Open a SECOND connection to the same device, for a consumer that needs its own descriptor.
+     *
+     * **Not a convenience — a correctness requirement.** `UsbDeviceConnection.requestWait()`
+     * returns *any* completed request on that connection, and the same is true of the usbfs reap
+     * ioctl underneath it: two independent transfer engines sharing one descriptor steal each
+     * other's completions. This link's reader owns its connection exclusively (see the note on
+     * [outQueue]), so anything else driving transfers on this device — the isochronous audio
+     * renderer — must open its own.
+     *
+     * usbfs allows the same device to be opened many times, and claims are per (descriptor,
+     * interface), so a claim made on this connection does not conflict with one made on that.
+     *
+     * The caller owns the returned connection and must close it.
+     */
+    fun openAuxConnection(): UsbDeviceConnection? {
+        val dev = device ?: return null
+        return usb.openDevice(dev)
+    }
+
+    /**
+     * The open connection's usbfs file descriptor, or -1 when the link is not running.
+     *
+     * Handed to native code that drives interfaces this link deliberately does NOT claim — the
+     * pad's isochronous audio endpoint (see `pad_audio` on the native side), which Android's own
+     * USB API cannot reach because `UsbRequest` rejects anything that is not bulk or interrupt.
+     * usbfs claims are per interface, so a native claim of the audio interface leaves this link's
+     * HID claim untouched.
+     *
+     * **The borrower must stop using it before [stop] runs**: closing the connection while a
+     * transfer is in flight pulls the descriptor out from under the kernel.
+     */
+    val fileDescriptor: Int get() = connection?.fileDescriptor ?: -1
+
     /**
      * Claim [dev]'s controller interface(s) and start the read loop. The caller has already
      * obtained USB permission. Returns false when nothing could be claimed.
@@ -114,6 +154,7 @@ class HidUsbLink(
         connection = conn
         device = dev
         claims = claimed
+        down.set(false)
         running = true
         Log.i(
             config.tag,
@@ -134,10 +175,7 @@ class HidUsbLink(
                 val gone: UsbDevice? = intent.getParcelableExtra(UsbManager.EXTRA_DEVICE)
                 if (gone?.deviceName == dev.deviceName) {
                     Log.i(config.tag, "USB detached (${dev.deviceName})")
-                    if (running) {
-                        running = false
-                        onClosed()
-                    }
+                    linkDown()
                 }
             }
         }
@@ -221,6 +259,9 @@ class HidUsbLink(
         if (live.isEmpty()) {
             Log.e(config.tag, "no IN request could be queued")
             finishReader(claims)
+            // `start` already returned true, so without this the owner would sit waiting on a
+            // capture that never streams and never reports itself dead.
+            linkDown()
             return
         }
         val scratch = ByteArray(64)
@@ -295,10 +336,23 @@ class HidUsbLink(
         } finally {
             finishReader(claims)
         }
-        if (running) {
-            running = false
-            onClosed()
-        }
+        linkDown()
+    }
+
+    /**
+     * Report the link down, exactly once, from whichever detector noticed first — the detach
+     * broadcast (main thread) or the reader thread on its way out.
+     *
+     * This only *signals*; releasing the connection and the interfaces stays the owner's job, via
+     * the [stop] its `onClosed` handler calls. Previously nothing released them on this path: the
+     * detach receiver flipped a flag and fired the callback, so an unplug left the connection open,
+     * the interfaces claimed (the pad could not return to Android's own input stack) and the
+     * receiver still registered — and a re-plug overwrote the field holding it, leaking a receiver
+     * that stayed live for the process's lifetime.
+     */
+    private fun linkDown() {
+        running = false
+        if (down.compareAndSet(false, true)) onClosed()
     }
 
     private fun finishReader(claims: List<Claim>) {
@@ -314,28 +368,35 @@ class HidUsbLink(
      * Write one raw report to the device: kind 0 = output report (the active interface's
      * interrupt-OUT, else a `SET_REPORT(Output)` control transfer), kind 1 = feature report
      * (`SET_REPORT(Feature)`). [data] is the full report, id byte first, hidapi framing.
+     *
+     * [coalesce] tells the pending-OUT queue whether a newer report of the same kind may replace
+     * this one — [OutReportQueue.KEY_RUMBLE] for motor levels, the default [OutReportQueue.NO_COALESCE]
+     * for one-shots (lightbar, player LEDs, trigger effects) the sender will not repeat.
+     *
+     * Returns whether the report reached the device or is queued for it. A caller that is writing
+     * a **stop** needs this: a discarded stop has nothing behind it, so it must not be mistaken
+     * for one that landed.
      */
-    fun writeRaw(kind: Int, data: ByteArray) {
-        if (data.isEmpty()) return
-        when (kind) {
+    fun writeRaw(kind: Int, data: ByteArray, coalesce: Int = OutReportQueue.NO_COALESCE): Boolean {
+        if (data.isEmpty()) return false
+        return when (kind) {
             0 -> {
                 if ((activeClaim ?: claims.firstOrNull())?.outReq != null) {
-                    // Interrupt-OUT rides UsbRequests submitted by the reader thread. Bounded,
-                    // newest-wins: these are level-styled commands the sender re-sends anyway.
-                    while (outQueue.size >= 32) outQueue.poll()
-                    outQueue.offer(data)
+                    // Interrupt-OUT rides UsbRequests submitted by the reader thread.
+                    outQueue.offer(data, coalesce)
                 } else {
                     setReport(REPORT_TYPE_OUTPUT, data)
                 }
             }
             1 -> setReport(REPORT_TYPE_FEATURE, data)
+            else -> false
         }
     }
 
-    private fun setReport(type: Int, data: ByteArray) {
-        val conn = connection ?: return
-        val ifId = (activeClaim ?: claims.firstOrNull())?.iface?.id ?: return
-        sendReport(conn, ifId, type, data)
+    private fun setReport(type: Int, data: ByteArray): Boolean {
+        val conn = connection ?: return false
+        val ifId = (activeClaim ?: claims.firstOrNull())?.iface?.id ?: return false
+        return sendReport(conn, ifId, type, data)
     }
 
     /**
@@ -344,9 +405,8 @@ class HidUsbLink(
      * queue would never drain (e.g. a rumble stop before the interfaces release). Safe from any
      * thread: EP0 control transfers are independent of the reader's `requestWait`.
      */
-    fun writeControl(data: ByteArray) {
-        if (data.isNotEmpty()) setReport(REPORT_TYPE_OUTPUT, data)
-    }
+    fun writeControl(data: ByteArray): Boolean =
+        data.isNotEmpty() && setReport(REPORT_TYPE_OUTPUT, data)
 
     private fun sendKeepAlive(conn: UsbDeviceConnection, ifaceId: Int) {
         for (f in config.keepAliveFeatures) sendReport(conn, ifaceId, REPORT_TYPE_FEATURE, f)
@@ -358,27 +418,48 @@ class HidUsbLink(
      * "unnumbered" (id 0 in wValue, id byte stripped from the payload). EP0 is independent of
      * the interrupt endpoints, so this is safe alongside the reader thread's requestWait.
      */
-    private fun sendReport(conn: UsbDeviceConnection, ifaceId: Int, type: Int, data: ByteArray) {
+    private fun sendReport(
+        conn: UsbDeviceConnection,
+        ifaceId: Int,
+        type: Int,
+        data: ByteArray,
+    ): Boolean {
         val id = data[0].toInt() and 0xFF
         val payload = if (id == 0) data.copyOfRange(1, data.size) else data
-        conn.controlTransfer(
-            0x21, // host→device, class, interface
-            0x09, // SET_REPORT
-            (type shl 8) or id,
-            ifaceId,
-            payload,
-            payload.size,
-            WRITE_TIMEOUT_MS,
-        )
+        // controlTransfer returns the byte count, or a negative value on failure — a failed write
+        // must be reported as such, not swallowed (a dropped rumble stop has nothing behind it).
+        val n = runCatching {
+            conn.controlTransfer(
+                0x21, // host→device, class, interface
+                0x09, // SET_REPORT
+                (type shl 8) or id,
+                ifaceId,
+                payload,
+                payload.size,
+                WRITE_TIMEOUT_MS,
+            )
+        }.getOrDefault(-1)
+        return n >= 0
     }
 
-    /** Stop the read loop and release the interfaces. Idempotent; does not fire [onClosed]. */
+    /**
+     * Stop the read loop and release the interfaces. Idempotent; does not fire [onClosed].
+     *
+     * Safe to call from the `onClosed` handler itself — that is how an unplug now gets cleaned up,
+     * and it arrives on the reader thread, which must not try to join itself.
+     */
     fun stop() {
         running = false
+        // Claim the down-latch so the reader's own exit does not report a close the owner asked for.
+        down.set(true)
         detachReceiver?.let { runCatching { context.unregisterReceiver(it) } }
         detachReceiver = null
-        runCatching { reader?.join(1000) }
-        reader = null
+        if (reader !== Thread.currentThread()) {
+            runCatching { reader?.join(1000) }
+            // Only forget the thread once it is actually gone: clearing it while it still runs
+            // would let a later stop() skip the join and free the connection under it.
+            reader = null
+        }
         outQueue.clear()
         activeClaim = null
         for (c in claims) runCatching { connection?.releaseInterface(c.iface) }

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

@@ -69,6 +69,10 @@ object NativeBridge {
          *  list and trust store show for it, same convention as [nativePair]'s `name`. `null`/blank ⇒
          *  the host falls back to a fingerprint-derived "device abcd1234" label. */
         deviceName: String?,
+        /** Advertise `CLIENT_CAP_PAD_AUDIO` — the SESSION-level negotiation for the 0xD1 per-pad
+         *  DualSense plane. Without it the host never sets `HOST_CAP_PAD_AUDIO` and emits nothing,
+         *  so a captured pad's own render capabilities would have nothing to gate. */
+        padAudioOk: Boolean,
     ): Long
 
     /** 64-hex SHA-256 of the cert the host presented on [handle]; valid after a successful connect. */
@@ -83,6 +87,18 @@ object NativeBridge {
      */
     external fun nativeSessionEnded(handle: Long): Boolean
 
+    /**
+     * WHY the session ended, as a [SessionEndReason] ordinal — decode with
+     * [SessionEndReason.fromNative]. `0` (NONE) before it ends, or on a `0` handle.
+     *
+     * The companion to [nativeSessionEnded], which only says THAT it ended. Both are needed: the
+     * flag to leave a dead stream, this to decide what to tell the user. A player quitting their
+     * game and a host falling off the network both end the session, and with no way to separate
+     * them the watchdog said "the host may be asleep" for all of them — wrong for every deliberate
+     * ending. Cheap (one atomic load); UI-safe.
+     */
+    external fun nativeEndReason(handle: Long): Int
+
     /**
      * Run the SPAKE2 PIN ceremony, presenting [certPem]/[keyPem]. Returns the host's verified
      * fingerprint (64-hex) to persist + pin, or `""` on failure (wrong PIN / MITM / unreachable).
@@ -332,6 +348,46 @@ object NativeBridge {
      */
     external fun nativeSetMicMuted(handle: Long, muted: Boolean)
 
+    /**
+     * Start tier-A DualSense pad audio: render the host's `0xD1` streams on the pad's own
+     * 4-channel USB audio device.
+     *
+     * [fd] is an open [android.hardware.usb.UsbDeviceConnection]'s file descriptor. Native code
+     * **borrows** it — it claims the pad's audio interface through usbfs (which leaves any HID
+     * claim on the same device alone) and never closes the descriptor. The caller must keep the
+     * connection open until [nativeStopPadAudio] returns.
+     *
+     * This also declares the pad's render capability to the host; without it no `0xD1` is sent.
+     *
+     * Returns false when there is nothing to render. A kernel that refuses the interface claim is
+     * NOT reported here — the renderer discovers that on its own thread and the session simply
+     * carries on without tier A, because some OEM kernels refuse and no app-side fix exists.
+     */
+    external fun nativeStartPadAudio(
+        handle: Long,
+        pad: Int,
+        fd: Int,
+        haptics: Boolean,
+        speaker: Boolean,
+    ): Boolean
+
+    /**
+     * Stop tier-A pad audio and join its render thread, and hand the pad back to wire rumble.
+     *
+     * Returns only once the thread is joined — so the `UsbDeviceConnection` may be closed as soon
+     * as this returns, and not before.
+     */
+    external fun nativeStopPadAudio(handle: Long, pad: Int)
+
+    /**
+     * Drive the pad with a test tone through the real render path — no host, no session.
+     *
+     * [fd] must come from a connection **nothing else is driving transfers on**: two engines on
+     * one usbfs descriptor reap each other's completions. Blocks for roughly [seconds]; run it off
+     * the main thread. Returns sample frames written, or negative on failure.
+     */
+    external fun nativePadAudioSelfTest(fd: Int, seconds: Int, hz: Int): Int
+
     /**
      * Is a mic capture actually RUNNING — i.e. did [nativeStartMic] open a stream, and has
      * [nativeStopMic] not been called since? Offer the in-stream mute control on THIS rather than

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

@@ -0,0 +1,89 @@
+package io.unom.punktfunk.kit
+
+/**
+ * The pending interrupt-OUT reports for a captured controller: a bounded FIFO whose overflow
+ * policy knows which reports may be thrown away and which may not.
+ *
+ * The queue exists because only one thread may drive a connection's `UsbRequest`s, so writes from
+ * the feedback threads are handed to the reader thread rather than submitted directly. It has to
+ * be bounded — a stalled or unplugged device would otherwise grow it without limit — and the
+ * question is what to discard when it fills.
+ *
+ * The old policy was "newest wins": drop from the head until there is room. That is right for
+ * rumble, which is *level-styled* — the host re-sends it continuously, so a dropped frame is
+ * replaced milliseconds later and nothing is permanently lost. It is wrong for everything else.
+ * A lightbar colour, a player-LED mask and an adaptive-trigger effect are **one-shots**: the host
+ * sends them on change and never repeats them. Dropping one leaves the pad wrong until the next
+ * time that value happens to change, which may be never.
+ *
+ * So eviction is driven by an explicit [key] supplied by the caller, not by inspecting the bytes.
+ * That distinction cannot be recovered from the report itself: every DualSense output report
+ * carries the *same* report id and differs only in its `valid_flag` bytes, so an id-keyed policy
+ * would happily let a rumble supersede a lightbar — the very bug this replaces, relocated.
+ *
+ * Two rules:
+ *  - A report offered with a coalescing key **replaces** the pending report with that key, in
+ *    place. A burst of rumble collapses to its latest value and never displaces anything else.
+ *  - Only when the queue is full does anything get dropped, and then the oldest *coalescable*
+ *    report goes first. A one-shot is discarded only if the queue is full of nothing but
+ *    one-shots — which needs [cap] distinct one-shots outstanding, far beyond what a real pad
+ *    produces.
+ *
+ * Thread-safe: offered by the feedback threads, drained by the reader thread.
+ */
+internal class OutReportQueue(private val cap: Int = CAP) {
+    private class Entry(val key: Int, val data: ByteArray)
+
+    private val items = ArrayDeque<Entry>()
+
+    /**
+     * Queue [data] for submission. [key] is [NO_COALESCE] for a one-shot, or a caller-chosen
+     * constant identifying a level-styled stream whose newer values supersede older ones.
+     *
+     * Returns false only if the report had to be dropped outright — the caller can then treat the
+     * write as failed rather than assuming it is on its way.
+     */
+    fun offer(data: ByteArray, key: Int = NO_COALESCE): Boolean = synchronized(items) {
+        if (key != NO_COALESCE) {
+            val at = items.indexOfFirst { it.key == key }
+            if (at >= 0) {
+                // Supersede in place: keeping the queue position stops a fast rumble stream from
+                // repeatedly jumping the one-shots queued ahead of it.
+                items[at] = Entry(key, data)
+                return true
+            }
+        }
+        if (items.size >= cap) {
+            val victim = items.indexOfFirst { it.key != NO_COALESCE }
+            if (victim >= 0) {
+                items.removeAt(victim)
+            } else if (key != NO_COALESCE) {
+                // Nothing coalescable to sacrifice and this report is itself replaceable — drop it
+                // rather than a one-shot that will never come again.
+                return false
+            } else {
+                items.removeFirst()
+            }
+        }
+        items.addLast(Entry(key, data))
+        return true
+    }
+
+    /** The next report to submit, or null when nothing is pending. */
+    fun poll(): ByteArray? = synchronized(items) { items.removeFirstOrNull()?.data }
+
+    fun clear() = synchronized(items) { items.clear() }
+
+    val size: Int get() = synchronized(items) { items.size }
+
+    companion object {
+        /** This report is a one-shot: never superseded, evicted only as a last resort. */
+        const val NO_COALESCE = 0
+
+        /** Motor levels — re-sent continuously, so only the newest is worth keeping. */
+        const val KEY_RUMBLE = 1
+
+        /** Deep enough to absorb a burst, small enough that a stalled device cannot bloat us. */
+        const val CAP = 32
+    }
+}

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

@@ -0,0 +1,47 @@
+package io.unom.punktfunk.kit
+
+/**
+ * The two conversions every rumble path in this module needs, in one place.
+ *
+ * Both used to be transcribed per call site: [wireAmplitudeToByte] existed twice, byte-identical,
+ * in `GamepadFeedback` and `DsDevice`; [unpackRumbleEvent] was inline bit-shifting in the poll loop
+ * with no test on either side of the JNI boundary. Neither is complicated — which is exactly why a
+ * silent divergence between copies would have been hard to notice.
+ */
+
+/**
+ * Wire amplitude (`0..0xFFFF`) → an 8-bit motor/vibrator level.
+ *
+ * The high byte, except that a **nonzero command never collapses to zero**: anything below 0x0100
+ * would otherwise round to silence, turning a weak-but-real rumble into no rumble at all. 1 is
+ * imperceptibly light, but it moves.
+ */
+internal fun wireAmplitudeToByte(v16: Int): Int {
+    val a = (v16 ushr 8) and 0xFF
+    return if (v16 != 0 && a == 0) 1 else a
+}
+
+/** One effective rumble command, as packed by the native side's `nativeNextRumble`. */
+internal data class RumbleCmd(val pad: Int, val low: Int, val high: Int, val backstopMs: Long)
+
+/**
+ * Unpack `NativeBridge.nativeNextRumble`'s `jlong`, or null for the timeout/closed sentinel.
+ *
+ * Layout, mirroring `clients/android/native/src/feedback.rs::pack_rumble`:
+ * bits 49..52 = wire pad index, 32..47 = backstop duration (ms), 16..31 = low, 0..15 = high.
+ * The pad field is 4 bits because `punktfunk_core::input::MAX_PADS` is 16 — the Rust side has a
+ * compile-time assertion tying the two together, so this can't silently start truncating.
+ *
+ * These are EFFECTIVE commands from the core's shared rumble policy engine: it owns every
+ * lease/staleness/close decision and emits explicit zeros, so apply them verbatim —
+ * `(0, 0)` = cancel, non-zero = one-shot for the backstop.
+ */
+internal fun unpackRumbleEvent(ev: Long): RumbleCmd? {
+    if (ev < 0L) return null // timeout / closed
+    return RumbleCmd(
+        pad = ((ev ushr 49) and 0xFL).toInt(),
+        low = ((ev ushr 16) and 0xFFFF).toInt(),
+        high = (ev and 0xFFFF).toInt(),
+        backstopMs = (ev ushr 32) and 0xFFFF,
+    )
+}

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

@@ -273,10 +273,20 @@ class Sc2Capture(
 
     private fun onLinkClosed() {
         Log.i(TAG, "SC2 link closed (unplug / power-off)")
+        // Both transports share this callback, so read which one was live BEFORE clearing it —
+        // releasing the other would tear down a link that never dropped.
+        val dropped = activeLink
         activeLink = LINK_NONE
         dongleLink = false
         releaseSlot()
         releaseUiKeys()
+        // Release the transport too — see the note in DsCapture.onLinkClosed. The Puck makes this
+        // worse than a single leak: it is the pad that gets power-cycled, so the same process can
+        // round-trip a link many times in one session.
+        when (dropped) {
+            LINK_USB -> usb.stop()
+            LINK_BLE -> ble.stop()
+        }
         onActiveChanged?.invoke(false)
     }
 

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

@@ -0,0 +1,56 @@
+package io.unom.punktfunk.kit
+
+/**
+ * Why a stream session ended — the Kotlin mirror of `punktfunk_core::client::PunktfunkEndReason`,
+ * read via [NativeBridge.nativeEndReason].
+ *
+ * The distinction that matters to a UI is **normal vs alarming**, and it is not a spectrum: a
+ * player quitting their game and a host falling off the network both arrive as "the session
+ * ended". With no way to tell them apart this client showed one message for all of them — and it
+ * was the alarming one ("Connection lost — the host may be asleep"), in front of players who had
+ * just quit their own game.
+ *
+ * Ordinals are an ABI contract with the Rust side: append only, never renumber.
+ */
+enum class SessionEndReason {
+    /** Not ended, or ended before a reason could be observed. Also the fallback for an unknown value. */
+    NONE,
+
+    /** This client closed the session — the user pressed back or stop. Nothing to report. */
+    LOCAL,
+
+    /**
+     * The host's launched game exited. A normal finish, and the one reason worth acting on: go back
+     * to the library the title was launched from, so the next one is a tap away.
+     */
+    GAME_EXITED,
+
+    /** The host ended the session deliberately (an operator "End", or it simply finished). Normal. */
+    HOST_ENDED,
+
+    /** The host closed reporting a failure of its own. Worth showing; the host's log has the detail. */
+    HOST_ERROR,
+
+    /**
+     * The connection died rather than being closed: idle timeout, reset, the network going away.
+     * This — and only this — is the "the host may be asleep, wake it" case.
+     */
+    LOST;
+
+    /**
+     * Is this an ordinary outcome rather than something to alarm the user about?
+     *
+     * The question nearly every caller actually asks. [LOCAL], [GAME_EXITED] and [HOST_ENDED] were
+     * all meant to happen. [NONE] counts as normal — no evidence of trouble is not evidence of it.
+     */
+    val isNormal: Boolean
+        get() = this != HOST_ERROR && this != LOST
+
+    companion object {
+        /**
+         * Decode the JNI byte. An unrecognized value becomes [NONE] rather than throwing: this
+         * crosses an ABI where the native side may be newer than this code.
+         */
+        fun fromNative(v: Int): SessionEndReason = entries.getOrNull(v) ?: NONE
+    }
+}

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

@@ -132,6 +132,27 @@ class HostDiscovery(context: Context) {
         handler.post(poll)
     }
 
+    /**
+     * Tear the browse down and start a fresh one. This is the manual rescan, and the recovery path
+     * for a browse that started while blocked (permission not yet granted, multicast filtered) or
+     * that never started at all ([start] gives up when `nativeDiscoveryStart` returns 0, and
+     * nothing else would ever retry it).
+     *
+     * It also puts a query back on the wire: `mdns-sd` re-queries on a doubling backoff that caps
+     * at an hour, so a long-lived browse is effectively passive — a host that appeared since, or
+     * whose announcement was lost to multicast, may never be asked for again.
+     *
+     * The currently-shown host set is left alone across the swap (rather than blinking empty via
+     * [stop]'s notification); the first poll of the new browse publishes the fresh set.
+     */
+    fun restart() {
+        val keep = onChange
+        onChange = null
+        stop()
+        onChange = keep
+        start()
+    }
+
     fun stop() {
         if (!running && nativeHandle == 0L) return
         running = false

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

@@ -37,9 +37,51 @@ data class Artwork(val portrait: String?, val header: String?, val hero: String?
     val posterCandidates: List<String> get() = listOfNotNull(portrait, header, hero)
 }
 
-/** One title in the unified library. [id] is store-qualified (`steam:<appid>` / `custom:<id>`). */
-data class GameEntry(val id: String, val store: String, val title: String, val art: Artwork) {
+/**
+ * One title in the unified library. [id] is store-qualified (`steam:<appid>` / `custom:<id>`).
+ *
+ * [role] is `"game"` (the default, and what an older host omits) or `"launcher"` — an entry that
+ * opens the launcher itself (Steam Big Picture, Heroic) rather than a title. Kept a plain nullable
+ * String on purpose: the host owns the vocabulary, and an unknown future value must degrade to a
+ * game rather than break the decode (design D4).
+ */
+data class GameEntry(
+    val id: String,
+    val store: String,
+    val title: String,
+    val art: Artwork,
+    val role: String? = null,
+) {
     val isCustom: Boolean get() = store == "custom"
+
+    /** Whether this entry opens a launcher rather than a game. */
+    val isLauncher: Boolean get() = role == "launcher"
+
+    /**
+     * Display name for the store badge — the same table the other clients use
+     * (`pf-console-ui::library::store_label`). Before this the UI said "Steam" for every non-custom
+     * entry, which a Lutris or GOG title made a lie.
+     */
+    val storeLabel: String get() = when (store) {
+        "steam" -> "Steam"
+        "custom" -> "Custom"
+        "heroic" -> "Heroic"
+        "lutris" -> "Lutris"
+        "epic" -> "Epic"
+        "gog" -> "GOG"
+        "xbox" -> "Xbox"
+        else -> "Game"
+    }
+}
+
+/**
+ * Design D4: launcher entries lead the shelf, keeping the host's title order within each group.
+ * Applied once where the library is fetched, so no screen has to remember the rule — and a library
+ * without launcher entries comes back untouched.
+ */
+fun List<GameEntry>.launchersFirst(): List<GameEntry> {
+    val launchers = filter { it.isLauncher }
+    return if (launchers.isEmpty()) this else launchers + filterNot { it.isLauncher }
 }
 
 /** Fetch outcome — three states so the UI can guide setup (the common case is "not paired yet"). */
@@ -108,10 +150,11 @@ object LibraryClient {
                         header = resolveArt(str(art, "header"), base),
                         hero = resolveArt(str(art, "hero"), base),
                     ),
+                    role = str(o, "role"),
                 ),
             )
         }
-        return out
+        return out.launchersFirst()
     }
 
     /** A present, non-null, non-blank JSON string field, else null. */
@@ -127,8 +170,14 @@ object LibraryClient {
  * An OkHttpClient that presents the paired client cert and pins the host's self-signed cert by
  * SHA-256(DER) — reused for BOTH the library fetch and the cover-art loads (so a paired client
  * reaches the host's own art proxy). The pinning trust manager trusts the host by fingerprint and
- * defers to normal public trust for any other origin (an external CDN URL); the hostname verifier
- * accepts the pinned host (whose self-signed cert has no matching SAN) and defers otherwise.
+ * defers to normal public trust for any other origin (an external CDN URL).
+ *
+ * The two checks are only sound TOGETHER, and the composition is the point: the trust manager
+ * cannot fail closed on its own (it has no hostname, so it must let a CDN chain through), so the
+ * hostname verifier is what makes the pinned host pin-only. Loosen either and a publicly-trusted
+ * certificate for any name is accepted for the host — which is exactly what 2026-08-05 review M-2
+ * found. The host's own cert is self-signed with no matching SAN, so it can never satisfy the
+ * default verifier; the pin is its only credential, on purpose.
  */
 fun mtlsHttpClient(certPem: String, keyPem: String, host: String, fpHex: String): OkHttpClient {
     val clientCert = CertificateFactory.getInstance("X.509")
@@ -162,7 +211,26 @@ fun mtlsHttpClient(certPem: String, keyPem: String, host: String, fpHex: String)
 
     val defaultVerifier = HttpsURLConnection.getDefaultHostnameVerifier()
     val verifier = HostnameVerifier { hostname, session ->
-        hostname == host || defaultVerifier.verify(hostname, session)
+        if (hostname == host) {
+            // The PINNED host fails closed: only the pinned leaf is acceptable for this name.
+            //
+            // This used to be a bare `hostname == host`, which composed with the trust manager's
+            // system-CA fall-through into "any publicly-trusted certificate, for any name, is
+            // accepted for the pinned host" — the pin was decorative (2026-08-05 review M-2). A
+            // MITM with any free CA-issued cert intercepted the connection, received the client's
+            // mTLS IDENTITY certificate, and served attacker-chosen library JSON and art URLs.
+            // The Rust (`pf-client-core`) and Apple (`ClientTLS`) paths already fail closed here;
+            // only Android did not.
+            try {
+                sha256Hex((session.peerCertificates.firstOrNull() as? X509Certificate)?.encoded ?: return@HostnameVerifier false) == pinned
+            } catch (_: Exception) {
+                false
+            }
+        } else {
+            // Any other origin (an external CDN art URL) is ordinary public trust: the system
+            // trust manager validated the chain, and this checks the name against it.
+            defaultVerifier.verify(hostname, session)
+        }
     }
 
     return OkHttpClient.Builder()

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

@@ -0,0 +1,102 @@
+package io.unom.punktfunk.kit
+
+import org.junit.Assert.assertArrayEquals
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertNull
+import org.junit.Assert.assertTrue
+import org.junit.Test
+
+/**
+ * The pending-OUT queue's overflow policy. What is being pinned here is the distinction the old
+ * "drop from the head until there is room" policy did not make: rumble is re-sent continuously and
+ * may be thrown away, while a lightbar/player-LED/trigger report is sent once and never repeated.
+ */
+class OutReportQueueTest {
+    /** A report carrying a 0..255 marker so a test can tell which one came back out. */
+    private fun report(marker: Int) = byteArrayOf(0x02, marker.toByte())
+
+    // Masked: the marker rides in a Byte, and Byte.toInt() sign-extends.
+    private fun drain(q: OutReportQueue): List<Int> =
+        generateSequence { q.poll() }.map { it[1].toInt() and 0xFF }.toList()
+
+    @Test
+    fun `rumble supersedes the pending rumble instead of queueing another`() {
+        val q = OutReportQueue()
+        assertTrue(q.offer(report(1), OutReportQueue.KEY_RUMBLE))
+        assertTrue(q.offer(report(2), OutReportQueue.KEY_RUMBLE))
+        assertTrue(q.offer(report(3), OutReportQueue.KEY_RUMBLE))
+        assertEquals("a rumble burst must collapse to one entry", 1, q.size)
+        assertArrayEquals(report(3), q.poll())
+        assertNull(q.poll())
+    }
+
+    @Test
+    fun `superseding keeps the queue position so a rumble stream cannot jump one-shots`() {
+        val q = OutReportQueue()
+        q.offer(report(1), OutReportQueue.KEY_RUMBLE)
+        q.offer(report(10)) // a one-shot queued behind it
+        q.offer(report(2), OutReportQueue.KEY_RUMBLE)
+        // The newer rumble takes the OLD rumble's slot, so the one-shot does not get starved
+        // behind an endlessly-renewed entry.
+        assertEquals(listOf(2, 10), drain(q))
+    }
+
+    @Test
+    fun `a full queue sacrifices rumble, never a one-shot`() {
+        val q = OutReportQueue(cap = 4)
+        q.offer(report(1), OutReportQueue.KEY_RUMBLE)
+        q.offer(report(10))
+        q.offer(report(11))
+        q.offer(report(12))
+        assertEquals(4, q.size)
+        // Full. The old policy dropped the head — here that is a rumble, but only by luck of
+        // ordering; what matters is that the one-shots all survive.
+        assertTrue(q.offer(report(13)))
+        assertEquals(listOf(10, 11, 12, 13), drain(q))
+    }
+
+    @Test
+    fun `the one-shot the host never repeats survives a rumble storm`() {
+        val q = OutReportQueue(cap = 4)
+        // The exact regression: a lightbar colour queued once, then a flood of rumble. Under the
+        // old newest-wins eviction the colour was dropped from the head and never came back,
+        // leaving the pad lit wrong until the value next happened to change.
+        q.offer(report(200)) // lightbar
+        repeat(50) { q.offer(report(it), OutReportQueue.KEY_RUMBLE) }
+        val out = drain(q)
+        assertTrue("the lightbar report must still be queued, got $out", out.contains(200))
+        assertEquals("rumble must not have accumulated", listOf(200, 49), out)
+    }
+
+    @Test
+    fun `a queue full of one-shots refuses a rumble rather than dropping one`() {
+        val q = OutReportQueue(cap = 2)
+        q.offer(report(10))
+        q.offer(report(11))
+        assertFalse(
+            "with nothing coalescable to sacrifice, the replaceable report yields",
+            q.offer(report(1), OutReportQueue.KEY_RUMBLE),
+        )
+        assertEquals(listOf(10, 11), drain(q))
+    }
+
+    @Test
+    fun `only a queue of nothing but one-shots drops one, and it is the oldest`() {
+        val q = OutReportQueue(cap = 2)
+        q.offer(report(10))
+        q.offer(report(11))
+        assertTrue(q.offer(report(12)))
+        assertEquals(listOf(11, 12), drain(q))
+    }
+
+    @Test
+    fun `clear empties the queue`() {
+        val q = OutReportQueue()
+        q.offer(report(1), OutReportQueue.KEY_RUMBLE)
+        q.offer(report(10))
+        q.clear()
+        assertEquals(0, q.size)
+        assertNull(q.poll())
+    }
+}

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

@@ -0,0 +1,79 @@
+package io.unom.punktfunk.kit
+
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertNotEquals
+import org.junit.Assert.assertNull
+import org.junit.Test
+
+/**
+ * The Kotlin half of the rumble JNI boundary. The Rust half is pinned by `pack_rumble_tests` in
+ * `clients/android/native/src/feedback.rs`; the two suites describe the same layout from opposite
+ * sides, which is the only thing that catches one of them drifting.
+ */
+class RumbleWireTest {
+
+    /** `pack_rumble` from the native side, transcribed — the packer these tests unpack. */
+    private fun pack(pad: Int, low: Int, high: Int, backstopMs: Int): Long =
+        ((pad and 0xF).toLong() shl 49) or
+            ((backstopMs.coerceAtMost(0xFFFF)).toLong() shl 32) or
+            (low.toLong() shl 16) or
+            high.toLong()
+
+    @Test
+    fun `every field round-trips at its extremes`() {
+        val cases = listOf(
+            listOf(0, 0, 0, 0),
+            listOf(15, 0xFFFF, 0xFFFF, 0xFFFF),
+            listOf(1, 0x1234, 0x5678, 500),
+            listOf(7, 0, 0xFFFF, 2000),
+        )
+        for ((pad, low, high, backstop) in cases) {
+            val cmd = unpackRumbleEvent(pack(pad, low, high, backstop))!!
+            assertEquals("pad", pad, cmd.pad)
+            assertEquals("low", low, cmd.low)
+            assertEquals("high", high, cmd.high)
+            assertEquals("backstop", backstop.toLong(), cmd.backstopMs)
+        }
+    }
+
+    /** MAX_PADS is 16, so all 16 indices must survive the 4-bit field without aliasing. */
+    @Test
+    fun `all sixteen pad indices are distinct`() {
+        val seen = (0 until 16).map { unpackRumbleEvent(pack(it, 1, 2, 3))!!.pad }
+        assertEquals((0 until 16).toList(), seen)
+    }
+
+    @Test
+    fun `the negative sentinel is not a command`() {
+        assertNull(unpackRumbleEvent(-1L))
+        assertNull(unpackRumbleEvent(Long.MIN_VALUE))
+    }
+
+    @Test
+    fun `a stop is distinguishable from a hold`() {
+        val stop = unpackRumbleEvent(pack(2, 0, 0, 0))!!
+        val hold = unpackRumbleEvent(pack(2, 0x8000, 0x8000, 500))!!
+        assertEquals(0, stop.low)
+        assertEquals(0, stop.high)
+        assertNotEquals(stop, hold)
+    }
+
+    // --- wireAmplitudeToByte (was two byte-identical private copies) ---
+
+    @Test
+    fun `amplitude takes the high byte`() {
+        assertEquals(0xFF, wireAmplitudeToByte(0xFFFF))
+        assertEquals(0x80, wireAmplitudeToByte(0x8000))
+        assertEquals(0x12, wireAmplitudeToByte(0x1234))
+    }
+
+    @Test
+    fun `zero stays silent but a weak nonzero never does`() {
+        assertEquals("only a real zero may render as silence", 0, wireAmplitudeToByte(0))
+        // Everything below 0x0100 has a zero high byte — without the floor these all vanish.
+        for (v in listOf(1, 0x0042, 0x00FF)) {
+            assertEquals("wire $v collapsed to silence", 1, wireAmplitudeToByte(v))
+        }
+        assertEquals(1, wireAmplitudeToByte(0x0100)) // first value that reaches 1 on its own
+    }
+}

clients/android/native/Cargo.toml

@@ -64,6 +64,14 @@ libc = "0.2"
 # host + Linux client use. audiopus_sys vendors libopus (pure C) and builds it static via cmake —
 # the cargo-ndk build sets LIBOPUS_STATIC=1/LIBOPUS_NO_PKG=1 so it links the bundled lib, not the host's.
 opus = "0.3"
+# Tier-A pad audio (WP9). Android's audio framework denylists the DualSense's output by VID/PID,
+# so the pad's isochronous endpoint is driven directly on the fd `UsbDeviceConnection` hands over.
+# Our own crates, developed openly because the hole they fill — isochronous USB in Rust — is an
+# ecosystem-wide one: https://github.com/unom-io/usbfs-iso
+# Pinned by revision rather than floating: this is a transport under a real-time deadline and it
+# should move when we choose to. Becomes a plain version dependency once the crates are published.
+uac-host = { git = "https://github.com/unom-io/usbfs-iso", rev = "f3de1fd62cec271d07f45664dc464f23e423e721" }
+usbfs-iso = { git = "https://github.com/unom-io/usbfs-iso", rev = "f3de1fd62cec271d07f45664dc464f23e423e721" }
 
 [lints]
 workspace = true

clients/android/native/src/audio.rs

@@ -12,10 +12,14 @@
 //! realtime callback and makes us own the buffer. So this client diverges deliberately to stop the
 //! Android-only crackle: (1) the callback is allocation/free-free — decoded buffers are recycled to
 //! the producer via a free-list instead of being freed on the audio thread (Android's Scudo `free`
-//! has unbounded tail latency); (2) the jitter ring is deeper (~40 ms prime / ~150 ms hard cap) and
-//! decoupled from the tiny LowLatency burst size, with de-prime hysteresis so a transient drain
-//! doesn't manufacture a silence; (3) the AAudio HW buffer is primed above its 2-burst default and
-//! grown on XRuns (Google's anti-glitch technique).
+//! has unbounded tail latency); (2) the jitter ring is deeper than the other clients' and decoupled
+//! from the tiny LowLatency burst size, with de-prime hysteresis so a transient drain doesn't
+//! manufacture a silence; (3) the AAudio HW buffer is primed above its 2-burst default and grown on
+//! XRuns (Google's anti-glitch technique).
+//!
+//! (2) is now the SHARED `punktfunk_core::audio::JitterPolicy` at `JitterTuning::AAUDIO`, which also
+//! fixed what this ring was missing: it had a hard cap but nothing that walked the depth back down,
+//! so drift and arrival bursts raised latency permanently and Android settled on its ceiling.
 
 use ndk::audio::{
     AudioCallbackResult, AudioContentType, AudioDirection, AudioFormat, AudioPerformanceMode,
@@ -34,26 +38,18 @@ const SAMPLE_RATE: i32 = 48_000;
 /// Decoded-chunk hand-off depth: 64 × 5 ms = 320 ms slack (matches the core's AUDIO_QUEUE).
 const RING_CHUNKS: usize = 64;
 
-// --- Jitter-ring depths, in MILLISECONDS (scaled to interleaved-f32 samples at runtime). --------
-// The channel count is negotiated, not a compile-time const, so these are kept in ms and multiplied
-// by `ms` (interleaved-f32 samples per millisecond at the resolved layout) inside `start`.
-// Unlike the Linux client (PipeWire adaptively rate-matches the stream to the graph clock, masking
-// host↔DAC drift + a shallow ring), AAudio hands us a raw callback and we own the buffer: drift and
-// WiFi power-save bunching land as underruns/overflows = crackle. So Android runs a deliberately
-// deeper, smoothly-managed ring than Linux — keep the two clients' depths intentionally divergent.
-/// Prime/target floor: fill to ~40 ms before playing (and after a sustained drain). Deep enough to
-/// ride out WiFi arrival jitter + clock drift; the dominant Android-only anti-crackle lever.
-const PRIME_FLOOR_MS: usize = 40;
-/// Ceiling for the burst-scaled target (so a large quantum can't push the prime depth too high).
-const PRIME_CEIL_MS: usize = 80;
-/// Drop-oldest headroom above the target before trimming — a ~80 ms band swallows an arrival burst
-/// without overflowing.
-const JITTER_HEADROOM_MS: usize = 80;
-/// Hard latency bound: never let the ring exceed ~150 ms (the only thing that caps added latency).
-const HARD_CAP_MS: usize = 150;
-/// Re-prime (go silent to refill) only after this many CONSECUTIVE empty callbacks, so one transient
-/// drain doesn't manufacture a fresh 40 ms silence (the old `if ring.is_empty()` re-primed instantly).
-const DEPRIME_AFTER_CALLBACKS: u32 = 5;
+// --- Jitter-ring depths now come from the SHARED policy (`punktfunk_core::audio::JitterTuning`). --
+// They used to be four Android-only constants here. The rationale for Android being DEEPER than the
+// other clients still holds and is preserved in `JitterTuning::AAUDIO`: unlike PipeWire, which
+// adaptively rate-matches the stream to the graph clock and masks host↔DAC drift, AAudio hands us a
+// raw callback and we own the buffer, so drift and Wi-Fi power-save bunching land as
+// underruns/overflows = crackle.
+//
+// Two things changed with the move. The prime floor drops 40 ms → 25 ms, because the policy GROWS
+// the target on the devices that actually underrun instead of every device pre-paying for the worst
+// one. And the ring finally sheds: it had a hard cap but nothing that walked the depth back down, so
+// any drift or burst raised latency permanently and Android converged on its 120 ms ceiling and
+// stayed there — the "audio latency is too high" report.
 /// Throttle the AAudio XRun-driven HW-buffer grow check (cheap, but no need to poll every quantum).
 const XRUN_CHECK_EVERY: u32 = 128;
 
@@ -104,6 +100,7 @@ struct Counters {
     pcm_written: AtomicU64,  // PCM frames copied out to AAudio (device clock is pulling)
     underruns: AtomicU64,    // callbacks that emitted silence (ring not primed / drained)
     ring_depth: AtomicU64,   // ring sample count at the last callback
+    target_ms: AtomicU64,    // the policy's LIVE target depth (it grows on this device's underruns)
 }
 
 /// Owned by [`crate::session::SessionHandle`]: the live AAudio stream + the decode thread.
@@ -126,10 +123,9 @@ impl AudioPlayback {
         // Interleaved f32 samples per millisecond at this layout (48 kHz × channels); the ms-
         // denominated jitter-ring depths scale by it.
         let ms = (SAMPLE_RATE as usize / 1000) * channels;
-        let prime_floor = PRIME_FLOOR_MS * ms;
-        let prime_ceil = PRIME_CEIL_MS * ms;
-        let jitter_headroom = JITTER_HEADROOM_MS * ms;
-        let hard_cap_max = HARD_CAP_MS * ms;
+        let tuning = punktfunk_core::audio::JitterTuning::AAUDIO;
+        // Worst transient the ring can hold before the policy trims it.
+        let hard_cap_max = tuning.hard_cap_ms as usize * ms;
         let counters = Arc::new(Counters::default());
 
         // One open attempt at a given sharing mode. Everything the realtime callback captures
@@ -157,8 +153,10 @@ impl AudioPlayback {
             // `decode_loop`.
             let mut ring: VecDeque<f32> =
                 VecDeque::with_capacity(hard_cap_max + RING_CHUNKS * 5 * ms);
-            let mut primed = false;
-            let mut empties: u32 = 0; // consecutive empty callbacks (de-prime hysteresis)
+            // Shared de-jitter policy — prime depth, drift correction, de-prime hysteresis. The
+            // hysteresis this replaces was Android-only; Linux and Windows carried the instant
+            // `if ring.is_empty()` re-prime until now.
+            let mut policy = punktfunk_core::audio::JitterPolicy::new(tuning, channels as u8);
             let mut cb_count: u32 = 0; // callbacks since open (throttles the XRun grow check)
             let mut last_xrun: i32 = 0; // last AAudio XRun count we grew the buffer for
             let callback = move |s: &AudioStream, data: *mut c_void, num_frames: i32| {
@@ -173,21 +171,25 @@ impl AudioPlayback {
                     ring.extend(chunk.drain(..));
                     let _ = free_tx.try_send(chunk);
                 }
-                // Jitter buffer: prime to ~40 ms (prime_floor) before playing and after a sustained
-                // drain; drop-oldest only above a wide ~120 ms band. Decoupled from the AAudio burst
-                // `want` (tiny on the LowLatency MMAP path) so the depth doesn't collapse to a single
-                // quantum.
-                let target = (3 * want).clamp(prime_floor, prime_ceil);
-                let hard_cap = (target + jitter_headroom).min(hard_cap_max);
-                while ring.len() > hard_cap {
-                    ring.pop_front();
+                // Jitter buffer: the shared policy decides prime/silence, trims a burst, and —
+                // new here — sheds ONE crossfaded 5 ms frame when the depth average has sat above
+                // target long enough to be drift rather than jitter. Without that shed this ring
+                // had no way back down: it clamped at 120 ms and stayed pinned there.
+                let step = policy.step(ring.len(), want);
+                if step.drop_front > 0 {
+                    punktfunk_core::audio::crossfade_drop(
+                        &mut ring,
+                        step.drop_front,
+                        step.crossfade,
+                    );
                 }
-                if !primed && ring.len() >= target {
-                    primed = true;
-                }
-                if primed {
+                let mut ran_short = false;
+                if !step.silence {
                     for slot in out.iter_mut() {
-                        *slot = ring.pop_front().unwrap_or(0.0);
+                        *slot = ring.pop_front().unwrap_or_else(|| {
+                            ran_short = true;
+                            0.0
+                        });
                     }
                     cb_counters
                         .pcm_written
@@ -196,20 +198,15 @@ impl AudioPlayback {
                     out.fill(0.0);
                     cb_counters.underruns.fetch_add(1, Ordering::Relaxed);
                 }
-                // Re-prime only after a RUN of empty callbacks, not a single transient one —
-                // otherwise every momentary drain costs a fresh 40 ms silence (the old behaviour,
-                // self-inflicted crackle on any jitter spike).
-                if ring.is_empty() {
-                    empties += 1;
-                    if empties >= DEPRIME_AFTER_CALLBACKS {
-                        primed = false;
-                    }
-                } else {
-                    empties = 0;
-                }
+                // No-op while un-primed, so a deliberate priming silence is never counted as an
+                // underrun (which would otherwise drive the adaptive floor up for no reason).
+                policy.note_read(ran_short);
                 cb_counters
                     .ring_depth
                     .store(ring.len() as u64, Ordering::Relaxed);
+                cb_counters
+                    .target_ms
+                    .store(policy.target_ms() as u64, Ordering::Relaxed);
                 // Google's AAudio anti-glitch technique: when the device reports new XRuns, grow the
                 // HW buffer by one burst (up to capacity). getXRunCount + setBufferSizeInFrames are
                 // both callback-safe / non-blocking, and set clamps to capacity so it self-limits.
@@ -408,10 +405,11 @@ fn decode_loop(
                         }
                         if count % 600 == 0 {
                             log::info!(
-                                "audio: opus={count} pcm_frames={} underruns={} ring={} peak={window_peak:.3}",
+                                "audio: opus={count} pcm_frames={} underruns={} buffer_ms={} target_ms={} peak={window_peak:.3}",
                                 counters.pcm_written.load(Ordering::Relaxed),
                                 counters.underruns.load(Ordering::Relaxed),
-                                counters.ring_depth.load(Ordering::Relaxed),
+                                counters.ring_depth.load(Ordering::Relaxed) / ms.max(1) as u64,
+                                counters.target_ms.load(Ordering::Relaxed),
                             );
                             window_peak = 0.0;
                         }

clients/android/native/src/feedback.rs

@@ -18,6 +18,29 @@ use std::time::Duration;
 /// observes its `running=false` flag promptly on teardown.
 const PULL_TIMEOUT: Duration = Duration::from_millis(100);
 
+/// Width of the packed `pad` field in [`pack_rumble`] — 4 bits, i.e. indices 0..15.
+const PAD_BITS: u32 = 4;
+/// The packing is only lossless while every representable pad index fits in [`PAD_BITS`]. This was
+/// a comment before; growing `MAX_PADS` past 16 would have silently aliased pad 16 onto pad 0
+/// rather than failing the build.
+const _: () = assert!(
+    punktfunk_core::input::MAX_PADS <= 1usize << PAD_BITS,
+    "MAX_PADS no longer fits the 4-bit pad field in the packed rumble long"
+);
+
+/// Pack one effective rumble command into the `jlong` `nativeNextRumble` returns.
+///
+/// Layout — mirrored by `unpackRumbleEvent` in `RumbleWire.kt`: bits 49..52 `pad`, 32..47
+/// `backstop_ms`, 16..31 `low`, 0..15 `high`. Always non-negative, so the `-1` timeout/closed
+/// sentinel stays unambiguous. Split out from the JNI entry point purely so it can be tested
+/// without a live session handle — the shift arithmetic is the part worth pinning.
+fn pack_rumble(pad: u16, low: u16, high: u16, backstop_ms: u32) -> jlong {
+    (jlong::from(pad & ((1 << PAD_BITS) - 1)) << 49)
+        | (jlong::from(backstop_ms.min(0xFFFF) as u16) << 32)
+        | (jlong::from(low) << 16)
+        | jlong::from(high)
+}
+
 // HID-output kind tags written into the returned ByteBuffer (Kotlin reads them back).
 const TAG_LED: u8 = 0x01;
 const TAG_PLAYER_LEDS: u8 = 0x02;
@@ -54,12 +77,15 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeNextRumble(
         // handle.
         let h = unsafe { &*(handle as *const SessionHandle) };
         match h.client.next_rumble_command(PULL_TIMEOUT) {
-            Ok(cmd) => {
-                (jlong::from(cmd.pad & 0xF) << 49)
-                    | (jlong::from(cmd.backstop_ms.min(0xFFFF) as u16) << 32)
-                    | (jlong::from(cmd.low) << 16)
-                    | jlong::from(cmd.high)
-            }
+            // A pad whose coils are ACTIVELY being driven by the 0xD1 haptics stream must not see
+            // wire rumble: `DsDevice` sets `valid_flag0` bit 1 (`HAPTICS_SELECT`) on every rumble
+            // write, and that bit disables the audio-haptics path — so one replayed command would
+            // mute the coils the stream is driving. Gating on *arrival of haptics frames* rather
+            // than on "a stream is open" is what keeps a rumble-only title working: it renders no
+            // haptics audio, so the host emits nothing on 0xD1 and the pad keeps its rumble.
+            // Dropping it here rather than in Kotlin keeps the rule next to the reason.
+            Ok(cmd) if crate::pad_audio::haptics_owns_coils((cmd.pad & 0xF) as u8) => -1,
+            Ok(cmd) => pack_rumble(cmd.pad, cmd.low, cmd.high, cmd.backstop_ms),
             Err(_) => -1, // NoFrame (timeout) or Closed — Kotlin loops on its running flag
         }
     })
@@ -156,7 +182,74 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeNextHidout(
                 out[3..n].copy_from_slice(&data);
                 n
             }
+            HidOutput::AudioCtl { .. } => {
+                // DS5 pad-audio routing/volumes — no Android replay path yet (the 0xD1 sample
+                // plane isn't rendered here either); drop it like TrackpadHaptic.
+                return -1;
+            }
         };
         n as jint
     })
 }
+
+#[cfg(test)]
+mod pack_rumble_tests {
+    use super::*;
+    use punktfunk_core::input::MAX_PADS;
+
+    /// Kotlin's `unpackRumbleEvent`, transcribed — if these two ever disagree the boundary is
+    /// broken, and nothing else in the build would say so.
+    fn unpack(ev: jlong) -> (u16, u16, u16, u32) {
+        let pad = ((ev >> 49) & 0xF) as u16;
+        let backstop = ((ev >> 32) & 0xFFFF) as u32;
+        let low = ((ev >> 16) & 0xFFFF) as u16;
+        let high = (ev & 0xFFFF) as u16;
+        (pad, low, high, backstop)
+    }
+
+    #[test]
+    fn round_trips_every_field_at_its_extremes() {
+        for &(pad, low, high, backstop) in &[
+            (0u16, 0u16, 0u16, 0u32),
+            (15, 0xFFFF, 0xFFFF, 0xFFFF),
+            (1, 0x1234, 0x5678, 500),
+            (7, 0, 0xFFFF, 2000),
+        ] {
+            let ev = pack_rumble(pad, low, high, backstop);
+            assert_eq!(unpack(ev), (pad, low, high, backstop), "pad {pad}");
+        }
+    }
+
+    #[test]
+    fn every_representable_pad_survives_the_four_bit_field() {
+        for pad in 0..MAX_PADS as u16 {
+            let (got, ..) = unpack(pack_rumble(pad, 1, 2, 3));
+            assert_eq!(got, pad, "pad {pad} aliased in the packed long");
+        }
+    }
+
+    #[test]
+    fn a_packed_command_is_never_negative() {
+        // `-1` is the timeout/closed sentinel; any packed value colliding with it would read as
+        // "no command" and the rumble would simply vanish.
+        assert!(pack_rumble(15, 0xFFFF, 0xFFFF, 0xFFFF) >= 0);
+        assert!(pack_rumble(0, 0, 0, 0) >= 0);
+    }
+
+    #[test]
+    fn an_oversized_backstop_saturates_instead_of_corrupting_the_pad_field() {
+        let ev = pack_rumble(3, 0, 0, u32::MAX);
+        let (pad, _, _, backstop) = unpack(ev);
+        assert_eq!(pad, 3, "a huge backstop must not bleed into the pad bits");
+        assert_eq!(backstop, 0xFFFF);
+    }
+
+    #[test]
+    fn a_stop_is_distinguishable_from_a_hold() {
+        let stop = pack_rumble(2, 0, 0, 0);
+        let hold = pack_rumble(2, 0x8000, 0x8000, 500);
+        assert_ne!(stop, hold);
+        assert_eq!(unpack(stop).1, 0);
+        assert_eq!(unpack(stop).2, 0);
+    }
+}

clients/android/native/src/lib.rs

@@ -37,6 +37,8 @@ mod discovery;
 mod feedback;
 #[cfg(target_os = "android")]
 mod mic;
+/// Tier-A DualSense pad audio: the 0xD1 plane rendered on the pad's own USB endpoint.
+mod pad_audio;
 mod session;
 mod stats;
 // Ungated like `discovery`: pure `jni` + `punktfunk_core::wol` (no Android framework), so it links

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

@@ -145,6 +145,7 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeConnect<'lo
     timeout_ms: jint,
     launch: JString<'local>,
     device_name: JString<'local>,
+    pad_audio_ok: jboolean,
 ) -> jlong {
     let host: String = match env.get_string(&host) {
         Ok(s) => s.into(),
@@ -268,7 +269,16 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeConnect<'lo
         // CLIENT_CAP_PHASE_LOCK is honest: the async decode loop's presenter feeds
         // report_phase (advisory in v1 — the host arms on report receipt — but the Hello
         // should say what the client does).
-        punktfunk_core::quic::CLIENT_CAP_PHASE_LOCK,
+        // CLIENT_CAP_PAD_AUDIO is the SESSION-level negotiation, separate from the per-pad
+        // arrival bits: without it the host never sets HOST_CAP_PAD_AUDIO and never emits 0xD1,
+        // so declaring a pad's render caps later would have nothing to gate. Gated on the
+        // settings so a user with pad audio off does not make the host provision endpoints.
+        punktfunk_core::quic::CLIENT_CAP_PHASE_LOCK
+            | if pad_audio_ok != 0 {
+                punktfunk_core::quic::CLIENT_CAP_PAD_AUDIO
+            } else {
+                0
+            },
         // Slice-progressive delivery, by decoder truth (Kotlin probes FEATURE_PartialFrame on
         // every decoder this device would use; `debug.punktfunk.force_parts` overrides for the
         // on-glass experiment): AU prefixes then arrive as `Frame::part` pieces and the decode
@@ -291,6 +301,8 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeConnect<'lo
                 audio: Mutex::new(None),
                 #[cfg(target_os = "android")]
                 mic: Mutex::new(None),
+                #[cfg(target_os = "android")]
+                pad_audio: Mutex::new(None),
                 // A fresh session is never muted (mute is per-session UI state, not a setting).
                 mic_muted: Arc::new(std::sync::atomic::AtomicBool::new(false)),
             };
@@ -392,6 +404,31 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSessionEnde
     })
 }
 
+/// `NativeBridge.nativeEndReason(handle): Int` — WHY the session ended, as a
+/// `punktfunk_core::client::PunktfunkEndReason` byte (Kotlin mirrors it in `SessionEndReason`).
+///
+/// Companion to `nativeSessionEnded`, which only says THAT it ended. Kotlin's watchdog needs both:
+/// the flag to leave a dead stream, and this to decide what — if anything — to tell the user. A
+/// player quitting their game and a host dropping off the network both end the session, and until
+/// this existed the watchdog worded them identically ("the host may be asleep"), which is wrong for
+/// every deliberate ending. `0` (NONE) on a `0` handle or before the session ends. Cheap (one
+/// atomic load); safe on the UI thread.
+#[no_mangle]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeEndReason(
+    _env: JNIEnv,
+    _this: JObject,
+    handle: jlong,
+) -> jint {
+    jni_guard(0, || {
+        if handle == 0 {
+            return 0;
+        }
+        // SAFETY: live handle per the nativeConnect/nativeClose contract.
+        let h = unsafe { &*(handle as *const SessionHandle) };
+        h.client.end_reason() as jint
+    })
+}
+
 /// `NativeBridge.nativePair(host, port, certPem, keyPem, pin, name): String` — run the SPAKE2 PIN
 /// ceremony, presenting our persistent identity. On success returns the host's verified fingerprint
 /// (64-hex) to persist + pin; on any failure (wrong PIN / MITM / host reject / unreachable) returns

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

@@ -61,6 +61,11 @@ pub(crate) struct SessionHandle {
     audio: Mutex<Option<crate::audio::AudioPlayback>>,
     #[cfg(target_os = "android")]
     mic: Mutex<Option<crate::mic::MicCapture>>,
+    /// Tier-A DualSense pad audio (the 0xD1 plane), started by `nativeStartPadAudio` once Kotlin
+    /// has claimed the pad's audio interface and handed its descriptor over. Session-lifetime and
+    /// `Option` because a session may have no wired DualSense at all, which is the common case.
+    #[cfg(target_os = "android")]
+    pub(crate) pad_audio: Mutex<Option<crate::pad_audio::PadAudio>>,
     /// In-stream mic mute, set via `nativeSetMicMuted` and read per 10 ms frame by the mic's
     /// encode loop ([`crate::mic`]). Session-lifetime rather than per-[`crate::mic::MicCapture`]
     /// for the same reason the stats gate is: the mic stops and restarts across a surface
@@ -99,6 +104,14 @@ impl SessionHandle {
     fn stop_mic(&self) {
         let _ = self.mic.lock().unwrap().take();
     }
+
+    /// Stop pad audio. Dropping the [`crate::pad_audio::PadAudio`] joins its render thread, which
+    /// is what guarantees nothing is still writing to the descriptor when Kotlin closes the
+    /// `UsbDeviceConnection`. Idempotent.
+    #[cfg(target_os = "android")]
+    pub(crate) fn stop_pad_audio(&self) {
+        let _ = self.pad_audio.lock().unwrap().take();
+    }
 }
 
 impl Drop for SessionHandle {
@@ -108,6 +121,8 @@ impl Drop for SessionHandle {
         self.stop_audio();
         #[cfg(target_os = "android")]
         self.stop_mic();
+        #[cfg(target_os = "android")]
+        self.stop_pad_audio();
     }
 }
 

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

@@ -460,6 +460,111 @@ pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeStopMic(
     })
 }
 
+/// `NativeBridge.nativeStartPadAudio(handle, pad, fd, haptics, speaker): Boolean` — start tier-A
+/// DualSense pad audio on a descriptor Kotlin has already obtained.
+///
+/// `fd` comes from `UsbDeviceConnection.getFileDescriptor()` **after** claiming the pad's audio
+/// streaming interface. Kotlin owns that connection and **must keep it open until
+/// `nativeStopPadAudio` returns**: the renderer borrows the descriptor and never closes it, so
+/// closing early would pull it out from under an in-flight isochronous transfer.
+///
+/// Returns `false` when there is nothing to render (both kinds disabled) or the thread would not
+/// start. A kernel that refuses the interface claim is NOT reported here — the renderer discovers
+/// that on its own thread and degrades to tier C, because some OEM kernels refuse and there is no
+/// app-side fix worth blocking a session on.
+#[no_mangle]
+#[cfg(target_os = "android")]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeStartPadAudio(
+    _env: JNIEnv,
+    _this: JObject,
+    handle: jlong,
+    pad: jni::sys::jint,
+    fd: jni::sys::jint,
+    haptics: jboolean,
+    speaker: jboolean,
+) -> jboolean {
+    jni_guard(0, || {
+        if handle == 0 || fd < 0 || !(0..16).contains(&pad) {
+            return 0;
+        }
+        // SAFETY: live handle per the nativeConnect/nativeClose contract.
+        let h = unsafe { &*(handle as *const SessionHandle) };
+        // Replace any previous renderer first: dropping it joins the old thread, so two of them
+        // can never hold the same descriptor at once.
+        h.stop_pad_audio();
+        // The capability declaration and the rumble suppression are NOT done here: the renderer
+        // makes both only once its USB stream actually opens (see `pad_audio::render`). Doing them
+        // at spawn time would, on a kernel that refuses the interface claim, take the pad off wire
+        // rumble and give it nothing in return — no haptics of any kind.
+        match crate::pad_audio::start(
+            std::sync::Arc::clone(&h.client),
+            pad as u8,
+            fd,
+            haptics != 0,
+            speaker != 0,
+        ) {
+            Some(p) => {
+                *h.pad_audio.lock().unwrap() = Some(p);
+                1
+            }
+            None => 0,
+        }
+    })
+}
+
+/// `NativeBridge.nativePadAudioSelfTest(fd, seconds, hz): Int` — drive the pad directly with a
+/// tone through the real client render path, with no host and no session involved.
+///
+/// The check a standalone harness cannot make: it owns its descriptor by construction, so it can
+/// never reveal that the client handed the renderer a descriptor something else was already
+/// driving. Returns sample frames written, or negative on failure (see `pad_audio::SelfTest`).
+#[no_mangle]
+#[cfg(target_os = "android")]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativePadAudioSelfTest(
+    _env: JNIEnv,
+    _this: JObject,
+    fd: jni::sys::jint,
+    seconds: jni::sys::jint,
+    hz: jni::sys::jint,
+) -> jni::sys::jint {
+    jni_guard(-1, || {
+        if fd < 0 {
+            return -1;
+        }
+        // SAFETY: Kotlin holds the owning UsbDeviceConnection open across this call and drives no
+        // other transfers on it (it opens a dedicated connection for exactly this).
+        unsafe { crate::pad_audio::self_test(fd, seconds, hz) }
+    })
+}
+
+/// `NativeBridge.nativeStopPadAudio(handle, pad)` — stop tier-A pad audio and join its thread.
+///
+/// Returns only once the render thread is joined, which is the point: Kotlin may close the
+/// `UsbDeviceConnection` as soon as this returns and not before.
+#[no_mangle]
+#[cfg(target_os = "android")]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeStopPadAudio(
+    _env: JNIEnv,
+    _this: JObject,
+    handle: jlong,
+    pad: jni::sys::jint,
+) {
+    jni_guard((), || {
+        if handle != 0 {
+            // SAFETY: live handle per the nativeConnect/nativeClose contract.
+            let h = unsafe { &*(handle as *const SessionHandle) };
+            h.stop_pad_audio();
+            if (0..16).contains(&pad) {
+                // Withdraw the capability and hand the pad back to wire rumble, in that order:
+                // the host stops sending 0xD1 before tier C resumes, so the two never overlap.
+                h.client.set_pad_audio_caps(pad as u8, 0);
+                crate::pad_audio::set_tier_a(pad as u8, false);
+                crate::pad_audio::clear_haptics_liveness(pad as u8);
+            }
+        }
+    })
+}
+
 /// `NativeBridge.nativeSetMicMuted(handle, muted)` — mute/unmute the mic uplink mid-stream.
 ///
 /// Muting deliberately does NOT stop the capture: the AAudio input stream, the input-preset rung

clients/apple/README.md

@@ -121,7 +121,11 @@ PUNKTFUNK_AUTOCONNECT=<box-ip> PUNKTFUNK_MODE=1280x720x60 swift run PunktfunkCli
   host's virtual pad.
 - **App Store screenshots** are automated — `tools/screenshots.sh all` renders the real UI at the
   required pixel sizes via a DEBUG-only shot mode; the `apple` CI workflow captures the iOS sizes on
-  every main push. See the script header for details.
+  every main push. See the script header for details. The script's `SCENES` array is the listing
+  set, in listing order; override it (`SCENES="06-gamepad-home 10-edithost" tools/screenshots.sh ios`)
+  to capture any of the other scenes in `ShotScenes.all`. Mock data — hosts, adverts, profiles — is
+  seeded in `ShotMock` so a capture is byte-for-byte deterministic and never browses the real LAN
+  (a stranger's hostname reached the live listing that way once).
 - Deeper design notes live in the internal planning repo (punktfunk-planning:
   `apple-stage2-presenter.md`).
 

clients/apple/Sources/PunktfunkClient/ContentView.swift

@@ -206,6 +206,20 @@ struct ContentView: View {
             model.setStatsVerbosity(StatsVerbosity(rawValue: raw) ?? .normal)
         }
         #if os(iOS) || os(tvOS)
+        // Coming back to the app re-arms the LAN browse. The home's `onAppear`/`onDisappear` do
+        // NOT fire across background/foreground, and a browse the system suspended while we were
+        // away does not resume on its own — so the host grid came back empty and stayed empty
+        // until the app was relaunched. No-op unless the browse is already running (mid-session
+        // the home has deliberately torn it down).
+        //
+        // Mobile only: macOS never suspends the process, and its `scenePhase` flips on every
+        // window focus change — re-arming there would rebuild the browser each time you alt-tab.
+        // A Mac browse that genuinely breaks is caught by `HostDiscovery`'s own sweep instead.
+        .onChange(of: scenePhase) { _, phase in
+            if phase == .active { discovery.refreshIfRunning() }
+        }
+        #endif
+        #if os(iOS) || os(tvOS)
         // Backgrounding driver. Only .background/.active matter; .inactive (a transient peek) is
         // ignored so neither branch fires for a Control-Center pull.
         //
@@ -335,6 +349,16 @@ struct ContentView: View {
             active: fullscreenForSession && model.connection != nil,
             isFullscreen: $isFullscreen))
         #endif
+        // A game launched from the library just exited, so the session ended on purpose: put the
+        // player back in that host's library rather than on host selection. Set on the outer Group
+        // (like the sheets below) so it survives the streaming → home transition the disconnect
+        // drives, and consumed here — the model hands the host over once and we clear it, so a
+        // later manual dismiss of the library can't be undone by a stale value.
+        .onChange(of: model.returnToLibrary) { _, host in
+            guard let host else { return }
+            model.returnToLibrary = nil
+            libraryTarget = host
+        }
         // On the outer Group so the sheet survives the trust-prompt → home transition
         // (the "Pair with PIN instead" path disconnects first — the host's accept loop
         // is sequential, a pairing connection would queue behind the live session).
@@ -512,6 +536,9 @@ struct ContentView: View {
                 waker: waker,
                 gamepadUI: gamepadUIActive,
                 onCancelConnect: { model.disconnect() })
+                // The takeover mounts OUTSIDE the gamepad screens (it covers the whole home), so
+                // it publishes the palette's ink itself rather than inheriting it.
+                .gamepadPaletteInk()
         }
     }
 

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

@@ -47,12 +47,16 @@ struct ConnectOverlay: View {
         return nil
     }
 
+    @Environment(\.gamepadInk) private var ink
+
     var body: some View {
         if let phase {
             ZStack {
                 if gamepadUI {
-                    // Console: an opaque, living aurora over everything.
-                    Color.black.ignoresSafeArea()
+                    // Console: an opaque, living aurora over everything, in the chosen palette.
+                    // The takeover's own text rides `ink`, so a pale palette flips it here too —
+                    // without that this is the one console screen that stays white-on-white.
+                    ink.isLight ? Color.white.ignoresSafeArea() : Color.black.ignoresSafeArea()
                     GamepadScreenBackground().ignoresSafeArea()
                     Color.clear.contentShape(Rectangle()).onTapGesture {}
                     content(phase).padding(40).frame(maxWidth: 460)
@@ -70,7 +74,8 @@ struct ConnectOverlay: View {
                         .padding(40)
                 }
             }
-            .environment(\.colorScheme, .dark)
+            // The console takeover follows the palette; the default UI's modal stays dark.
+            .environment(\.colorScheme, gamepadUI && ink.isLight ? .light : .dark)
             .transition(.opacity)
             #if os(iOS) || os(macOS)
             .background { ConnectControllerInput(waker: waker, onCancelConnect: onCancelConnect) }

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

@@ -12,6 +12,7 @@ import SwiftUI
 #if os(iOS) || os(macOS) || os(tvOS)
 
 struct GamepadAddHostView: View {
+    @Environment(\.gamepadInk) private var ink
     @Environment(\.dismiss) private var dismiss
     let onAdd: (StoredHost) -> Void
 
@@ -47,12 +48,12 @@ struct GamepadAddHostView: View {
             VStack(spacing: 4) {
                 Text("Add Host")
                     .font(.geist(gamepadTitleSize(compact: compact), .bold, relativeTo: .title))
-                    .foregroundStyle(.white)
+                    .foregroundStyle(ink.fg)
                 if !compact {
                     Text("Hosts on this network appear automatically — add one by address "
                         + "for everything else.")
                         .font(.geist(GamepadFormMetrics.detailFont, relativeTo: .caption))
-                        .foregroundStyle(.white.opacity(0.55))
+                        .foregroundStyle(ink.fg(0.55))
                         .multilineTextAlignment(.center)
                         .frame(maxWidth: GamepadFormMetrics.rowMaxWidth * 0.72)
                 }
@@ -73,6 +74,9 @@ struct GamepadAddHostView: View {
         }
         // No aurora — the same clean Liquid-Glass-over-dark base as the gamepad settings screen.
         .background { GamepadFormBackground() }
+        // Publish the palette's ink to this screen (text, glass, accent, scrims) — a
+        // pale palette flips all of them, and no leaf should have to read the setting.
+        .gamepadPaletteInk()
         // A port can't exceed 5 digits — cap while typing so the row can't grow absurd.
         .onChange(of: port) { _, value in
             if value.count > 5 { port = String(value.prefix(5)) }
@@ -143,7 +147,7 @@ struct GamepadAddHostView: View {
         Button { dismiss() } label: {
             Image(systemName: "xmark")
                 .font(.system(size: GamepadFormMetrics.closeFont, weight: .semibold))
-                .foregroundStyle(.white)
+                .foregroundStyle(ink.fg)
                 .frame(width: GamepadFormMetrics.closeSide, height: GamepadFormMetrics.closeSide)
                 .glassBackground(Circle(), interactive: true)
                 .contentShape(Circle())
@@ -180,22 +184,22 @@ struct GamepadAddHostView: View {
             if row.isAction {
                 Label("Add Host", systemImage: "plus.circle.fill")
                     .font(.geist(m.labelFont, .semibold, relativeTo: .body))
-                    .foregroundStyle(canAdd ? Color.brand : .white.opacity(0.35))
+                    .foregroundStyle(canAdd ? ink.accent : ink.fg(0.35))
                     .frame(maxWidth: .infinity)
             } else {
                 Text(row.label)
                     .font(.geist(m.labelFont, .semibold, relativeTo: .body))
-                    .foregroundStyle(.white)
+                    .foregroundStyle(ink.fg)
                 Spacer(minLength: 12)
                 Text(row.value.isEmpty ? row.placeholder : row.value)
                     .font(.geistFixed(m.valueFont, .medium))
-                    .foregroundStyle(row.value.isEmpty ? .white.opacity(0.35) : .white)
+                    .foregroundStyle(row.value.isEmpty ? ink.fg(0.35) : ink.fg)
                     .lineLimit(1)
                     .truncationMode(.head) // keep the end of a long address visible while typing
                 if editing == row.id {
                     // The live-edit caret: this row is what the keyboard tray is typing into.
                     Rectangle()
-                        .fill(Color.brand)
+                        .fill(ink.accent)
                         .frame(width: 2, height: m.labelFont + 2)
                 }
             }
@@ -206,12 +210,12 @@ struct GamepadAddHostView: View {
         // takes the brand wash, and the edited row keeps its brand caret border.
         .consoleGlass(
             RoundedRectangle(cornerRadius: m.rowCorner, style: .continuous),
-            tint: (focused || editing == row.id) ? Color.brand.opacity(0.30) : nil,
+            tint: (focused || editing == row.id) ? ink.accent(0.30) : nil,
             interactive: focused)
         .overlay {
             RoundedRectangle(cornerRadius: m.rowCorner, style: .continuous)
                 .strokeBorder(
-                    editing == row.id ? Color.brand.opacity(0.7) : .white.opacity(focused ? 0.28 : 0.06),
+                    editing == row.id ? ink.accent(0.7) : ink.fg(focused ? 0.28 : 0.06),
                     lineWidth: 1)
         }
         .scaleEffect(focused ? 1.0 : 0.98)

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

@@ -89,6 +89,7 @@ struct GamepadHint: Identifiable {
 /// worn as a self-contained Liquid Glass pill (like the top-bar controller chip) so it floats over
 /// the backdrop instead of dissolving into it.
 struct GamepadHintBar: View {
+    @Environment(\.gamepadInk) private var ink
     let hints: [GamepadHint]
 
     // 10-foot legend on tvOS, in-hand sizes elsewhere.
@@ -108,26 +109,35 @@ struct GamepadHintBar: View {
                 HStack(spacing: 7) {
                     Image(systemName: hint.glyph)
                         .font(.system(size: Self.glyphFont))
-                        .foregroundStyle(.white)
+                        .foregroundStyle(ink.fg)
                     Text(hint.text)
                 }
                 .fixedSize() // keep glyph + label together; never truncate a hint mid-word
             }
         }
         .font(.geist(Self.textFont, .semibold, relativeTo: .subheadline))
-        .foregroundStyle(.white.opacity(0.85))
+        .foregroundStyle(ink.fg(0.85))
         .padding(Self.pad)
         .consoleGlass(Capsule())
-        .overlay(Capsule().strokeBorder(.white.opacity(0.12), lineWidth: 1))
+        .overlay(Capsule().strokeBorder(ink.fg(0.12), lineWidth: 1))
     }
 }
 
-/// The console backdrop: a living aurora in the brand's violet family, drifting slowly over black
-/// so it reads as ambience behind the cards, never as content. On iOS 18 / macOS 15+ it's an
-/// animated `MeshGradient` — a continuous silk of colour whose control points wander on slow,
-/// out-of-phase sinusoids — finished with an elliptical vignette (pools light in the centre, sinks
-/// the corners) and a top/bottom legibility scrim. Older OSes fall back to the original drifting
-/// radial-blob field, unchanged, so nothing regresses.
+/// The console backdrop: a living aurora drifting slowly over black so it reads as ambience behind
+/// the cards, never as content. On iOS 18 / macOS 15+ it's an animated `MeshGradient` — a continuous
+/// silk of colour whose control points wander on slow, out-of-phase sinusoids — finished with an
+/// elliptical vignette (pools light in the centre, sinks the corners) and a top/bottom legibility
+/// scrim. Older OSes fall back to the original drifting radial-blob field, unchanged, so nothing
+/// regresses.
+///
+/// `calm` is what the FORM screens (settings, add-host) wear: the same living field with its pools
+/// dimmed onto its own corner colour, so those screens keep real colour under their Liquid Glass
+/// rows without the launcher's contrast. They used to sit on a still gradient; nothing in the
+/// gamepad UI is backed by a static image now. Motion is identical in both modes on purpose — only
+/// the contrast differs, so a screen change can't make the field jump.
+///
+/// `GamepadPalette` recolours the whole thing (the shared `ui_palette` setting) by transforming the
+/// COLOURS, not by stacking a filter — see GamepadPalette.swift for why.
 ///
 /// Deliberately pure SwiftUI, no `.metal`: these sources build under both SwiftPM (`swift run`/
 /// tests) and the Xcode project's synchronized folders, and a compiled metallib is only reliably
@@ -136,77 +146,90 @@ struct GamepadHintBar: View {
 /// can't inflate the caller's layout past the safe area (see the layout note in GamepadHomeView's
 /// header). Honors Reduce Motion by freezing the field at a fixed phase.
 struct GamepadScreenBackground: View {
+    @Environment(\.gamepadInk) private var ink
+    /// Quiet the field for a form screen (see the type comment).
+    var calm = false
+
     @Environment(\.accessibilityReduceMotion) private var reduceMotion
+    @AppStorage(DefaultsKey.uiPalette) private var paletteID = "violet"
 
     var body: some View {
+        let palette = GamepadPalette.named(paletteID)
         Group {
             if reduceMotion {
-                composite(at: 0)
+                composite(at: 0, palette: palette)
             } else {
                 // 30 Hz is plenty for a field that drifts centimetres per minute, and halves the
                 // redraw cost of a battery-fed couch device vs. the display's native rate.
                 TimelineView(.animation(minimumInterval: 1.0 / 30.0)) { context in
-                    composite(at: context.date.timeIntervalSinceReferenceDate)
+                    composite(at: context.date.timeIntervalSinceReferenceDate, palette: palette)
                 }
             }
         }
         .ignoresSafeArea()
     }
 
-    /// The colour field under a very slow warm/cool hue sway, an elliptical vignette, and the
-    /// title/hints legibility scrim.
-    private func composite(at t: TimeInterval) -> some View {
-        ZStack {
-            Color.black
-            colorField(at: t)
+    /// The colour field under a very slow warm/cool hue sway, the calm flattening, an elliptical
+    /// vignette, and the title/hints legibility scrim — in that order, matching the console
+    /// shader's `composite` so the two platforms' backdrops stay the same picture.
+    private func composite(at t: TimeInterval, palette: GamepadPalette) -> some View {
+        // Where the scrims tend, and how hard. Mixing a PALE field toward white at the dark
+        // field's strength bleaches the chroma straight out of the gradient, so a pale palette
+        // gets under half — the same `u_scrim.a` the console shader carries.
+        let scrim: Color = palette.light ? ink.fg : .black
+        let strength = palette.light ? 0.45 : 1.0
+        return ZStack {
+            Self.color(palette.ground)
+            colorField(at: t, palette: palette)
                 // ±8° over ~5 min — the whole field very slowly warms and cools.
                 .hueRotation(.degrees(sin(t * 0.021) * 8))
-            // Cinematic vignette: darker toward the edges so the cards sit in the pooled light.
-            // Soft (extends past the frame) so the corners deepen rather than crush to black.
+                // Calm = col·0.6 + ground·0.4: over the ground, `.opacity` IS the multiply…
+                .opacity(calm ? 0.6 : 1)
+            if calm {
+                // …and a plusLighter wash of the palette's own ground IS the add. Chosen so the
+                // ground lands exactly where it was and the bright pools come down to meet it.
+                Self.color(palette.ground)
+                    .opacity(0.4)
+                    .blendMode(.plusLighter)
+            }
+            // Cinematic vignette: the edges settle toward the scrim so the cards sit in the
+            // pooled light. Soft (extends past the frame) so the corners deepen rather than
+            // crush. Halved under calm: a launcher's cards sit in the pooled centre, but a form
+            // screen's rows run out toward the edges, where crushing them just eats the list.
             EllipticalGradient(
-                colors: [.clear, .black.opacity(0.42)],
+                colors: [.clear, scrim.opacity((calm ? 0.21 : 0.42) * strength)],
                 center: .center, startRadiusFraction: 0.25, endRadiusFraction: 1.15)
             // Legibility grounding for the pinned title (top) and hint pill (bottom). This one
-            // darkens the aurora itself (it's the backdrop's bottom layer — nothing behind it to
-            // blur), so it stays a gradient, just a light one now.
+            // works on the field itself (it's the backdrop's bottom layer — nothing behind it to
+            // blur), so it stays a gradient, just a light one.
             LinearGradient(
                 stops: [
-                    .init(color: .black.opacity(0.38), location: 0),
-                    .init(color: .black.opacity(0.06), location: 0.32),
-                    .init(color: .black.opacity(0.08), location: 0.68),
-                    .init(color: .black.opacity(0.40), location: 1),
+                    .init(color: scrim.opacity(0.38 * strength), location: 0),
+                    .init(color: scrim.opacity(0.06 * strength), location: 0.32),
+                    .init(color: scrim.opacity(0.08 * strength), location: 0.68),
+                    .init(color: scrim.opacity(0.40 * strength), location: 1),
                 ],
                 startPoint: .top, endPoint: .bottom)
         }
     }
 
-    @ViewBuilder private func colorField(at t: TimeInterval) -> some View {
+    @ViewBuilder private func colorField(at t: TimeInterval, palette: GamepadPalette) -> some View {
         if #available(iOS 18, macOS 15, tvOS 18, *) {
             MeshGradient(
                 width: 4, height: 4,
                 points: Self.meshPoints(at: t),
-                colors: Self.meshColors,
+                colors: palette.meshColors.map(Self.color),
                 smoothsColors: true)
         } else {
-            LegacyBlobField(t: t)
+            LegacyBlobField(t: t, palette: palette)
         }
     }
 
     // MARK: - MeshGradient aurora (iOS 18 / macOS 15+)
 
-    /// Sixteen mesh colours (row-major, 4×4): dark-violet corners sink the frame, the edges carry
-    /// mid-tone violets, and the four interior points hold the bright brand family — a violet and a
-    /// blue-violet up top, a magenta-violet and a violet below — so warm pools on the left, cool on
-    /// the right, and the silk shifts temperature as those interior points drift.
-    private static let meshColors: [Color] = {
-        let corner = Color(red: 0.075, green: 0.060, blue: 0.160)
-        return [
-            corner, Color(red: 0.34, green: 0.27, blue: 0.72), Color(red: 0.30, green: 0.26, blue: 0.74), corner,
-            Color(red: 0.42, green: 0.20, blue: 0.54), Color(red: 0.49, green: 0.39, blue: 0.95), Color(red: 0.28, green: 0.31, blue: 0.84), Color(red: 0.16, green: 0.26, blue: 0.64),
-            Color(red: 0.45, green: 0.23, blue: 0.60), Color(red: 0.53, green: 0.31, blue: 0.75), Color(red: 0.35, green: 0.35, blue: 0.91), Color(red: 0.19, green: 0.28, blue: 0.70),
-            corner, Color(red: 0.22, green: 0.18, blue: 0.54), Color(red: 0.24, green: 0.20, blue: 0.58), corner,
-        ]
-    }()
+    static func color(_ c: SIMD3<Double>) -> Color {
+        Color(red: c.x, green: c.y, blue: c.z)
+    }
 
     /// The 4×4 control points at time `t`: every boundary point is PINNED to the frame (so the mesh
     /// always fills edge-to-edge — a drifting edge point would shrink the mesh and expose the black
@@ -233,15 +256,18 @@ struct GamepadScreenBackground: View {
 }
 
 /// Pre-18/15 fallback for `GamepadScreenBackground`: the original drifting radial-blob field — four
-/// soft colour blobs on slow Lissajous paths, additively blended. Kept verbatim so older OSes see
-/// exactly the aurora they shipped with (the mesh path is the upgrade for OS 18/15+).
+/// soft colour blobs on slow Lissajous paths, additively blended. Geometry and motion are verbatim
+/// so older OSes see exactly the aurora they shipped with (the mesh path is the upgrade for OS
+/// 18/15+); only the blob COLOURS now pass through the palette, so an older device honours the
+/// setting too instead of being stuck on violet.
 private struct LegacyBlobField: View {
     let t: TimeInterval
+    let palette: GamepadPalette
 
     /// One drifting color blob: a base position + drift ellipse (unit coordinates), angular speeds
-    /// (rad/s — periods of 30–90 s), and a radius that slowly breathes.
+    /// (rad/s — periods of 30–90 s), and a radius that slowly breathes. The COLOUR comes from the
+    /// palette's ramp at draw time (see `blobColors`), so an older OS honours the setting too.
     private struct Blob {
-        let color: Color
         let center: CGPoint
         let drift: CGSize
         let speed: (x: Double, y: Double)
@@ -252,20 +278,16 @@ private struct LegacyBlobField: View {
     }
 
     private static let blobs: [Blob] = [
-        Blob(color: Color(red: 0.53, green: 0.47, blue: 0.96), // brand violet
-             center: CGPoint(x: 0.30, y: 0.24), drift: CGSize(width: 0.16, height: 0.10),
+        Blob(center: CGPoint(x: 0.30, y: 0.24), drift: CGSize(width: 0.16, height: 0.10),
              speed: (0.111, 0.083), phase: (0.0, 1.9),
              radius: 0.52, breathe: (0.07, 0.061), opacity: 0.52),
-        Blob(color: Color(red: 0.24, green: 0.20, blue: 0.72), // deep indigo
-             center: CGPoint(x: 0.78, y: 0.66), drift: CGSize(width: 0.13, height: 0.14),
+        Blob(center: CGPoint(x: 0.78, y: 0.66), drift: CGSize(width: 0.13, height: 0.14),
              speed: (0.071, 0.096), phase: (2.4, 0.7),
              radius: 0.58, breathe: (0.08, 0.049), opacity: 0.55),
-        Blob(color: Color(red: 0.62, green: 0.30, blue: 0.80), // plum
-             center: CGPoint(x: 0.16, y: 0.82), drift: CGSize(width: 0.12, height: 0.09),
+        Blob(center: CGPoint(x: 0.16, y: 0.82), drift: CGSize(width: 0.12, height: 0.09),
              speed: (0.089, 0.067), phase: (4.1, 3.2),
              radius: 0.44, breathe: (0.09, 0.078), opacity: 0.42),
-        Blob(color: Color(red: 0.22, green: 0.38, blue: 0.86), // cool blue
-             center: CGPoint(x: 0.70, y: 0.12), drift: CGSize(width: 0.10, height: 0.08),
+        Blob(center: CGPoint(x: 0.70, y: 0.12), drift: CGSize(width: 0.10, height: 0.08),
              speed: (0.059, 0.104), phase: (1.2, 5.0),
              radius: 0.40, breathe: (0.06, 0.055), opacity: 0.38),
     ]
@@ -275,26 +297,31 @@ private struct LegacyBlobField: View {
             let side = max(geo.size.width, geo.size.height)
             ZStack {
                 ForEach(Self.blobs.indices, id: \.self) { i in
-                    blobView(Self.blobs[i], in: geo.size, side: side)
+                    blobView(Self.blobs[i], tone: palette.blobColors[i], in: geo.size, side: side)
                 }
             }
             .drawingGroup()
         }
     }
 
-    private func blobView(_ blob: Blob, in size: CGSize, side: CGFloat) -> some View {
+    private func blobView(
+        _ blob: Blob, tone: SIMD3<Double>, in size: CGSize, side: CGFloat
+    ) -> some View {
         let x = blob.center.x + blob.drift.width * CGFloat(sin(t * blob.speed.x + blob.phase.x))
         let y = blob.center.y + blob.drift.height * CGFloat(cos(t * blob.speed.y + blob.phase.y))
         let r = side * blob.radius
             * (1 + blob.breathe.amount * CGFloat(sin(t * blob.breathe.speed + blob.phase.x)))
+        let color = GamepadScreenBackground.color(tone)
         return Circle()
             .fill(RadialGradient(
-                colors: [blob.color, blob.color.opacity(0)],
+                colors: [color, color.opacity(0)],
                 center: .center, startRadius: 0, endRadius: r / 2))
             .frame(width: r, height: r)
             .position(x: x * size.width, y: y * size.height)
             .opacity(blob.opacity)
-            .blendMode(.plusLighter)
+            // Additive only works over a DARK ground; over a pale one every blob saturates to
+            // white and the field turns grey. Pale palettes tint instead.
+            .blendMode(palette.light ? .normal : .plusLighter)
     }
 }
 
@@ -304,15 +331,17 @@ private struct LegacyBlobField: View {
 /// the tray's text sits on a softly blurred backdrop that dissolves into the rows.
 struct GamepadTrayScrim: View {
     let edge: VerticalEdge
+    @Environment(\.gamepadInk) private var ink
 
     var body: some View {
         let fromEdge: UnitPoint = edge == .top ? .top : .bottom
         let toContent: UnitPoint = edge == .top ? .bottom : .top
         Rectangle()
             .fill(.ultraThinMaterial)
-            // These trays always sit on the dark console UI; force dark so the material frosts dark
-            // (white text stays legible) regardless of the system appearance.
-            .environment(\.colorScheme, .dark)
+            // Force the frost to match the PALETTE, not the system appearance: the tray exists
+            // to keep the pinned title legible, so it has to frost dark under white ink and
+            // light under dark ink.
+            .environment(\.colorScheme, ink.isLight ? .light : .dark)
             // Fade the whole blur out toward the content so it dissolves rather than ending on a line.
             .mask {
                 LinearGradient(
@@ -330,27 +359,16 @@ struct GamepadTrayScrim: View {
     }
 }
 
-/// The calm backdrop for the gamepad UI's form screens (settings, add-host) — NOT the launcher's
-/// drifting aurora (this stays still and quiet), but deliberately NOT near-black either: Liquid
-/// Glass refracts whatever sits behind it, so over black the rows turn invisible. A deep indigo
-/// base plus two soft, static violet/indigo glows give the glass real colour and luminance to lens,
-/// so the rows read as glass while the screen stays restful.
+/// The backdrop for the gamepad UI's form screens (settings, add-host). It used to be a STILL pair
+/// of glows over a deep indigo base — deliberately not near-black, because Liquid Glass refracts
+/// whatever sits behind it and over black the rows turn invisible. It is now the launcher's own
+/// living field at `calm`, which keeps that luminance under the glass, keeps the palette setting
+/// honoured on every screen rather than only the launcher, and leaves nothing in the gamepad UI
+/// backed by a static image. Kept as its own type because that is what the form screens ask for by
+/// name; the console (`pf-console-ui`) made the same substitution behind its `Bg::Form`.
 struct GamepadFormBackground: View {
     var body: some View {
-        ZStack {
-            Color(red: 0.075, green: 0.062, blue: 0.150)
-            // Violet lift top-leading, cooler indigo bottom-trailing — resolution-independent
-            // (fraction radii) so the glow scale tracks the window on any screen.
-            EllipticalGradient(
-                colors: [Color(red: 0.40, green: 0.31, blue: 0.68).opacity(0.9), .clear],
-                center: UnitPoint(x: 0.26, y: 0.14),
-                startRadiusFraction: 0, endRadiusFraction: 0.78)
-            EllipticalGradient(
-                colors: [Color(red: 0.20, green: 0.24, blue: 0.58).opacity(0.75), .clear],
-                center: UnitPoint(x: 0.82, y: 0.9),
-                startRadiusFraction: 0, endRadiusFraction: 0.78)
-        }
-        .ignoresSafeArea()
+        GamepadScreenBackground(calm: true)
     }
 }
 
@@ -373,6 +391,7 @@ struct ConsoleBareButtonStyle: ButtonStyle {
 /// 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 {
+    @Environment(\.gamepadInk) private var ink
     let controller: GamepadManager.DiscoveredController
 
     // Legible from the couch on tvOS, quiet in hand elsewhere.
@@ -397,15 +416,15 @@ struct ControllerStatusChip: View {
                 Image(systemName: batterySymbol(level))
                     .font(.system(size: Self.font))
                     .foregroundStyle(level <= 0.2 && !controller.isCharging
-                        ? AnyShapeStyle(.red) : AnyShapeStyle(.white.opacity(0.7)))
+                        ? AnyShapeStyle(.red) : AnyShapeStyle(ink.fg(0.7)))
             }
         }
         .font(.geist(Self.font, .medium, relativeTo: .caption))
-        .foregroundStyle(.white.opacity(0.7))
+        .foregroundStyle(ink.fg(0.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))
+        .background(Capsule().fill(ink.fg(0.08)))
+        .overlay(Capsule().strokeBorder(ink.fg(0.12), lineWidth: 1))
     }
 
     private func batterySymbol(_ level: Float) -> String {

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

@@ -23,14 +23,15 @@ import SwiftUI
 #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
-/// action. Hashable so it can be the carousel's scroll-position identity.
+/// One navigable tile: a saved host, a discovered-but-unsaved one, or one of the trailing
+/// actions. Hashable so it can be the carousel's scroll-position identity.
 private enum GamepadHomeTarget: Hashable {
     /// A saved host's own tile, or one of its pinned host+profile cards (§5.2a) — which on a
     /// controller-first surface are THE profile affordance: focus and press, no menus.
     case saved(UUID, profile: String?)
     case discovered(String)
     case addHost
+    case rescan
 }
 
 /// A fully-resolved launcher tile — display fields + the activate action, built fresh each render
@@ -63,6 +64,7 @@ private struct HomeTile: Identifiable {
 }
 
 struct GamepadHomeView: View {
+    @Environment(\.gamepadInk) private var ink
     @ObservedObject var store: HostStore
     @ObservedObject var model: SessionModel
     @ObservedObject var discovery: HostDiscovery
@@ -114,6 +116,9 @@ struct GamepadHomeView: View {
                 .padding(.top, compact ? 4 : 8)
         }
         .background { GamepadScreenBackground() }
+        // Publish the palette's ink to this screen (text, glass, accent, scrims) — a
+        // pale palette flips all of them, and no leaf should have to read the setting.
+        .gamepadPaletteInk()
         .onAppear { discovery.start() }
         .onDisappear { discovery.stop() }
         // Reachability sweep (mDNS-independent) so routed/VPN hosts that never advertise still show
@@ -135,7 +140,7 @@ struct GamepadHomeView: View {
         // fullScreenCover, so they become generously sized sheets over the dimmed launcher.
         #if os(macOS)
         .sheet(isPresented: $showSettings) {
-            GamepadSettingsView()
+            GamepadSettingsView(store: store)
                 .frame(width: 720, height: 640)
         }
         .sheet(isPresented: $showAddHost) {
@@ -144,7 +149,7 @@ struct GamepadHomeView: View {
         }
         .frame(minWidth: 640, minHeight: 420)
         #else
-        .fullScreenCover(isPresented: $showSettings) { GamepadSettingsView() }
+        .fullScreenCover(isPresented: $showSettings) { GamepadSettingsView(store: store) }
         .fullScreenCover(isPresented: $showAddHost) {
             GamepadAddHostView { store.add($0) }
         }
@@ -176,18 +181,33 @@ struct GamepadHomeView: View {
     // MARK: - Chrome
 
     private var titleBar: some View {
-        Text("Select a Host")
-            .font(.geist(gamepadTitleSize(compact: compact), .bold, relativeTo: .title))
-            .foregroundStyle(.white)
-            .frame(maxWidth: .infinity)
-            .overlay(alignment: .trailing) {
-                // Which pad is driving this UI (name + battery) — quiet, and only where there's
-                // room; a compact-height phone gives the pixels to the carousel instead.
-                if !compact, let active = gamepads.active {
-                    ControllerStatusChip(controller: active)
-                        .padding(.trailing, 20)
-                }
-            }
+        // The chip used to be a trailing `.overlay`, which reserves no width: on a portrait phone
+        // it sat directly on top of the centred title ("Select a Host" ran straight into the pad
+        // name). Laying it out as a row with a hidden mirror on the leading side keeps the title
+        // optically centred AND clear of the chip at every width; the title shrinks a little
+        // before it would ever truncate.
+        HStack(spacing: 12) {
+            statusChip(hidden: true)
+            Text("Select a Host")
+                .font(.geist(gamepadTitleSize(compact: compact), .bold, relativeTo: .title))
+                .foregroundStyle(ink.fg)
+                .lineLimit(1)
+                .minimumScaleFactor(0.75)
+                .frame(maxWidth: .infinity)
+            statusChip(hidden: false)
+        }
+        .padding(.horizontal, 20)
+    }
+
+    /// Which pad is driving this UI (name + battery) — quiet, and only where there's room; a
+    /// compact-height phone gives the pixels to the carousel instead. `hidden` renders the same
+    /// chip purely as a width reserve.
+    @ViewBuilder private func statusChip(hidden: Bool) -> some View {
+        if !compact, let active = gamepads.active {
+            ControllerStatusChip(controller: active)
+                .opacity(hidden ? 0 : 1)
+                .accessibilityHidden(hidden)
+        }
     }
 
     private var cardSpacing: CGFloat {
@@ -247,10 +267,14 @@ struct GamepadHomeView: View {
 
     private var hints: [GamepadHint] {
         let selected = tiles.first { $0.id == selection }
+        let action: String? = switch selected?.id {
+        case .addHost: "Add Host"
+        case .rescan: "Rescan"
+        default: nil
+        }
         var hints = [GamepadHint(
             glyph: buttonGlyph(\.buttonA, fallback: "a.circle"),
-            text: selected?.id == .addHost ? "Add Host"
-                : (selected?.canWake == true ? "Wake & Connect" : "Connect"))]
+            text: action ?? (selected?.canWake == true ? "Wake & Connect" : "Connect"))]
         if libraryEnabled, selected?.hasLibrary == true {
             hints.append(.init(glyph: buttonGlyph(\.buttonY, fallback: "y.circle"), text: "Library"))
         }
@@ -310,7 +334,15 @@ struct GamepadHomeView: View {
             subtitle: "Register a host by address",
             icon: "plus",
             activate: { showAddHost = true })
-        return saved + discovered + [add]
+        // A controller surface has no toolbar and no pull-to-refresh, so the rescan the field
+        // asked for is a tile like any other — one press from wherever the stick already is.
+        let rescan = HomeTile(
+            id: .rescan,
+            title: "Rescan",
+            subtitle: discovery.isScanning ? "Scanning…" : "Look for hosts on this network",
+            icon: "arrow.clockwise",
+            activate: { discovery.refresh() })
+        return saved + discovered + [add, rescan]
     }
 
     /// Only saved hosts have a library — matches the touch grid, where "Browse Library…" is a
@@ -327,6 +359,7 @@ struct GamepadHomeView: View {
 /// touch grid's `HostCardView`. Renders only its base look; the centered-tile pop is layered on by
 /// the caller's `.scrollTransition` so it always tracks the real scroll position.
 private struct GamepadHostTile: View {
+    @Environment(\.gamepadInk) private var ink
     let tile: HomeTile
     let size: CGSize
 
@@ -366,7 +399,7 @@ private struct GamepadHostTile: View {
                     if tile.isPaired {
                         Image(systemName: "lock.fill")
                             .font(.system(size: Self.statusFont, weight: .semibold))
-                            .foregroundStyle(.white.opacity(0.5))
+                            .foregroundStyle(ink.fg(0.5))
                     }
                     if tile.isOnline {
                         Circle()
@@ -379,7 +412,7 @@ private struct GamepadHostTile: View {
             Spacer(minLength: 0)
             Text(tile.title)
                 .font(.geist(Self.titleFont, .bold, relativeTo: .title2))
-                .foregroundStyle(.white)
+                .foregroundStyle(ink.fg)
                 .lineLimit(1)
                 .minimumScaleFactor(0.7)
             if let profile = tile.profile {
@@ -389,7 +422,7 @@ private struct GamepadHostTile: View {
             }
             Text(tile.subtitle)
                 .font(.geist(Self.subtitleFont, relativeTo: .caption))
-                .foregroundStyle(.white.opacity(0.55))
+                .foregroundStyle(ink.fg(0.55))
                 .lineLimit(1)
                 .padding(.top, 2)
         }
@@ -399,12 +432,12 @@ private struct GamepadHostTile: View {
         // Add-Host tiles stay neutral glass with a dashed edge. Glass clips to the shape itself.
         .consoleGlass(
             RoundedRectangle(cornerRadius: Self.corner, style: .continuous),
-            tint: tile.filled ? Color.brand.opacity(0.20) : nil)
+            tint: tile.filled ? ink.accent(0.20) : nil)
         .overlay {
             RoundedRectangle(cornerRadius: Self.corner, style: .continuous)
                 .strokeBorder(
                     LinearGradient(
-                        colors: [.white.opacity(0.22), .white.opacity(0.04)],
+                        colors: [ink.fg(0.22), ink.fg(0.04)],
                         startPoint: .top, endPoint: .bottom),
                     style: StrokeStyle(lineWidth: 1, dash: tile.filled ? [] : [6, 5]))
         }
@@ -416,15 +449,15 @@ private struct GamepadHostTile: View {
         return ZStack {
             shape.fill(tile.filled
                 ? AnyShapeStyle(LinearGradient(
-                    colors: [Color.brand, Color.brand.opacity(0.68)],
+                    colors: [ink.accent, ink.accent(0.68)],
                     startPoint: .top, endPoint: .bottom))
-                : AnyShapeStyle(Color.brand.opacity(0.16)))
+                : AnyShapeStyle(ink.accent(0.16)))
             if tile.isConnecting {
-                ProgressView().tint(.white)
+                ProgressView().tint(ink.fg)
             } else if let icon = tile.icon {
                 Image(systemName: icon)
                     .font(.system(size: Self.iconFont, weight: .semibold))
-                    .foregroundStyle(Color.brand)
+                    .foregroundStyle(ink.accent)
             } else if let mark = osIconImage(for: tile.osChain) {
                 // The OS mark stands in for the initial (template asset — tints like the text it
                 // replaces), and carries the label, since nothing else on the tile names the OS.
@@ -432,18 +465,18 @@ private struct GamepadHostTile: View {
                     .resizable()
                     .scaledToFit()
                     .frame(width: Self.monogramFont, height: Self.monogramFont)
-                    .foregroundStyle(tile.filled ? .white : Color.brand)
+                    .foregroundStyle(tile.filled ? ink.fg : ink.accent)
                     .accessibilityLabel(tile.osChain ?? "")
             } else {
                 Text(monogram(tile.title))
                     .font(.geistFixed(Self.monogramFont, .bold))
-                    .foregroundStyle(tile.filled ? .white : Color.brand)
+                    .foregroundStyle(tile.filled ? ink.fg : ink.accent)
             }
         }
         .frame(width: Self.badgeSide, height: Self.badgeSide)
         .overlay {
             if !tile.filled {
-                shape.strokeBorder(Color.brand.opacity(0.5), lineWidth: 1)
+                shape.strokeBorder(ink.accent(0.5), lineWidth: 1)
             }
         }
     }

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

@@ -0,0 +1,91 @@
+// The ink the gamepad UI draws with under the chosen background palette.
+//
+// The console screens were white-on-dark throughout with the brand violet hardcoded as the
+// accent. Both had to become palette-derived at once: a pale field needs dark text or it is
+// unreadable, and a violet focus wash on a copper field is exactly the clash this exists to fix.
+//
+// Handed down the view tree as an environment value rather than passed to each screen, so a
+// leaf (a row, a hint pill, a card) can ask for the right colour without every caller in between
+// knowing about palettes. `pf-console-ui` does the same thing with a thread-local `Ink`.
+
+import PunktfunkShared
+import SwiftUI
+
+#if os(iOS) || os(macOS) || os(tvOS)
+
+struct GamepadInk: Equatable, Sendable {
+    /// Primary text/glyph colour.
+    let fg: Color
+    /// Focus wash, selected tab pill, switch track, caret — the palette's own accent.
+    let accent: Color
+    /// What reads ON the accent (a filled pill's label).
+    let onAccent: Color
+    /// The base fill every glass surface starts from.
+    let glass: Color
+    /// What a wash laid UNDER text tends toward: black on a dark field, white on a pale one.
+    let shade: Color
+    /// How hard those washes go. A pale field needs far less — mixing toward white at the dark
+    /// field's strength bleaches the chroma straight out of the gradient.
+    let shadeScale: Double
+    /// True when the field is pale, for the few places that need to branch rather than blend
+    /// (a material's `colorScheme`, a shadow's presence).
+    let isLight: Bool
+
+    /// The foreground at `alpha`.
+    func fg(_ alpha: Double) -> Color { fg.opacity(alpha) }
+    /// The accent at `alpha`.
+    func accent(_ alpha: Double) -> Color { accent.opacity(alpha) }
+    /// A wash under text: `alpha` is the dark-field strength, scaled for a pale one.
+    func shade(_ alpha: Double) -> Color { shade.opacity(alpha * shadeScale) }
+
+    static func of(_ p: GamepadPalette) -> GamepadInk {
+        let accent = Color(red: p.accent.x, green: p.accent.y, blue: p.accent.z)
+        let accentLuma = 0.2126 * p.accent.x + 0.7152 * p.accent.y + 0.0722 * p.accent.z
+        // Chosen by luminance, not by `light`: an accent is picked for contrast against the
+        // GLASS, not against the field.
+        let onAccent: Color = accentLuma > 0.55 ? .black : .white
+        guard p.light else {
+            return GamepadInk(
+                fg: .white, accent: accent, onAccent: onAccent,
+                glass: Color(red: 0.086, green: 0.086, blue: 0.125),
+                shade: .black, shadeScale: 1, isLight: false)
+        }
+        return GamepadInk(
+            // Tinted toward the palette's own ground so it doesn't read as a foreign grey.
+            fg: Color(red: p.ground.x * 0.16, green: p.ground.y * 0.14, blue: p.ground.z * 0.20),
+            accent: accent, onAccent: onAccent,
+            glass: .white,
+            shade: .white, shadeScale: 0.45, isLight: true)
+    }
+
+    /// The shipped dark look — what a preview or a test composition gets.
+    static let dark = GamepadInk.of(GamepadPalette.named("violet"))
+}
+
+private struct GamepadInkKey: EnvironmentKey {
+    static let defaultValue = GamepadInk.dark
+}
+
+extension EnvironmentValues {
+    /// The ink of the palette currently drawing. Set once, high up (see `GamepadInkModifier`).
+    var gamepadInk: GamepadInk {
+        get { self[GamepadInkKey.self] }
+        set { self[GamepadInkKey.self] = newValue }
+    }
+}
+
+extension View {
+    /// Resolve the stored `ui_palette` and publish its ink to everything below. Applied by the
+    /// gamepad screens' common root so no individual view has to read the setting.
+    func gamepadPaletteInk() -> some View { modifier(GamepadInkModifier()) }
+}
+
+private struct GamepadInkModifier: ViewModifier {
+    @AppStorage(DefaultsKey.uiPalette) private var paletteID = "violet"
+
+    func body(content: Content) -> some View {
+        content.environment(\.gamepadInk, GamepadInk.of(GamepadPalette.named(paletteID)))
+    }
+}
+
+#endif

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

@@ -14,6 +14,7 @@ import SwiftUI
 #if os(iOS) || os(macOS)
 
 struct GamepadKeyboard: View {
+    @Environment(\.gamepadInk) private var ink
     @Binding var text: String
     /// Restricts typed characters (e.g. digits for a port field); backspace always works.
     var allowed: CharacterSet?
@@ -79,7 +80,7 @@ struct GamepadKeyboard: View {
         }
         .overlay {
             RoundedRectangle(cornerRadius: 22, style: .continuous)
-                .strokeBorder(.white.opacity(0.12), lineWidth: 1)
+                .strokeBorder(ink.fg(0.12), lineWidth: 1)
         }
         .sensoryFeedback(.selection, trigger: cursor)
         .sensoryFeedback(.impact(weight: .light), trigger: pressTick)
@@ -110,11 +111,11 @@ struct GamepadKeyboard: View {
                     .font(.geist(15, .semibold, relativeTo: .callout))
             }
         }
-        .foregroundStyle(focused ? Color.black : .white)
+        .foregroundStyle(focused ? Color.black : ink.fg)
         .frame(maxWidth: .infinity, minHeight: compact ? 34 : 42)
         .background {
             RoundedRectangle(cornerRadius: 9, style: .continuous)
-                .fill(focused ? AnyShapeStyle(Color.brand) : AnyShapeStyle(.white.opacity(0.08)))
+                .fill(focused ? AnyShapeStyle(ink.accent) : AnyShapeStyle(ink.fg(0.08)))
         }
         .animation(.smooth(duration: 0.12), value: focused)
         .contentShape(Rectangle())

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

@@ -35,6 +35,10 @@ struct GamepadMenuList<Item: Identifiable, Row: View>: View where Item.ID: Hasha
     let onActivate: (Item) -> Void
     /// B → back/dismiss; nil disables it.
     var onBack: (() -> Void)?
+    /// L1 (`-1`) / R1 (`+1`) — a step SIDEWAYS out of the list: the settings screen's section
+    /// tabs. Wired on tvOS too, where the focus engine owns up/down but leaves the shoulders
+    /// to the poll. nil ⇒ the shoulders do nothing.
+    var onShoulder: ((Int) -> Void)?
     /// Whether this list currently owns controller input — same handoff contract as
     /// GamepadCarousel's `isActive` (a covered screen must stop polling the shared pad).
     var isActive: Bool = true
@@ -159,6 +163,7 @@ struct GamepadMenuList<Item: Identifiable, Row: View>: View where Item.ID: Hasha
             case .up, .down: break
             }
         }
+        input.onShoulder = { forward in onShoulder?(forward ? 1 : -1) }
         #else
         input.onMove = { direction in
             switch direction {
@@ -170,6 +175,7 @@ struct GamepadMenuList<Item: Identifiable, Row: View>: View where Item.ID: Hasha
         }
         input.onConfirm = { activate() }
         input.onBack = onBack
+        input.onShoulder = { forward in onShoulder?(forward ? 1 : -1) }
         #endif
     }
 

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

@@ -53,7 +53,18 @@ struct HomeView: View {
         NavigationStack {
             Group {
                 if store.hosts.isEmpty && discoveredUnsaved.isEmpty {
-                    emptyState
+                    #if os(tvOS)
+                    emptyState // no pull-to-refresh on a remote; the action row carries Refresh
+                    #else
+                    // Inside a ScrollView purely so the pull gesture works on the ONE screen
+                    // where a rescan matters most: the one that found nothing.
+                    ScrollView {
+                        emptyState
+                            .frame(maxWidth: .infinity)
+                            .containerRelativeFrame(.vertical)
+                    }
+                    .refreshable { await discovery.rescan() }
+                    #endif
                 } else {
                     ScrollView {
                         if !store.hosts.isEmpty {
@@ -94,6 +105,7 @@ struct HomeView: View {
                             } label: {
                                 Label("Settings", systemImage: "gearshape")
                             }
+                            refreshButton
                         }
                         .padding(.top, 24)
                         // One FULL-WIDTH focus target for any downward move out of the grid.
@@ -106,6 +118,9 @@ struct HomeView: View {
                         .focusSection()
                         #endif
                     }
+                    #if !os(tvOS)
+                    .refreshable { await discovery.rescan() }
+                    #endif
                 }
             }
             .navigationTitle("Punktfunk")
@@ -151,6 +166,7 @@ struct HomeView: View {
                 if showsArrangeMenu {
                     ToolbarItem(placement: .topBarTrailing) { arrangeMenu }
                 }
+                ToolbarItem(placement: .topBarTrailing) { refreshButton }
                 ToolbarItem(placement: .topBarTrailing) { addHostButton }
                 #else
                 if showsArrangeMenu {
@@ -159,6 +175,10 @@ struct HomeView: View {
                             .help("Sort and group the host list")
                     }
                 }
+                ToolbarItem(placement: .primaryAction) {
+                    refreshButton
+                        .help("Scan the network for hosts again")
+                }
                 ToolbarItem(placement: .primaryAction) {
                     addHostButton
                         .help("Add a host")
@@ -324,13 +344,20 @@ struct HomeView: View {
         ContentUnavailableView {
             Label("No Hosts", systemImage: "rectangle.connected.to.line.below")
         } description: {
-            Text("Add your punktfunk host with the + button.")
+            Text("Add your punktfunk host with the + button, or scan the network again.")
         } actions: {
             Button("Add Host") { showAddHost = true }
                 .glassProminentButtonStyle()
                 #if os(iOS)
                 .controlSize(.large)
                 #endif
+            // The screen a host SHOULD have appeared on is where a rescan is worth offering
+            // outright rather than hiding behind a pull gesture.
+            Button("Scan Again") { discovery.refresh() }
+                .disabled(discovery.isScanning)
+                #if os(iOS)
+                .controlSize(.large)
+                #endif
             #if os(tvOS)
             Button("Settings") { showSettings = true }
             #endif
@@ -345,6 +372,18 @@ struct HomeView: View {
         }
     }
 
+    /// Re-run mDNS discovery from scratch. Discovery heals itself now (`HostDiscovery`'s sweep),
+    /// so this is the fallback the field asked for — and the fastest way past the iOS
+    /// local-network permission gate, which only a NEW browser can clear.
+    private var refreshButton: some View {
+        Button {
+            discovery.refresh()
+        } label: {
+            Label("Refresh", systemImage: "arrow.clockwise")
+        }
+        .disabled(discovery.isScanning)
+    }
+
     #if !os(tvOS)
     /// One host has no order and nothing to divide, so the control stays out of the way until
     /// there is a list to arrange.

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

@@ -19,6 +19,7 @@ import SwiftUI
 import GameController
 
 struct LibraryCoverflowView: View {
+    @Environment(\.gamepadInk) private var ink
     let games: [GameEntry]
     let imageSession: URLSession?
     var onLaunch: ((String) -> Void)?
@@ -46,18 +47,24 @@ struct LibraryCoverflowView: View {
                 .padding(.vertical, compact ? 6 : 10)
         }
         .background { GamepadScreenBackground() }
+        // Publish the palette's ink to this screen (text, glass, accent, scrims) — a
+        // pale palette flips all of them, and no leaf should have to read the setting.
+        .gamepadPaletteInk()
     }
 
     @ViewBuilder private func content(for size: CGSize) -> some View {
         // Fit the tallest poster into the height the detail line + paddings leave (the hints are a
         // safe-area inset, already out of this budget) — capped so it never dwarfs a large iPad and
         // clamped by width on a narrow screen.
-        let reserved: CGFloat = compact ? 72 : 96 // detail line + spacers
+        let reserved: CGFloat = (compact ? 72 : 96) + (showsGroupHeading ? 26 : 0)
         let coverHeight = min(360, min(max(140, size.height - reserved), size.width * 0.9))
         let coverWidth = coverHeight * 2 / 3
 
         VStack(spacing: 0) {
             Spacer(minLength: 4)
+            if showsGroupHeading {
+                groupHeading.padding(.bottom, 6)
+            }
             carousel(coverWidth: coverWidth, coverHeight: coverHeight)
             detailPanel
                 .padding(.top, 12)
@@ -89,10 +96,12 @@ struct LibraryCoverflowView: View {
         PosterImage(candidates: game.art.posterCandidates, title: game.title, session: imageSession)
             .frame(width: width, height: height)
             .clipShape(RoundedRectangle(cornerRadius: 16, style: .continuous))
-            .overlay(alignment: .topLeading) { StoreBadge(isCustom: game.isCustom) }
+            .overlay(alignment: .topLeading) {
+                StoreBadge(label: game.storeLabel, isLauncher: game.isLauncher)
+            }
             .overlay {
                 RoundedRectangle(cornerRadius: 16, style: .continuous)
-                    .strokeBorder(.white.opacity(0.12), lineWidth: 1)
+                    .strokeBorder(ink.fg(0.12), lineWidth: 1)
             }
             .shadow(color: .black.opacity(0.5), radius: 16, y: 12)
             .scrollTransition { content, phase in
@@ -112,21 +121,42 @@ struct LibraryCoverflowView: View {
             }
     }
 
+    /// Does this library have both groups? Only then does the heading earn its row — a
+    /// launcher-less library gets exactly the layout it had before design D4.
+    private var showsGroupHeading: Bool {
+        games.contains(where: \.isLauncher) && games.contains { !$0.isLauncher }
+    }
+
+    /// Which group the cursor is in. A coverflow is one-dimensional, so instead of a second focus
+    /// rail (a whole new up/down nav model for two or three tiles) the heading names the group and
+    /// changes as the selection crosses the boundary — the launcher entries lead the strip.
+    private var groupHeading: some View {
+        let selected = games.first { $0.id == selection }
+        return Text(selected?.isLauncher == true ? "LAUNCHERS" : "GAMES")
+            .font(.geist(11, .semibold, relativeTo: .caption2))
+            .tracking(1.4)
+            .foregroundStyle(ink.fg(0.45))
+    }
+
     /// The centered title + store tag — empty (not hidden) so the layout doesn't jump.
     @ViewBuilder private var detailPanel: some View {
         let game = games.first { $0.id == selection }
         VStack(spacing: 6) {
             Text(game?.title ?? " ")
                 .font(.geist(compact ? 22 : 25, .bold, relativeTo: .title))
-                .foregroundStyle(.white)
+                .foregroundStyle(ink.fg)
                 .lineLimit(1)
                 .minimumScaleFactor(0.75)
                 .multilineTextAlignment(.center)
             if let game {
-                Text(game.isCustom ? "CUSTOM" : "STEAM")
-                    .font(.geist(11, .semibold, relativeTo: .caption2))
-                    .tracking(1.2)
-                    .foregroundStyle(.white.opacity(0.5))
+                // main's richer store label, in the palette's ink.
+                Text(
+                    game.isLauncher
+                        ? "\(game.storeLabel.uppercased()) · LAUNCHER" : game.storeLabel.uppercased()
+                )
+                .font(.geist(11, .semibold, relativeTo: .caption2))
+                .tracking(1.2)
+                .foregroundStyle(ink.fg(0.5))
             }
         }
         .frame(maxWidth: .infinity)
@@ -139,7 +169,10 @@ struct LibraryCoverflowView: View {
     private var hints: [GamepadHint] {
         var hints: [GamepadHint] = []
         if onLaunch != nil {
-            hints.append(.init(glyph: buttonGlyph(\.buttonA, fallback: "a.circle"), text: "Launch"))
+            // You *open* a launcher and *launch* a game — the hint follows the focused entry.
+            let opens = games.first { $0.id == selection }?.isLauncher == true
+            hints.append(
+                .init(glyph: buttonGlyph(\.buttonA, fallback: "a.circle"), text: opens ? "Open" : "Launch"))
         }
         hints.append(.init(glyph: buttonGlyph(\.buttonB, fallback: "b.circle"), text: "Close"))
         return hints

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

@@ -80,21 +80,47 @@ struct LibraryView: View {
     }
 
     private var grid: some View {
-        ScrollView {
-            LazyVGrid(columns: columns, spacing: 18) {
-                ForEach(games) { game in
-                    if let onLaunch {
-                        Button { onLaunch(game.id) } label: { GameCard(game: game, imageSession: imageSession) }
-                            .buttonStyle(.plain)
-                    } else {
-                        GameCard(game: game, imageSession: imageSession)
-                    }
+        // Design D4: launcher entries get their own section above the titles, never interleaved.
+        // Both headers appear only when both groups exist, so a library without launcher entries
+        // renders exactly as it did before.
+        let launchers = games.filter(\.isLauncher)
+        let titles = games.filter { !$0.isLauncher }
+        let both = !launchers.isEmpty && !titles.isEmpty
+        return ScrollView {
+            VStack(alignment: .leading, spacing: 18) {
+                if !launchers.isEmpty {
+                    if both { sectionHeader("Launchers") }
+                    tiles(launchers)
+                }
+                if !titles.isEmpty {
+                    if both { sectionHeader("Games") }
+                    tiles(titles)
                 }
             }
             .padding()
         }
     }
 
+    private func tiles(_ entries: [GameEntry]) -> some View {
+        LazyVGrid(columns: columns, spacing: 18) {
+            ForEach(entries) { game in
+                if let onLaunch {
+                    Button { onLaunch(game.id) } label: { GameCard(game: game, imageSession: imageSession) }
+                        .buttonStyle(.plain)
+                } else {
+                    GameCard(game: game, imageSession: imageSession)
+                }
+            }
+        }
+    }
+
+    private func sectionHeader(_ text: String) -> some View {
+        Text(text)
+            .font(.geist(12, .semibold, relativeTo: .caption))
+            .tracking(1.1)
+            .foregroundStyle(.secondary)
+    }
+
     private var columns: [GridItem] {
         #if os(tvOS)
         let minW: CGFloat = 220
@@ -152,12 +178,15 @@ struct LibraryView: View {
             return
         }
         do {
+            // `launchersFirst` groups launcher entries ahead of titles once, here, so the grid and
+            // the gamepad coverflow both inherit the D4 ordering.
             games = try await LibraryClient.fetch(
                 address: current.address,
                 port: current.effectiveMgmtPort,
                 certPEM: identity.certPEM,
                 keyPEM: identity.keyPEM,
-                hostFingerprint: current.pinnedSHA256)
+                hostFingerprint: current.pinnedSHA256
+            ).launchersFirst
             imageSession?.finishTasksAndInvalidate()
             imageSession = try LibraryImageLoader.session(
                 address: current.address,
@@ -185,7 +214,9 @@ private struct GameCard: View {
                 .aspectRatio(2.0 / 3.0, contentMode: .fit)
                 .frame(maxWidth: .infinity)
                 .clipShape(RoundedRectangle(cornerRadius: 10, style: .continuous))
-                .overlay(alignment: .topLeading) { StoreBadge(isCustom: game.isCustom) }
+                .overlay(alignment: .topLeading) {
+                    StoreBadge(label: game.storeLabel, isLauncher: game.isLauncher)
+                }
             Text(game.title)
                 .font(.geist(12, relativeTo: .caption))
                 .lineLimit(2)

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

@@ -12,14 +12,21 @@ import AppKit
 /// The store-provenance badge (Steam vs. a user-curated custom entry) overlaid on a poster —
 /// shared by the touch grid's `GameCard` and the gamepad coverflow's cover cell.
 struct StoreBadge: View {
-    let isCustom: Bool
+    /// Which store surfaced the entry, already resolved to a display name (`GameEntry.storeLabel`).
+    let label: String
+    /// A launcher entry (design D4) gets the brand fill, so "opens Steam" is legible at poster size
+    /// without reading the title.
+    var isLauncher: Bool = false
 
     var body: some View {
-        Text(isCustom ? "Custom" : "Steam")
+        Text(label)
             .font(.geist(11, .semibold, relativeTo: .caption2))
+            .foregroundStyle(isLauncher ? AnyShapeStyle(.white) : AnyShapeStyle(.primary))
             .padding(.horizontal, 6)
             .padding(.vertical, 3)
-            .background(.ultraThinMaterial, in: Capsule())
+            .background(
+                isLauncher ? AnyShapeStyle(Color.brand) : AnyShapeStyle(.ultraThinMaterial),
+                in: Capsule())
             .padding(6)
     }
 }

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

@@ -24,6 +24,13 @@ import ImageIO
 
 @MainActor
 enum ScreenshotMode {
+    /// This process was launched to capture a screenshot. Cheap enough to consult from the
+    /// stores' persistence paths (`HostStore` / `ProfileStore`), which must NOT write their
+    /// mock contents back into a real user's App Group when the harness runs on a dev Mac.
+    static var isActive: Bool {
+        !(ProcessInfo.processInfo.environment["PUNKTFUNK_SHOT_SCENE"] ?? "").isEmpty
+    }
+
     /// The scene requested via PUNKTFUNK_SHOT_SCENE, or nil for a normal launch.
     static var requestedScene: ShotScene? {
         let name = ProcessInfo.processInfo.environment["PUNKTFUNK_SHOT_SCENE"] ?? ""
@@ -41,8 +48,11 @@ struct ScreenshotHostView: View {
         scene.make()
             .environment(\.colorScheme, scene.colorScheme)
             .frame(maxWidth: .infinity, maxHeight: .infinity)
-            .background(Color.black)
-            .ignoresSafeArea()
+            // Black fills the display, but the SCENE keeps its safe area. Ignoring it wholesale
+            // here pushed the stream hero's HUD under the Dynamic Island (the resolution/bitrate
+            // line was unreadable in every 6.9" capture); scenes that genuinely want full bleed —
+            // the streamed frame itself — ignore it themselves.
+            .background(Color.black.ignoresSafeArea())
             #if os(macOS)
             .background(MacShotWindowConfigurator(scene: scene))
             #elseif os(iOS)
@@ -129,18 +139,64 @@ enum MacSelfCapture {
 #endif
 
 #if os(iOS)
-/// Best-effort orientation lock for the requested scene (landscape for the stream hero, portrait
-/// for chrome). Requires the app to allow those orientations in Info.plist.
+/// Orientation lock for the requested scene (landscape for the stream hero, portrait for chrome).
+/// Requires the app to allow those orientations in Info.plist — it does, for both.
 private struct IOSOrientationConfigurator: UIViewControllerRepresentable {
     let orientation: ShotOrientation
 
-    func makeUIViewController(context: Context) -> UIViewController { UIViewController() }
+    func makeUIViewController(context: Context) -> ShotOrientationController {
+        ShotOrientationController(mask: mask)
+    }
 
-    func updateUIViewController(_ vc: UIViewController, context: Context) {
-        guard let scene = vc.view.window?.windowScene else { return }
-        let mask: UIInterfaceOrientationMask = orientation == .landscape ? .landscapeRight : .portrait
-        scene.requestGeometryUpdate(.iOS(interfaceOrientations: mask))
-        vc.setNeedsUpdateOfSupportedInterfaceOrientations()
+    func updateUIViewController(_ vc: ShotOrientationController, context: Context) {
+        vc.mask = mask
+        vc.applyGeometry()
+    }
+
+    private var mask: UIInterfaceOrientationMask {
+        orientation == .landscape ? .landscapeRight : .portrait
+    }
+}
+
+/// Asks the window scene to rotate, from a place where there IS a window.
+///
+/// The previous version made the request inside `updateUIViewController`, where `view.window` is
+/// still nil: SwiftUI makes exactly one update pass for a representable mounted as a `.background`,
+/// before the hierarchy is in a window, so the `guard` fell through and nothing ever asked again.
+/// Every scene declared `.landscape` — the stream hero and the trust card — was therefore captured
+/// in PORTRAIT at the portrait App Store size. Overriding `supportedInterfaceOrientations` as well
+/// keeps the scene from rotating back if the simulator reports a device orientation change.
+final class ShotOrientationController: UIViewController {
+    var mask: UIInterfaceOrientationMask
+
+    init(mask: UIInterfaceOrientationMask) {
+        self.mask = mask
+        super.init(nibName: nil, bundle: nil)
+    }
+
+    @available(*, unavailable)
+    required init?(coder: NSCoder) { fatalError("not from a nib") }
+
+    override var supportedInterfaceOrientations: UIInterfaceOrientationMask { mask }
+
+    override func viewDidAppear(_ animated: Bool) {
+        super.viewDidAppear(animated)
+        applyGeometry()
+    }
+
+    func applyGeometry() {
+        // `view.window` once mounted; the connected-scene lookup covers the first update pass,
+        // which still runs before this controller is in a window.
+        let scene = view.window?.windowScene
+            ?? UIApplication.shared.connectedScenes.compactMap { $0 as? UIWindowScene }.first
+        guard let scene else { return }
+        // Report a refusal instead of silently shipping the wrong orientation — that is exactly
+        // how every landscape scene went out as a portrait PNG for as long as it did.
+        scene.requestGeometryUpdate(.iOS(interfaceOrientations: mask)) { error in
+            print("PF_SHOT_ORIENTATION_REFUSED \(error.localizedDescription)")
+            fflush(stdout)
+        }
+        setNeedsUpdateOfSupportedInterfaceOrientations()
     }
 }
 #endif

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

@@ -81,24 +81,126 @@ enum ShotScenes {
 
 @MainActor
 enum ShotMock {
-    /// A populated saved-host grid: a pinned recent host, a couple more, mixed online state.
+    // Stable ids so the store, the adverts and the profile bindings all point at the same things
+    // across every scene and every run.
+    static let battlestationID = UUID(uuidString: "5B0D1E00-0000-4000-8000-000000000001")!
+    static let livingRoomID = UUID(uuidString: "5B0D1E00-0000-4000-8000-000000000002")!
+    static let workshopID = UUID(uuidString: "5B0D1E00-0000-4000-8000-000000000003")!
+    static let officeID = UUID(uuidString: "5B0D1E00-0000-4000-8000-000000000004")!
+    static let editingID = UUID(uuidString: "5B0D1E00-0000-4000-8000-000000000005")!
+    static let bedroomID = UUID(uuidString: "5B0D1E00-0000-4000-8000-000000000006")!
+
+    static let hdrProfileID = "a71c4e0d9f22"
+    static let couchProfileID = "3e88b107c4da"
+
+    /// The catalog the host cards read their chips and pinned cards from. Seeded once, on the
+    /// first store build — `ProfileStore` is a singleton, and in shot mode its write-back is
+    /// suppressed, so this never reaches a real user's catalog.
+    static func installProfiles() {
+        guard !profilesInstalled else { return }
+        profilesInstalled = true
+        ProfileStore.shared.debugSet([
+            StreamProfile(name: "4K HDR", id: hdrProfileID, accent: "#8B7BF7"),
+            StreamProfile(name: "Couch 1080p", id: couchProfileID, accent: "#4FD1A5"),
+        ])
+    }
+
+    private static var profilesInstalled = false
+
+    /// A populated saved-host grid: the most-recent host bound to a profile (its chip), a second
+    /// paired machine, and one asleep box we hold a MAC for (so its card offers Wake-on-LAN). OS
+    /// chains give every tile its real vendor mark instead of a letter monogram.
+    ///
+    /// No PINNED host+profile card: it renders a second tile for the SAME host, which is the
+    /// feature working as designed but reads as a duplicate to anyone meeting the app in a store
+    /// listing. The binding chip carries the profile story on its own.
     static func hostStore() -> HostStore {
+        installProfiles()
         let store = HostStore()
         store.hosts = [
-            StoredHost(name: "Battlestation", address: "192.168.1.20", port: 9777,
-                       pinnedSHA256: fingerprint, lastConnected: Date().addingTimeInterval(-420)),
-            StoredHost(name: "Living Room PC", address: "192.168.1.41", port: 9777,
-                       pinnedSHA256: fingerprint),
-            StoredHost(name: "Workshop", address: "10.0.0.7", port: 9777),
+            StoredHost(
+                id: battlestationID, name: "Battlestation", address: "192.168.1.20", port: 9777,
+                pinnedSHA256: fingerprint, lastConnected: Date().addingTimeInterval(-420),
+                macAddresses: ["a4:b1:c2:d3:e4:f5"], profileID: hdrProfileID,
+                osChain: "windows/11"),
+            StoredHost(
+                id: livingRoomID, name: "Living Room PC", address: "192.168.1.41", port: 9777,
+                pinnedSHA256: hostFingerprint(1), lastConnected: Date().addingTimeInterval(-86_400),
+                macAddresses: ["b8:27:eb:11:22:33"], osChain: "linux/fedora/bazzite"),
+            StoredHost(
+                id: officeID, name: "Office NUC", address: "192.168.1.33", port: 9777,
+                pinnedSHA256: hostFingerprint(4), lastConnected: Date().addingTimeInterval(-259_200),
+                profileID: couchProfileID, osChain: "linux/ubuntu"),
+            StoredHost(
+                id: workshopID, name: "Workshop", address: "10.0.0.7", port: 9777,
+                pinnedSHA256: hostFingerprint(2), macAddresses: ["de:ad:be:ef:00:07"],
+                osChain: "linux/arch"),
+            StoredHost(
+                id: editingID, name: "Editing Rig", address: "192.168.1.62", port: 9777,
+                pinnedSHA256: hostFingerprint(5), lastConnected: Date().addingTimeInterval(-604_800),
+                osChain: "linux/nobara"),
+            StoredHost(
+                id: bedroomID, name: "Bedroom Mini", address: "192.168.1.77", port: 9777,
+                pinnedSHA256: hostFingerprint(6), macAddresses: ["00:1a:2b:3c:4d:5e"],
+                osChain: "windows/11"),
         ]
         return store
     }
 
-    static let host = StoredHost(name: "Battlestation", address: "192.168.1.20", port: 9777,
-                                 pinnedSHA256: fingerprint)
+    /// Discovery, seeded rather than live. Two saved hosts advertise (so their cards read ONLINE
+    /// through the real `advertises` path, and the reachability probe skips them — no network from
+    /// a capture), "Workshop" stays quiet so the grid shows an asleep machine, and one genuinely
+    /// new host populates the "On this network" section.
+    ///
+    /// A live browse made the shot non-deterministic AND leaked whatever was on the capturing
+    /// machine's LAN into the App Store listing.
+    static func discovery() -> HostDiscovery {
+        let discovery = HostDiscovery()
+        discovery.debugSet([
+            HostDiscovery.debugAdvert(
+                id: "battlestation", name: "Battlestation", host: "192.168.1.20",
+                fingerprintHex: fingerprint.hexLower, macAddresses: ["a4:b1:c2:d3:e4:f5"],
+                osChain: "windows/11"),
+            HostDiscovery.debugAdvert(
+                id: "living-room", name: "Living Room PC", host: "192.168.1.41",
+                fingerprintHex: hostFingerprint(1).hexLower, macAddresses: ["b8:27:eb:11:22:33"],
+                osChain: "linux/fedora/bazzite"),
+            HostDiscovery.debugAdvert(
+                id: "office-nuc", name: "Office NUC", host: "192.168.1.33",
+                fingerprintHex: hostFingerprint(4).hexLower, osChain: "linux/ubuntu"),
+            HostDiscovery.debugAdvert(
+                id: "studio", name: "Studio PC", host: "192.168.1.58",
+                fingerprintHex: hostFingerprint(3).hexLower, requiresPairing: true, allowsTofu: false,
+                osChain: "windows/11"),
+        ])
+        return discovery
+    }
+
+    static let host = StoredHost(
+        id: battlestationID, name: "Battlestation", address: "192.168.1.20", port: 9777,
+        pinnedSHA256: fingerprint, osChain: "windows/11")
+
+    /// What the pairing sheet calls THIS device. Taken from the platform, not from
+    /// `UIDevice.current.name` — on a capture simulator that is the harness's own throwaway name
+    /// (`pf-shot-iphone-6.9` went out on the store listing that way).
+    static var clientDeviceName: String {
+        #if os(tvOS)
+        "Apple TV"
+        #elseif os(macOS)
+        "MacBook Pro"
+        #else
+        UIDevice.current.userInterfaceIdiom == .pad ? "iPad Pro" : "iPhone"
+        #endif
+    }
 
     /// A plausible-looking 32-byte SHA-256 for the trust card / pin lock glyphs.
-    static let fingerprint = Data((0..<32).map { UInt8(($0 &* 37 &+ 0x1d) & 0xff) })
+    static let fingerprint = hostFingerprint(0)
+
+    /// Distinct per host — `StoredHost.matches` prefers a fingerprint comparison, so sharing one
+    /// across the mock grid made a single advert light up every card.
+    static func hostFingerprint(_ seed: Int) -> Data {
+        Data((0..<32).map { UInt8((($0 &* 37) &+ 0x1d &+ (seed &* 91)) & 0xff) })
+    }
 }
 
 // MARK: - Home
@@ -106,7 +208,7 @@ enum ShotMock {
 private struct ShotHome: View {
     @StateObject private var store = ShotMock.hostStore()
     @StateObject private var model = SessionModel()
-    @StateObject private var discovery = HostDiscovery()
+    @StateObject private var discovery = ShotMock.discovery()
 
     var body: some View {
         #if os(macOS)
@@ -134,7 +236,7 @@ private struct ShotHome: View {
 private struct ShotGamepadHome: View {
     @StateObject private var store = ShotMock.hostStore()
     @StateObject private var model = SessionModel()
-    @StateObject private var discovery = HostDiscovery()
+    @StateObject private var discovery = ShotMock.discovery()
     @StateObject private var waker = HostWaker()
 
     var body: some View {
@@ -146,7 +248,9 @@ private struct ShotGamepadHome: View {
 }
 
 private struct ShotGamepadSettings: View {
-    var body: some View { GamepadSettingsView() }
+    @StateObject private var store = ShotMock.hostStore()
+
+    var body: some View { GamepadSettingsView(store: store) }
 }
 
 private struct ShotGamepadAddHost: View {
@@ -164,7 +268,7 @@ private struct ShotConnect: View {
 
     @StateObject private var store = ShotMock.hostStore()
     @StateObject private var model = SessionModel()
-    @StateObject private var discovery = HostDiscovery()
+    @StateObject private var discovery = ShotMock.discovery()
     @StateObject private var waker = HostWaker()
 
     var body: some View {
@@ -241,9 +345,9 @@ private struct ShotSettings: View {
         #elseif os(iOS)
         // SettingsView owns its NavigationSplitView (sidebar + detail) and Done button, so it is
         // rendered directly — a wrapping NavigationStack would nest a split view in a stack. Open
-        // on General so the shot lands on real controls (iPad: sidebar + General detail; iPhone:
-        // the General page) instead of the bare category list.
-        SettingsView(initialCategory: .general)
+        // on Display rather than the bare category list: resolution, frame rate, bitrate, HDR and
+        // codec are what someone reads a streaming app's settings shot to find out.
+        SettingsView(initialCategory: .display)
         #else
         NavigationStack { SettingsView() }
         #endif
@@ -253,16 +357,44 @@ private struct ShotSettings: View {
 // MARK: - Pair (PIN ceremony)
 
 private struct ShotPair: View {
+    /// The PIN as the host's web console shows it, and a device name that doesn't depend on what
+    /// the capture simulator happens to be called.
+    private var sheet: some View {
+        PairSheet(
+            host: ShotMock.host, shotPIN: "418 306",
+            shotClientName: ShotMock.clientDeviceName, onPaired: { _ in })
+    }
+
     var body: some View {
+        #if os(iOS)
+        // PRESENT it, don't rebuild it. `PairSheet` is a bottom sheet on iOS — it carries its own
+        // `.presentationDetents([.medium, .large])` and the system's Liquid Glass background, both
+        // of which only exist inside a real `.sheet`. Composed into a ZStack instead (what this
+        // scene used to do), the detents were inert, the grouped Form stretched to the full height
+        // of the screen, and the capture was a thin strip of content over a huge black void.
+        ShotHome()
+            .sheet(isPresented: .constant(true)) {
+                // Pinned to one detent. The sheet ships `[.medium, .large]` so it can grow over
+                // the keyboard, and the resting height leaves a wide empty band between the form
+                // and the button row; a capture wants the snug version.
+                sheet.presentationDetents([.fraction(0.52)])
+            }
+        #elseif os(tvOS)
+        // tvOS pushes the ceremony as a full screen (HomeView's `navigationDestination`).
+        NavigationStack { sheet }
+        #else
+        // macOS: a fixed-width panel (`.frame(width: 400).fixedSize()`) that hugs its content, so
+        // floating it over the dimmed grid matches how the window-modal sheet reads. `screencapture
+        // -l<windowID>` grabs one window, and an AppKit sheet is a child window — a real `.sheet`
+        // would fall outside the capture.
         ZStack {
             ShotHome().blur(radius: 28).overlay(Color.black.opacity(0.5))
-            PairSheet(host: ShotMock.host, onPaired: { _ in })
-                .frame(maxWidth: 460)
+            sheet
                 .background(.regularMaterial, in: RoundedRectangle(cornerRadius: 18))
                 .clipShape(RoundedRectangle(cornerRadius: 18))
                 .shadow(radius: 40, y: 16)
-                .padding(40)
         }
+        #endif
     }
 }
 

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

@@ -65,6 +65,14 @@ final class SessionModel: ObservableObject {
     @Published private(set) var connection: PunktfunkConnection?
     /// The host this session is for (a value copy; identity = id).
     @Published private(set) var activeHost: StoredHost?
+    /// The library entry this session was launched with (`connect(launchID:)`), or nil if the user
+    /// just connected to the host's desktop. Kept because where the client should go when the
+    /// session ends depends on where it came FROM: a title launched out of the library belongs back
+    /// in that library when its game exits, not on the host-selection screen.
+    private var launchedTitleID: String?
+    /// Set when a session ended because its game exited and it began as a library launch: the host
+    /// whose library to reopen. The view layer consumes it and sets it back to nil.
+    @Published var returnToLibrary: StoredHost?
     /// The settings THIS session runs on — the globals with its profile overlaid, resolved once at
     /// connect (design/client-settings-profiles.md §4.2). Also mirrored into `SessionSettings` for
     /// the readers that live in PunktfunkKit and can't see this model.
@@ -249,6 +257,7 @@ final class SessionModel: ObservableObject {
         guard phase == .idle else { return }
         phase = .connecting
         activeHost = host
+        launchedTitleID = launchID
         errorMessage = nil
         settings = effective
         statsVerbosity = StatsVerbosity(rawValue: effective.statsVerbosity) ?? .normal
@@ -607,6 +616,8 @@ final class SessionModel: ObservableObject {
         }
         connection = nil
         activeHost = nil
+        // Read by `sessionEnded` BEFORE it calls us, so clearing here can't rob it of the answer.
+        launchedTitleID = nil
         phase = .idle
         fps = 0
         mbps = 0
@@ -626,10 +637,36 @@ final class SessionModel: ObservableObject {
 
     /// Called (via the main actor) when the pump hits end-of-session.
     func sessionEnded() {
-        guard connection != nil else { return }
+        guard let conn = connection else { return }
         let name = activeHost?.displayName ?? "host"
+        // WHY it ended, asked while the connection is still up — `disconnect` tears it down.
+        let reason = conn.sessionEndReason
+        // Where a game exit sends us: back into the library this title was launched from, so the
+        // next one is a tap away. Only for a launch that CAME from the library — a game exiting in
+        // a plain desktop session has no library to return to.
+        let host = activeHost
+        let cameFromLibrary = launchedTitleID != nil
         disconnect(deliberate: false) // host/network ended it — keep the linger for a reconnect
-        errorMessage = "Session ended by \(name)."
+        switch reason {
+        case .gameExited:
+            // The player quit their own game. Not a failure, and they are probably after the next
+            // title — so no banner, and back to the library it came from.
+            if cameFromLibrary, let host {
+                returnToLibrary = host
+            }
+        case .hostEnded, .local:
+            // Someone asked for this: an operator "End" on the host, or our own close racing in.
+            // Say it plainly, without the error framing.
+            errorMessage = "\(name) ended the session."
+        case .hostError:
+            errorMessage = "\(name) ended the session with an error."
+        case .lost:
+            errorMessage = "Lost the connection to \(name)."
+        case .none:
+            // No verdict (an older core, or the close raced the read): keep the wording this path
+            // has always used rather than inventing one.
+            errorMessage = "Session ended by \(name)."
+        }
     }
 
     /// Resize overlay START (main actor — from the Match-window follower's `onResizeTarget`): the
@@ -675,8 +712,13 @@ final class SessionModel: ObservableObject {
         // `gamepadForwarding` off means the host gets this device's pads from somewhere else
         // (USB passthrough, or a pad plugged into the host) — capture still runs, and still
         // watches for the escape chord, but puts nothing on the wire.
+        // System-button routing: whether raw guide/share presses ride the wire, and whether
+        // hold-Select arms as the alternate guide route (auto = on everywhere but macOS —
+        // iOS reserves the physical Home press, tvOS never delivers it).
         let capture = GamepadCapture(
-            connection: conn, manager: .shared, forwarding: settings.gamepadForwarding)
+            connection: conn, manager: .shared, forwarding: settings.gamepadForwarding,
+            systemForward: settings.systemButtonsForward,
+            guideGesture: settings.guideGestureEnabled)
         // 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() }

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

@@ -10,6 +10,20 @@
 // on stale captured state. Left/right CLAMPS at a choice list's ends (the dull boundary thud tells
 // the thumb it's the last option); A always cycles forward, wrapping, so every option is reachable
 // with one button. Toggles read left = off, right = on — refusing a no-op with the same thud.
+//
+// The rows are split across SECTION TABS (`GpSettingsTab`) — L1/R1 on a pad, a tap elsewhere. They
+// used to be one long scroll with inline group headers, which meant thumbing past Video and Audio
+// to reach the controller settings; a tab is one shoulder press, and each tab remembers where its
+// focus was. The tab names match the desktop console's and the Android client's, so a setting is
+// found under the same word wherever you look for it.
+//
+// The trailing Profiles tab (design/client-settings-profiles.md §5.2a/§5.4) is the pin manager
+// for this controller-first surface: a row per catalog profile opens the pin-to-hosts picker — an
+// in-place swap of the row list (B peels back, the "one layer" rule GamepadAddHostView set) with
+// one toggle row per saved host, writing `StoredHost.pinnedProfileIDs` via HostStore.setPinned.
+// Pins are presentation only: never the host's default binding, never the profile itself —
+// profiles are created and edited in the standard interface (and can't be on tvOS, whose
+// per-device catalog the detail strings are honest about).
 
 import PunktfunkKit
 import SwiftUI
@@ -19,14 +33,32 @@ import GameController
 import CoreHaptics
 #endif
 
+/// The settings screen's sections. Order IS the strip order and the L1/R1 cycle order; the names
+/// match `pf-console-ui`'s `TABS` and the Android client's `GpTab`.
+enum GpSettingsTab: String, CaseIterable, Hashable {
+    case stream = "Stream"
+    case video = "Video"
+    case audio = "Audio"
+    case controller = "Controller"
+    case interface = "Interface"
+    case profiles = "Profiles"
+}
+
 struct GamepadSettingsView: View {
+    @Environment(\.gamepadInk) private var ink
     @Environment(\.dismiss) private var dismiss
+    /// The saved-host store — the pin picker writes `setPinned` through it and the profile rows
+    /// count pins from its live hosts. Threaded in from GamepadHomeView like the home screen
+    /// itself (ContentView owns the instance).
+    @ObservedObject var store: HostStore
     @AppStorage(DefaultsKey.streamWidth) private var width = 1920
     @AppStorage(DefaultsKey.streamHeight) private var height = 1080
     @AppStorage(DefaultsKey.streamHz) private var hz = 60
     @AppStorage(DefaultsKey.compositor) private var compositor = 0
     @AppStorage(DefaultsKey.gamepadType) private var gamepadType = 0
     @AppStorage(DefaultsKey.gamepadForwarding) private var gamepadForwarding = true
+    @AppStorage(DefaultsKey.systemButtons) private var systemButtons = "auto"
+    @AppStorage(DefaultsKey.guideGesture) private var guideGesture = "auto"
     @AppStorage(DefaultsKey.bitrateKbps) private var bitrateKbps = 0
     @AppStorage(DefaultsKey.audioChannels) private var audioChannels = 2
     @AppStorage(DefaultsKey.hdrEnabled) private var hdrEnabled = true
@@ -41,6 +73,9 @@ struct GamepadSettingsView: View {
     @AppStorage(DefaultsKey.hudPlacement) private var hudPlacement = HUDPlacement.topTrailing.rawValue
     @AppStorage(DefaultsKey.libraryEnabled) private var libraryEnabled = true
     @AppStorage(DefaultsKey.gamepadUIEnabled) private var gamepadUIEnabled = true
+    /// The gamepad UI's background colour family — the backdrop BEHIND this screen re-colours as
+    /// the row steps, which is why the picker lives here and not in a sheet.
+    @AppStorage(DefaultsKey.uiPalette) private var paletteID = "violet"
     @AppStorage(DefaultsKey.autoWake) private var autoWakeEnabled = true
     @AppStorage(DefaultsKey.presentPriority) private var presentPriority =
         SettingsOptions.presentPriorityDefault
@@ -52,16 +87,34 @@ struct GamepadSettingsView: View {
     @AppStorage(DefaultsKey.rumbleOnDevice) private var rumbleOnDevice = false
     #endif
     @ObservedObject private var gamepads = GamepadManager.shared
+    /// The profile catalog (ProfileStore.shared, like every other surface that reads it) — the
+    /// Profiles rows re-derive from it each render, so a rename/delete made in the standard
+    /// interface shows up live.
+    @ObservedObject private var profiles = ProfileStore.shared
 
     #if os(iOS)
     /// `.compact` in a landscape phone window — tighter chrome so more rows fit.
     @Environment(\.verticalSizeClass) private var vSizeClass
+    /// `.regular` only on an iPad-class window — see `showsSectionHint`.
+    @Environment(\.horizontalSizeClass) private var hSizeClass
 
     private var compact: Bool { vSizeClass == .compact }
     #else
     private let compact = false // no size classes on macOS; the sheet is sized generously
     #endif
     @State private var focusID: String?
+    /// The section showing. The pin picker ignores it — that layer replaces the whole list.
+    @State private var tab: GpSettingsTab = .stream
+    /// Where each tab's focus was when it was last left, so a detour doesn't lose your place.
+    @State private var tabFocus: [GpSettingsTab: String] = [:]
+    @Namespace private var tabHighlight
+    #if os(tvOS)
+    /// Real focus on the strip — the tvOS route to the sections (see `tabStrip`).
+    @FocusState private var focusedTab: GpSettingsTab?
+    #endif
+    /// The pin-to-hosts picker's profile — non-nil swaps the row list for one toggle row per
+    /// saved host (§5.2a); B (Menu on tvOS) peels back to the settings rows.
+    @State private var pinTarget: StreamProfile?
     /// The direction of the last value step (+1 right/forward, -1 left) — picks which edge the
     /// changed value slides in from, so the animation follows the user's motion.
     @State private var lastAdjustDelta = 1
@@ -72,7 +125,8 @@ struct GamepadSettingsView: View {
             focusID: $focusID,
             onAdjust: { row, delta in adjust(id: row.id, by: delta) },
             onActivate: { activate(id: $0.id) },
-            onBack: { dismiss() }
+            onBack: { back() },
+            onShoulder: { step(tabBy: $0) }
         ) { row, focused in
             rowView(row, focused: focused)
                 .frame(maxWidth: GamepadFormMetrics.rowMaxWidth)
@@ -80,27 +134,28 @@ struct GamepadSettingsView: View {
         }
         .frame(maxWidth: .infinity)
         .safeAreaInset(edge: .top, spacing: 0) {
-            Text("Settings")
-                .font(.geist(gamepadTitleSize(compact: compact), .bold, relativeTo: .title))
-                .foregroundStyle(.white)
-                .padding(.top, gamepadTitleTopPadding(compact: compact))
-                .padding(.bottom, compact ? 4 : 8)
-                .frame(maxWidth: .infinity)
-                .overlay(alignment: .trailing) { closeButton.padding(.trailing, 20) }
-                .background { GamepadTrayScrim(edge: .top) }
+            VStack(spacing: compact ? 4 : 8) {
+                Text(title)
+                    .font(.geist(gamepadTitleSize(compact: compact), .bold, relativeTo: .title))
+                    .foregroundStyle(ink.fg)
+                    .frame(maxWidth: .infinity)
+                    .overlay(alignment: .trailing) { closeButton.padding(.trailing, 20) }
+                // The picker is one layer deeper — its rows aren't sections of anything, so the
+                // strip would be a control that does nothing while it's up.
+                if pinTarget == nil { tabStrip }
+            }
+            .padding(.top, gamepadTitleTopPadding(compact: compact))
+            .padding(.bottom, compact ? 4 : 8)
+            .background { GamepadTrayScrim(edge: .top) }
         }
         .safeAreaInset(edge: .bottom, alignment: .leading, spacing: 0) {
             VStack(alignment: .leading, spacing: 8) {
                 Text(focusedDetail)
                     .font(.geist(GamepadFormMetrics.detailFont, relativeTo: .caption))
-                    .foregroundStyle(.white.opacity(0.55))
+                    .foregroundStyle(ink.fg(0.55))
                     .lineLimit(2, reservesSpace: true)
                     .animation(.smooth(duration: 0.2), value: focusID)
-                GamepadHintBar(hints: [
-                    .init(glyph: "arrow.left.and.right", text: "Adjust"),
-                    .init(glyph: buttonGlyph(\.buttonA, fallback: "a.circle"), text: "Change"),
-                    .init(glyph: buttonGlyph(\.buttonB, fallback: "b.circle"), text: "Done"),
-                ])
+                GamepadHintBar(hints: hints)
             }
             // Equal distance from the left and bottom edges for the legend pill (see GamepadHomeView).
             .padding(.leading, compact ? 12 : 18)
@@ -110,9 +165,13 @@ struct GamepadSettingsView: View {
             .frame(maxWidth: .infinity, alignment: .leading)
             .background { GamepadTrayScrim(edge: .bottom) }
         }
-        // No aurora here — the settings read as clean Liquid Glass over a quiet dark base, so the
-        // glass rows are the only material on the screen.
+        // The launcher's living field, calmed (GamepadFormBackground) — the glass rows keep real
+        // colour and luminance to lens without the launcher's contrast, and the palette setting
+        // applies here too, so this screen previews the row you're stepping.
         .background { GamepadFormBackground() }
+        // Publish the palette's ink to this screen (text, glass, accent, scrims) — a
+        // pale palette flips all of them, and no leaf should have to read the setting.
+        .gamepadPaletteInk()
         .onAppear {
             gamepads.refresh()
             gamepads.startDiscovery()
@@ -120,13 +179,108 @@ struct GamepadSettingsView: View {
         .onDisappear { gamepads.stopDiscovery() }
     }
 
+    /// The section switcher. Horizontally scrollable so a narrow phone in landscape never has to
+    /// squeeze six pills — the selected one is always scrolled into view, whether it was reached
+    /// by shoulder button, tap, or (tvOS) the focus engine.
+    private var tabStrip: some View {
+        ScrollViewReader { proxy in
+            ScrollView(.horizontal) {
+                HStack(spacing: 6) {
+                    ForEach(GpSettingsTab.allCases, id: \.self) { t in
+                        #if os(tvOS)
+                        // Focusable, because L1/R1 is NOT a route here: a Siri Remote has no
+                        // extended gamepad profile, so it never reaches GamepadMenuList's poll.
+                        // As focusable Buttons the pills are simply above the rows, and moving
+                        // focus up onto one switches section — the standard tvOS tab bar.
+                        Button { select(tab: t) } label: { pill(t) }
+                            .buttonStyle(ConsoleBareButtonStyle())
+                            .focused($focusedTab, equals: t)
+                            .id(t)
+                        #else
+                        pill(t)
+                            .contentShape(Capsule())
+                            .onTapGesture { select(tab: t) }
+                            .id(t)
+                        #endif
+                    }
+                }
+                .padding(.horizontal, 24)
+            }
+            .scrollIndicators(.never)
+            .animation(.smooth(duration: 0.22), value: tab)
+            .onChange(of: tab) { _, t in
+                withAnimation(.easeOut(duration: 0.2)) { proxy.scrollTo(t) }
+            }
+            #if os(tvOS)
+            .onChange(of: focusedTab) { _, t in
+                // Focus IS selection on a tab bar; nil means focus dropped back into the rows.
+                if let t { select(tab: t) }
+            }
+            #endif
+        }
+    }
+
+    private func pill(_ t: GpSettingsTab) -> some View {
+        let selected = t == tab
+        return Text(t.rawValue)
+            .font(.geist(compact ? 12 : 13, .semibold, relativeTo: .footnote))
+            .foregroundStyle(selected ? ink.fg : ink.fg(0.55))
+            .padding(.horizontal, 13)
+            .padding(.vertical, 7)
+            .background {
+                // One shared capsule that MOVES between pills, rather than one per pill fading
+                // in and out — the highlight travels the way the press did.
+                if selected {
+                    Capsule()
+                        .fill(ink.accent(0.85))
+                        .matchedGeometryEffect(id: "tab", in: tabHighlight)
+                }
+            }
+    }
+
+    /// Whether the legend advertises the shoulder shortcut. Held back on an iPhone, whose legend
+    /// is already at its width and would push "Done" off the edge — the strip is visible and
+    /// tappable there anyway. Never on tvOS: a Siri Remote has no shoulders, and its route to the
+    /// sections is the focus engine (see `tabStrip`).
+    private var showsSectionHint: Bool {
+        #if os(tvOS)
+        false
+        #elseif os(iOS)
+        hSizeClass == .regular
+        #else
+        true
+        #endif
+    }
+
+    /// L1/R1 — one section along, wrapping (the strip is a ring, like A's value cycle).
+    private func step(tabBy delta: Int) {
+        guard pinTarget == nil else { return }
+        let all = GpSettingsTab.allCases
+        guard let i = all.firstIndex(of: tab) else { return }
+        let n = all.count
+        select(tab: all[((i + delta) % n + n) % n])
+    }
+
+    private func select(tab next: GpSettingsTab) {
+        guard next != tab else { return }
+        tabFocus[tab] = focusID
+        // Restore where this tab was, if that row is still in it (a row can come and go with the
+        // hardware it depends on); otherwise the focus list seeds its first row. Resolved against
+        // `allRows` rather than `rows` so it doesn't depend on `tab`'s write being visible yet.
+        let landing = tabFocus[next].flatMap { id in
+            allRows.contains { $0.tab == next && $0.id == id } ? id : nil
+        }
+        tab = next
+        focusID = landing
+    }
+
     /// Touch/click fallback for closing — the controller path is B, a hardware keyboard's Esc
     /// rides the cancel action.
     private var closeButton: some View {
         Button { dismiss() } label: {
             Image(systemName: "xmark")
                 .font(.system(size: GamepadFormMetrics.closeFont, weight: .semibold))
-                .foregroundStyle(.white)
+                .foregroundStyle(ink.fg)
                 .frame(width: GamepadFormMetrics.closeSide, height: GamepadFormMetrics.closeSide)
                 .glassBackground(Circle(), interactive: true)
                 .contentShape(Circle())
@@ -138,33 +292,77 @@ struct GamepadSettingsView: View {
         .accessibilityLabel("Close settings")
     }
 
+    /// "Settings", or "Pin “Work”" while the pin picker is up — the title is what says which
+    /// layer the row list currently is.
+    private var title: String {
+        pinTarget.map { "Pin “\($0.name)”" } ?? "Settings"
+    }
+
+    /// The legend follows the layer: value-editing hints on the settings rows, pin/unpin on the
+    /// picker — where B reads "Back" (it peels to the settings rows, GamepadAddHostView's "one
+    /// layer" rule), and a hostless picker has nothing to pin, so only Back remains.
+    private var hints: [GamepadHint] {
+        guard pinTarget != nil else {
+            // The shoulders change section, so that cell leads — where it fits and where the
+            // shoulders exist at all (see `showsSectionHint`).
+            let sections: [GamepadHint] = showsSectionHint
+                ? [.init(glyph: buttonGlyph(\.leftShoulder, fallback: "l1.rectangle.roundedbottom"),
+                         text: "Section")]
+                : []
+            // A dimmed row takes neither, so offering them would be the same lie the row itself
+            // used to tell — only Done remains, and the detail line says what to turn on first.
+            guard rows.first(where: { $0.id == focusID })?.enabled ?? true else {
+                return sections
+                    + [.init(glyph: buttonGlyph(\.buttonB, fallback: "b.circle"), text: "Done")]
+            }
+            return sections + [
+                .init(glyph: "arrow.left.and.right", text: "Adjust"),
+                .init(glyph: buttonGlyph(\.buttonA, fallback: "a.circle"), text: "Change"),
+                .init(glyph: buttonGlyph(\.buttonB, fallback: "b.circle"), text: "Done"),
+            ]
+        }
+        guard !store.hosts.isEmpty else {
+            return [.init(glyph: buttonGlyph(\.buttonB, fallback: "b.circle"), text: "Back")]
+        }
+        return [
+            .init(glyph: buttonGlyph(\.buttonA, fallback: "a.circle"), text: "Pin / Unpin"),
+            .init(glyph: buttonGlyph(\.buttonB, fallback: "b.circle"), text: "Back"),
+        ]
+    }
+
+    /// B peels one layer: the pin picker back to the settings rows — focus returning to the
+    /// profile row it came from — then the screen itself.
+    private func back() {
+        if let profile = pinTarget {
+            pinTarget = nil
+            focusID = "profile-\(profile.id)"
+        } else {
+            dismiss()
+        }
+    }
+
     // MARK: - Row rendering
 
     private func rowView(_ row: Row, focused: Bool) -> some View {
         let m = GamepadFormMetrics.self
+        // No section header: the tab strip names the section now, and repeating it above the
+        // first row of every tab was just a second label saying the same word.
         return VStack(alignment: .leading, spacing: 6) {
-            if let header = row.header {
-                Text(header)
-                    .font(.geist(m.headerFont, .semibold, relativeTo: .caption))
-                    .tracking(1.4)
-                    .foregroundStyle(.white.opacity(0.45))
-                    .padding(.leading, m.rowHPad)
-                    .padding(.top, 14)
-            }
             HStack(spacing: 14) {
                 Image(systemName: row.icon)
                     .font(.system(size: m.iconFont))
-                    .foregroundStyle(focused ? Color.brand : .white.opacity(0.55))
+                    .foregroundStyle(focused ? ink.accent : ink.fg(0.55))
                     .frame(width: m.iconWidth)
                 Text(row.label)
                     .font(.geist(m.labelFont, .semibold, relativeTo: .body))
-                    .foregroundStyle(.white)
+                    .foregroundStyle(ink.fg)
                     .lineLimit(1)
                 Spacer(minLength: 12)
                 HStack(spacing: 9) {
                     Image(systemName: "chevron.left")
                         .font(.system(size: m.chevronFont, weight: .semibold))
-                        .foregroundStyle(.white.opacity(focused ? 0.6 : 0))
+                        .foregroundStyle(
+                            ink.fg(focused && row.adjustable && row.enabled ? 0.6 : 0))
                     // Keyed by the value so a change slides the new option in instead of
                     // hard-swapping the string — a QUIET horizontal slip following the user's
                     // motion (a right-step enters from the right), crossfading over ~14 pt.
@@ -175,7 +373,7 @@ struct GamepadSettingsView: View {
                     ZStack {
                         Text(row.value)
                             .font(.geist(m.valueFont, .medium, relativeTo: .callout))
-                            .foregroundStyle(focused ? .white : .white.opacity(0.6))
+                            .foregroundStyle(focused ? ink.fg : ink.fg(0.6))
                             .lineLimit(1)
                             .id(row.value)
                             .transition(.asymmetric(
@@ -185,19 +383,23 @@ struct GamepadSettingsView: View {
                     .animation(.smooth(duration: 0.22), value: row.value)
                     Image(systemName: "chevron.right")
                         .font(.system(size: m.chevronFont, weight: .semibold))
-                        .foregroundStyle(.white.opacity(focused ? 0.6 : 0))
+                        .foregroundStyle(
+                            ink.fg(focused && row.adjustable && row.enabled ? 0.6 : 0))
                 }
             }
+            // Contents only — the glass and border below stay at full strength, so a dimmed row
+            // still reads as a row you can sit on (which you can: its detail is the point).
+            .opacity(row.enabled ? 1 : 0.45)
             .padding(.horizontal, m.rowHPad)
             .padding(.vertical, m.rowVPad)
             // Every row is Liquid Glass; the focused one takes a brand wash and reacts to press.
             .consoleGlass(
                 RoundedRectangle(cornerRadius: m.rowCorner, style: .continuous),
-                tint: focused ? Color.brand.opacity(0.30) : nil,
+                tint: focused ? ink.accent(0.30) : nil,
                 interactive: focused)
             .overlay {
                 RoundedRectangle(cornerRadius: m.rowCorner, style: .continuous)
-                    .strokeBorder(.white.opacity(focused ? 0.28 : 0.06), lineWidth: 1)
+                    .strokeBorder(ink.fg(focused ? 0.28 : 0.06), lineWidth: 1)
             }
             .scaleEffect(focused ? 1.0 : 0.98)
             .animation(.smooth(duration: 0.18), value: focused)
@@ -212,13 +414,24 @@ struct GamepadSettingsView: View {
 
     private struct Row: Identifiable {
         let id: String
-        /// Section header drawn above this row (the first row of each group carries it).
-        var header: String?
+        /// Which section tab this row belongs to. Every row has exactly one, and `rows` shows
+        /// only the current tab's — see `allRows`.
+        var tab: GpSettingsTab = .stream
         let icon: String
         let label: String
         let value: String
         /// One-line explanation shown near the hint bar while this row is focused.
         let detail: String
+        /// Whether left/right means anything here — false hides the value's chevrons (the
+        /// Profiles rows navigate, and the placeholder rows do nothing at all).
+        var adjustable = true
+        /// Dimmed and inert when false: a row whose meaning depends on another setting that is
+        /// currently off. It stays in the list and stays FOCUSABLE — its `detail` is how the
+        /// user learns which switch to flip first, and a row that vanished mid-list would
+        /// shift everything under the cursor. Enforced centrally in `adjust(id:by:)` /
+        /// `activate(id:)`, not per closure, so no row builder can forget it.
+        /// (Android's `GpRow.enabled` and `pf-console-ui`'s `RowSpec.enabled` are the twins.)
+        var enabled = true
         /// Left/right step; returns whether the value actually changed (false ⇒ boundary thud).
         let adjust: (Int) -> Bool
         /// A — cycle forward (wrapping) / flip.
@@ -229,15 +442,27 @@ struct GamepadSettingsView: View {
     /// (never on state captured at wire time).
     private func adjust(id: String, by delta: Int) -> Bool {
         lastAdjustDelta = delta
-        return rows.first { $0.id == id }?.adjust(delta) ?? false
+        guard let row = rows.first(where: { $0.id == id }), row.enabled else { return false }
+        return row.adjust(delta)
     }
 
     private func activate(id: String) {
         lastAdjustDelta = 1 // A always cycles forward
-        rows.first { $0.id == id }?.activate()
+        guard let row = rows.first(where: { $0.id == id }), row.enabled else { return }
+        row.activate()
     }
 
+    /// What the focus list actually shows: the current tab's rows — or the pin picker's, which
+    /// replaces the whole list while it's up (same screen, one layer deeper, so the focus list's
+    /// controller wiring and the tvOS focus engine carry over as is).
     private var rows: [Row] {
+        if let profile = pinTarget { return pinRows(for: profile) }
+        return allRows.filter { $0.tab == tab }
+    }
+
+    /// Every row on the screen, tagged with its section. Built as one list (not per tab) so the
+    /// platform-conditional insertions below can still place a row RELATIVE to another by id.
+    private var allRows: [Row] {
         let resolution = resolutionOptions
         let refresh = SettingsOptions.refreshRates(including: hz)
             .map { (label: "\($0) Hz", tag: $0) }
@@ -245,7 +470,7 @@ struct GamepadSettingsView: View {
         let controllers = SettingsOptions.controllerOptions(gamepads)
         var list: [Row] = [
             choiceRow(
-                id: "resolution", header: "Stream", icon: "aspectratio",
+                id: "resolution", tab: .stream, icon: "aspectratio",
                 label: "Resolution",
                 detail: "The host creates a virtual display at exactly this size — no scaling.",
                 options: resolution, current: "\(width)x\(height)"
@@ -256,53 +481,48 @@ struct GamepadSettingsView: View {
                 height = parts[1]
             },
             choiceRow(
-                id: "refresh", icon: "gauge.with.needle", label: "Refresh rate",
+                id: "refresh", tab: .stream, icon: "gauge.with.needle", label: "Refresh rate",
                 detail: "Rates this display can actually show.",
                 options: refresh, current: hz
             ) { hz = $0 },
             choiceRow(
-                id: "bitrate", icon: "speedometer", label: "Bitrate",
+                id: "bitrate", tab: .stream, icon: "speedometer", label: "Bitrate",
                 detail: "Automatic uses the host's default (20 Mbps). "
                     + "Run a speed test from the touch UI for an informed value.",
                 options: bitrate, current: bitrateKbps
             ) { bitrateKbps = $0 },
             choiceRow(
-                id: "compositor", icon: "macwindow", label: "Compositor",
+                id: "compositor", tab: .stream, icon: "macwindow", label: "Compositor",
                 detail: "Which compositor drives the virtual output — honored only if "
                     + "available on the host.",
                 options: SettingsOptions.compositors, current: compositor
             ) { compositor = $0 },
-            toggleRow(
-                id: "autoWake", icon: "power", label: "Auto-wake on connect",
-                detail: "Send Wake-on-LAN to a sleeping saved host and wait for it before "
-                    + "streaming. Off connects straight through.",
-                value: $autoWakeEnabled),
-
             choiceRow(
-                id: "codec", header: "Video", icon: "film", label: "Video codec",
+                id: "codec", tab: .video, icon: "film", label: "Video codec",
                 detail: "A preference — the host falls back if it can't encode this one "
                     + "(10-bit and 4:4:4 are HEVC-only).",
                 options: SettingsOptions.codecs, current: codec
             ) { codec = $0 },
             toggleRow(
-                id: "hdr", icon: "sun.max", label: "10-bit HDR",
+                id: "hdr", tab: .video, icon: "sun.max", label: "10-bit HDR",
                 detail: "HDR10 — engages when the host sends HDR content and this display "
                     + "supports it.",
                 value: $hdrEnabled),
             toggleRow(
-                id: "chroma", icon: "textformat", label: "Full chroma (4:4:4)",
+                id: "chroma", tab: .video, icon: "textformat", label: "Full chroma (4:4:4)",
                 detail: "Sharper text and UI at more bandwidth — needs host opt-in and "
                     + "hardware decode.",
                 value: $enable444),
             choiceRow(
-                id: "presentPriority", icon: "rectangle.stack", label: "Prioritize",
+                id: "presentPriority", tab: .video, icon: "rectangle.stack", label: "Prioritize",
                 detail: "Lowest latency shows each frame the moment the display can take it; "
                     + "Smoothness buffers a few frames to even out network hiccups. Applies "
                     + "from the next session.",
                 options: SettingsOptions.presentPriorities, current: presentPriority
             ) { presentPriority = $0 },
             choiceRow(
-                id: "smoothBuffer", icon: "square.stack.3d.up", label: "Smoothness buffer",
+                id: "smoothBuffer", tab: .video, icon: "square.stack.3d.up",
+                label: "Smoothness buffer",
                 detail: "How many frames Smoothness holds — each adds about a refresh of "
                     + "display latency and absorbs about a refresh of jitter. Only applies "
                     + "when prioritizing smoothness.",
@@ -310,66 +530,102 @@ struct GamepadSettingsView: View {
             ) { smoothBuffer = $0 },
 
             choiceRow(
-                id: "audio", header: "Audio", icon: "speaker.wave.2", label: "Audio channels",
+                id: "audio", tab: .audio, icon: "speaker.wave.2", label: "Audio channels",
                 detail: "The speaker layout requested from the host.",
                 options: SettingsOptions.audioChannels, current: audioChannels
             ) { audioChannels = $0 },
             toggleRow(
-                id: "mic", icon: "mic", label: "Microphone",
+                id: "mic", tab: .audio, icon: "mic", label: "Microphone",
                 detail: "Send this device's microphone to the host's virtual mic.",
                 value: $micEnabled),
             toggleRow(
-                id: "echoCancel", icon: "waveform", label: "Echo cancellation",
+                id: "echoCancel", tab: .audio, icon: "waveform", label: "Echo cancellation",
                 detail: "Cancel the audio this device plays out of the mic signal — stops "
                     + "speaker setups feeding the game back to the host.",
                 value: $echoCancel),
 
             toggleRow(
-                id: "padForward", header: "Controller", icon: "gamecontroller",
+                id: "padForward", tab: .controller, icon: "gamecontroller",
                 label: "Forward controllers",
                 detail: "Send this device's controllers to the host. Turn it off when your "
                     + "controller already reaches the host another way — USB passthrough such "
                     + "as VirtualHere — so games don't see two of them.",
                 value: $gamepadForwarding),
+            // The four rows below only mean something while something is being forwarded, so
+            // they follow the switch above — the same relationship the touch settings draw with
+            // `.disabled(!effective.gamepadForwarding)`. This screen could not express it until
+            // `Row.enabled` existed, so it alone left them live and steppable.
             choiceRow(
-                id: "pad", icon: "gamecontroller", label: "Use controller",
+                id: "pad", tab: .controller, icon: "gamecontroller", label: "Use controller",
                 detail: "Which pad is forwarded to the host, as player 1.",
-                options: controllers, current: gamepads.preferredID
+                options: controllers, current: gamepads.preferredID,
+                enabled: gamepadForwarding
             ) { gamepads.preferredID = $0 },
             choiceRow(
-                id: "padType", icon: "dpad", label: "Controller type",
+                id: "padType", tab: .controller, icon: "dpad", label: "Controller type",
                 detail: "The virtual pad the host creates — Automatic matches this controller.",
-                options: SettingsOptions.padTypes, current: gamepadType
+                options: SettingsOptions.padTypes, current: gamepadType,
+                enabled: gamepadForwarding
             ) { gamepadType = $0 },
+            choiceRow(
+                id: "systemButtons", tab: .controller, icon: "house.circle",
+                label: "Guide button",
+                detail: "Where the guide (Xbox/PS) and share presses go while streaming — "
+                    + "Automatic sends them to the host whenever this device delivers them.",
+                options: SettingsOptions.systemButtons, current: systemButtons,
+                enabled: gamepadForwarding
+            ) { systemButtons = $0 },
+            choiceRow(
+                id: "guideGesture", tab: .controller, icon: "hand.point.up.left",
+                label: "Hold Select for guide",
+                detail: "Hold Select alone to press the host's guide button — keep holding "
+                    + "for a Gaming-Mode host's quick-access menu. A tap still goes through.",
+                options: SettingsOptions.guideGestures, current: guideGesture,
+                enabled: gamepadForwarding
+            ) { guideGesture = $0 },
 
             choiceRow(
-                id: "hud", header: "Interface", icon: "chart.bar", label: "Statistics overlay",
+                id: "palette", tab: .interface, icon: "paintpalette", label: "Background",
+                detail: "The colour family this backdrop drifts through — it changes as you "
+                    + "step, so pick by looking. Appearance only.",
+                options: GamepadPalette.all.map { (label: $0.name, tag: $0.id) },
+                current: GamepadPalette.named(paletteID).id
+            ) { paletteID = $0 },
+            toggleRow(
+                id: "autoWake", tab: .interface, icon: "power", label: "Auto-wake on connect",
+                detail: "Send Wake-on-LAN to a sleeping saved host and wait for it before "
+                    + "streaming. Off connects straight through.",
+                value: $autoWakeEnabled),
+            choiceRow(
+                id: "hud", tab: .interface, icon: "chart.bar", label: "Statistics overlay",
                 detail: "How much to show while streaming — Compact is a one-line pill, "
                     + "Detailed adds the latency stage breakdown.",
                 options: SettingsOptions.statsVerbosities, current: statsVerbosityRaw
             ) { statsVerbosityRaw = $0 },
             choiceRow(
-                id: "hudPlacement", icon: "rectangle.inset.topright.filled", label: "Overlay position",
+                id: "hudPlacement", tab: .interface, icon: "rectangle.inset.topright.filled",
+                label: "Overlay position",
                 detail: "Which corner the statistics overlay sits in.",
                 options: SettingsOptions.hudPlacements, current: hudPlacement
             ) { hudPlacement = $0 },
             toggleRow(
-                id: "library", icon: "square.grid.2x2", label: "Game library",
+                id: "library", tab: .interface, icon: "square.grid.2x2", label: "Game library",
                 detail: "Browse and launch the host's games with \(buttonName(\.buttonY, "Y")).",
                 value: $libraryEnabled),
             toggleRow(
-                id: "gamepadUI", icon: "hand.tap", label: "Controller-optimized UI",
+                id: "gamepadUI", tab: .interface, icon: "hand.tap",
+                label: "Controller-optimized UI",
                 detail: "Turn off to use the touch interface even with a controller connected.",
                 value: $gamepadUIEnabled),
         ]
         #if os(macOS)
         // The windowed safe-present toggle slots in after "Smoothness buffer" (staying inside
-        // the Video group) — macOS only, mirroring the touch SettingsView's Presentation row
+        // the Video tab) — macOS only, mirroring the touch SettingsView's Presentation row
         // (the DCP swapID-panic mitigation; see DefaultsKey.windowedSafePresent).
         if let at = list.firstIndex(where: { $0.id == "smoothBuffer" }) {
             list.insert(
                 toggleRow(
-                    id: "windowedSafePresent", icon: "macwindow.badge.plus",
+                    id: "windowedSafePresent", tab: .video, icon: "macwindow.badge.plus",
                     label: "Safe windowed presentation",
                     detail: "Windowed streams present in step with the compositor — avoids a "
                         + "macOS display-driver crash on high-refresh displays, at a small "
@@ -379,14 +635,14 @@ struct GamepadSettingsView: View {
         }
         #endif
         #if os(iOS)
-        // The device-rumble mirror slots in after "Controller type" (staying inside the
-        // Controller group — the next row carries the "Interface" header). iPhone only in
-        // practice: hidden where the device itself can't play haptics (iPad).
+        // The device-rumble mirror slots in after "Controller type", inside the Controller tab.
+        // iPhone only in practice: hidden where the device itself can't play haptics (iPad).
         if CHHapticEngine.capabilitiesForHardware().supportsHaptics,
             let at = list.firstIndex(where: { $0.id == "padType" }) {
             list.insert(
                 toggleRow(
-                    id: "deviceRumble", icon: "iphone.radiowaves.left.and.right",
+                    id: "deviceRumble", tab: .controller,
+                    icon: "iphone.radiowaves.left.and.right",
                     label: "Rumble on this iPhone",
                     detail: "Also play player 1's rumble on the phone's own Taptic Engine — "
                         + "for clip-on pads without rumble motors.",
@@ -394,7 +650,99 @@ struct GamepadSettingsView: View {
                 at: at + 1)
         }
         #endif
-        return list
+        return list + profileRows
+    }
+
+    // MARK: - Profiles (§5.2a)
+
+    /// The trailing Profiles section: one row per catalog profile, its value how many saved
+    /// hosts pin it, A opening the pin-to-hosts picker. Read-only beyond that — this surface
+    /// pins and unpins, but profiles are created and edited elsewhere (design §5.4), so
+    /// left/right is a boundary thud, not an editor.
+    private var profileRows: [Row] {
+        guard !profiles.profiles.isEmpty else {
+            return [Row(
+                id: "noProfiles", tab: .profiles, icon: "slider.horizontal.3",
+                label: "No profiles yet", value: "",
+                detail: emptyCatalogDetail,
+                adjustable: false,
+                adjust: { _ in false }, activate: {})]
+        }
+        return profiles.profiles.map { profile in
+            let pins = store.hosts
+                .filter { ($0.pinnedProfileIDs ?? []).contains(profile.id) }.count
+            return Row(
+                id: "profile-\(profile.id)", tab: .profiles,
+                icon: "slider.horizontal.3", label: profile.name,
+                value: pins == 0 ? "Not pinned" : "Pinned to \(pins) host\(pins == 1 ? "" : "s")",
+                detail: profileDetail,
+                adjustable: false,
+                adjust: { _ in false },
+                activate: {
+                    // Focus lands on the picker's first row — the focus list's reconcile
+                    // follows this id when the row set swaps underneath it.
+                    focusID = store.hosts.first.map { "pinHost-\($0.id.uuidString)" } ?? "noHosts"
+                    pinTarget = profile
+                })
+        }
+    }
+
+    /// The pin-to-hosts picker: one toggle row per SAVED host, sharing the settings rows'
+    /// toggle semantics (left = unpin, right = pin, A flips; asking for the state it's in is a
+    /// boundary thud). Writes ride `HostStore.setPinned` — pin appends, unpin removes — and
+    /// NEVER the host's default binding (`profileID`): a pin is presentation only (§5.2a).
+    private func pinRows(for profile: StreamProfile) -> [Row] {
+        guard !store.hosts.isEmpty else {
+            return [Row(
+                id: "noHosts", tab: .profiles, icon: "desktopcomputer",
+                label: "No saved hosts yet",
+                value: "",
+                detail: "Pair with a host first, then pin this profile to it.",
+                adjustable: false,
+                adjust: { _ in false }, activate: {})]
+        }
+        return store.hosts.map { host in
+            let hostID = host.id
+            let pinned = (host.pinnedProfileIDs ?? []).contains(profile.id)
+            return Row(
+                id: "pinHost-\(hostID.uuidString)", tab: .profiles, icon: "desktopcomputer",
+                label: host.displayName,
+                value: pinned ? "Pinned" : "Off",
+                detail: "A pinned profile appears as its own card on the host — one press "
+                    + "connects with it.",
+                adjust: { delta in
+                    let target = delta > 0
+                    guard pinned != target else { return false }
+                    store.setPinned(hostID, profileID: profile.id, pinned: target)
+                    return true
+                },
+                activate: { store.setPinned(hostID, profileID: profile.id, pinned: !pinned) })
+        }
+    }
+
+    /// The profile rows' explainer. tvOS gets its own: the catalog is per-device (the App Group
+    /// suite — nothing syncs it) and tvOS has no profile editor at all (§5.4), so pointing a TV
+    /// user at a "standard interface" would promise profiles that can never arrive there.
+    private var profileDetail: String {
+        #if os(tvOS)
+        return "Pin this profile to a host and it appears as its own card on the home screen — "
+            + "one press connects with it."
+        #else
+        return "Pin this profile to a host and it appears as its own card — one press connects "
+            + "with it. Profiles are created and edited in Punktfunk's standard interface."
+        #endif
+    }
+
+    /// What the empty catalog's placeholder explains — again honest on tvOS, where profiles
+    /// cannot be created (on the device or anywhere that would reach its per-device catalog).
+    private var emptyCatalogDetail: String {
+        #if os(tvOS)
+        return "Profiles bundle stream settings for different uses. Creating them isn't "
+            + "available on Apple TV yet."
+        #else
+        return "Profiles bundle stream settings for different uses. Create them in Punktfunk's "
+            + "standard interface, then pin them here as one-press connect cards."
+        #endif
     }
 
     /// Resolution choices as "WxH" tags — the current size is inserted when it's a custom mode
@@ -419,14 +767,16 @@ struct GamepadSettingsView: View {
     // MARK: - Row builders
 
     private func choiceRow<T: Equatable>(
-        id: String, header: String? = nil, icon: String, label: String, detail: String,
-        options: [(label: String, tag: T)], current: T, write: @escaping (T) -> Void
+        id: String, tab: GpSettingsTab, icon: String, label: String, detail: String,
+        options: [(label: String, tag: T)], current: T, enabled: Bool = true,
+        write: @escaping (T) -> Void
     ) -> Row {
         let index = options.firstIndex { $0.tag == current }
         return Row(
-            id: id, header: header, icon: icon, label: label,
+            id: id, tab: tab, icon: icon, label: label,
             value: index.map { options[$0].label } ?? "—",
             detail: detail,
+            enabled: enabled,
             adjust: { delta in
                 // Unknown current value: snap to the first option on any step.
                 guard let index else {
@@ -446,13 +796,14 @@ struct GamepadSettingsView: View {
     }
 
     private func toggleRow(
-        id: String, header: String? = nil, icon: String, label: String, detail: String,
-        value: Binding<Bool>
+        id: String, tab: GpSettingsTab, icon: String, label: String, detail: String,
+        value: Binding<Bool>, enabled: Bool = true
     ) -> Row {
         Row(
-            id: id, header: header, icon: icon, label: label,
+            id: id, tab: tab, icon: icon, label: label,
             value: value.wrappedValue ? "On" : "Off",
             detail: detail,
+            enabled: enabled,
             adjust: { delta in
                 // Directional semantics: left = off, right = on; a no-op reads as a boundary.
                 let target = delta > 0

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

@@ -34,6 +34,22 @@ enum SettingsOptions {
         ("DualShock 4", 4),
     ]
 
+    /// System-button routing (the cross-client `system_buttons` key): where the guide
+    /// (Xbox/PS) and share presses land while streaming. Auto = forward on Apple.
+    static let systemButtons: [(label: String, tag: String)] = [
+        ("Automatic", "auto"),
+        ("Send to host", "forward"),
+        ("This device", "local"),
+    ]
+
+    /// The hold-Select guide gesture (the cross-client `guide_gesture` key). Auto = on
+    /// everywhere but macOS.
+    static let guideGestures: [(label: String, tag: String)] = [
+        ("Automatic", "auto"),
+        ("On", "on"),
+        ("Off", "off"),
+    ]
+
     static let hudPlacements: [(label: String, tag: String)] =
         HUDPlacement.allCases.map { ($0.label, $0.rawValue) }
 
@@ -155,14 +171,26 @@ enum SettingsOptions {
 
     /// This device's native mode first, then the presets, deduped by dimensions (native wins a
     /// tie).
+    ///
+    /// On iOS the native row is followed by its **safe-area** variant, which is the same mode
+    /// narrowed so the picture clears the sensor housing and the rounded corners — see
+    /// [`SafeDisplay`] for why a narrower mode is the whole fix. It is emitted unconditionally and
+    /// left to the dedup below: on a device with no housing the two modes are identical, the
+    /// duplicate is dropped, and no pointless row appears.
     @MainActor
     static func resolutionModes() -> [(name: String, w: Int, h: Int)] {
         var native: [(name: String, w: Int, h: Int)] = []
         #if os(iOS) || os(tvOS)
         let bounds = UIScreen.main.nativeBounds // portrait-oriented pixels (tvOS: the TV mode)
-        native = [("This device",
-                   Int(max(bounds.width, bounds.height)),
-                   Int(min(bounds.width, bounds.height)))]
+        let nativeW = Int(max(bounds.width, bounds.height))
+        let nativeH = Int(min(bounds.width, bounds.height))
+        native = [("This device", nativeW, nativeH)]
+        #if os(iOS)
+        let safe = SafeDisplay.mode(
+            nativeWidth: nativeW, nativeHeight: nativeH,
+            sideInsetPoints: mainWindowSideInset(), scale: UIScreen.main.nativeScale)
+        native.append(("This device (safe area)", safe.width, safe.height))
+        #endif
         #else
         if let screen = NSScreen.main {
             let scale = screen.backingScaleFactor
@@ -175,6 +203,26 @@ enum SettingsOptions {
         return (native + resolutionPresets).filter { seen.insert("\($0.w)x\($0.h)").inserted }
     }
 
+    #if os(iOS)
+    /// The key window's per-side safe-area inset in points, resolved for the LANDSCAPE stream even
+    /// when this settings screen is currently portrait (see `SafeDisplay.sideInsetPoints`).
+    ///
+    /// Zero when no window is up yet — the safe mode then equals the native one and `resolutionModes`
+    /// dedups the row away, which is the right answer for a device we can't measure.
+    @MainActor
+    private static func mainWindowSideInset() -> Double {
+        let insets = UIApplication.shared.connectedScenes
+            .compactMap { $0 as? UIWindowScene }
+            .flatMap(\.windows)
+            .first { $0.isKeyWindow }?
+            .safeAreaInsets
+        guard let insets else { return 0 }
+        return SafeDisplay.sideInsetPoints(
+            left: Double(insets.left), right: Double(insets.right), top: Double(insets.top),
+            isPhone: UIDevice.current.userInterfaceIdiom == .phone)
+    }
+    #endif
+
     /// Refresh rates the device can actually display (no point asking the host to render frames
     /// the screen can't show), plus any stored custom value so it stays selectable.
     @MainActor

clients/apple/Sources/PunktfunkClient/Settings/SettingsView+Scope.swift

@@ -126,6 +126,14 @@ enum SettingsFields {
         .init(name: "gamepad_forwarding", key: DefaultsKey.gamepadForwarding,
               overlay: \.gamepadForwarding, effective: \.gamepadForwarding)
     }
+    static var systemButtons: SettingsField<String> {
+        .init(name: "system_buttons", key: DefaultsKey.systemButtons,
+              overlay: \.systemButtons, effective: \.systemButtons)
+    }
+    static var guideGesture: SettingsField<String> {
+        .init(name: "guide_gesture", key: DefaultsKey.guideGesture,
+              overlay: \.guideGesture, effective: \.guideGesture)
+    }
     static var statsVerbosity: SettingsField<String> {
         .init(name: "stats_verbosity", key: DefaultsKey.statsVerbosity,
               overlay: \.statsVerbosity, effective: \.statsVerbosity)

clients/apple/Sources/PunktfunkClient/Settings/SettingsView+Sections.swift

@@ -681,6 +681,29 @@ extension SettingsView {
                 }
                 .disabled(!effective.gamepadForwarding)
             }
+            described("Where the guide (Xbox/PS) and share presses go while streaming. "
+                + "Automatic sends them to the host whenever this device delivers them "
+                + "— the hold-Select gesture below reaches the host regardless.",
+                field: "system_buttons") {
+                Picker("Guide button", selection: scoped(SettingsFields.systemButtons)) {
+                    Text("Automatic").tag("auto")
+                    Text("Send to host").tag("forward")
+                    Text("This device").tag("local")
+                }
+                .disabled(!effective.gamepadForwarding)
+            }
+            described("Hold Select on its own to press the host's guide button — keep "
+                + "holding for a Gaming-Mode host's quick-access menu. A Select tap still "
+                + "goes through, slightly delayed. Automatic arms it wherever the real "
+                + "button can't reach the host (this device reserves it).",
+                field: "guide_gesture") {
+                Picker("Hold Select for guide", selection: scoped(SettingsFields.guideGesture)) {
+                    Text("Automatic").tag("auto")
+                    Text("On").tag("on")
+                    Text("Off").tag("off")
+                }
+                .disabled(!effective.gamepadForwarding)
+            }
             #if os(iOS)
             // iPhone only in practice: hidden where the device itself can't play haptics (iPad).
             if !inProfileScope, CHHapticEngine.capabilitiesForHardware().supportsHaptics {

clients/apple/Sources/PunktfunkClient/Stores/HostStore.swift

@@ -191,6 +191,12 @@ final class HostStore: ObservableObject {
 
 
     private func persist() {
+        #if DEBUG
+        // The screenshot harness fills a store with mock hosts (ShotMock) purely to render a
+        // scene. On a dev Mac that store is the SAME App-Group suite the real app reads, so
+        // persisting would replace the tester's saved hosts with "Battlestation" & co.
+        if ScreenshotMode.isActive { return }
+        #endif
         if let data = try? JSONEncoder().encode(hosts) {
             defaults.set(data, forKey: Self.key)
         }

clients/apple/Sources/PunktfunkClient/Stores/ProfileStore.swift

@@ -20,7 +20,14 @@ final class ProfileStore: ObservableObject {
     static let shared = ProfileStore()
 
     @Published private(set) var catalog: ProfileCatalog {
-        didSet { catalog.save() }
+        didSet {
+            #if DEBUG
+            // Shot mode seeds this SINGLETON with mock profiles to populate the host cards.
+            // Saving would write them into the tester's real catalog — see HostStore.persist().
+            if ScreenshotMode.isActive { return }
+            #endif
+            catalog.save()
+        }
     }
 
     var profiles: [StreamProfile] { catalog.profiles }
@@ -33,6 +40,14 @@ final class ProfileStore: ObservableObject {
         id.flatMap { catalog.profile(id: $0) }
     }
 
+    #if DEBUG
+    /// Shot-mode seed: replace the catalog outright so a capture shows a known set of profiles
+    /// rather than the tester's. Safe because `didSet` suppresses the write-back in shot mode.
+    func debugSet(_ profiles: [StreamProfile]) {
+        catalog = ProfileCatalog(profiles: profiles)
+    }
+    #endif
+
     /// This host's default profile, dangling ids dropped — a deleted profile resolves as "Default
     /// settings", never an error (§4.4).
     func binding(for host: StoredHost) -> StreamProfile? { catalog.binding(for: host) }

clients/apple/Sources/PunktfunkClient/Support/GlassStyle.swift

@@ -80,6 +80,12 @@ private struct ConsoleGlass<S: Shape>: ViewModifier {
     let shape: S
     var tint: Color?
     var interactive = false
+    /// The console surface follows the background palette: a PALE field needs the material to
+    /// frost light and the glass to read as white, or the dark ink on top of it disappears.
+    /// Defaults to the dark ink, so every non-gamepad caller is unchanged.
+    @Environment(\.gamepadInk) private var ink
+
+    private var scheme: ColorScheme { ink.isLight ? .light : .dark }
 
     func body(content: Content) -> some View {
         #if os(tvOS)
@@ -89,16 +95,16 @@ private struct ConsoleGlass<S: Shape>: ViewModifier {
         // the 10-foot platform). The tint rides an overlay so the focused row keeps its wash.
         content.background {
             shape.fill(.ultraThinMaterial)
-                .environment(\.colorScheme, .dark)
+                .environment(\.colorScheme, scheme)
                 .overlay {
                     if let tint { shape.fill(tint) }
                 }
         }
         #else
         if #available(iOS 26, macOS 26, *) {
-            content.glassEffect(glass, in: shape)
+            content.glassEffect(glass, in: shape).environment(\.colorScheme, scheme)
         } else {
-            content.background { shape.fill(.ultraThinMaterial).environment(\.colorScheme, .dark) }
+            content.background { shape.fill(.ultraThinMaterial).environment(\.colorScheme, scheme) }
         }
         #endif
     }

clients/apple/Sources/PunktfunkClient/Trust/PairSheet.swift

@@ -109,7 +109,7 @@ struct PairSheet: View {
                         #endif
                     TextField(
                         "Client name", text: $clientName,
-                        prompt: Text("How the host lists this Mac"))
+                        prompt: Text(Self.clientNamePrompt))
                         #if os(tvOS)
                         .labelsHidden() // prefilled → tvOS floats the label off-center
                         #endif
@@ -184,6 +184,16 @@ struct PairSheet: View {
         #endif
     }
 
+    /// The field prompt names the device you are actually on — it said "this Mac" on every
+    /// platform, which on an iPhone is simply wrong.
+    private static var clientNamePrompt: String {
+        #if os(macOS)
+        "How the host lists this Mac"
+        #else
+        "How the host lists this device"
+        #endif
+    }
+
     private func runCeremony() {
         busy = true
         errorText = nil
@@ -229,3 +239,24 @@ struct PairSheet: View {
         }
     }
 }
+
+#if DEBUG
+extension PairSheet {
+    /// Screenshot-harness seed (`ShotScenes`). A capture of the untouched sheet shows an empty PIN
+    /// field, a DISABLED "Pair & Connect", and — because the client name defaults to the device's
+    /// own — whatever the capture simulator happens to be called (`pf-shot-iphone-6.9` reached App
+    /// Store Connect that way). Seeding both fields captures the ceremony as a user meets it,
+    /// mid-entry, with a live primary button.
+    ///
+    /// An extension so `PairSheet` keeps its memberwise initialiser, and THIS file so it can reach
+    /// the private state.
+    init(
+        host: StoredHost, shotPIN: String, shotClientName: String,
+        onPaired: @escaping (Data) -> Void
+    ) {
+        self.init(host: host, onPaired: onPaired)
+        _pin = State(initialValue: shotPIN)
+        _clientName = State(initialValue: shotClientName)
+    }
+}
+#endif

clients/apple/Sources/PunktfunkKit/Audio/AudioRing.swift

@@ -3,28 +3,66 @@ import os
 
 /// SPSC-ish jitter ring (interleaved float, `channels` per frame), drain thread → render
 /// callback. The unfair lock is held for microseconds; fine at render-callback rates. Priming:
-/// reads return silence until enough is buffered (at least `prefill`, and at least one
+/// reads return silence until enough is buffered (at least the target, and at least one
 /// packet more than the device's render quantum — large-buffer devices would otherwise
-/// chronically out-demand the prefill and oscillate prime → dropout → re-prime), and an
-/// underrun re-primes, concealing jitter as one short dip instead of sustained crackle.
+/// chronically out-demand the prefill and oscillate prime → dropout → re-prime).
 /// All counts stay whole frames (multiples of `channels`), so the interleave can never slip.
+///
+/// **Drift correction.** Both ends run at 48 kHz but on different crystals, so backlog from a
+/// network stall or plain host-vs-DAC skew never drains on its own: without correction one 300 ms
+/// hiccup leaves audio 300 ms behind video for the rest of the session. This used to be handled by
+/// a `highWater` shed that dropped a whole `2 × prefill` at once — its own comment called that "one
+/// audible blip". It is now the same two-stage scheme the Rust clients share
+/// (`punktfunk_core::audio::JitterPolicy`): a slow depth average that sits above target for a
+/// sustained window sheds ONE 5 ms frame with a crossfade, and the hard cap is only a backstop.
+/// Keep the constants here in step with `JitterTuning.COREAUDIO`.
 final class AudioRing: @unchecked Sendable {
+    /// Mirrors `JitterTuning::COREAUDIO` — see that type for the rationale.
+    private static let targetMS = 20
+    private static let headroomMS = 30
+    private static let hardCapMS = 90
+    private static let deprimeAfter = 4
+    /// The protocol's frame: the shed unit, and the slack added over a large device quantum.
+    private static let frameMS = 5
+    /// Depth average must exceed target by this before drift correction fires — the middle of the
+    /// headroom band, so the smooth shed always gets its chance BEFORE the hard cap trims.
+    private static let shedExcessMS = 15
+    /// …and must stay there for this much consumed audio. Long, because a shed is the only thing
+    /// here a listener could notice; it must never fire on a transient.
+    private static let shedSustainMS = 2_000
+    private static let crossfadeMS = 2
+    /// Time constant of the depth average.
+    private static let ewmaTauMS = 1_000
+
     private var buf: [Float]
     private var readIdx = 0
     private var writeIdx = 0
     private var primed = false
     private var renderQuantum = 0
-    private let prefill: Int
-    private let highWater: Int
+    private var emptyReads = 0
+    private var depthAvg: Double = 0
+    private var overRun = 0
+    /// Reported, not acted on: short reads that actually starved the callback, and smooth drift
+    /// corrections. A rising underrun count means the ring is being starved (network or CPU),
+    /// which is a different problem from the depth being wrong.
+    private var underrunCount = 0
+    private var shedCount = 0
     private let channels: Int
+    private let perMS: Int
     private let lock = OSAllocatedUnfairLock()
 
-    /// `capacity`/`prefill` in samples (interleaved — `channels` per frame, both whole frames).
-    init(capacity: Int, prefill: Int, channels: Int) {
+    /// `capacity` in samples (interleaved — `channels` per frame, a whole number of frames).
+    /// The de-jitter depth is the ring's own business (`targetMS`), not a caller's prefill.
+    init(capacity: Int, channels: Int) {
         buf = [Float](repeating: 0, count: capacity)
-        self.prefill = prefill
         self.channels = channels
-        highWater = prefill * 4
+        perMS = 48 * channels
+    }
+
+    /// Live target depth in interleaved samples, lifted so it can always serve one device quantum
+    /// plus a packet (a large-buffer device cannot sustain a target below its own quantum).
+    private var target: Int {
+        max(Self.targetMS * perMS, renderQuantum + Self.frameMS * perMS)
     }
 
     func write(_ samples: UnsafePointer<Float>, count: Int) {
@@ -42,12 +80,12 @@ final class AudioRing: @unchecked Sendable {
             buf[(writeIdx + i) % capacity] = samples[i]
         }
         writeIdx += count
-        // Latency clamp: both ends run at 48 kHz, so backlog from a network stall (or
-        // creeping host-vs-DAC clock skew) never drains on its own — without this, one
-        // 300 ms hiccup leaves audio 300 ms behind video for the rest of the session.
-        // Shedding down to 2× prefill costs one audible blip instead.
-        if writeIdx - readIdx > highWater {
-            readIdx = writeIdx - prefill * 2
+        // Backstop only: the smooth shed in `read` is what normally holds the depth down.
+        let cap = min(target + Self.headroomMS * perMS, Self.hardCapMS * perMS)
+        if writeIdx - readIdx > cap {
+            readIdx = writeIdx - cap
+            depthAvg = Double(cap)
+            overRun = 0
         }
     }
 
@@ -57,16 +95,37 @@ final class AudioRing: @unchecked Sendable {
         defer { lock.unlock() }
         renderQuantum = max(renderQuantum, count)
         let available = writeIdx - readIdx
+
+        // Depth average, weighted by the callback size so its time constant is independent of the
+        // device quantum.
+        let alpha = min(1.0, Double(count) / Double(Self.ewmaTauMS * perMS))
+        depthAvg += (Double(available) - depthAvg) * alpha
+
         if !primed {
-            // One 5 ms host packet (240 frames × channels) of slack beyond the device's demand.
-            if available >= max(prefill, renderQuantum + 240 * channels) {
+            if available >= target {
                 primed = true
+                emptyReads = 0
             } else {
                 for i in 0..<count { out[i] = 0 }
                 return
             }
         }
-        let n = min(available, count)
+
+        // Drift correction: shed exactly one frame, crossfaded, once the AVERAGE has sat above
+        // the threshold for the sustain window. Anything shorter is jitter and must be left alone.
+        if depthAvg > Double(target + Self.shedExcessMS * perMS) {
+            overRun += count
+            if overRun >= Self.shedSustainMS * perMS {
+                overRun = 0
+                shedOneFrame()
+                shedCount += 1
+                depthAvg = Double(writeIdx - readIdx)
+            }
+        } else {
+            overRun = 0
+        }
+
+        let n = min(writeIdx - readIdx, count)
         let capacity = buf.count
         for i in 0..<n {
             out[i] = buf[(readIdx + i) % capacity]
@@ -74,9 +133,63 @@ final class AudioRing: @unchecked Sendable {
         readIdx += n
         if n < count {
             for i in n..<count { out[i] = 0 }
-            primed = false // underrun — re-prime before resuming
+            // De-prime only after a RUN of short reads: a single transient drain must not
+            // manufacture a whole target's worth of fresh silence.
+            emptyReads += 1
+            underrunCount += 1
+            if emptyReads >= Self.deprimeAfter { primed = false }
+        } else {
+            emptyReads = 0
         }
     }
+
+    /// Drop one protocol frame from the front, linearly crossfading the seam so the correction is
+    /// inaudible rather than a click. Mirrors `punktfunk_core::audio::crossfade_drop`; caller holds
+    /// the lock.
+    private func shedOneFrame() {
+        let drop = Self.frameMS * perMS
+        let available = writeIdx - readIdx
+        guard available > drop else { return }
+        let fade = min(Self.crossfadeMS * perMS, min(drop, available - drop))
+        let capacity = buf.count
+        if fade > 0 {
+            // The tail of what we discard fades out into the head of what survives.
+            for i in 0..<fade {
+                let old = buf[(readIdx + drop - fade + i) % capacity]
+                let new = buf[(readIdx + drop + i) % capacity]
+                let t = Float(i + 1) / Float(fade + 1)
+                buf[(readIdx + drop + i) % capacity] = old * (1 - t) + new * t
+            }
+        }
+        readIdx += drop
+    }
+
+    /// Current buffered depth in milliseconds — for the stats overlay and the drain thread's
+    /// periodic log.
+    var bufferedMS: Int {
+        lock.lock()
+        defer { lock.unlock() }
+        return (writeIdx - readIdx) / max(perMS, 1)
+    }
+
+    /// One consistent snapshot of the ring's vitals, taken under a single lock so the numbers in
+    /// a log line describe the same instant. Mirrors what the three Rust clients report.
+    struct Stats {
+        let bufferedMS: Int
+        let targetMS: Int
+        let underruns: Int
+        let sheds: Int
+    }
+
+    var stats: Stats {
+        lock.lock()
+        defer { lock.unlock() }
+        return Stats(
+            bufferedMS: (writeIdx - readIdx) / max(perMS, 1),
+            targetMS: target / max(perMS, 1),
+            underruns: underrunCount,
+            sheds: shedCount)
+    }
 }
 
 /// CoreAudio channel layout for the canonical wire order FL FR FC LFE RL RR [SL SR]. nil for

clients/apple/Sources/PunktfunkKit/Audio/SessionAudio.swift

@@ -317,10 +317,10 @@ public final class SessionAudio {
         // Build the playback layout from the host-RESOLVED channel count (never the request):
         // 2 = stereo / 6 = 5.1 / 8 = 7.1, canonical wire order FL FR FC LFE RL RR SL SR.
         let channels = Int(connection.resolvedAudioChannels)
-        // 1 s interleaved capacity, ~20 ms prefill (four 5 ms host packets of jitter absorption
-        // before the first sample plays), both scaled by the channel count.
-        let ring = self.ring ?? AudioRing(
-            capacity: 48_000 * channels, prefill: 960 * channels, channels: channels)
+        // 1 s interleaved capacity, scaled by the channel count. The de-jitter depth itself is
+        // the ring's own business now (`AudioRing.targetMS`, mirroring `JitterTuning::COREAUDIO`)
+        // rather than a prefill passed in here.
+        let ring = self.ring ?? AudioRing(capacity: 48_000 * channels, channels: channels)
         self.ring = ring
 
         // Engine-native deinterleaved float; the render block deinterleaves from the ring. Surround
@@ -403,6 +403,7 @@ public final class SessionAudio {
         stateLock.unlock()
         let thread = Thread { [connection, flag, drainDone] in
             defer { drainDone.signal() }
+            var drained = 0
             // Decode happens IN-CORE (libopus multistream) — AudioToolbox's Opus path is
             // stereo-only — and is handed back as interleaved f32 PCM in wire channel order.
             // Per-iteration autorelease pool: no runloop on this thread (see Stage2Pipeline).
@@ -421,6 +422,17 @@ public final class SessionAudio {
                         ring.write(base, count: pcm.frameCount * pcm.channels)
                     }
                 }
+                // Periodic vitals (~10 s at the protocol's 5 ms frames). The other three clients
+                // log buffer depth and underruns; without this an Apple audio report — latency or
+                // dropout — arrives with no numbers at all, which is the position every platform
+                // was in before the 2026-08 audio work.
+                drained += 1
+                if drained % 2_000 == 0 {
+                    let s = ring.stats
+                    log.info(
+                        "audio: buffer_ms=\(s.bufferedMS) target_ms=\(s.targetMS) underruns=\(s.underruns) drift_sheds=\(s.sheds)"
+                    )
+                }
                 return true
                 }
             }

clients/apple/Sources/PunktfunkKit/Connection/HostDiscovery.swift

@@ -9,6 +9,25 @@
 //
 // iOS/tvOS gate Bonjour browsing on Info.plist `NSBonjourServices` listing `_punktfunk._udp`
 // (Config/Info.plist) — without it the system blocks the browse and nothing is returned.
+//
+// SELF-HEALING is what the bookkeeping below is for. Neither Network.framework primitive
+// recovers on its own, and all three failure modes read as "the host isn't there":
+//
+//   - `browseResultsChangedHandler` fires only when the result SET changes. A service that is
+//     found but whose resolve fails is never re-offered — from the browser's point of view
+//     nothing changed — so one unlucky resolve hid that host for the life of the process.
+//   - `NWConnection` has no timeout. A resolve that cannot complete (v6-only advert against our
+//     IPv4 pin, Wi-Fi still associating, host mid-reboot) parks in `.preparing`/`.waiting`
+//     forever instead of failing, so the retry path above was never even reached.
+//   - `NWBrowser` parks in `.waiting` when the browse is blocked. On iOS that is where the LOCAL
+//     NETWORK PRIVACY gate lands the first launch after install: the browse starts, the system
+//     puts up its "find and connect to devices on your local network" prompt, and the browser
+//     waits. Granting permission does NOT revive that browser — only a new one sees the grant.
+//
+// Every one of those presented as "restarting the app fixes it", which is what field reports
+// described. A 1 Hz `sweep` therefore times out stuck resolves, retries failed ones on a backoff
+// and re-arms a browser that stopped working; `refresh()` forces the same recovery immediately,
+// behind the UI's pull-to-refresh and Refresh button.
 
 #if canImport(Network)
 import Foundation
@@ -48,92 +67,256 @@ public struct DiscoveredHost: Identifiable, Sendable, Equatable {
 public final class HostDiscovery: ObservableObject {
     /// Currently-visible hosts, deduped by `id`, sorted by name. Main-actor.
     @Published public private(set) var hosts: [DiscoveredHost] = []
+    /// True for a moment after a rescan is kicked off, so a Refresh control can show that it did
+    /// something on the surfaces with no pull-to-refresh spinner of their own (macOS, tvOS).
+    @Published public private(set) var isScanning = false
 
     private var browser: NWBrowser?
-    /// Keyed by the service endpoint's description (a stable, Sendable handle we can capture
-    /// into the resolve callbacks without smuggling non-Sendable Network types across hops).
-    private var resolved: [String: DiscoveredHost] = [:]
+    /// Every service the browser currently reports, keyed by the endpoint's description (a stable,
+    /// Sendable handle we can capture into the resolve callbacks without smuggling non-Sendable
+    /// Network types across hops). Held — not just diffed — so a retry can re-resolve a service
+    /// the browser will never report again (see the file header).
+    private var services: [String: NWBrowser.Result] = [:]
+    /// The transport address a completed resolve produced, per service key. The rest of a
+    /// `DiscoveredHost` comes from the advert's TXT, which is re-read on every browse report.
+    private var addresses: [String: (host: String, port: UInt16)] = [:]
     private var connections: [String: NWConnection] = [:]
+    /// Deadline for each in-flight resolve — `NWConnection` has none of its own.
+    private var deadlines: [String: Date] = [:]
+    /// Consecutive failed resolves per service, and when the next attempt is allowed.
+    private var failures: [String: Int] = [:]
+    private var retryAt: [String: Date] = [:]
+    /// Services whose address should be re-resolved even though we already have one — set by
+    /// `refresh()`. The old address keeps showing until the new one lands, so a rescan never
+    /// blinks the list empty; without this a manual Refresh silently skipped every host it had
+    /// already resolved, which is exactly the host whose address may have moved.
+    private var staleAddresses: Set<String> = []
+    /// Consecutive non-ready browser states, and when to tear it down and re-arm. nil = healthy.
+    private var browserFailures = 0
+    private var browserRearmAt: Date?
+    /// Bumped on every re-arm so callbacks from a superseded browser — and from the resolves it
+    /// started — are ignored instead of clobbering the current generation's bookkeeping.
+    private var generation = 0
+    /// The 1 Hz maintenance tick. Nothing else re-drives a stuck resolve or a sick browser.
+    private var sweep: Task<Void, Never>?
+    private var scanningUntil: Date?
+
+    /// A LAN resolve answers in milliseconds; this only has to outlast a slow Wi-Fi wake.
+    private static let resolveTimeout: TimeInterval = 6
+    /// How long `isScanning` holds — and `rescan()` waits — after a manual refresh.
+    private static let scanSettle: TimeInterval = 1.5
+    /// 1s, 2s, 4s, 8s … capped at 30s, for the resolve retry and the browser re-arm alike. Long
+    /// enough that a genuinely-down network doesn't spin the main queue, short enough that a host
+    /// coming back is picked up while the user is still looking at the screen.
+    private static func backoff(_ failures: Int) -> TimeInterval {
+        min(pow(2, Double(max(0, failures - 1))), 30)
+    }
 
     public init() {}
 
     /// Start browsing `_punktfunk._udp`. Idempotent — a second call while live is a no-op.
     public func start() {
+        #if DEBUG
+        guard !debugPinned else { return } // a seeded advert set outranks the live LAN
+        #endif
         guard browser == nil else { return }
+        armBrowser()
+        startSweep()
+    }
+
+    /// Stop browsing and drop all discovered state.
+    public func stop() {
+        sweep?.cancel()
+        sweep = nil
+        generation &+= 1
+        browser?.cancel()
+        browser = nil
+        for conn in connections.values { conn.cancel() }
+        connections.removeAll()
+        deadlines.removeAll()
+        services.removeAll()
+        addresses.removeAll()
+        failures.removeAll()
+        retryAt.removeAll()
+        staleAddresses.removeAll()
+        browserFailures = 0
+        browserRearmAt = nil
+        scanningUntil = nil
+        if isScanning { isScanning = false }
+        if !hosts.isEmpty { hosts = [] }
+    }
+
+    /// Force a rescan now: re-arm the browser and retry every service whose resolve had failed,
+    /// clearing the backoffs so nothing is left waiting. This is the manual escape hatch for the
+    /// failure modes in the file header — and the only thing that clears the iOS local-network
+    /// permission gate without an app restart, since only a NEW browser sees a permission the
+    /// user granted after the old one started.
+    ///
+    /// Also starts discovery if it wasn't running, so a Refresh button does the obvious thing.
+    public func refresh() {
+        #if DEBUG
+        guard !debugPinned else { return } // as in `start()` — the harness's set is the truth
+        #endif
+        isScanning = true
+        scanningUntil = Date().addingTimeInterval(Self.scanSettle)
+        failures.removeAll()
+        retryAt.removeAll()
+        staleAddresses = Set(services.keys)
+        browserFailures = 0
+        armBrowser()
+        startSweep()
+        pump()
+    }
+
+    /// `refresh()` for a `.refreshable` gesture: holds briefly so the control's spinner reflects a
+    /// browse that had time to answer instead of blinking out instantly.
+    public func rescan() async {
+        refresh()
+        try? await Task.sleep(nanoseconds: UInt64(Self.scanSettle * 1_000_000_000))
+    }
+
+    /// `refresh()`, but only when discovery is already running — the app-foreground hook. iOS
+    /// suspends a backgrounded process's browse and `onAppear`/`onDisappear` don't fire across
+    /// background/foreground, so a browse that died while suspended stayed dead on return; this
+    /// re-arms it without starting a browse on a screen that deliberately isn't browsing
+    /// (mid-session, where the home tore discovery down).
+    public func refreshIfRunning() {
+        guard browser != nil else { return }
+        refresh()
+    }
+
+    deinit {
+        sweep?.cancel()
+        browser?.cancel()
+        for conn in connections.values { conn.cancel() }
+    }
+
+    #if DEBUG
+    /// A seeded advert set is in force — `start()` must not replace it with the live browse.
+    private var debugPinned = false
+
+    /// Screenshot/preview seam, the discovery counterpart to `HostWaker.debugSet`: publish a FIXED
+    /// set of adverts and keep browsing off. Without it a capture shows whatever happens to be on
+    /// the machine's LAN — the App Store screenshots shipped a stranger's hostname more than once —
+    /// and every mock host reads Offline because nothing advertises it.
+    public func debugSet(_ adverts: [DiscoveredHost]) {
+        stop()
+        debugPinned = true
+        hosts = adverts
+    }
+
+    /// Builds one advert. `DiscoveredHost`'s memberwise init is internal (a public struct's is), and
+    /// making it public would expose a wire-shaped model's construction to every consumer just to
+    /// serve the harness.
+    public static func debugAdvert(
+        id: String, name: String, host: String, port: UInt16 = 9777,
+        fingerprintHex: String? = nil, requiresPairing: Bool = false, allowsTofu: Bool = true,
+        macAddresses: [String] = [], osChain: String = ""
+    ) -> DiscoveredHost {
+        DiscoveredHost(
+            id: id, name: name, host: host, port: port, fingerprintHex: fingerprintHex,
+            requiresPairing: requiresPairing, allowsTofu: allowsTofu,
+            macAddresses: macAddresses, osChain: osChain)
+    }
+    #endif
+
+    // MARK: - Browser
+
+    /// Build and start a fresh browser, retiring the previous one and every resolve it started.
+    /// Those resolves' callbacks are gated on `generation`, so they must not be left holding map
+    /// entries — `pump()` restarts them against the new generation.
+    private func armBrowser() {
+        generation &+= 1
+        browser?.cancel()
+        for conn in connections.values { conn.cancel() }
+        connections.removeAll()
+        deadlines.removeAll()
+        browserRearmAt = nil
+
+        let generation = self.generation
         let browser = NWBrowser(
             for: .bonjourWithTXTRecord(type: "_punktfunk._udp", domain: nil),
             using: NWParameters())
         browser.browseResultsChangedHandler = { results, _ in
-            MainActor.assumeIsolated { [weak self] in self?.reconcile(results) }
+            MainActor.assumeIsolated { [weak self] in
+                guard let self, generation == self.generation else { return }
+                self.reconcile(results)
+            }
         }
         browser.stateUpdateHandler = { state in
-            // A failed browser never recovers on its own; tear down and re-arm so transient
-            // network changes (Wi-Fi flip, VPN) don't leave discovery silently dead.
             MainActor.assumeIsolated { [weak self] in
-                if case .failed = state { self?.restart() }
+                guard let self, generation == self.generation else { return }
+                self.browserStateChanged(state)
             }
         }
         self.browser = browser
         browser.start(queue: .main)
     }
 
-    /// Stop browsing and drop all discovered state.
-    public func stop() {
-        browser?.cancel()
-        browser = nil
-        for conn in connections.values { conn.cancel() }
-        connections.removeAll()
-        resolved.removeAll()
-        if !hosts.isEmpty { hosts = [] }
-    }
-
-    deinit {
-        browser?.cancel()
-        for conn in connections.values { conn.cancel() }
-    }
-
-    private func restart() {
-        stop()
-        start()
-    }
-
-    /// Diff the browser's current result set against what we're tracking: drop departed
-    /// services, resolve newly-seen ones.
-    private func reconcile(_ results: Set<NWBrowser.Result>) {
-        let live = Set(results.map { Self.key($0) })
-        for key in resolved.keys where !live.contains(key) { resolved[key] = nil }
-        for key in connections.keys where !live.contains(key) {
-            connections[key]?.cancel()
-            connections[key] = nil
+    /// A browser that stops working never recovers on its own, and it has two ways to stop:
+    /// `.failed` (dead) and `.waiting` (blocked — a network change, or the iOS local-network
+    /// permission gate described in the file header). Schedule a re-arm for both, on a backoff:
+    /// re-arming synchronously on `.failed` alone both missed the permission case entirely and
+    /// could spin the main queue on a browser that fails instantly every time.
+    private func browserStateChanged(_ state: NWBrowser.State) {
+        switch state {
+        case .ready:
+            browserFailures = 0
+            browserRearmAt = nil
+        case .failed, .waiting:
+            guard browserRearmAt == nil else { return } // one re-arm already scheduled
+            browserFailures += 1
+            browserRearmAt = Date().addingTimeInterval(Self.backoff(browserFailures))
+        default:
+            break // .setup / .cancelled — nothing to heal
         }
+    }
+
+    /// Diff the browser's current result set against what we're tracking: drop departed services,
+    /// record the rest — re-reading the advert every time, so a host that re-keys, moves or flips
+    /// its pairing policy republishes under the same name and the card follows it — then resolve
+    /// whatever still needs an address.
+    private func reconcile(_ results: Set<NWBrowser.Result>) {
+        var live: Set<String> = []
         for result in results {
             let key = Self.key(result)
-            if resolved[key] == nil, connections[key] == nil { resolve(result) }
+            live.insert(key)
+            services[key] = result
         }
+        for key in Array(services.keys) where !live.contains(key) { forget(key) }
         publish()
+        pump()
+    }
+
+    private func forget(_ key: String) {
+        connections[key]?.cancel()
+        connections[key] = nil
+        deadlines[key] = nil
+        services[key] = nil
+        addresses[key] = nil
+        failures[key] = nil
+        retryAt[key] = nil
+        staleAddresses.remove(key)
+    }
+
+    // MARK: - Resolve
+
+    /// Start the resolves that are due: every live service with no address yet, nothing in flight,
+    /// and past its retry time.
+    private func pump() {
+        let now = Date()
+        for (key, result) in services {
+            guard addresses[key] == nil || staleAddresses.contains(key) else { continue }
+            guard connections[key] == nil else { continue }
+            if let at = retryAt[key], at > now { continue }
+            resolve(key, result)
+        }
     }
 
     /// Resolve one service to IP:port via a short UDP connection (it reaches `.ready` once the
-    /// path is established — no data is sent), reading the TXT up front so the callback only
-    /// captures Sendable values + the endpoint key.
-    private func resolve(_ result: NWBrowser.Result) {
-        let key = Self.key(result)
-        let name = Self.instanceName(result.endpoint)
-        var fp: String?
-        var pair: String?
-        var id: String?
-        var macs: [String] = []
-        var osChain = ""
-        if case let .bonjour(txt) = result.metadata {
-            fp = Self.entry(txt, "fp")
-            pair = Self.entry(txt, "pair")
-            id = Self.entry(txt, "id")
-            macs = (Self.entry(txt, "mac") ?? "")
-                .split(separator: ",")
-                .map { $0.trimmingCharacters(in: .whitespaces) }
-                .filter { !$0.isEmpty }
-            osChain = sanitizeOsChain(Self.entry(txt, "os") ?? "")
-        }
+    /// path is established — no data is sent). The TXT is NOT read here: it comes from the browse
+    /// result at publish time, so a re-advertised host doesn't need a fresh resolve to be re-read.
+    private func resolve(_ key: String, _ result: NWBrowser.Result) {
         // Resolve over IPv4 only: Network.framework prefers IPv6 (RFC 6724), and the host's OS
         // mDNS responder often answers AAAA for its hostname even though the punktfunk host stack
         // (control QUIC + data UDP) binds IPv4 sockets exclusively — a v6-resolved address would
@@ -145,44 +328,125 @@ public final class HostDiscovery: ObservableObject {
         }
         let conn = NWConnection(to: result.endpoint, using: params)
         connections[key] = conn
+        deadlines[key] = Date().addingTimeInterval(Self.resolveTimeout)
+        let generation = self.generation
         conn.stateUpdateHandler = { state in
             MainActor.assumeIsolated { [weak self] in
-                guard let self, let conn = self.connections[key] else { return }
+                // Look the connection back up rather than capturing it — capturing it here would
+                // retain the connection through its own handler.
+                guard let self, generation == self.generation,
+                      let conn = self.connections[key] else { return }
                 switch state {
                 case .ready:
-                    if case let .hostPort(host, port)? = conn.currentPath?.remoteEndpoint,
-                       let address = Self.hostString(host) {
-                        self.resolved[key] = DiscoveredHost(
-                            id: (id?.isEmpty == false) ? id! : name,
-                            name: name, host: address, port: port.rawValue,
-                            fingerprintHex: fp, requiresPairing: pair == "required",
-                            allowsTofu: pair == "optional", macAddresses: macs,
-                            osChain: osChain)
-                        self.publish()
-                    }
-                    conn.cancel()
+                    let endpoint = conn.currentPath?.remoteEndpoint
                     self.connections[key] = nil
+                    self.deadlines[key] = nil
+                    conn.cancel()
+                    if case let .hostPort(host, port)? = endpoint,
+                       let address = Self.hostString(host) {
+                        self.addresses[key] = (address, port.rawValue)
+                        self.failures[key] = nil
+                        self.retryAt[key] = nil
+                        self.staleAddresses.remove(key)
+                        self.publish()
+                    } else {
+                        // Ready but no usable remote — a failed attempt, not a finished one.
+                        self.resolveFailed(key)
+                    }
                 case .failed, .cancelled:
                     self.connections[key] = nil
+                    self.deadlines[key] = nil
+                    self.resolveFailed(key)
                 default:
-                    break
+                    break // .preparing / .waiting — the sweep's deadline is what ends these
                 }
             }
         }
         conn.start(queue: .main)
     }
 
-    /// Publish the resolved set, deduped by `id` (a host on several interfaces / re-advertising
-    /// collapses to one row), sorted by name.
+    private func resolveFailed(_ key: String) {
+        let count = (failures[key] ?? 0) + 1
+        failures[key] = count
+        retryAt[key] = Date().addingTimeInterval(Self.backoff(count))
+    }
+
+    // MARK: - Sweep
+
+    private func startSweep() {
+        sweep?.cancel()
+        sweep = Task { [weak self] in
+            while !Task.isCancelled {
+                try? await Task.sleep(nanoseconds: 1_000_000_000)
+                guard !Task.isCancelled, let self else { return }
+                self.tick()
+            }
+        }
+    }
+
+    private func tick() {
+        let now = Date()
+        // Time out the resolves that parked. Without this they never end, and `pump()` skips a
+        // service that has a connection in flight — so that host stayed invisible indefinitely.
+        for key in deadlines.filter({ $0.value <= now }).keys {
+            connections[key]?.cancel()
+            connections[key] = nil
+            deadlines[key] = nil
+            resolveFailed(key)
+        }
+        if let at = browserRearmAt, at <= now { armBrowser() }
+        pump()
+        if let until = scanningUntil, until <= now {
+            scanningUntil = nil
+            isScanning = false
+        }
+    }
+
+    // MARK: - Publish
+
+    /// Publish the live adverts that have an address, deduped by `id` (a host on several
+    /// interfaces / re-advertising collapses to one row), sorted by name.
     private func publish() {
         var byID: [String: DiscoveredHost] = [:]
-        for host in resolved.values { byID[host.id] = host }
+        for key in services.keys.sorted() {
+            guard let result = services[key], let address = addresses[key] else { continue }
+            let host = Self.host(from: result, address: address.host, port: address.port)
+            byID[host.id] = host
+        }
         let next = byID.values.sorted {
             $0.name.localizedCaseInsensitiveCompare($1.name) == .orderedAscending
         }
         if next != hosts { hosts = next }
     }
 
+    /// Join a browse result's advert (instance name + TXT) to a resolved address.
+    private static func host(
+        from result: NWBrowser.Result, address: String, port: UInt16
+    ) -> DiscoveredHost {
+        let name = instanceName(result.endpoint)
+        var fp: String?
+        var pair: String?
+        var id: String?
+        var macs: [String] = []
+        var osChain = ""
+        if case let .bonjour(txt) = result.metadata {
+            fp = entry(txt, "fp")
+            pair = entry(txt, "pair")
+            id = entry(txt, "id")
+            macs = (entry(txt, "mac") ?? "")
+                .split(separator: ",")
+                .map { $0.trimmingCharacters(in: .whitespaces) }
+                .filter { !$0.isEmpty }
+            osChain = sanitizeOsChain(entry(txt, "os") ?? "")
+        }
+        return DiscoveredHost(
+            id: (id?.isEmpty == false) ? id! : name,
+            name: name, host: address, port: port,
+            fingerprintHex: fp, requiresPairing: pair == "required",
+            allowsTofu: pair == "optional", macAddresses: macs,
+            osChain: osChain)
+    }
+
     private static func key(_ result: NWBrowser.Result) -> String {
         "\(result.endpoint)"
     }

clients/apple/Sources/PunktfunkKit/Connection/LibraryClient.swift

@@ -38,12 +38,46 @@ public struct LaunchSpec: Codable, Hashable, Sendable {
 /// One title in the unified library. `id` is store-qualified: `steam:<appid>` / `custom:<id>`.
 public struct GameEntry: Codable, Hashable, Identifiable, Sendable {
     public var id: String
-    public var store: String // "steam" | "custom"
+    public var store: String // "steam" | "custom" | "lutris" | "heroic" | "epic" | "gog" | "xbox"
     public var title: String
     public var art: Artwork
     public var launch: LaunchSpec?
+    /// `"game"` (the default, and what an older host omits) or `"launcher"` — an entry that opens
+    /// the launcher itself (Steam Big Picture, Heroic) rather than a title. Deliberately a plain
+    /// optional String: the host owns the vocabulary, and an unknown future value must never fail
+    /// the whole library decode. Anything that isn't `"launcher"` is a game (design D4).
+    public var role: String?
 
     public var isCustom: Bool { store == "custom" }
+
+    /// Whether this entry opens a launcher rather than a game.
+    public var isLauncher: Bool { role == "launcher" }
+
+    /// Display name for the store badge — the same table the Rust clients use
+    /// (`pf-console-ui::library::store_label`). Before this existed the badge said "Steam" for
+    /// every non-custom entry, which a Lutris or GOG title made a lie.
+    public var storeLabel: String {
+        switch store {
+        case "steam": return "Steam"
+        case "custom": return "Custom"
+        case "heroic": return "Heroic"
+        case "lutris": return "Lutris"
+        case "epic": return "Epic"
+        case "gog": return "GOG"
+        case "xbox": return "Xbox"
+        default: return "Game"
+        }
+    }
+}
+
+public extension Array where Element == GameEntry {
+    /// Design D4: launcher entries lead the shelf, and the host's title order survives within each
+    /// group. Applied once where the library is fetched, so no individual view has to remember
+    /// the rule — and a library without launcher entries comes back untouched.
+    var launchersFirst: [GameEntry] {
+        let launchers = filter(\.isLauncher)
+        return launchers.isEmpty ? self : launchers + filter { !$0.isLauncher }
+    }
 }
 
 /// Errors surfaced to the UI so it can guide setup (the common case is "not paired yet").

clients/apple/Sources/PunktfunkKit/Connection/PunktfunkConnection.swift

@@ -1430,6 +1430,49 @@ public final class PunktfunkConnection {
         }
     }
 
+    /// Why a stream session ended — the Swift mirror of `PunktfunkEndReason` (ABI v17).
+    ///
+    /// The distinction that matters to a UI is normal vs alarming, and it is not a spectrum: a
+    /// player quitting their game and a host falling off the network both arrive as "the session
+    /// ended". Without this every client wrote one message for all of them, and every client chose
+    /// an error.
+    public enum SessionEndReason: UInt8, Sendable {
+        /// Not ended, or ended before a reason could be observed. Also the fallback for an
+        /// unrecognized value — the core may be newer than this code.
+        case none = 0
+        /// This client closed the session. Nothing to report: the UI initiated it.
+        case local = 1
+        /// The host's launched game exited. A normal finish, and the one reason worth acting on:
+        /// go back to the library the title was launched from.
+        case gameExited = 2
+        /// The host ended the session deliberately (an operator "End", or it simply finished).
+        case hostEnded = 3
+        /// The host closed reporting a failure of its own.
+        case hostError = 4
+        /// The connection died rather than being closed: idle timeout, reset, network gone. This —
+        /// and only this — is the "the host may be asleep" case.
+        case lost = 5
+
+        /// Is this an ordinary outcome rather than something to alarm the user about? `.none`
+        /// counts as normal: no evidence of trouble is not evidence of it.
+        public var isNormal: Bool { self != .hostError && self != .lost }
+    }
+
+    /// Why this session ended. Only meaningful once it HAS ended (a plane threw `.closed`, or
+    /// `onSessionEnd` fired) — before that it is `.none`.
+    ///
+    /// Read it before tearing the connection down: once `close()` has been requested this reports
+    /// `.none`, which is the safe direction (the caller falls back to its normal handling).
+    public var sessionEndReason: SessionEndReason {
+        guard let h = liveHandle() else { return .none }
+        var out: UInt8 = 0
+        guard punktfunk_connection_end_reason(h, &out) == statusOK else { return .none }
+        return SessionEndReason(rawValue: out) ?? .none
+    }
+
+    /// Shorthand for the single most actionable reason: the host's launched game exited.
+    public var endedBecauseGameExited: Bool { sessionEndReason == .gameExited }
+
     deinit { close() }
 
     /// Snapshot the handle unless close is pending (callers hold their plane lock).

clients/apple/Sources/PunktfunkKit/Gamepad/ControllerTester.swift

@@ -12,7 +12,7 @@ import GameController
 public final class ControllerTester: ObservableObject {
     // `.manual`: the panel's toggles hold a level until changed — no session wire refreshes
     // exist here to keep the renderer's staleness watchdog fed.
-    private let renderer = RumbleRenderer(policy: .manual)
+    private let renderer = RumbleRenderer()
     private weak var controller: GCController?
 
     /// The rumble backend now in use — "DualSense HID · USB/Bluetooth", "CoreHaptics", or "—" —

clients/apple/Sources/PunktfunkKit/Gamepad/DualSenseHID.swift

@@ -21,8 +21,12 @@ import os
 
 private let log = Logger(subsystem: "io.unom.punktfunk", category: "gamepad")
 
-/// Opens the first connected Sony DualSense and forwards motor rumble to it over raw HID.
-/// Single-pad model (we forward exactly one controller), so the first match is the right one.
+/// Opens one connected Sony DualSense and forwards motor rumble to it over raw HID.
+///
+/// A caller that owns a particular pad passes the location id it wants (see
+/// `open(preferringLocationID:)`); the renderer takes that from the `GCController` it is bound to,
+/// so with two DualSenses attached each renderer drives its own device. Without a preference the
+/// lowest location id wins — an arbitrary but *stable* choice, where `Set.first` was neither.
 final class DualSenseHID {
     private let manager: IOHIDManager
     private var device: IOHIDDevice?
@@ -43,9 +47,57 @@ final class DualSenseHID {
 
     deinit { close() }
 
-    /// Find and open the first connected DualSense. Returns false if none is present or it can't
-    /// be opened (caller then falls back to CoreHaptics).
-    func open() -> Bool {
+    /// The IOKit location id of the device this instance opened — the handle a caller correlates
+    /// with its `GCController`. `nil` until a successful `open`.
+    private(set) var locationID: UInt32?
+
+    /// A device's location id, or `nil` if IOKit does not report one.
+    static func locationID(of dev: IOHIDDevice) -> UInt32? {
+        IOHIDDeviceGetProperty(dev, kIOHIDLocationIDKey as CFString) as? UInt32
+    }
+
+    /// Every connected DualSense/Edge, by location id — what a caller pairs against its controllers.
+    static func attachedLocationIDs() -> [UInt32] {
+        let mgr = IOHIDManagerCreate(kCFAllocatorDefault, IOOptionBits(kIOHIDOptionsTypeNone))
+        let matches = productIDs.map { pid in
+            [kIOHIDVendorIDKey: vendorSony, kIOHIDProductIDKey: pid] as CFDictionary
+        }
+        IOHIDManagerSetDeviceMatchingMultiple(mgr, matches as CFArray)
+        guard IOHIDManagerOpen(mgr, IOOptionBits(kIOHIDOptionsTypeNone)) == kIOReturnSuccess else {
+            return []
+        }
+        defer { IOHIDManagerClose(mgr, IOOptionBits(kIOHIDOptionsTypeNone)) }
+        let devices = IOHIDManagerCopyDevices(mgr) as? Set<IOHIDDevice> ?? []
+        return devices.compactMap(locationID(of:)).sorted()
+    }
+
+    /// Which attached device to drive, as an index into `ids` — the whole selection rule, pure so
+    /// it can be tested without an `IOHIDDevice` (which cannot be constructed).
+    ///
+    /// `IOHIDManagerCopyDevices` returns an unordered `Set`, so the previous `Set.first` was not
+    /// merely arbitrary — it can differ between two calls in one process. With two DualSenses that
+    /// made each renderer's pad→device binding a coin flip: both could land on the same device
+    /// (one pad's rumble coming out of the other, and the two per-instance write dedupes fighting
+    /// over it) or split by luck. An explicit location id makes the binding deterministic; the
+    /// lowest-id fallback at least makes it stable. `nil` ids sort last so a device IOKit cannot
+    /// place never displaces one it can.
+    static func preferredIndex(among ids: [UInt32?], preferring wanted: UInt32?) -> Int? {
+        if let wanted, let hit = ids.firstIndex(where: { $0 == wanted }) { return hit }
+        return ids.indices.min { (ids[$0] ?? .max) < (ids[$1] ?? .max) }
+    }
+
+    /// Pick the device to drive from everything attached (see [`preferredIndex`]).
+    static func pick(_ devices: Set<IOHIDDevice>, preferring wanted: UInt32?) -> IOHIDDevice? {
+        let ordered = Array(devices)
+        guard let i = preferredIndex(among: ordered.map(locationID(of:)), preferring: wanted) else {
+            return nil
+        }
+        return ordered[i]
+    }
+
+    /// Find and open a connected DualSense, preferring the one at `preferredLocationID`. Returns
+    /// false if none is present or it can't be opened (caller then falls back to CoreHaptics).
+    func open(preferringLocationID preferred: UInt32? = nil) -> Bool {
         let matches = Self.productIDs.map { pid in
             [kIOHIDVendorIDKey: Self.vendorSony, kIOHIDProductIDKey: pid] as CFDictionary
         }
@@ -55,13 +107,21 @@ final class DualSenseHID {
             return false
         }
         guard let devices = IOHIDManagerCopyDevices(manager) as? Set<IOHIDDevice>,
-              let dev = devices.first
+              let dev = Self.pick(devices, preferring: preferred)
         else {
             log.info("rumble: no DualSense HID device found — falling back to CoreHaptics")
             IOHIDManagerClose(manager, IOOptionBits(kIOHIDOptionsTypeNone))
             return false
         }
         device = dev
+        locationID = Self.locationID(of: dev)
+        if let preferred, locationID != preferred {
+            // Not fatal — one pad still gets rumble — but with two pads attached it means this
+            // renderer is driving the wrong one, and it is invisible without the log line.
+            log.error(
+                "rumble: wanted DualSense at location \(preferred, privacy: .public) but opened \(self.locationID.map(String.init) ?? "unknown", privacy: .public)"
+            )
+        }
         let transport = IOHIDDeviceGetProperty(dev, kIOHIDTransportKey as CFString) as? String
         bluetooth = transport?.lowercased().contains("bluetooth") ?? false
         log.info("rumble: DualSense raw-HID rumble active (transport=\(self.transport, privacy: .public))")
@@ -70,8 +130,16 @@ final class DualSenseHID {
 
     /// Drive the motors. `low` = left/heavy (low-frequency), `high` = right/light (high-frequency),
     /// each 0...255. (0, 0) stops.
-    func rumble(low: UInt8, high: UInt8) {
-        guard let dev = device else { return }
+    ///
+    /// Returns whether the write reached the device. The caller needs this: it used to be logged
+    /// and swallowed, so a failed write still counted as a successful render. That matters most
+    /// for a **stop**, which has nothing behind it — the renderer stamps its write clock even on
+    /// failure, the keepalive re-write only fires for non-zero levels, and the ticker is cancelled
+    /// once the target is `(0, 0)`. On USB there is no firmware timeout either, so a swallowed
+    /// stop left the motors running with nothing scheduled to try again.
+    @discardableResult
+    func rumble(low: UInt8, high: UInt8) -> Bool {
+        guard let dev = device else { return false }
         let report = bluetooth
             ? Self.bluetoothReport(low: low, high: high)
             : Self.usbReport(low: low, high: high)
@@ -81,7 +149,9 @@ final class DualSenseHID {
         }
         if rc != kIOReturnSuccess {
             log.error("rumble: IOHIDDeviceSetReport failed (0x\(String(format: "%08x", rc), privacy: .public))")
+            return false
         }
+        return true
     }
 
     func close() {

clients/apple/Sources/PunktfunkKit/Gamepad/GamepadCapture.swift

@@ -67,6 +67,17 @@ public final class GamepadCapture {
         var axes: [Int32] = [0, 0, 0, 0, 0, 0]
         var fingerActive: [Bool] = [false, false]
         var lastMotionNs: UInt64 = 0
+        // Hold-Select→guide gesture state (pf-client-core's `SelectGesture`, adapted to
+        // this class's mask-diff model): a Select pressed ALONE is held out of the mask
+        // until it resolves into a tap (delivered on release) or — past `guideHold` — a
+        // synthetic guide, down until release.
+        var selectPending = false
+        var selectAsGuide = false
+        /// A delivered tap's release is owed (`tapTimer` scheduled) — its down went out
+        /// outside `buttons`, so `flush` must know to lift it.
+        var tapReleaseOwed = false
+        var gestureTimer: Timer?
+        var tapTimer: Timer?
         init(controller: GCController, pad: UInt32, pref: PunktfunkConnection.GamepadType) {
             self.controller = controller
             self.pad = pad
@@ -87,10 +98,29 @@ public final class GamepadCapture {
     /// `onDisconnectRequest`; the chord keeps forwarding to the host meanwhile (the user is
     /// leaving anyway). The desktop clients' quick-press step (leave fullscreen / release
     /// capture) has no Apple equivalent worth wiring — macOS has ⌃⌥⇧Q/D, touch has the HUD.
-    private static let escapeChord: UInt32 =
+    /// Internal rather than private only so `GamepadEscapeChordTests` can pin it against
+    /// `escapeChordElements` below — the two must not drift.
+    static let escapeChord: UInt32 =
         GamepadWire.leftShoulder | GamepadWire.rightShoulder | GamepadWire.start | GamepadWire.back
+    /// `escapeChord`'s four elements by GameController alias — the ONLY system gestures claimed
+    /// while forwarding is off (see `openSlot`). Kept beside the mask it mirrors: change one and
+    /// change the other, or the chord silently stops reaching us on tvOS. A test asserts the two
+    /// agree, because the failure is invisible until someone is stuck in a stream on an Apple TV.
+    static let escapeChordElements = [
+        GCInputLeftShoulder, GCInputRightShoulder, GCInputButtonMenu, GCInputButtonOptions,
+    ]
     /// pf-client-core's `DISCONNECT_HOLD` — the same 1.5 s on every client.
     private static let disconnectHold: TimeInterval = 1.5
+    /// pf-client-core's `GUIDE_HOLD`: hold Select alone this long → the HOST's guide goes
+    /// down (until release, so a long hold is the host's long-press — a Gaming-Mode
+    /// host's QAM). The gesture exists because iOS reserves the physical Home press (the
+    /// Game Overlay; sanctioned opt-out only via the user's iOS 27+ Home-button setting)
+    /// and tvOS never delivers it at all.
+    private static let guideHold: TimeInterval = 0.35
+    /// pf-client-core's `TAP_PRESS`: a held-back Select tap is delivered as a press with
+    /// its release this far behind — back-to-back transitions can fold into nothing in
+    /// the host's per-pad input fold.
+    private static let tapPress: TimeInterval = 0.05
     private var chordTimer: Timer?
     /// Fired ON MAIN once the escape chord has been held `disconnectHold` — the session owner
     /// disconnects. On tvOS this (plus the Siri Remote's hold-Back) is the ONLY way out of a
@@ -115,10 +145,23 @@ public final class GamepadCapture {
     /// "don't forward" is one fact in one place rather than a condition at twelve call sites.
     private var wire: PunktfunkConnection? { forwarding ? connection : nil }
 
-    public init(connection: PunktfunkConnection, manager: GamepadManager, forwarding: Bool = true) {
+    /// Forward the raw guide + share/QAM presses (`EffectiveSettings.systemButtonsForward`,
+    /// default true on Apple — where the OS shows its own overlay for them, that's the OS's
+    /// business; local mode exists for profile parity with the Gaming-Mode clients).
+    public let systemForward: Bool
+    /// The hold-Select guide gesture (`EffectiveSettings.guideGestureEnabled` — auto = on
+    /// everywhere but macOS). See `guideHold`.
+    public let guideGesture: Bool
+
+    public init(
+        connection: PunktfunkConnection, manager: GamepadManager, forwarding: Bool = true,
+        systemForward: Bool = true, guideGesture: Bool = false
+    ) {
         self.connection = connection
         self.manager = manager
         self.forwarding = forwarding
+        self.systemForward = systemForward
+        self.guideGesture = guideGesture
     }
 
     public func start() {
@@ -202,11 +245,28 @@ public final class GamepadCapture {
         // gesture attached the press is the system's, not the game's. During capture the remote
         // session IS the game: the share button must reach the host (e.g. Steam screenshots),
         // the PS button must open the host's Steam overlay. Restored to .enabled on close.
-        for element in c.physicalInputProfile.elements.values {
+        //
+        // With forwarding OFF none of that applies — no press reaches the host, so taking the
+        // user's screenshot gesture away buys nothing. NARROWED, not skipped: the escape chord
+        // is still read off this slot, and on tvOS it is the only controller way out of a
+        // stream, so the chord's own four elements keep their claim. (Menu especially: leave
+        // its gesture attached on tvOS and the press is the system's — the chord would never
+        // complete and the session would have no controller exit at all.)
+        let claimed = forwarding
+            ? Array(c.physicalInputProfile.elements.values)
+            : Self.escapeChordElements.compactMap { c.physicalInputProfile.elements[$0] }
+        for element in claimed {
             element.preferredSystemGestureState = .disabled
         }
         // The Home/PS button (→ guide; the host maps it to the DualSense PS / Xbox guide bit,
-        // BTN_MODE on the virtual xpad — the Steam-overlay button). Driven DIRECTLY from this
+        // BTN_MODE on the virtual xpad — the Steam-overlay button). On iOS 26 the OS opens its
+        // Game Overlay for this press regardless of the gesture claim below (the app is
+        // LSApplicationCategoryType=games, which enrolls it); the sanctioned per-controller
+        // opt-out is the USER's iOS 27+ Home-button setting. TODO(iOS 27 SDK): read
+        // `GCControllerHomeButtonSettingsManager` and surface a one-time
+        // `openControllerHomeButtonSettings(for:)` deep-link so users can hand the button to
+        // the stream — the class is Swift-only and 27.0+, so it needs the Xcode 27 SDK to
+        // even compile. Until then hold-Select is the reliable route. Driven DIRECTLY from this
         // handler's pressed value (not via buttonMask), because the legacy
         // `extendedGamepad.buttonHome` is unreliable/often nil even when the physical element
         // exists. On tvOS the element is absent (reserved) → nil, the whole block no-ops.
@@ -235,7 +295,11 @@ public final class GamepadCapture {
                 MainActor.assumeIsolated { if let self, let slot { self.touch(slot, finger: 1, x: x, y: y) } }
             }
         }
-        if let motion = c.motion {
+        // Motion is wire-only — `forwardMotion` has nothing to do with forwarding off, and no
+        // local feature reads it. Powering the IMU anyway costs the pad real battery (it streams
+        // gyro + accel continuously over Bluetooth, which is why `closeSlot` is careful to power
+        // it back down), so with nothing to forward we simply never turn it on.
+        if forwarding, let motion = c.motion {
             if motion.sensorsRequireManualActivation { motion.sensorsActive = true }
             motion.valueChangedHandler = { [weak self, weak slot] m in
                 MainActor.assumeIsolated { if let self, let slot { self.forwardMotion(slot, m) } }
@@ -289,7 +353,14 @@ public final class GamepadCapture {
         // as "changed" — otherwise the first stick/button move after a guide press would emit a
         // spurious guide-UP while the button is still physically held (and drop the bit from
         // `slot.buttons`, swallowing the real release too). `flush`/`allButtons` still release it.
-        let newButtons = Self.buttonMask(g) | (slot.buttons & GamepadWire.guide)
+        var raw = Self.buttonMask(g)
+        // Raw system buttons stay local when passthrough is off: misc1 (share/QAM) is
+        // masked here, guide is gated at its own handler.
+        if !systemForward { raw &= ~GamepadWire.misc1 }
+        // The hold-Select gesture rewrites the mask: a Select pressed alone is held out
+        // until it resolves (tap on release / synthetic guide past the threshold).
+        if guideGesture { raw = gestureFiltered(slot, raw) }
+        let newButtons = raw | (slot.buttons & GamepadWire.guide)
         let changed = newButtons ^ slot.buttons
         if changed != 0 {
             for bit in GamepadWire.allButtons where changed & bit != 0 {
@@ -312,10 +383,106 @@ public final class GamepadCapture {
         updateEscapeChord()
     }
 
+    /// The hold-Select→guide state machine over one sync's raw mask (pf-client-core's
+    /// `SelectGesture` rules): Select pressed ALONE is suppressed while pending; another
+    /// button joining makes it real (unsuppressed — the diff sends its down); released
+    /// inside `guideHold` it's a tap, delivered out-of-band on release with the release
+    /// `tapPress` behind; past the threshold `gestureHoldFired` turned it into a synthetic
+    /// guide, lifted here when Select physically releases.
+    ///
+    /// One deliberate divergence from the Rust worker: while transformed into a guide the
+    /// Select stays OUT of `slot.buttons`, so the escape chord doesn't complete on top of
+    /// an in-flight guide-hold — release Select and press the chord plainly instead (the
+    /// chord's four-at-once press never lingers in pending long enough to be affected).
+    private func gestureFiltered(_ slot: Slot, _ raw: UInt32) -> UInt32 {
+        let back = GamepadWire.back
+        let backDown = raw & back != 0
+        let othersDown = raw & ~back != 0
+        if slot.selectAsGuide {
+            if backDown { return raw & ~back }
+            slot.selectAsGuide = false
+            sendGuide(slot, down: false, raw: false)
+            return raw
+        }
+        if slot.selectPending {
+            if !backDown {
+                endPending(slot)
+                deliverTap(slot)
+                return raw
+            }
+            if othersDown {
+                // A combo after all — Select unsuppresses and the diff sends its down.
+                endPending(slot)
+                return raw
+            }
+            return raw & ~back
+        }
+        if backDown, !othersDown, slot.buttons & back == 0 {
+            // Newly pressed, alone: hold it back. An owed tap release goes out first so
+            // the host never sees two downs in a row.
+            if slot.tapReleaseOwed { finishTap(slot) }
+            slot.selectPending = true
+            let timer = Timer(timeInterval: Self.guideHold, repeats: false) { [weak self, weak slot] _ in
+                Task { @MainActor in
+                    if let self, let slot { self.gestureHoldFired(slot) }
+                }
+            }
+            RunLoop.main.add(timer, forMode: .common)
+            slot.gestureTimer?.invalidate()
+            slot.gestureTimer = timer
+            return raw & ~back
+        }
+        return raw
+    }
+
+    /// The hold threshold passed with Select still pending → it IS the guide now, down
+    /// until the physical release (`gestureFiltered`'s `selectAsGuide` branch lifts it).
+    private func gestureHoldFired(_ slot: Slot) {
+        guard slot.selectPending else { return }
+        slot.selectPending = false
+        slot.gestureTimer = nil
+        slot.selectAsGuide = true
+        sendGuide(slot, down: true, raw: false)
+    }
+
+    private func endPending(_ slot: Slot) {
+        slot.selectPending = false
+        slot.gestureTimer?.invalidate()
+        slot.gestureTimer = nil
+    }
+
+    /// Deliver a held-back Select tap: the press now, its release `tapPress` behind. Both
+    /// sends bypass `slot.buttons` (the raw mask no longer carries Select, so the diff
+    /// stays consistent); `tapReleaseOwed` is what `flush` checks so the press can't
+    /// outlive the slot.
+    private func deliverTap(_ slot: Slot) {
+        wire?.send(.gamepadButton(GamepadWire.back, down: true, pad: slot.pad))
+        slot.tapReleaseOwed = true
+        let timer = Timer(timeInterval: Self.tapPress, repeats: false) { [weak self, weak slot] _ in
+            Task { @MainActor in
+                if let self, let slot { self.finishTap(slot) }
+            }
+        }
+        RunLoop.main.add(timer, forMode: .common)
+        slot.tapTimer?.invalidate()
+        slot.tapTimer = timer
+    }
+
+    private func finishTap(_ slot: Slot) {
+        guard slot.tapReleaseOwed else { return }
+        slot.tapReleaseOwed = false
+        slot.tapTimer?.invalidate()
+        slot.tapTimer = nil
+        wire?.send(.gamepadButton(GamepadWire.back, down: false, pad: slot.pad))
+    }
+
     /// Forward the guide (Home/PS) transition directly — it's kept out of `buttonMask` (the legacy
     /// `buttonHome` element is unreliable). Folds into the slot's `buttons` so a held PS button is
-    /// released by `flush` on focus loss / close just like the others.
-    private func sendGuide(_ slot: Slot, down: Bool) {
+    /// released by `flush` on focus loss / close just like the others. `raw: true` marks the
+    /// physical Home handler's calls, which the system-buttons policy can keep local; the
+    /// gesture's synthetic transitions pass `raw: false` and always go out.
+    private func sendGuide(_ slot: Slot, down: Bool, raw: Bool = true) {
+        if raw, !systemForward { return }
         guard !suspended else { return }
         let bit = GamepadWire.guide
         let now = down ? (slot.buttons | bit) : (slot.buttons & ~bit)
@@ -449,6 +616,12 @@ public final class GamepadCapture {
     /// (no GC calls) — safe against an already-removed device. Does NOT close the slot or send
     /// GamepadRemove (that's `closeSlot`).
     private func flush(_ slot: Slot) {
+        // Gesture first: a pending (never-sent) Select just drops, an owed tap release
+        // goes out, and a transformed guide's bit — folded into `buttons` by `sendGuide`
+        // — is lifted by the loop below like any held button.
+        endPending(slot)
+        slot.selectAsGuide = false
+        if slot.tapReleaseOwed { finishTap(slot) }
         for bit in GamepadWire.allButtons where slot.buttons & bit != 0 {
             wire?.send(.gamepadButton(bit, down: false, pad: slot.pad))
         }

clients/apple/Sources/PunktfunkKit/Gamepad/GamepadFeedback.swift

@@ -65,7 +65,7 @@ public final class GamepadFeedback {
         #if os(iOS)
         if UserDefaults.standard.bool(forKey: DefaultsKey.rumbleOnDevice),
             CHHapticEngine.capabilitiesForHardware().supportsHaptics {
-            deviceRumble = RumbleRenderer(policy: .session, actuator: .device)
+            deviceRumble = RumbleRenderer(actuator: .device)
         } else {
             deviceRumble = nil
         }
@@ -117,7 +117,15 @@ public final class GamepadFeedback {
             reset(slot.controller)
             slots[pad] = nil
             let renderer = withRouting { rumbleByPad.removeValue(forKey: pad) }
-            renderer?.stop()
+            // OFF the main actor. `RumbleRenderer.stop()` is a `queue.sync`, and its body is a
+            // per-motor `CHHapticEngine.stop()` — an XPC round trip to gamecontrollerd, which the
+            // renderer's own notes record as able to hang — plus `DualSenseHID.close()`, whose
+            // blocking `IOHIDDeviceSetReport` goes to a device that has just departed. It also
+            // queues behind any in-flight `setup()`. This runs on every unplug and every pin
+            // change, and the main thread is what drives the presenter's CADisplayLink, so
+            // blocking here hitches the picture mid-stream. The renderer is already detached from
+            // routing above, so nothing observes it after this point.
+            if let renderer { Task.detached { renderer.stop() } }
         }
         for (pad, controller) in want {
             if let slot = slots[pad] {
@@ -128,7 +136,7 @@ public final class GamepadFeedback {
                 replay(slot)
             } else {
                 slots[pad] = Slot(controller: controller)
-                let renderer = RumbleRenderer(policy: .session)
+                let renderer = RumbleRenderer()
                 renderer.retarget(controller)
                 withRouting { rumbleByPad[pad] = renderer }
             }
@@ -282,6 +290,12 @@ public final class GamepadFeedback {
     private func reset(_ controller: GCController?) {
         guard let c = controller else { return }
         c.playerIndex = .indexUnset
+        // Put the lightbar out too. This class is what turned it on (see the `Led` and
+        // `PlayerLeds` arms), and every DS write is valid-flag-selective, so a colour the game
+        // set stays lit in firmware after the stream ends — back at the launcher, or for a pad
+        // that merely left the forwarded set. A DS4 is cleared incidentally because its player
+        // indicator IS the lightbar; a DualSense is not.
+        c.light?.color = GCColor(red: 0, green: 0, blue: 0)
         if let ds = c.extendedGamepad as? GCDualSenseGamepad {
             ds.leftTrigger.setModeOff()
             ds.rightTrigger.setModeOff()

clients/apple/Sources/PunktfunkKit/Gamepad/RumbleRenderer.swift

@@ -43,8 +43,14 @@ enum RumbleTuning {
 
     /// Wire amplitude (0...0xFFFF) → CoreHaptics intensity (0...1).
     static func amplitude(_ wire: UInt16) -> Float { Float(wire) / 65535 }
-    /// Wire amplitude → DualSense HID motor byte.
-    static func hidByte(_ wire: UInt16) -> UInt8 { UInt8(wire >> 8) }
+    /// Wire amplitude → DualSense HID motor byte. A nonzero command never collapses to silence:
+    /// the top byte of anything below 0x0100 is 0, so a weak-but-real rumble used to render as
+    /// nothing at all on this path. Floored at 1 — imperceptibly light, but moving. (Android's
+    /// `toAmplitude` has always done this; this was the odd one out.)
+    static func hidByte(_ wire: UInt16) -> UInt8 {
+        let b = UInt8(wire >> 8)
+        return wire != 0 && b == 0 ? 1 : b
+    }
     /// Single-actuator pads render whichever motor is stronger.
     static func combined(low: UInt16, high: UInt16) -> UInt16 { max(low, high) }
     /// Are two baked levels the same (skip the rebuild)?
@@ -81,10 +87,11 @@ enum RumbleTuning {
 ///  4. **Escalating stop.** A throwing `player.stop` means the engine's state is unknown — the
 ///     whole engine is stopped (silencing every player it hosts) and lazily rebuilt behind the
 ///     exponential backoff.
-///  5. **Staleness watchdog** (`Policy.session`): audible with no wire command for
-///     `sessionStaleSeconds` → force silence. A lost stop can outlive the host's 500 ms heal
-///     only if the channel itself died, and then the pad must not buzz forever. `Policy.manual`
-///     (the settings test panel) instead holds a level until it is changed.
+///  5. **No staleness watchdog here.** There was one, keyed off a `Policy` type and a
+///     `sessionStaleSeconds`; both are gone. Every liveness decision — lease expiry, legacy-host
+///     staleness, session close — now belongs to punktfunk-core's shared policy engine
+///     (`client/rumble.rs`), which emits explicit zero commands, so this renderer applies what it
+///     is told and never decides on its own when a level should end.
 ///
 /// Engines are created lazily on the first nonzero amplitude and torn down on retarget;
 /// failures (pads without haptics, engine resets) downgrade to silence — rumble is best-effort
@@ -93,17 +100,6 @@ enum RumbleTuning {
 /// `@unchecked Sendable` is sound because every property is read and written only inside
 /// `queue` closures — the serial queue is the synchronization.
 final class RumbleRenderer: @unchecked Sendable {
-    /// Who ends an un-refreshed nonzero target. Session mode applies the core policy engine's
-    /// commands verbatim — the engine (punktfunk-core `client/rumble.rs`) owns every lease,
-    /// staleness, and close decision and emits explicit zeros, so the renderer keeps NO
-    /// staleness policy of its own anymore. The controller test panel (`manual`) holds a slider
-    /// level indefinitely; both are identical renderer-side today, the distinction is kept for
-    /// the call sites' intent.
-    struct Policy {
-        static let session = Policy()
-        static let manual = Policy()
-    }
-
     /// Which physical actuator this renderer drives: the forwarded controller's haptics engine
     /// (the default), or THIS device's own Taptic Engine (`CHHapticEngine()`) — the opt-in
     /// "rumble on this device" mirror for phone-clip pads that ship without rumble motors.
@@ -115,7 +111,6 @@ final class RumbleRenderer: @unchecked Sendable {
     }
 
     private let queue = DispatchQueue(label: "io.unom.punktfunk.haptics", qos: .userInteractive)
-    private let policy: Policy
     private let actuator: Actuator
 
     /// One finite haptic play on a motor: the player plus when (engine timeline) it expires.
@@ -190,8 +185,7 @@ final class RumbleRenderer: @unchecked Sendable {
         ((0, 0), DispatchTime(uptimeNanoseconds: 0))
     #endif
 
-    init(policy: Policy = .session, actuator: Actuator = .controller) {
-        self.policy = policy
+    init(actuator: Actuator = .controller) {
         self.actuator = actuator
     }
 
@@ -459,6 +453,18 @@ final class RumbleRenderer: @unchecked Sendable {
         if split {
             low = makeMotor(haptics, .leftHandle, sharpness: RumbleTuning.sharpnessLow)
             high = makeMotor(haptics, .rightHandle, sharpness: RumbleTuning.sharpnessHigh)
+            // HALF a split is worse than none, and it used to pass silently: only the all-nil case
+            // below counts as failure, so one surviving handle left `ok` true and `reportHealth(nil)`
+            // announced HEALTHY. What actually rendered was wrong in a direction that depends on
+            // which handle died — lose `high` and `render` falls to the combined branch (selected
+            // purely by `high != nil`), playing max(low, high) on the LEFT handle at the combined
+            // sharpness; lose `low` and the split branch's reconcile no-ops on the nil slot, so the
+            // heavy motor is discarded outright. Tear the survivor down and take the combined path,
+            // which at least renders both motors somewhere.
+            if low == nil || high == nil {
+                log.warning("rumble: only one split-handle engine came up — falling back to combined")
+                teardown() // disarms handlers, stops the survivor's players + engine, nils both
+            }
         } else {
             low = makeMotor(haptics, .default, sharpness: RumbleTuning.sharpnessCombined)
         }
@@ -587,7 +593,9 @@ final class RumbleRenderer: @unchecked Sendable {
         #if os(macOS)
         guard let c, c.extendedGamepad is GCDualSenseGamepad else { return false }
         let hid = DualSenseHID()
-        guard hid.open() else { return false }
+        // Ask for the device this renderer's controller actually is, so two attached DualSenses
+        // do not both get driven through whichever one an unordered Set happened to yield first.
+        guard hid.open(preferringLocationID: Self.hidLocationID(for: c)) else { return false }
         dualSenseHID = hid
         return true
         #else
@@ -595,6 +603,24 @@ final class RumbleRenderer: @unchecked Sendable {
         #endif
     }
 
+    #if os(macOS)
+    /// Correlate a `GCController` with an IOKit location id.
+    ///
+    /// GameController exposes no location id, so there is no direct mapping. What it does expose is
+    /// a stable per-controller ordering, and IOKit's location ids are stable per port: pairing the
+    /// two by rank makes each renderer pick a *distinct* device, which is the property that was
+    /// missing. With one pad attached this is the same device it always was.
+    static func hidLocationID(for c: GCController) -> UInt32? {
+        let ids = DualSenseHID.attachedLocationIDs()
+        guard ids.count > 1 else { return ids.first }
+        let peers = GCController.controllers().filter { $0.extendedGamepad is GCDualSenseGamepad }
+        guard let rank = peers.firstIndex(where: { $0 === c }), rank < ids.count else {
+            return ids.first
+        }
+        return ids[rank]
+    }
+    #endif
+
     /// Write the target to the DualSense over HID if that's the active backend; false → not a
     /// HID pad, so the caller renders via CoreHaptics. Deduped on the pad's 0...255 resolution,
     /// with a periodic keepalive re-write while nonzero (the ticker calls back in here).
@@ -605,8 +631,20 @@ final class RumbleRenderer: @unchecked Sendable {
         let keepalive = levels != (0, 0)
             && seconds(since: lastHidWrite.at) > RumbleTuning.hidKeepaliveSeconds
         if levels != lastHidWrite.levels || keepalive {
-            hid.rumble(low: levels.0, high: levels.1)
-            lastHidWrite = (levels, .now())
+            if hid.rumble(low: levels.0, high: levels.1) {
+                lastHidWrite = (levels, .now())
+            } else {
+                // The write did not reach the device. Do NOT stamp the clock — that would claim a
+                // render that never happened, and for a stop there is nothing behind it: the
+                // keepalive only re-writes non-zero levels and the ticker is cancelled once the
+                // target is (0, 0), so the motors would keep running with nothing scheduled.
+                // Drop the handle instead: the pad reverts to CoreHaptics, and a reconnect
+                // rebuilds it. Health is reported so the state is visible rather than silent.
+                log.error("rumble: HID write failed — dropping the handle, falling back")
+                closeHID()
+                reportHealth("Lost the direct connection to this DualSense; using the system path.")
+                return false
+            }
         }
         return true
         #else

clients/apple/Sources/PunktfunkKit/Views/StreamView.swift

@@ -538,14 +538,25 @@ public final class StreamLayerView: NSView {
         }
     }
 
-    /// Tell the host who renders the pointer (the §8 mid-stream render flip): we draw it only
-    /// while the DESKTOP model is engaged (the local OS cursor wears the host shape); under
-    /// the capture model — and while released — the host composites it into the video (full
-    /// fidelity, the pre-channel look). One edge-detected reconciler, called from every
+    /// Tell the host who renders the pointer (the §8 mid-stream render flip). The host may
+    /// composite one into the video ONLY while we are holding a grabbed, hidden pointer — the
+    /// capture model, engaged. That is the one state with no local cursor on screen.
+    ///
+    /// Every other state leaves a normal OS cursor visible over the video: the desktop model
+    /// draws it wearing the host's shape, and a RELEASED view shows the plain arrow. A
+    /// host-composited pointer then appears *underneath* it as a second cursor — and, because a
+    /// released view forwards no motion, one that never moves. On glass that reads as a frozen
+    /// duplicate stuck wherever the host pointer was last left (verified: `client_draws=false
+    /// blended=true live=(-1, 622)` — parked on the streamed output's left edge while the user
+    /// moved their own cursor around freely).
+    ///
+    /// So "released" counts as WE draw it: the host stops compositing, the client keeps
+    /// receiving shape/state over the channel (the forwarder only ticks on this side of the
+    /// flip), and re-engaging is seamless. One edge-detected reconciler, called from every
     /// transition (chord, engage/release, session start).
     private func reconcileCursorRender() {
         guard cursorChannelActive, let connection else { return }
-        let clientDraws = captured && desktopMouse
+        let clientDraws = !captured || desktopMouse
         guard sentClientDraws != clientDraws else { return }
         sentClientDraws = clientDraws
         connection.setCursorRender(clientDraws: clientDraws)

clients/apple/Sources/PunktfunkKit/Views/StreamViewIOS.swift

@@ -186,6 +186,16 @@ public final class StreamViewController: StreamViewControllerBase {
     // pointer back to iPadOS, so an unwanted drop is re-requested below. The DELIBERATE releases
     // (⌘⎋, ⌃⌥⇧Q, the Stream menu, backgrounding) all clear `captured` first, so `wantsPointerLock`
     // is already false when their drop is observed and none of them are fought here.
+    //
+    // Recovery is TWO-STAGE, because either stage alone leaves a hole:
+    //   1. the burst below, fired the instant the drop is observed — wins back a lock the system
+    //      is willing to return immediately (a transient drop that wasn't Escape at all);
+    //   2. a CLICK into the video while still captured (`onPointerButton`) — the fallback for the
+    //      Escape case proper, where the platform declines during the moment right after its own
+    //      release gesture and the burst therefore expires having achieved nothing.
+    // Stage 2 is what keeps a lost burst from being permanent: `captured` is still true, so no
+    // other path would ever ask again, and the capture would spend the rest of its life on the
+    // absolute pointer — clicking correctly, aiming not at all.
     /// Whether this capture ever actually held the lock. Only a lock we HELD is worth winning back
     /// — never having been granted one means the scene doesn't qualify, not that Esc took it.
     /// Cleared when capture ends, so each capture starts from a clean slate.
@@ -215,6 +225,15 @@ public final class StreamViewController: StreamViewControllerBase {
     /// How long an escalated attempt reports `prefersPointerLocked == false` before flipping back,
     /// so the system observes a real transition instead of coalescing the flip away.
     private static let pointerLockForcedOffHold: TimeInterval = 0.05
+    /// Attempts spent in the QUIET tail (see `scheduleQuietRelock()`), reset with the burst.
+    private var pointerRelockQuietAttempt = 0
+    /// When the quiet tail re-asks, measured from the drop. The visible burst above spends its whole
+    /// budget inside ~0.6 s — and the pointer-lock cooldown the platform applies right after its own
+    /// Escape gesture is about a second, so every one of those attempts asks while the answer can
+    /// only be no. These land AFTER it. They are "quiet" because unlike the burst they do not hide
+    /// the cursor or mute motion: the pointer behaves exactly as it does today while they run, so
+    /// stretching the recovery costs the user nothing if it also fails.
+    private static let pointerRelockQuietDelays: [TimeInterval] = [1.2, 2.4]
     #endif
 
     /// Reads whether the scene's pointer is actually locked right now; nil = state
@@ -330,12 +349,80 @@ public final class StreamViewController: StreamViewControllerBase {
         // SwiftUI places us in the hierarchy AFTER start()'s setCaptured(true), and may reparent us
         // later — re-anchor the chain here so a lock requested before we had a parent still lands.
         updatePointerLockChain()
+        anchorKeyResponder()
     }
 
     public override func didMove(toParent parent: UIViewController?) {
         super.didMove(toParent: parent)
         updatePointerLockChain() // chain shape changed — re-anchor (or no-op if not yet in a window)
     }
+
+    /// Put THIS controller on the responder chain for hardware key presses.
+    ///
+    /// Nothing of ours is otherwise a first responder during a normal stream: keys arrive on the
+    /// GameController (`GCKeyboard`) path, which is a parallel HID feed that does not consume the
+    /// UIKit event, and `StreamLayerUIView` only becomes first responder to summon the SOFT
+    /// keyboard (it is `UIKeyInput`, so making it one for any other reason would raise the on-screen
+    /// keyboard mid-game). With no responder of ours in the chain, every hardware key press reaches
+    /// UIKit unclaimed — and an unclaimed press is what lets the system apply its own default for
+    /// that key. `pressesBegan` below is where we claim Escape; this is what gets it delivered.
+    ///
+    /// A controller is not `UIKeyInput`, so being first responder raises no keyboard. Deferred to
+    /// the soft keyboard whenever the view has taken over, so the three-finger-swipe keyboard is
+    /// unaffected.
+    ///
+    /// Only while captured — the whole claim is scoped to "the stream owns the keyboard", and
+    /// holding the chain outside that would sit in front of SwiftUI's focus for no reason. Safe to
+    /// call from anywhere: `start()` engages capture BEFORE SwiftUI puts us in a window (where
+    /// `becomeFirstResponder` cannot succeed), so `viewDidAppear` calls it again to catch up.
+    private func anchorKeyResponder() {
+        guard captured, !streamView.isFirstResponder, !isFirstResponder else { return }
+        becomeFirstResponder()
+    }
+
+    public override var canBecomeFirstResponder: Bool { true }
+
+    /// Claim Escape while the stream owns the keyboard, so the SYSTEM never gets to act on it.
+    ///
+    /// This is the fix for "Escape hands the mouse back to iPadOS": the platform releases the
+    /// scene's pointer lock on an Escape that nothing claimed — the same "let me out" the web
+    /// Pointer Lock API mandates. Every recovery attempt before this one fought that release AFTER
+    /// the fact (a re-lock burst, then a click), and the platform's post-Escape cooldown means the
+    /// burst is refused by construction. Claiming the press means there is nothing to recover from.
+    ///
+    /// Escape is forwarded to the host on the GCKeyboard path, which is untouched by this — that
+    /// path never sees the UIKit responder chain, so the host still receives the keystroke and
+    /// in-game menus still open. Only the system's own interpretation is suppressed.
+    ///
+    /// Strictly scoped: only while `captured` (the stream owns input), and only Escape. Anything
+    /// else — including every key while the pointer is released — goes to `super` untouched, so
+    /// Escape still dismisses sheets, exits full screen and does everything else it should whenever
+    /// we are not holding the keyboard. The deliberate ways out are unaffected: ⌘⎋ and ⌃⌥⇧Q are
+    /// recognized on the GCKeyboard path and clear `captured` themselves.
+    public override func pressesBegan(_ presses: Set<UIPress>, with event: UIPressesEvent?) {
+        let unclaimed = presses.filter { !claimsPress($0) }
+        if !unclaimed.isEmpty || presses.isEmpty {
+            super.pressesBegan(unclaimed, with: event)
+        }
+    }
+
+    public override func pressesEnded(_ presses: Set<UIPress>, with event: UIPressesEvent?) {
+        let unclaimed = presses.filter { !claimsPress($0) }
+        if !unclaimed.isEmpty || presses.isEmpty {
+            super.pressesEnded(unclaimed, with: event)
+        }
+    }
+
+    public override func pressesCancelled(_ presses: Set<UIPress>, with event: UIPressesEvent?) {
+        // Never swallowed: a cancelled press is the system taking the key away from us, and
+        // dropping it here would strand UIKit's own bookkeeping for a press we did claim.
+        super.pressesCancelled(presses, with: event)
+    }
+
+    /// Is this press one the stream owns outright (Escape while captured)?
+    private func claimsPress(_ press: UIPress) -> Bool {
+        captured && press.key?.keyCode == .keyboardEscape
+    }
     #endif
 
     #if os(tvOS)
@@ -446,6 +533,32 @@ public final class StreamViewController: StreamViewControllerBase {
             }
             guard self.inputCapture?.gcMouseForwarding == false else { return }
             self.inputCapture?.sendMouseButton(button, pressed: down)
+            // …and if we're captured but NOT locked, this click is also the recovery gesture for an
+            // Escape-drop the burst lost. iPadOS refuses to re-lock in the moment right after its
+            // own "let me out" gesture, so the burst fired at the drop can spend its whole budget
+            // and give up while the capture is still wanted. Nothing else would ever re-ask —
+            // setCaptured is the only other requester and a bare Esc never clears `captured` — so
+            // without this the session stays on the absolute path for the rest of the capture:
+            // clicks still land where you aim (absolute positions keep forwarding) but the game
+            // gets no relative deltas, so camera look is dead. A click is a real user gesture,
+            // which is exactly what the platform wants before it will hand the lock back.
+            //
+            // On the button UP, so the click has fully forwarded on ONE transport first: asking on
+            // the DOWN can flip `gcMouseForwarding` mid-click and strand the release on the GCMouse
+            // path. Gated on `pointerLockWasEngaged` exactly as the drop path is, so a scene that
+            // never qualifies (Stage Manager, Split View) is never bursted at, and on a burst not
+            // already being in flight — a pending burst mutes absolute motion, so re-arming one on
+            // every click of a menu the user is still aiming around would freeze the cursor between
+            // clicks. Only once it has settled does a further click buy a fresh budget (clearing the
+            // attempt counter, so a gesture isn't refused inside the 2 s window the drop's own burst
+            // may have just spent).
+            if !down, self.wantsPointerLock, self.pointerLockWasEngaged,
+                !self.pointerRelockPending, self.pointerLockEngaged() != true {
+                self.pointerRelockAttempt = 0
+                self.pointerRelockQuietAttempt = 0 // a real gesture buys a fresh tail too
+                self.updatePointerLockChain() // a reparent since the drop would break the walk to us
+                self.requestPointerRelock()
+            }
         }
         // Scroll is the ONE indirect channel that is NOT gated on the lock. The scroll pan keeps
         // firing while the scene is pointer-locked (it is the only way trackpad two-finger scrolling
@@ -714,10 +827,16 @@ public final class StreamViewController: StreamViewControllerBase {
             guard captureEnabled, !captured, connection != nil else { return }
             inputCapture?.setForwarding(true, suppressClick: fromClick)
             captured = true
+            // Claim the responder chain for as long as we own the keyboard — `pressesBegan` has to
+            // be delivered to us before it can keep Escape away from the system.
+            anchorKeyResponder()
         } else {
             guard captured else { return }
             inputCapture?.setForwarding(false)
             captured = false
+            // Hand the chain back: released means Escape is the system's again, and staying first
+            // responder for a stream that no longer owns input would sit in front of SwiftUI focus.
+            if isFirstResponder { resignFirstResponder() }
         }
         setNeedsUpdateOfPrefersPointerLocked()
         updatePointerLockChain() // (re)anchor the SwiftUI ancestors so the lock actually resolves
@@ -747,6 +866,7 @@ public final class StreamViewController: StreamViewControllerBase {
             pointerLockWasEngaged = true
             pointerRelockPending = false
             pointerRelockAttempt = 0
+            pointerRelockQuietAttempt = 0 // granted — any scheduled tail finds nothing to do
         } else if wantsPointerLock, pointerLockWasEngaged {
             requestPointerRelock()
         } else {
@@ -755,6 +875,7 @@ public final class StreamViewController: StreamViewControllerBase {
             if !wantsPointerLock { pointerLockWasEngaged = false }
             pointerRelockPending = false
             pointerRelockAttempt = 0
+            pointerRelockQuietAttempt = 0
         }
         let useGCMouse = captured && locked
         // Lock dropped (or capture ended) while the GCMouse path held a button down: once
@@ -795,10 +916,12 @@ public final class StreamViewController: StreamViewControllerBase {
             pointerRelockAttempt = 0
         }
         guard pointerRelockAttempt < Self.pointerRelockAttemptLimit else {
-            // Out of budget: fall back to exactly today's behavior — the iPadOS cursor comes back
-            // and a click into the video re-captures. The caller invalidates the interaction, so
-            // the cursor can never stay hidden on a lock the system won't grant.
+            // Out of VISIBLE budget: give the cursor straight back (the caller invalidates the
+            // interaction, so it can never stay hidden on a lock the system won't grant) and hand
+            // off to the quiet tail, which keeps asking after the platform's post-Escape cooldown
+            // without costing the user anything while it does.
             pointerRelockPending = false
+            scheduleQuietRelock()
             return
         }
         pointerRelockAttempt += 1
@@ -846,6 +969,43 @@ public final class StreamViewController: StreamViewControllerBase {
             }
         }
     }
+
+    /// Keep asking for the lock after the visible burst has given up — past the cooldown the
+    /// platform applies to its own Escape gesture, which is the window the burst spends entirely.
+    ///
+    /// Deliberately NOT a longer burst. `pointerRelockPending` hides the cursor and mutes absolute
+    /// motion, which is only tolerable for the couple of frames a fast re-grab takes; holding that
+    /// for seconds would trade a released pointer for a frozen one. These attempts leave the
+    /// pointer fully usable — if they all fail the user sees exactly today's behaviour, and a click
+    /// is still the immediate way back.
+    ///
+    /// Each attempt presents a real false→true transition (the same escalation the burst uses on
+    /// its later tries) because re-asserting a value the system already holds is what didn't take.
+    /// A grant arrives as a `didChange` → `syncPointerLock`, which resets the counters, so a
+    /// successful attempt silently ends the tail.
+    private func scheduleQuietRelock() {
+        guard pointerRelockQuietAttempt < Self.pointerRelockQuietDelays.count else { return }
+        let delay = Self.pointerRelockQuietDelays[pointerRelockQuietAttempt]
+        pointerRelockQuietAttempt += 1
+        DispatchQueue.main.asyncAfter(deadline: .now() + delay) { [weak self] in
+            guard let self else { return }
+            // Still wanted, still ours to want, and still not held — otherwise the tail is moot.
+            guard self.wantsPointerLock, self.pointerLockWasEngaged,
+                self.pointerLockEngaged() != true,
+                self.view.window?.windowScene?.activationState == .foregroundActive
+            else { return }
+            self.pointerLockForcedOff = true
+            self.setNeedsUpdateOfPrefersPointerLocked()
+            self.updatePointerLockChain()
+            DispatchQueue.main.asyncAfter(deadline: .now() + Self.pointerLockForcedOffHold) {
+                [weak self] in
+                guard let self else { return }
+                self.pointerLockForcedOff = false
+                self.setNeedsUpdateOfPrefersPointerLocked()
+                self.scheduleQuietRelock() // no-op once the delays are spent, or once granted
+            }
+        }
+    }
     #endif
 
     deinit {

clients/apple/Sources/PunktfunkShared/DefaultsKeys.swift

@@ -38,6 +38,17 @@ public enum DefaultsKey {
     /// host two pads for one pair of hands. Read at connect: `SessionModel` then never starts
     /// `GamepadCapture`, so no slot opens, no arrival is sent and no virtual pad is built.
     public static let gamepadForwarding = "punktfunk.gamepadForwarding"
+    /// Where a controller's SYSTEM buttons (guide + the share/QAM misc) land while streaming:
+    /// `"auto"` | `"forward"` | `"local"` — the cross-client `system_buttons` key. Auto
+    /// forwards on every Apple platform: the local Game Overlay is the OS's business (and on
+    /// iOS 27+ the user can hand the Home button to the app in Settings), so suppressing our
+    /// send would gain nothing.
+    public static let systemButtons = "punktfunk.systemButtons"
+    /// The hold-Select guide gesture: `"auto"` | `"on"` | `"off"` — the cross-client
+    /// `guide_gesture` key. Auto arms it everywhere but macOS: iOS reserves the physical Home
+    /// press for the Game Overlay (uncapturable pre-27) and tvOS never delivers it at all, so
+    /// holding Select is the controller route to the host's guide there.
+    public static let guideGesture = "punktfunk.guideGesture"
     public static let bitrateKbps = "punktfunk.bitrateKbps"
     /// 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 in-core decode + AVAudioEngine layout.
@@ -168,6 +179,14 @@ public enum DefaultsKey {
     /// layout (the console launcher, gamepad-navigable settings, a coverflow-style library)
     /// whenever a gamepad is connected. On by default; see `GamepadUIEnvironment.isActive`.
     public static let gamepadUIEnabled = "punktfunk.gamepadUIEnabled"
+    /// Which colour family the gamepad UI's living backdrop drifts through — a
+    /// `GamepadPalette` id ("violet" = the brand default, then "tide"/"forest"/"ember"/
+    /// "rose"/"graphite"). The cross-client `ui_palette` key: the desktop console and the
+    /// Android client carry the same table under the same names. Presentation only, so it is
+    /// a device preference and never part of a stream profile. An unknown value reads as the
+    /// default rather than failing — a newer client may have shipped a palette this build
+    /// doesn't know.
+    public static let uiPalette = "punktfunk.uiPalette"
     /// iPhone: ALSO play the rumble the host addresses to controller 1 (wire pad 0) on this
     /// device's own Taptic Engine — for phone-clip pads that ship without rumble motors, where
     /// the phone body is the only actuator in the player's hands. Off by default (opt-in); read

clients/apple/Sources/PunktfunkShared/EffectiveSettings.swift

@@ -35,6 +35,10 @@ public struct EffectiveSettings: Equatable, Sendable {
     public var invertScroll = false
     public var gamepadType = 0
     public var gamepadForwarding = true
+    /// Cross-client `system_buttons`: "auto" | "forward" | "local".
+    public var systemButtons = "auto"
+    /// Cross-client `guide_gesture`: "auto" | "on" | "off".
+    public var guideGesture = "auto"
     /// A `StatsVerbosity` raw value; the enum lives in PunktfunkKit, which this module can't see.
     public var statsVerbosity = "normal"
     public var fullscreenWhileStreaming = true
@@ -95,6 +99,8 @@ public struct EffectiveSettings: Equatable, Sendable {
         invertScroll = bool(DefaultsKey.invertScroll, invertScroll)
         gamepadType = int(DefaultsKey.gamepadType, gamepadType)
         gamepadForwarding = bool(DefaultsKey.gamepadForwarding, gamepadForwarding)
+        systemButtons = str(DefaultsKey.systemButtons, systemButtons)
+        guideGesture = str(DefaultsKey.guideGesture, guideGesture)
         statsVerbosity = Self.storedStatsVerbosity(defaults)
         fullscreenWhileStreaming = bool(
             DefaultsKey.fullscreenWhileStreaming, fullscreenWhileStreaming)
@@ -121,6 +127,36 @@ public struct EffectiveSettings: Equatable, Sendable {
         return "normal"
     }
 
+    /// The `system_buttons` policy resolved for this platform: forward the raw guide (and
+    /// share/QAM misc) presses? Auto = forward on every Apple platform — where the OS shows
+    /// its own overlay for the press that is the OS's business, and suppressing our send
+    /// would only break users who handed the button to the app (iOS 27's Home-button
+    /// setting; macOS with the gestures claimed).
+    public var systemButtonsForward: Bool {
+        switch systemButtons {
+        case "local": return false
+        default: return true
+        }
+    }
+
+    /// The hold-Select guide gesture resolved for this platform ([`guideGesture`]). Auto =
+    /// on everywhere but macOS: iOS reserves the physical Home press (the Game Overlay,
+    /// uncapturable pre-27) and tvOS never delivers it, so holding Select is the controller
+    /// route to the host's guide — and, held on, to a Gaming-Mode host's QAM. On macOS the
+    /// raw press reaches the host, so auto stays off and Select keeps its exact timing.
+    public var guideGestureEnabled: Bool {
+        switch guideGesture {
+        case "on": return true
+        case "off": return false
+        default:
+            #if os(macOS)
+            return false
+            #else
+            return true
+            #endif
+        }
+    }
+
     /// The one resolution seam: this overlay on top of these settings. Pure — no store reads, no
     /// clock — so it is testable field by field. A `.some` that happens to equal the base is a
     /// legitimate PIN: it keeps its value when the global later moves.
@@ -143,6 +179,8 @@ public struct EffectiveSettings: Equatable, Sendable {
         if let v = overlay.invertScroll { s.invertScroll = v }
         if let v = overlay.gamepadType { s.gamepadType = v }
         if let v = overlay.gamepadForwarding { s.gamepadForwarding = v }
+        if let v = overlay.systemButtons { s.systemButtons = v }
+        if let v = overlay.guideGesture { s.guideGesture = v }
         if let v = overlay.statsVerbosity { s.statsVerbosity = v }
         if let v = overlay.fullscreenWhileStreaming { s.fullscreenWhileStreaming = v }
         if let v = overlay.enable444 { s.enable444 = v }

clients/apple/Sources/PunktfunkShared/GamepadPalette.swift

@@ -0,0 +1,177 @@
+// The gamepad UI's background colour families, and the ink each one calls for.
+//
+// A palette is a short ordered ramp of DISTINCT hues, not one hue at several brightnesses. The
+// 4×4 mesh samples that ramp diagonally with a per-cell offset (`cellRamp`), so neighbouring
+// cells land on different parts of it and the colours pool and swirl the way a real gradient
+// poster does; the mesh's existing control-point drift then moves those pools around. An earlier
+// version rotated ONE field's hue per palette, which is why every non-default palette read flat.
+//
+// A palette also owns the UI sitting on it: `accent` is the focus wash / selected pill / switch
+// colour, and `light` flips the ink so a pale field gets dark text instead of white.
+//
+// The table, `ramp` and `cellRamp` are mirrored in `pf-console-ui`'s `library.rs` (Rust) and the
+// Android client's `GamepadPalette.kt` (Kotlin) under the same ids, so one `ui_palette` value is
+// one look on every client. Keep the three copies in step: a palette added here without the
+// others is a value the other clients silently render as Violet.
+//
+// It lives in PunktfunkShared rather than next to the views because that is the target the tests
+// can reach — the arithmetic below is the part that has to agree across three languages.
+
+import Foundation
+import simd
+
+public struct GamepadPalette: Identifiable, Equatable, Sendable {
+    /// The stored `ui_palette` value (`DefaultsKey.uiPalette`).
+    public let id: String
+    /// What the settings row shows.
+    public let name: String
+    /// The colour ramp, dark end first. Empty = use `violetMesh` verbatim (the brand default,
+    /// kept bit-identical to what every install already sees).
+    public let stops: [SIMD3<Double>]
+    /// The field's ground — what the corners settle onto and what the calm mix lifts toward.
+    public let ground: SIMD3<Double>
+    /// The UI accent: focus wash, selected tab pill, switch track, caret.
+    public let accent: SIMD3<Double>
+    /// A pale field: the UI flips to dark ink and the legibility scrims go white.
+    public let light: Bool
+
+    /// Where each of the 16 mesh cells samples the ramp. The base is the diagonal
+    /// `0.5·(x + y)` — top-left is the ramp's dark end, bottom-right its bright one — and the
+    /// per-cell nudges break the banding a pure diagonal would give, so hues pool instead of
+    /// striping.
+    static let cellRamp: [Double] = [
+         0.10, -0.06,  0.04, -0.12,
+        -0.08,  0.14, -0.10,  0.06,
+         0.06, -0.12,  0.16, -0.04,
+        -0.10,  0.08, -0.06,  0.12,
+    ]
+
+    /// The brand default's 16 mesh colours, row-major 4×4: dark-violet corners sink the frame,
+    /// the edges carry mid-tone violets, and the interior holds the bright brand family.
+    public static let violetMesh: [SIMD3<Double>] = {
+        let corner = SIMD3(0.075, 0.060, 0.160)
+        return [
+            corner, SIMD3(0.34, 0.27, 0.72), SIMD3(0.30, 0.26, 0.74), corner,
+            SIMD3(0.42, 0.20, 0.54), SIMD3(0.49, 0.39, 0.95), SIMD3(0.28, 0.31, 0.84), SIMD3(0.16, 0.26, 0.64),
+            SIMD3(0.45, 0.23, 0.60), SIMD3(0.53, 0.31, 0.75), SIMD3(0.35, 0.35, 0.91), SIMD3(0.19, 0.28, 0.70),
+            corner, SIMD3(0.22, 0.18, 0.54), SIMD3(0.24, 0.20, 0.58), corner,
+        ]
+    }()
+
+    /// The brand default's blob ramp — the four colours the pre-18/15 legacy field used, kept so
+    /// `violet` is unchanged on older OSes too.
+    static let violetBlobs: [SIMD3<Double>] = [
+        SIMD3(0.53, 0.47, 0.96), SIMD3(0.24, 0.20, 0.72), SIMD3(0.62, 0.30, 0.80),
+        SIMD3(0.22, 0.38, 0.86), SIMD3(0.53, 0.47, 0.96),
+    ]
+
+    /// The twelve shipped palettes: the brand default, five more dark fields, then six pale
+    /// ones. Cycling order runs dark → light, so stepping the row walks the whole range one way.
+    public static let all: [GamepadPalette] = [
+        // --- dark fields (white ink) ---
+        GamepadPalette(
+            id: "violet", name: "Violet", stops: [],
+            ground: SIMD3(0.075, 0.060, 0.160), accent: SIMD3(0.525, 0.471, 0.961), light: false),
+        GamepadPalette(
+            // Deep indigo climbing through violet into a hot magenta.
+            id: "nebula", name: "Nebula",
+            stops: [SIMD3(0.07, 0.05, 0.20), SIMD3(0.26, 0.14, 0.54), SIMD3(0.52, 0.20, 0.72),
+                    SIMD3(0.82, 0.26, 0.62), SIMD3(0.98, 0.46, 0.68)],
+            ground: SIMD3(0.055, 0.040, 0.135), accent: SIMD3(0.95, 0.42, 0.72), light: false),
+        GamepadPalette(
+            // Ink-blue water: teal → cerulean → a violet undertow.
+            id: "abyss", name: "Abyss",
+            stops: [SIMD3(0.02, 0.10, 0.17), SIMD3(0.04, 0.28, 0.42), SIMD3(0.07, 0.46, 0.63),
+                    SIMD3(0.16, 0.38, 0.78), SIMD3(0.26, 0.22, 0.58)],
+            ground: SIMD3(0.018, 0.070, 0.130), accent: SIMD3(0.26, 0.76, 0.92), light: false),
+        GamepadPalette(
+            // Banked coals: plum embers → crimson → burnt orange → gold.
+            id: "ember", name: "Ember",
+            stops: [SIMD3(0.16, 0.03, 0.10), SIMD3(0.45, 0.06, 0.12), SIMD3(0.72, 0.18, 0.06),
+                    SIMD3(0.90, 0.42, 0.08), SIMD3(0.95, 0.68, 0.18)],
+            ground: SIMD3(0.090, 0.035, 0.040), accent: SIMD3(0.98, 0.62, 0.26), light: false),
+        GamepadPalette(
+            // Forest floor into moss and a lime break.
+            id: "moss", name: "Moss",
+            stops: [SIMD3(0.03, 0.11, 0.09), SIMD3(0.06, 0.27, 0.20), SIMD3(0.09, 0.45, 0.31),
+                    SIMD3(0.28, 0.61, 0.28), SIMD3(0.58, 0.77, 0.31)],
+            ground: SIMD3(0.025, 0.085, 0.070), accent: SIMD3(0.48, 0.86, 0.46), light: false),
+        GamepadPalette(
+            // Neutral, but never flat: barely-there saturation that still travels from a cool
+            // charcoal to a warm stone.
+            id: "graphite", name: "Graphite",
+            stops: [SIMD3(0.06, 0.07, 0.11), SIMD3(0.15, 0.18, 0.25), SIMD3(0.30, 0.31, 0.35),
+                    SIMD3(0.45, 0.42, 0.38), SIMD3(0.60, 0.56, 0.49)],
+            ground: SIMD3(0.055, 0.055, 0.070), accent: SIMD3(0.78, 0.80, 0.86), light: false),
+        // --- pale fields (dark ink) ---
+        GamepadPalette(
+            // The holographic foil: rose → lilac → periwinkle → aqua, with a white bloom.
+            id: "holo", name: "Holo",
+            stops: [SIMD3(0.99, 0.72, 0.90), SIMD3(0.80, 0.60, 0.98), SIMD3(0.58, 0.62, 0.99),
+                    SIMD3(0.55, 0.86, 0.98), SIMD3(0.94, 0.98, 1.00)],
+            ground: SIMD3(0.96, 0.92, 0.99), accent: SIMD3(0.42, 0.28, 0.86), light: true),
+        GamepadPalette(
+            // The poster sunset: periwinkle → magenta → scarlet → tangerine → gold.
+            id: "sunset", name: "Sunset",
+            stops: [SIMD3(0.55, 0.45, 0.92), SIMD3(0.86, 0.31, 0.66), SIMD3(0.97, 0.26, 0.34),
+                    SIMD3(0.99, 0.51, 0.18), SIMD3(1.00, 0.80, 0.22)],
+            ground: SIMD3(0.98, 0.74, 0.34), accent: SIMD3(0.64, 0.13, 0.44), light: true),
+        GamepadPalette(
+            // Peach into blush and lilac — the softest of the set.
+            id: "bloom", name: "Bloom",
+            stops: [SIMD3(1.00, 0.86, 0.72), SIMD3(0.99, 0.73, 0.79), SIMD3(0.95, 0.65, 0.89),
+                    SIMD3(0.82, 0.68, 0.96), SIMD3(0.73, 0.79, 0.99)],
+            ground: SIMD3(0.99, 0.90, 0.89), accent: SIMD3(0.72, 0.24, 0.55), light: true),
+        GamepadPalette(
+            // First light: pale gold → coral → lilac.
+            id: "dawn", name: "Dawn",
+            stops: [SIMD3(1.00, 0.92, 0.70), SIMD3(1.00, 0.80, 0.62), SIMD3(0.99, 0.66, 0.62),
+                    SIMD3(0.90, 0.62, 0.78), SIMD3(0.77, 0.69, 0.95)],
+            ground: SIMD3(1.00, 0.93, 0.82), accent: SIMD3(0.82, 0.33, 0.28), light: true),
+        GamepadPalette(
+            // Sea glass: mint → aqua → a pale sky.
+            id: "mint", name: "Mint",
+            stops: [SIMD3(0.82, 0.98, 0.90), SIMD3(0.62, 0.94, 0.88), SIMD3(0.55, 0.88, 0.95),
+                    SIMD3(0.63, 0.82, 0.99), SIMD3(0.82, 0.87, 1.00)],
+            ground: SIMD3(0.90, 0.98, 0.96), accent: SIMD3(0.04, 0.42, 0.40), light: true),
+        GamepadPalette(
+            // Near-white, but iridescent rather than flat — rose, sky, mint and cream in turn.
+            id: "opal", name: "Opal",
+            stops: [SIMD3(0.98, 0.92, 0.96), SIMD3(0.87, 0.93, 0.99), SIMD3(0.91, 0.99, 0.95),
+                    SIMD3(0.99, 0.96, 0.88), SIMD3(0.94, 0.90, 0.99)],
+            ground: SIMD3(0.97, 0.96, 0.99), accent: SIMD3(0.36, 0.32, 0.44), light: true),
+    ]
+
+    /// The palette stored under `id`, falling back to the brand default — an unknown name is a
+    /// palette a newer client shipped, not a reason to draw nothing.
+    public static func named(_ id: String) -> GamepadPalette {
+        all.first { $0.id == id } ?? all[0]
+    }
+
+    /// Sample an ordered colour ramp at `t` ∈ [0, 1] (linear between neighbouring stops).
+    public static func ramp(_ stops: [SIMD3<Double>], _ t: Double) -> SIMD3<Double> {
+        guard let first = stops.first else { return SIMD3(0, 0, 0) }
+        guard stops.count > 1 else { return first }
+        let x = min(max(t, 0), 1) * Double(stops.count - 1)
+        let i = min(Int(x.rounded(.down)), stops.count - 2)
+        let f = x - Double(i)
+        return stops[i] + (stops[i + 1] - stops[i]) * f
+    }
+
+    /// The 16 mesh colours for this palette: the ramp sampled per cell, or `violetMesh` verbatim
+    /// for the brand default.
+    public var meshColors: [SIMD3<Double>] {
+        guard !stops.isEmpty else { return Self.violetMesh }
+        return (0..<16).map { i in
+            let (x, y) = (Double(i % 4) / 3.0, Double(i / 4) / 3.0)
+            return Self.ramp(stops, 0.5 * (x + y) + Self.cellRamp[i])
+        }
+    }
+
+    /// Four drifting blob colours for the pre-18/15 legacy field. Spread across the ramp so it
+    /// still shows several hues at once.
+    public var blobColors: [SIMD3<Double>] {
+        let s = stops.isEmpty ? Self.violetBlobs : stops
+        return (0..<4).map { Self.ramp(s, 0.15 + 0.25 * Double($0)) }
+    }
+}

clients/apple/Sources/PunktfunkShared/SafeDisplay.swift

@@ -0,0 +1,86 @@
+// Safe-area stream sizing — the pure geometry behind the "safe area" resolution row.
+//
+// An iPhone clips the picture in HARDWARE: the sensor housing (notch / Dynamic Island) and the four
+// rounded corners eat whatever the stream draws underneath them. The session view is deliberately
+// edge-to-edge (ContentView's `.ignoresSafeArea()` on iOS) and the presenter aspect-FITS the host
+// mode into it, so which pixels survive is decided entirely by the mode's aspect ratio:
+//
+//   * A 16:9 mode on a 19.5:9 phone pillarboxes, and those black bars land exactly on the unsafe
+//     regions. That is why 1080p has always "just worked" and never needed a setting.
+//   * The device's NATIVE mode has the screen's own aspect ratio, so it fills every pixel —
+//     including the ones behind the housing and under the corner radii. That is the mode that
+//     loses its corners, and the reason this file exists.
+//
+// So the fix needs no layout change and no input change: ask the host for a mode that is narrower
+// by the safe-area insets, and the existing aspect-fit centres it inside the safe region. Pointer
+// input keeps mapping correctly for free, because `hostPoint(from:)` derives the video rect from
+// the live host mode (`AVMakeRect(aspectRatio:insideRect:)`) instead of assuming full-bleed.
+//
+// The formula is Moonlight's (its settings' resolution table carries the same row): full native
+// height, width reduced by the left+right safe-area insets. Width-only is not a simplification —
+// under aspect-fit only one axis can bind, and on a landscape phone that axis is always the
+// horizontal one. Insetting the height too would shrink the picture without uncovering anything.
+
+import Foundation
+
+public enum SafeDisplay {
+    /// The host rejects odd dimensions and anything under 320×200 (`validate_dimensions` in
+    /// `pf-encode`), so the computed mode is even-floored and clamped exactly like `RenderScale`.
+    public static let minWidth = 320
+    public static let minHeight = 200
+
+    /// A portrait top inset at or above this many points means a sensor housing rather than a
+    /// status bar. Notched and Dynamic Island iPhones report 44–59 pt; a plain status bar (older
+    /// iPhones, every iPad) reports 20–24 pt. Used only by [`sideInsetPoints`] and only when the
+    /// horizontal insets are unavailable — see there for why that case exists at all.
+    public static let housingTopInsetThreshold: Double = 40
+
+    /// The per-side inset, in points, that the **landscape** stream will be subject to — which is
+    /// not necessarily the inset the caller can read right now.
+    ///
+    /// The stream is always landscape, but the settings screen the resolution row is rendered in may
+    /// be portrait, and `safeAreaInsets` only ever describes the CURRENT orientation. In portrait a
+    /// notched iPhone reports its housing on `top` and reports `left`/`right` as zero, so reading
+    /// the horizontal insets there would compute "no inset needed" for exactly the devices that
+    /// need one.
+    ///
+    /// - In landscape, `max(left, right)` is the answer directly. (iOS symmetrizes the two so
+    ///   content stays centred, so they normally agree; `max` is simply the safe reduction.)
+    /// - In portrait, the housing's portrait TOP inset equals its landscape SIDE inset on every
+    ///   notched/Dynamic Island iPhone — the same physical intrusion, measured on the axis that
+    ///   happens to be vertical at the time — so `top` is the correct stand-in. It is accepted only
+    ///   on phones and only past [`housingTopInsetThreshold`], so an iPad's status bar (or an older
+    ///   iPhone's) never fabricates an inset for a device with nothing to avoid.
+    ///
+    /// Returns 0 when there is no housing to route around, which makes the safe mode identical to
+    /// the native one — and the caller's dedup then drops the duplicate row on its own.
+    public static func sideInsetPoints(
+        left: Double, right: Double, top: Double, isPhone: Bool
+    ) -> Double {
+        let horizontal = max(left, right)
+        if horizontal > 0 { return horizontal }
+        if isPhone, top >= housingTopInsetThreshold { return top }
+        return 0
+    }
+
+    /// The landscape safe-area mode in PIXELS: full native height, width reduced by
+    /// `sideInsetPoints` on each side.
+    ///
+    /// `nativeWidth`/`nativeHeight` are the device's native landscape pixels (the long edge first —
+    /// `UIScreen.main.nativeBounds` is portrait-oriented, so the caller swaps). `scale` converts the
+    /// point-valued insets into those same pixels and must therefore be `nativeScale`, not `scale`:
+    /// with Display Zoom on, the two differ and only the former matches `nativeBounds`.
+    ///
+    /// Even-floored and clamped so the result is directly host-valid — an odd width is rejected
+    /// outright by the encoder, and an inset subtraction lands odd about half the time.
+    public static func mode(
+        nativeWidth: Int, nativeHeight: Int, sideInsetPoints: Double, scale: Double
+    ) -> (width: Int, height: Int) {
+        let insetPixels = max(0, sideInsetPoints) * max(scale, 1) * 2 // both sides
+        let width = Double(nativeWidth) - insetPixels
+        let evenFloor: (Double, Int) -> Int = { value, minimum in
+            max(Int(value.rounded(.down)), minimum) / 2 * 2
+        }
+        return (evenFloor(width, minWidth), evenFloor(Double(nativeHeight), minHeight))
+    }
+}

clients/apple/Sources/PunktfunkShared/StreamProfile.swift

@@ -111,6 +111,8 @@ public struct SettingsOverlay: Codable, Equatable, Sendable {
     public var invertScroll: Bool?
     public var gamepadType: Int?
     public var gamepadForwarding: Bool?
+    public var systemButtons: String?
+    public var guideGesture: String?
     /// A `StatsVerbosity` raw value ("off"/"compact"/"normal"/"detailed") — the enum lives in
     /// PunktfunkKit, which this module must not depend on.
     public var statsVerbosity: String?
@@ -153,6 +155,8 @@ public struct SettingsOverlay: Codable, Equatable, Sendable {
         case invertScroll = "invert_scroll"
         case gamepadType = "gamepad"
         case gamepadForwarding = "gamepad_forwarding"
+        case systemButtons = "system_buttons"
+        case guideGesture = "guide_gesture"
         case statsVerbosity = "stats_verbosity"
         case fullscreenWhileStreaming = "fullscreen_on_stream"
         case enable444 = "enable_444"
@@ -187,6 +191,8 @@ public struct SettingsOverlay: Codable, Equatable, Sendable {
         invertScroll = bool(.invertScroll)
         gamepadType = int(.gamepadType)
         gamepadForwarding = bool(.gamepadForwarding)
+        systemButtons = str(.systemButtons)
+        guideGesture = str(.guideGesture)
         statsVerbosity = str(.statsVerbosity)
         fullscreenWhileStreaming = bool(.fullscreenWhileStreaming)
         enable444 = bool(.enable444)
@@ -224,6 +230,8 @@ public struct SettingsOverlay: Codable, Equatable, Sendable {
         try c.encodeIfPresent(gamepadType, forKey: AnyKey(Key.gamepadType.rawValue))
         try c.encodeIfPresent(
             gamepadForwarding, forKey: AnyKey(Key.gamepadForwarding.rawValue))
+        try c.encodeIfPresent(systemButtons, forKey: AnyKey(Key.systemButtons.rawValue))
+        try c.encodeIfPresent(guideGesture, forKey: AnyKey(Key.guideGesture.rawValue))
         try c.encodeIfPresent(statsVerbosity, forKey: AnyKey(Key.statsVerbosity.rawValue))
         try c.encodeIfPresent(
             fullscreenWhileStreaming, forKey: AnyKey(Key.fullscreenWhileStreaming.rawValue))
@@ -277,6 +285,8 @@ public enum OverlayField {
         case "invert_scroll": overlay.invertScroll = nil
         case "gamepad": overlay.gamepadType = nil
         case "gamepad_forwarding": overlay.gamepadForwarding = nil
+        case "system_buttons": overlay.systemButtons = nil
+        case "guide_gesture": overlay.guideGesture = nil
         case "stats_verbosity": overlay.statsVerbosity = nil
         case "fullscreen_on_stream": overlay.fullscreenWhileStreaming = nil
         case "enable_444": overlay.enable444 = nil
@@ -313,6 +323,8 @@ public enum OverlayField {
         case "invert_scroll": return o.invertScroll != nil
         case "gamepad": return o.gamepadType != nil
         case "gamepad_forwarding": return o.gamepadForwarding != nil
+        case "system_buttons": return o.systemButtons != nil
+        case "guide_gesture": return o.guideGesture != nil
         case "stats_verbosity": return o.statsVerbosity != nil
         case "fullscreen_on_stream": return o.fullscreenWhileStreaming != nil
         case "enable_444": return o.enable444 != nil

clients/apple/Tests/PunktfunkKitTests/AudioRingDriftTests.swift

@@ -0,0 +1,95 @@
+// The Apple half of the shared de-jitter policy (`punktfunk_core::audio::JitterPolicy`, whose
+// constants `AudioRing` mirrors). These pin the two behaviours a listener actually notices, in the
+// one client where the policy is hand-written in a second language rather than shared as code — so
+// a divergence from the Rust side shows up here rather than as a field report.
+//
+// The defect being pinned: the ring primed *up* to a target and clamped at a ceiling, with nothing
+// walking the depth back *down*. Host-vs-DAC clock skew of a few dozen ppm therefore added latency
+// permanently, and the only correction was a `highWater` shed that dropped `2 x prefill` at once —
+// its own comment called that "one audible blip".
+
+#if !os(tvOS)
+import XCTest
+
+@testable import PunktfunkKit
+
+final class AudioRingDriftTests: XCTestCase {
+    private let channels = 2
+    private var perMS: Int { 48 * channels }
+
+    /// Run `ms` of audio through the ring at a `quantumMS` device where the producer delivers
+    /// `driftPPM` more than the consumer takes. Returns `(final ms, peak ms, silent callbacks)`.
+    private func simulate(ms: Int, quantumMS: Int, driftPPM: Int) -> (Int, Int, Int) {
+        let ring = AudioRing(capacity: 48_000 * channels, channels: channels)
+        let want = quantumMS * perMS
+        var scratch = [Float](repeating: 0, count: want)
+        // Non-zero so a silent callback is distinguishable from real audio.
+        let producer = [Float](repeating: 0.25, count: want + 8)
+        var carry = 0, peak = 0, final = 0, silent = 0
+
+        for i in 0..<(ms / quantumMS) {
+            carry += want * driftPPM
+            let extra = carry / 1_000_000
+            carry -= extra * 1_000_000
+            producer.withUnsafeBufferPointer { ring.write($0.baseAddress!, count: want + extra) }
+
+            scratch.withUnsafeMutableBufferPointer { ring.read(into: $0.baseAddress!, count: want) }
+            // Skip the priming window at the very start.
+            if i > 20, scratch.allSatisfy({ $0 == 0 }) { silent += 1 }
+            peak = max(peak, ring.bufferedMS)
+            final = ring.bufferedMS
+        }
+        return (final, peak, silent)
+    }
+
+    /// THE regression: with the host clock running fast, buffered latency must return to target
+    /// instead of climbing to the hard cap and staying pinned there. +200 ppm is deliberately
+    /// harsher than real hardware (tens of ppm).
+    func testDriftDoesNotRatchetLatencyToTheCeiling() {
+        let (final, peak, silent) = simulate(ms: 5 * 60 * 1_000, quantumMS: 5, driftPPM: 200)
+        // Must settle inside the headroom band (target 20 + headroom 30), never near the 90 ms cap.
+        XCTAssertLessThanOrEqual(final, 50, "settled at \(final) ms — that is the ratchet")
+        XCTAssertLessThanOrEqual(peak, 50, "peaked at \(peak) ms")
+        XCTAssertEqual(silent, 0, "drift correction must never starve the callback")
+    }
+
+    /// The mirror case: a host clock running SLOW must keep audio flowing rather than being
+    /// "corrected" into a stutter.
+    func testNegativeDriftKeepsPlaying() {
+        let (_, _, silent) = simulate(ms: 2 * 60 * 1_000, quantumMS: 5, driftPPM: -200)
+        XCTAssertEqual(silent, 0, "a draining ring must re-prime, not chatter")
+    }
+
+    /// A device that pulls a large quantum cannot sustain a target below it — the ring must lift
+    /// its target rather than oscillating prime → dropout → re-prime forever.
+    func testLargeDeviceQuantumStillPlays() {
+        let (_, _, silent) = simulate(ms: 60 * 1_000, quantumMS: 40, driftPPM: 0)
+        XCTAssertEqual(silent, 0, "a 40 ms quantum must not starve a 20 ms target")
+    }
+
+    /// One transient drain must not manufacture a whole target's worth of fresh silence: the ring
+    /// de-primes only after a RUN of short reads.
+    func testSingleShortReadDoesNotDeprime() {
+        let ring = AudioRing(capacity: 48_000 * channels, channels: channels)
+        let want = 5 * perMS
+        var scratch = [Float](repeating: 0, count: want)
+        // Prime well past target.
+        let big = [Float](repeating: 0.5, count: 60 * perMS)
+        big.withUnsafeBufferPointer { ring.write($0.baseAddress!, count: big.count) }
+        scratch.withUnsafeMutableBufferPointer { ring.read(into: $0.baseAddress!, count: want) }
+        XCTAssertTrue(scratch.contains { $0 != 0 }, "should be playing after priming")
+
+        // Drain it dry with one oversized read, then feed a normal quantum again. The length comes
+        // off the buffer pointer, not off `huge`: touching the array inside the closure that is
+        // already holding it exclusively is an exclusivity violation.
+        var huge = [Float](repeating: 0, count: 200 * perMS)
+        huge.withUnsafeMutableBufferPointer { ring.read(into: $0.baseAddress!, count: $0.count) }
+        let feed = [Float](repeating: 0.5, count: want)
+        feed.withUnsafeBufferPointer { ring.write($0.baseAddress!, count: want) }
+        scratch.withUnsafeMutableBufferPointer { ring.read(into: $0.baseAddress!, count: want) }
+        XCTAssertTrue(
+            scratch.contains { $0 != 0 },
+            "a single short read must not force a full re-prime")
+    }
+}
+#endif