feat(clients/gamepad-ui): multi-tone palettes, and a UI that takes its colours from them

The first pass built each palette by rotating ONE colour field's hue, and it
showed: every option was a single tone at several brightnesses, which reads flat
next to any real gradient. A palette is now an ordered ramp of DISTINCT hues.
The 4×4 mesh samples that ramp along the diagonal with a fixed per-cell offset
table, so neighbouring cells land on different parts of it and the colours pool
and swirl instead of banding; the control points' existing drift then moves the
pools around. Violet keeps its explicit sixteen colours, so the default is
untouched.

Twelve of them now, dark first then pale: Violet, Nebula, Abyss, Ember, Moss,
Graphite, then Holo, Sunset, Bloom, Dawn, Mint, Opal. Holo and Sunset are
straight takes on the two reference gradients — foil and poster.

`every_palette_is_multi_tone` measures the hue spread across all sixteen cells
and fails under 45° (20° for Graphite and Opal, which are meant to be
restrained). It caught Ember at 35°, all reds and oranges — the very flatness
this rework exists to remove — and Graphite at 3° despite a comment claiming it
drifted cool to warm. Both were rebuilt until the numbers matched the prose.

The UI follows the palette now, rather than wearing brand violet over whatever
happens to be behind it. Each palette carries an accent and a light flag, and an
Ink derived from those (foreground, accent, on-accent, glass, scrim and its
strength) is published to the whole tree — a thread-local in the console, an
environment value on Apple, a CompositionLocal on Android. Pale palettes flip
the ink: dark text on white frost, with the materials, tray scrims and every
wash that sits under text following suit.

Three things only the renders could have told us:

  - Additive blending blows out over a pale ground. Android's blobs and Apple's
    legacy field composite with Plus/plusLighter, which over near-white
    saturates every blob to white — Holo rendered as a grey wash. Pale palettes
    blend normally.
  - A white scrim at the dark field's strength BLEACHES the gradient. Mixing
    toward black at 0.4 reads as depth; toward white at 0.4 destroys the chroma
    it is drawn over. The scrim now carries a per-palette strength.
  - White glass over a bright field has far less separating it from its backdrop
    than dark glass over a dark one, and needed more body.

Verified: console build + clippy -D warnings + 173 tests, Apple build + 200
tests + an iOS-triple typecheck, Android compile + 62 tests, and eyeball passes
on real renders of both the vivid and the pale ends (console CPU rasters; a new
Roborazzi light-palette scene, which is what exposed the blend-mode bug).

.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/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/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/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
@@ -98,6 +99,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 = {
@@ -201,8 +211,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 }
 

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/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()
@@ -170,8 +171,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 +196,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 +222,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)
@@ -299,7 +303,7 @@ private fun Coverflow(
                     current?.title ?: " ",
                     style = MaterialTheme.typography.titleLarge,
                     fontWeight = FontWeight.Bold,
-                    color = Color.White,
+                    color = ink.fg,
                     maxLines = 1,
                     overflow = TextOverflow.Ellipsis,
                 )
@@ -307,7 +311,7 @@ private fun Coverflow(
                     Text(
                         if (current.isCustom) "CUSTOM" else "STEAM",
                         style = MaterialTheme.typography.labelMedium,
-                        color = Color.White.copy(alpha = 0.5f),
+                        color = ink.fg(0.5f),
                         letterSpacing = 2.sp,
                     )
                 }
@@ -319,6 +323,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 +331,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) {
@@ -343,7 +348,7 @@ private fun Poster(game: GameEntry, loader: ImageLoader, modifier: Modifier = Mo
                 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),
             )
@@ -353,7 +358,7 @@ private fun Poster(game: GameEntry, loader: ImageLoader, modifier: Modifier = Mo
             Text(
                 if (game.isCustom) "Custom" else "Steam",
                 style = MaterialTheme.typography.labelSmall,
-                color = Color.White,
+                color = ink.fg,
                 modifier = Modifier
                     .clip(RoundedCornerShape(50))
                     .background(Color.Black.copy(alpha = 0.5f))

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. */
@@ -539,6 +598,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 +689,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

@@ -838,6 +838,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 +896,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

@@ -323,6 +323,7 @@ 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
@@ -506,6 +507,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 {

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/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,12 +133,17 @@ 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
@@ -119,6 +152,9 @@ class DsCapture(
             // 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()
@@ -133,16 +169,112 @@ 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
@@ -235,6 +367,10 @@ class DsCapture(
             // 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()
         }
     }
 
@@ -275,6 +411,35 @@ class DsCapture(
         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) {

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

@@ -131,15 +131,9 @@ class GamepadFeedback(
             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)
+                // 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.
@@ -147,12 +141,7 @@ class GamepadFeedback(
                 // 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(
-                        pad,
-                        ((ev ushr 16) and 0xFFFF).toInt(),
-                        (ev and 0xFFFF).toInt(),
-                        backstopMs,
-                    )
+                    renderRumble(cmd.pad, cmd.low, cmd.high, cmd.backstopMs)
                 }.onFailure { failures = noteRenderFailure("rumble", it, failures) }
             }
         }, "pf-rumble").apply { isDaemon = true; start() }
@@ -292,8 +281,8 @@ 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) {
@@ -342,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
@@ -357,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

@@ -98,6 +98,40 @@ class HidUsbLink(
     /** 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.

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. */
@@ -332,6 +336,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/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/library/Library.kt

@@ -127,8 +127,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 +168,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/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)),
             };

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

@@ -512,6 +512,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

@@ -63,6 +63,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 +115,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 +139,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 +148,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 +180,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 {
@@ -327,6 +346,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 +386,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 +399,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 +409,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 +419,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 +436,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 +452,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/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,6 +47,9 @@ 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 {
@@ -92,7 +96,7 @@ struct LibraryCoverflowView: View {
             .overlay(alignment: .topLeading) { StoreBadge(isCustom: game.isCustom) }
             .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
@@ -118,7 +122,7 @@ struct LibraryCoverflowView: View {
         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)
@@ -126,7 +130,7 @@ struct LibraryCoverflowView: View {
                 Text(game.isCustom ? "CUSTOM" : "STEAM")
                     .font(.geist(11, .semibold, relativeTo: .caption2))
                     .tracking(1.2)
-                    .foregroundStyle(.white.opacity(0.5))
+                    .foregroundStyle(ink.fg(0.5))
             }
         }
         .frame(maxWidth: .infinity)

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

@@ -675,8 +675,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) }
 

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

@@ -59,6 +59,9 @@ public final class HostDiscovery: ObservableObject {
 
     /// 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 }
         let browser = NWBrowser(
             for: .bonjourWithTXTRecord(type: "_punktfunk._udp", domain: nil),
@@ -92,6 +95,35 @@ public final class HostDiscovery: ObservableObject {
         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
+
     private func restart() {
         stop()
         start()

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/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.
@@ -446,6 +456,31 @@ 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.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

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/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

clients/apple/Tests/PunktfunkKitTests/DualSenseHIDTests.swift

@@ -43,5 +43,33 @@ final class DualSenseHIDTests: XCTestCase {
         let crc = DualSenseHID.crc32(seed: UInt8(ascii: "1"), Array("23456789".utf8))
         XCTAssertEqual(crc, 0xCBF4_3926)
     }
+
+    // MARK: - Device selection (B14)
+
+    /// With two DualSenses attached, each renderer must drive its OWN device. The old code took
+    /// `Set.first` from an unordered set, so the pad→device binding was a coin flip that could
+    /// point both renderers at the same pad.
+    func testPreferredIndexHonoursAnExplicitLocation() {
+        let ids: [UInt32?] = [0x1D18_0000, 0x1420_0000, 0x1411_0000]
+        XCTAssertEqual(DualSenseHID.preferredIndex(among: ids, preferring: 0x1420_0000), 1)
+        XCTAssertEqual(DualSenseHID.preferredIndex(among: ids, preferring: 0x1D18_0000), 0)
+    }
+
+    /// No preference (or one the pad no longer has): fall back to the LOWEST id — arbitrary, but
+    /// stable across calls, which `Set.first` was not.
+    func testPreferredIndexFallsBackToTheLowestIdDeterministically() {
+        let ids: [UInt32?] = [0x1D18_0000, 0x1420_0000, 0x1411_0000]
+        XCTAssertEqual(DualSenseHID.preferredIndex(among: ids, preferring: nil), 2)
+        // A wanted id that is gone (pad unplugged between enumeration and open) must not fail the
+        // open — it degrades to the same stable fallback.
+        XCTAssertEqual(DualSenseHID.preferredIndex(among: ids, preferring: 0xDEAD_BEEF), 2)
+    }
+
+    /// A device IOKit reports no location for must never displace one it can place.
+    func testPreferredIndexSortsUnplaceableDevicesLast() {
+        XCTAssertEqual(DualSenseHID.preferredIndex(among: [nil, 0x1420_0000], preferring: nil), 1)
+        XCTAssertEqual(DualSenseHID.preferredIndex(among: [nil, nil], preferring: nil), 0)
+        XCTAssertNil(DualSenseHID.preferredIndex(among: [], preferring: nil))
+    }
 }
 #endif

clients/apple/Tests/PunktfunkKitTests/GamepadEscapeChordTests.swift

@@ -0,0 +1,52 @@
+import GameController
+import XCTest
+
+@testable import PunktfunkKit
+
+/// The escape chord's mask and its GameController alias list have to describe the same four
+/// buttons. `GamepadCapture.openSlot` claims the system gesture of every element while forwarding
+/// is on, but only of `escapeChordElements` while it is off — so if the alias list ever stops
+/// covering the mask, the missing button's press stays the system's and the chord never completes.
+///
+/// That matters most on tvOS, where this chord is the only controller way out of a stream: the
+/// symptom is a session nobody can leave with the pad in their hands, and nothing logs or crashes.
+/// Hence a test on the invariant rather than trusting the comment beside it.
+@MainActor
+final class GamepadEscapeChordTests: XCTestCase {
+
+    /// The intended alias↔bit pairing, spelled out independently of the implementation.
+    private let pairing: [(alias: String, bit: UInt32)] = [
+        (GCInputLeftShoulder, GamepadWire.leftShoulder),
+        (GCInputRightShoulder, GamepadWire.rightShoulder),
+        (GCInputButtonMenu, GamepadWire.start),
+        (GCInputButtonOptions, GamepadWire.back),
+    ]
+
+    func testChordMaskIsExactlyTheFourPairedButtons() {
+        XCTAssertEqual(
+            pairing.reduce(UInt32(0)) { $0 | $1.bit },
+            GamepadCapture.escapeChord,
+            "the chord mask and the alias pairing describe different buttons")
+    }
+
+    func testEveryChordBitHasAnElementToClaim() {
+        // One alias per bit — a mask that grew a fifth button without a matching alias would
+        // leave that button's gesture with the OS while forwarding is off.
+        XCTAssertEqual(
+            GamepadCapture.escapeChordElements.count,
+            GamepadCapture.escapeChord.nonzeroBitCount,
+            "alias list and chord mask differ in size")
+        XCTAssertEqual(GamepadCapture.escapeChordElements, pairing.map(\.alias))
+    }
+
+    /// The claim list is a strict subset of what a forwarding slot takes — it is a NARROWING of
+    /// the full sweep, never an extra grab, and it must not be empty (that would be "skip", which
+    /// is the behaviour this deliberately avoids).
+    func testClaimListIsNonEmptyAndAllDistinct() {
+        XCTAssertFalse(GamepadCapture.escapeChordElements.isEmpty)
+        XCTAssertEqual(
+            Set(GamepadCapture.escapeChordElements).count,
+            GamepadCapture.escapeChordElements.count,
+            "a repeated alias would mean a chord bit has no element")
+    }
+}

clients/apple/Tests/PunktfunkKitTests/GamepadPaletteTests.swift

@@ -0,0 +1,110 @@
+// The gamepad UI's background palettes. These assertions are the CONTRACT the Rust
+// (`pf-console-ui::library`) and Kotlin (`GamepadPalette.kt`) 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.
+
+import XCTest
+import simd
+@testable import PunktfunkShared
+
+final class GamepadPaletteTests: XCTestCase {
+    private func luma(_ c: SIMD3<Double>) -> Double {
+        0.2126 * c.x + 0.7152 * c.y + 0.0722 * c.z
+    }
+
+    /// Hue angle in degrees, or nil for something too grey to have one.
+    private func hue(_ c: SIMD3<Double>) -> Double? {
+        let maxV = max(c.x, c.y, c.z)
+        let minV = min(c.x, c.y, c.z)
+        let d = maxV - minV
+        guard d >= 0.04 else { return nil }
+        let h: Double
+        if maxV == c.x {
+            h = 60 * (((c.y - c.z) / d).truncatingRemainder(dividingBy: 6))
+        } else if maxV == c.y {
+            h = 60 * ((c.z - c.x) / d + 2)
+        } else {
+            h = 60 * ((c.x - c.y) / d + 4)
+        }
+        return (h + 360).truncatingRemainder(dividingBy: 360)
+    }
+
+    /// The brand default must still be the SHIPPED field, colour for colour. Every install
+    /// already sees it, and a palette table that quietly restyled the default would be a
+    /// regression dressed as a feature.
+    func testVioletIsTheUntouchedShippedField() {
+        let violet = GamepadPalette.named("violet")
+        XCTAssertEqual(GamepadPalette.all.first?.id, "violet")
+        XCTAssertTrue(violet.stops.isEmpty, "the default is the explicit grid")
+        XCTAssertEqual(violet.meshColors, GamepadPalette.violetMesh)
+        // An unknown name is a newer client's palette, not an error.
+        XCTAssertEqual(GamepadPalette.named("chartreuse").id, "violet")
+        XCTAssertEqual(GamepadPalette.named("").id, "violet")
+    }
+
+    /// Ids, order and the light/dark split are the cross-client contract.
+    func testTableMatchesTheOtherClients() {
+        XCTAssertEqual(
+            GamepadPalette.all.map(\.id),
+            ["violet", "nebula", "abyss", "ember", "moss", "graphite",
+             "holo", "sunset", "bloom", "dawn", "mint", "opal"])
+        // Dark fields lead, pale ones follow, so stepping the row walks one direction.
+        let firstLight = GamepadPalette.all.firstIndex { $0.light }
+        XCTAssertEqual(firstLight, 6)
+        XCTAssertTrue(GamepadPalette.all.dropFirst(6).allSatisfy(\.light))
+    }
+
+    /// 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.
+    func testEveryPaletteIsMultiTone() {
+        for p in GamepadPalette.all {
+            let hues = p.meshColors.compactMap(hue)
+            XCTAssertGreaterThanOrEqual(hues.count, 8, "\(p.id): too few coloured cells")
+            var spread = 0.0
+            for a in hues {
+                for b in hues {
+                    let d = abs(a - b).truncatingRemainder(dividingBy: 360)
+                    spread = max(spread, min(d, 360 - d))
+                }
+            }
+            // Graphite and Opal are deliberately near-neutral; the rest must travel.
+            let floor = (p.id == "graphite" || p.id == "opal") ? 20.0 : 45.0
+            XCTAssertGreaterThanOrEqual(spread, floor, "\(p.id) spans only \(spread)° of hue")
+        }
+    }
+
+    /// Every colour stays in gamut, and a pale palette really is pale — its ink flips, so a
+    /// mislabelled one would put dark text on a dark field.
+    func testPalettesAreInGamutAndHonestAboutLightness() {
+        for p in GamepadPalette.all {
+            for c in p.meshColors + p.blobColors {
+                for v in [c.x, c.y, c.z] {
+                    XCTAssertTrue((0...1).contains(v), "\(p.id) \(c)")
+                }
+            }
+            let mean = p.meshColors.map(luma).reduce(0, +) / Double(p.meshColors.count)
+            if p.light {
+                XCTAssertGreaterThan(mean, 0.5, "\(p.id) is flagged light")
+                XCTAssertGreaterThan(luma(p.ground), 0.6, "\(p.id)'s ground is dark")
+                XCTAssertLessThan(luma(p.accent), 0.45, "\(p.id)'s accent is too pale")
+            } else {
+                XCTAssertLessThan(mean, 0.45, "\(p.id) is flagged dark")
+                XCTAssertLessThan(luma(p.ground), 0.2, "\(p.id)'s ground is light")
+                XCTAssertGreaterThan(luma(p.accent), 0.25, "\(p.id)'s accent is too dark")
+            }
+        }
+    }
+
+    /// The ramp is the shared sampling rule the Rust and Kotlin ports reproduce.
+    func testRampInterpolatesBetweenStops() {
+        let stops = [SIMD3(0.0, 0.0, 0.0), SIMD3(1.0, 0.0, 0.0), SIMD3(1.0, 1.0, 1.0)]
+        XCTAssertEqual(GamepadPalette.ramp(stops, 0), SIMD3(0.0, 0.0, 0.0))
+        XCTAssertEqual(GamepadPalette.ramp(stops, 1), SIMD3(1.0, 1.0, 1.0))
+        XCTAssertEqual(GamepadPalette.ramp(stops, 0.5), SIMD3(1.0, 0.0, 0.0))
+        XCTAssertEqual(GamepadPalette.ramp(stops, 0.25).x, 0.5, accuracy: 1e-9)
+        // Out of range clamps rather than trapping.
+        XCTAssertEqual(GamepadPalette.ramp(stops, -3), SIMD3(0.0, 0.0, 0.0))
+        XCTAssertEqual(GamepadPalette.ramp(stops, 9), SIMD3(1.0, 1.0, 1.0))
+        XCTAssertEqual(GamepadPalette.ramp([], 0.5), SIMD3(0.0, 0.0, 0.0))
+    }
+}

clients/apple/Tests/PunktfunkKitTests/GamepadWireTests.swift

@@ -79,7 +79,7 @@ final class GamepadWireTests: XCTestCase {
         XCTAssertEqual(GamepadWire.axisRSY, UInt32(PUNKTFUNK_AXIS_RS_Y))
         XCTAssertEqual(GamepadWire.axisLT, UInt32(PUNKTFUNK_AXIS_LT))
         XCTAssertEqual(GamepadWire.axisRT, UInt32(PUNKTFUNK_AXIS_RT))
-        XCTAssertEqual(GamepadWire.maxPads, Int(MAX_PADS))
+        XCTAssertEqual(GamepadWire.maxPads, Int(PUNKTFUNK_MAX_PADS))
     }
 
     func testPadIndexRidesFlagsOnEveryPerPadEvent() {

clients/apple/Tests/PunktfunkKitTests/RumbleTuningTests.swift

@@ -56,7 +56,7 @@ final class RumbleTuningTests: XCTestCase {
     /// storm, an audible target left to the ticker (watchdog path), then `stop()` — which runs
     /// `queue.sync` against the same serial queue the ticker fires on and must not deadlock.
     func testRendererSurvivesCallStormAndTeardownWithoutController() {
-        let renderer = RumbleRenderer(policy: .session)
+        let renderer = RumbleRenderer()
         renderer.retarget(nil)
         for i in 0..<500 {
             renderer.apply(
@@ -72,7 +72,7 @@ final class RumbleTuningTests: XCTestCase {
     /// every policy stop (lease expiry, legacy staleness, session close), and the renderer's only
     /// job is to apply them. Drive the real queue/ticker (no physical pad) and confirm no wedge.
     func testZeroCommandSilencesAndTeardownDoesNotDeadlock() {
-        let renderer = RumbleRenderer(policy: .session)
+        let renderer = RumbleRenderer()
         renderer.retarget(nil)
         renderer.apply(low: 0x8000, high: 0x8000)
         Thread.sleep(forTimeInterval: 0.1)

clients/apple/store/README.md

@@ -0,0 +1,51 @@
+# App Store copy
+
+Source of truth for what goes into App Store Connect. Every character-limited field in here has
+been counted with `check-limits.py`; run it after any edit.
+
+```sh
+python3 clients/apple/store/check-limits.py
+```
+
+| File | Covers |
+|------|--------|
+| [`ios.md`](ios.md) | iOS/iPadOS Promotional Text (DE + EN), with alternates |
+| [`macos.md`](macos.md) | macOS Promotional Text, Description, Keywords (DE + EN) |
+| [`tvos.md`](tvos.md) | tvOS Promotional Text, Description, Keywords (DE + EN) |
+| [`review-notes.md`](review-notes.md) | App Review notes template + pre-submission checklist |
+| [`privacy-app-addendum.md`](privacy-app-addendum.md) | App-specific privacy text to add to the existing policy page |
+
+German is primary throughout and uses the same informal "du" voice as the website
+(`punktfunk-website/messages/de.json`). English is a localisation, not a translation exercise — a
+few lines diverge where the German idiom does not carry.
+
+## Three things that contradicted the original brief
+
+1. **A Mac cannot be a host.** The brief suggested Mac copy could cover "running as a host/server
+   or client on Mac". There is no macOS host — `punktfunk-host` has no macOS capture, virtual
+   display, or encode backend. The macOS copy is client-only and says so explicitly.
+2. **The existing privacy policy is website-only.** It covers server logs, Plausible, and a
+   language cookie, and never mentions the apps. Linking it unchanged from App Store Connect is
+   the kind of thing that draws a reviewer's attention to analytics that have nothing to do with
+   the app. See `privacy-app-addendum.md` for the text to append.
+3. **App Review notes cap at 4000 characters**, not the unlimited field the brief implied. The
+   template is 3919 and fits.
+
+## Claims used, and where they come from
+
+Everything asserted in the copy was checked against the source rather than the marketing site:
+
+- Hardware decode, HDR/4:4:4, controller and input support — `clients/apple/README.md`
+- Entitlements and their justifications — `Config/Punktfunk.entitlements`,
+  `Config/Punktfunk-macOS.entitlements` (both carry detailed rationale comments)
+- Background audio mode and its 2.5.4 constraints — `Config/Info.plist`
+- "Collects no data" — verified by absence: no analytics SDK in `Package.swift`, no telemetry
+  symbols in `Sources/`, `URLSession` used only against the paired host
+- Host platforms and protocol details — root `README.md`, `docs/releases/v0.24.0.md`
+- Feature ship dates — `git tag --contains` on the relevant commits
+
+## Not done here
+
+`clients/apple` has no `PrivacyInfo.xcprivacy`. The app uses `UserDefaults`, which is a
+required-reason API, so a manifest is expected. Flagged at the end of `review-notes.md`; left
+alone because it is a code change, not copy.

clients/apple/store/check-limits.py

@@ -0,0 +1,82 @@
+#!/usr/bin/env python3
+"""Check every App Store copy block in this directory against its field limit.
+
+App Store Connect silently truncates or hard-rejects over-long fields, and the German copy is the
+easy one to get wrong because umlauts read as one character but two bytes. Apple counts characters,
+so `len()` on a `str` is the right measure — do not switch this to a byte count.
+
+Each fenced code block in the .md files here is one field. Which limit applies is inferred from the
+nearest heading above it. Exit status is non-zero if anything is over, so CI can gate on it.
+"""
+
+from __future__ import annotations
+
+import pathlib
+import re
+import sys
+
+LIMITS = {"PROMO": 170, "DESC": 4000, "KW": 100, "NOTES": 4000}
+
+
+def blocks(text: str):
+    """Yield (heading, body) for every fenced block, tagged with the heading above it."""
+    heading = None
+    buf: list[str] | None = None
+    for line in text.split("\n"):
+        if line.startswith("#") and buf is None:
+            heading = line.lstrip("#").strip()
+        if line.strip() == "```":
+            if buf is None:
+                buf = []
+            else:
+                yield heading or "", "\n".join(buf)
+                buf = None
+            continue
+        if buf is not None:
+            buf.append(line)
+
+
+def kind_of(heading: str, body: str) -> str:
+    low = heading.lower()
+    if "keyword" in low or re.fullmatch(r"(de|en) \(\d+\)", low):
+        return "KW"
+    if "template" in low:
+        return "NOTES"
+    return "DESC" if len(body) > 400 else "PROMO"
+
+
+def main() -> int:
+    here = pathlib.Path(__file__).parent
+    failures = 0
+    stale = 0
+    for path in sorted(here.glob("*.md")):
+        found = list(blocks(path.read_text(encoding="utf-8")))
+        if not found:
+            continue
+        print(f"\n=== {path.name} ===")
+        for heading, body in found:
+            kind = kind_of(heading, body)
+            limit = LIMITS[kind]
+            n = len(body)
+            over = n > limit
+            failures += over
+            # Headings carry the count in parentheses; flag any that drifted from the real length.
+            claimed = re.search(r"\((\d+)\)\s*$", heading)
+            drift = ""
+            if claimed and int(claimed.group(1)) != n:
+                drift = f"   [heading claims {claimed.group(1)}]"
+                stale += 1
+            status = "OVER" if over else "ok"
+            print(f"  [{kind:5}] {status:>4} {n:>4}/{limit}  {heading[:48]}{drift}")
+
+    if failures:
+        print(f"\n{failures} block(s) OVER the limit")
+    elif stale:
+        print(f"\nAll within limits, but {stale} heading count(s) are stale")
+    else:
+        print("\nAll blocks within limits, all heading counts accurate")
+    return 1 if failures or stale else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

clients/apple/store/ios.md

@@ -0,0 +1,71 @@
+# iOS / iPadOS — App Store metadata
+
+Existing, unchanged:
+
+- **Name:** Punktfunk
+- **Subtitle (DE):** Schnell, lokal & offen.
+
+Only the Promotional Text is new here. It is the one field that can be changed **without** a new
+build or a review, so it is the right place for "what landed most recently".
+
+---
+
+## Promotional Text (DE) — max 170 characters
+
+### Primary (160)
+
+```
+Neu: Profile pro Host – Auflösung, Bitrate und Ton einmal einstellen, dann mit einem Tipp verbinden. Dazu Live Activity, Sperrbildschirm-Widget und Wake-on-LAN.
+```
+
+### Alternate A — evergreen hook, no "new" claim (156)
+
+```
+Dein Gaming-PC auf dem iPhone, in dessen exakter Auflösung – ohne Konto, ohne Cloud, nur dein Netzwerk. Hardware-Decoding, HDR und dein DualSense mit allem.
+```
+
+### Alternate B — leads on the DualSense (161)
+
+```
+Dein DualSense, vollständig: Rumble, adaptive Trigger, Lightbar, Touchpad und Gyro gehen bis ins Spiel durch. Dazu Profile pro Host und Wake-on-LAN vom Sofa aus.
+```
+
+### Alternate C — leads on latency (153)
+
+```
+Kein Konto, keine Cloud, kein Umweg: punktfunk/1 fährt über QUIC direkt zu deinem PC. Auflösungswechsel mitten im Stream, ohne die Verbindung zu trennen.
+```
+
+---
+
+## Promotional Text (EN) — max 170 characters
+
+### Primary (152)
+
+```
+New: per-host profiles — set resolution, bitrate and audio once, then connect with one tap. Plus Live Activities, a Lock Screen widget, and Wake-on-LAN.
+```
+
+### Alternate A — evergreen hook (159)
+
+```
+Your gaming PC on your iPhone, at your iPhone's exact resolution — no account, no cloud, just your network. Hardware decoding, HDR, and your DualSense in full.
+```
+
+### Alternate B — leads on the DualSense (160)
+
+```
+Your DualSense, in full: rumble, adaptive triggers, lightbar, touchpad and gyro all reach the game. Plus per-host profiles and Wake-on-LAN from across the room.
+```
+
+---
+
+## Notes on the claims
+
+- "Profile pro Host" shipped in **v0.22.0** (`25b12780`, `80c0ca69`) and is in every tag since. It is
+  the strongest recent user-facing Apple feature, so "Neu" is defensible for one release cycle — but
+  drop the word once 0.25 ships something newer.
+- Live Activities and the Hosts widget shipped long ago (`ba1caf02`, in v0.15.0+). They are safe to
+  *mention* but should not be called "neu".
+- The only Apple-visible feature unique to **v0.24.0** is the "Forward controllers" off switch
+  (`b297542c`), which is too niche to headline.

clients/apple/store/macos.md

@@ -0,0 +1,159 @@
+# macOS — App Store metadata
+
+> **Scope correction.** The Mac app is a **client only**. There is no macOS host: `punktfunk-host`
+> has no macOS capture, virtual-display, or encode backend (the two `cfg!(target_os = "macos")` hits
+> in the host crate are OS *detection* for the host tile and a path helper; the loopback-test host
+> is a synthetic frame source for `test-loopback.sh`, not a shippable host). A macOS host is a
+> feasibility study — it needs four new backends and the private `CGVirtualDisplay` API.
+> None of the copy below claims a Mac can host, and it should not until that ships.
+
+- **Name:** Punktfunk
+- **Subtitle (DE):** Schnell, lokal & offen.
+- **Subtitle (EN):** Fast, local & open.
+
+---
+
+## Promotional Text (DE) — max 170 characters
+
+### Primary (164)
+
+```
+Neu: Profile pro Host – ein Mac, mehrere Gaming-PCs, jeder mit eigenen Einstellungen. Dazu AV1-Hardware-Decoding auf M3 und neuer, HDR und volles 4:4:4 für Schrift.
+```
+
+### Alternate (156)
+
+```
+Dein Gaming-PC im Fenster oder im Vollbild, in der exakten Auflösung deines Displays. Maus und Tastatur gehen durch, Auflösungswechsel ohne neue Verbindung.
+```
+
+## Promotional Text (EN) — max 170 characters
+
+### Primary (161)
+
+```
+New: per-host profiles — one Mac, several gaming PCs, each with its own settings. Plus AV1 hardware decoding on M3 and later, HDR, and full 4:4:4 for crisp text.
+```
+
+### Alternate (156)
+
+```
+Your gaming PC in a window or full screen, at your display's exact resolution. Mouse and keyboard pass straight through; resize without dropping the stream.
+```
+
+---
+
+## Description (DE) — max 4000 characters
+
+```
+Punktfunk streamt deinen Gaming-PC auf den Mac – in der exakten Auflösung und Bildwiederholrate deines Displays, über dein eigenes Netzwerk, ohne Konto und ohne Cloud.
+
+Punktfunk besteht aus zwei Hälften: einem Host auf dem PC, von dem du streamst, und dieser App auf dem Gerät, auf dem du spielst. Der Host ist quelloffen und kostenlos, läuft auf Linux und auf Windows 11 – auf dem Gaming-Rig unterm Schreibtisch, auf einem Laptop oder headless auf einem Server, an dem gar kein Monitor hängt.
+
+DEIN MAC BEKOMMT SEIN EIGENES DISPLAY
+
+Für jede Verbindung legt der Host ein echtes virtuelles Display an – in genau der Auflösung und Bildrate, die dein Mac meldet. Kein Skalieren, keine schwarzen Balken, kein Umsortieren deiner echten Monitore. Änderst du mitten im Stream die Fenstergröße oder gehst auf Vollbild, wird die Auflösung neu ausgehandelt, ohne die Verbindung zu trennen. Mehrere Geräte können gleichzeitig streamen, jedes auf seinem eigenen Display.
+
+SCHNELL, WEIL UNS DER GANZE WEG GEHÖRT
+
+Die nativen Apps sprechen punktfunk/1: eine QUIC-Steuerebene und eine verschlüsselte Datenebene mit Vorwärtsfehlerkorrektur, die Auflösung und Bildrate mitten im Stream wechselt, ohne neu zu verbinden. Dekodiert wird in Hardware über VideoToolbox – H.264, HEVC und AV1 auf Macs, die AV1 in Hardware können (M3 und neuer).
+
+FÜR DEN MAC GEMACHT
+
+• Im Fenster oder im Vollbild, auf jedem angeschlossenen Display
+• Maus und Tastatur gehen vollständig durch – Klick zum Fangen, Cmd+Esc oder Ctrl+Alt+Shift+Q zum Freigeben
+• Ein Stream-Menü in der Menüleiste: Maus freigeben, Trennen, Statistik einblenden
+• Mikrofon-Uplink mit Echounterdrückung – dein Mac wird zum Headset am PC
+• HDR mit PQ-Passthrough und ein optionaler Vollchroma-Modus (4:4:4), damit kleine Schrift und feine Linien scharf bleiben
+
+CONTROLLER, VOLLSTÄNDIG
+
+DualSense, Xbox- und weitere MFi-kompatible Controller. Beim DualSense gehen Rumble, Lightbar, Player-LEDs, adaptive Trigger, Touchpad und Gyro bis ins Spiel durch. Welchen Typ das virtuelle Gamepad am Host annimmt, richtet sich nach dem, was bei dir wirklich in der Hand liegt.
+
+DEINE BIBLIOTHEK, DEIN NETZWERK
+
+Installierte Steam-Titel und selbst hinzugefügte Spiele erscheinen als Raster mit Artwork und starten direkt. Hosts findet die App im Netzwerk von allein. Beim ersten Mal koppelst du einmalig mit einer PIN, danach verbindet sich der Mac über eine gepinnte Identität aus deinem Schlüsselbund – kein Konto, kein Login. Einen schlafenden PC weckt Punktfunk per Wake-on-LAN.
+
+MESSEN STATT GLAUBEN
+
+Ein gestuftes Overlay zeigt Bildrate, Bitrate und Latenz – über zwei Maschinen hinweg um den Uhrenversatz korrigiert, also eine Messung und kein Versprechen. Ein Geschwindigkeitstest pro Host schlägt eine passende Bitrate vor. Profile halten pro Host fest, wie gestreamt werden soll.
+
+WAS DU BRAUCHST
+
+Einen Punktfunk-Host auf einem Linux-PC oder auf Windows 11 (22H2 oder neuer) im selben Netzwerk. Der Host ist quelloffen (MIT/Apache-2.0) und kostenlos – Anleitungen und Quellcode findest du auf punktfunk.unom.io. Diese App ist der Client: ein Mac kann derzeit nicht selbst Host sein.
+
+Kein Konto. Keine Cloud. Keine Telemetrie. Die App erfasst keine Daten über dich.
+```
+
+---
+
+## Description (EN) — max 4000 characters
+
+```
+Punktfunk streams your gaming PC to your Mac — at your display's exact resolution and refresh rate, over your own network, with no account and no cloud.
+
+Punktfunk comes in two halves: a host on the PC you stream from, and this app on the device you play on. The host is open source and free, and runs on Linux and on Windows 11 — on the gaming rig under your desk, on a laptop, or headless on a server with no monitor attached at all.
+
+YOUR MAC GETS A DISPLAY OF ITS OWN
+
+For every connection, the host creates a real virtual display at exactly the resolution and refresh rate your Mac reports. No scaling, no black bars, no rearranging your actual monitors. Resize the window mid-stream or go full screen and the resolution is renegotiated without dropping the connection. Several devices can stream at once, each on its own display.
+
+FAST, BECAUSE WE OWN THE WHOLE PATH
+
+The native apps speak punktfunk/1: a QUIC control plane and an encrypted data plane with forward error correction, able to change resolution and frame rate mid-stream without reconnecting. Decoding is done in hardware through VideoToolbox — H.264, HEVC, and AV1 on Macs with an AV1 hardware decoder (M3 and later).
+
+BUILT FOR THE MAC
+
+• In a window or full screen, on any attached display
+• Mouse and keyboard pass straight through — click to capture, Cmd+Esc or Ctrl+Alt+Shift+Q to release
+• A Stream menu in the menu bar: release the mouse, disconnect, toggle the stats overlay
+• Microphone uplink with echo cancellation — your Mac becomes the headset on your PC
+• HDR with PQ passthrough, plus an optional full-chroma (4:4:4) mode that keeps small text and fine UI lines sharp
+
+CONTROLLERS, IN FULL
+
+DualSense, Xbox, and other MFi-compatible controllers. On a DualSense, rumble, lightbar, player LEDs, adaptive triggers, touchpad, and gyro all reach the game. The virtual gamepad the host presents takes its type from the controller actually in your hands.
+
+YOUR LIBRARY, YOUR NETWORK
+
+Installed Steam titles and games you add yourself appear as a grid with artwork, ready to launch. The app finds hosts on your network by itself. The first time, you pair once with a PIN; after that your Mac reconnects on a pinned identity stored in your keychain — no account, no login. Punktfunk can wake a sleeping PC over Wake-on-LAN.
+
+MEASURED, NOT PROMISED
+
+A tiered overlay shows frame rate, bitrate, and latency — corrected for clock skew across the two machines, so it is a measurement rather than a claim. A per-host speed test suggests a bitrate that matches your link. Profiles remember how each host should be streamed.
+
+WHAT YOU NEED
+
+A Punktfunk host on a Linux PC or on Windows 11 (22H2 or later) on the same network. The host is open source (MIT/Apache-2.0) and free — guides and source at punktfunk.unom.io. This app is the client: a Mac cannot currently act as a host.
+
+No account. No cloud. No telemetry. This app collects no data about you.
+```
+
+---
+
+## Keywords — max 100 characters
+
+Comma-separated, **no spaces after the commas** (spaces count against the limit). The app name and
+the subtitle are already indexed, so `punktfunk`, `schnell`, `lokal`, and `offen` are deliberately
+absent — repeating them would waste characters.
+
+### DE (97)
+
+```
+streaming,spiele,remote,desktop,fernzugriff,pc,linux,windows,controller,gamepad,latenz,quelloffen
+```
+
+### EN (95)
+
+```
+streaming,remote,desktop,pc,linux,windows,gaming,controller,gamepad,latency,selfhosted,lan,play
+```
+
+**Deliberately excluded:** `Moonlight`, `GameStream`, `NVIDIA`, `Steam`. Punktfunk genuinely is
+GameStream-compatible and does read your Steam library, but App Store Review Guideline 4.1 and the
+metadata rules disallow third-party app, product, and company names in the **keyword** field — it is
+a routine rejection. Saying it in the description is fine; the current descriptions avoid naming
+Moonlight and mention Steam only as a factual statement about your own library.
+
+The previous keyword set (`Game-Streaming, Lokal, Open-Source, Gaming`) spent characters on spaces,
+on `Lokal` (already in the subtitle), and on both `Game-Streaming` and `Gaming`, which share a stem.

clients/apple/store/privacy-app-addendum.md

@@ -0,0 +1,146 @@
+# Privacy — what to link from App Store Connect
+
+## The situation
+
+You already have a privacy policy at **punktfunk.unom.io/legal/privacy**. It is good, current
+(Stand: 28. Juni 2026), and localised DE/EN. But it is a **website** privacy policy: it covers
+server log files, Plausible Analytics on `analytics.unom.io`, the `PARAGLIDE_LOCALE` cookie, and
+self-hosted fonts. It does not mention the apps at all.
+
+That is a problem for App Store Connect in two directions:
+
+1. Apple requires the linked policy to describe **the app's** data practices. A reviewer following
+   the link finds a page about a website.
+2. It reads as *contradicting* a "Data Not Collected" declaration. The page prominently describes
+   analytics and a cookie. A reviewer who skims it sees "Reichweitenmessung mit Plausible
+   Analytics" and has every reason to question the App Privacy answers.
+
+**Recommendation:** keep the existing page and append an app-specific section to it (the text
+below), so one URL covers both. The alternative — a separate `/legal/privacy-apps` route — also
+works, but one URL is less to keep in sync.
+
+The page is CMS-driven (`src/routes/legal/privacy.tsx` renders Payload `RichText` blocks from the
+`pages` collection, slug `legal/privacy`, tenant `punktfunk`), so this is a CMS edit rather than a
+code change.
+
+## Confirming the "collects no data" framing
+
+Checked against the source rather than taken on trust, and it holds:
+
+- **No analytics, telemetry, or crash-reporting SDK.** `Package.swift` declares no such dependency.
+  A case-insensitive sweep of `Sources/` for `sentry|firebase|analytics|telemetry|amplitude|
+  mixpanel|crashlytics|posthog|plausible` returns 43 hits — 43 of them the word "amplitude" in
+  haptics code (rumble amplitude), and one the English word "plausible" in a comment.
+- **No outbound calls to us.** The only `URLSession` use is `LibraryClient`, fetching cover art
+  **from the paired host**, over a TLS session that pins the host's own certificate. The only
+  external URLs anywhere in the Swift sources are three UI links the user can tap: the docs site,
+  the source on `git.unom.io`, and the Discord invite.
+- **No account system.** Identity is a client keypair in the device keychain
+  (`keychain-access-groups`, `ClientIdentityStore`); pairing is SPAKE2 with a PIN, host-to-device.
+- **Data stays on device.** Saved hosts and settings live in a shared `UserDefaults` suite
+  (`group.io.unom.punktfunk`) so the widget can read them. Nothing syncs; there is no CloudKit
+  entitlement.
+- **No ATT.** No `NSUserTrackingUsageDescription` anywhere, consistent with no tracking.
+
+So **App Privacy → "Data Not Collected"** is accurate for all four platforms. Two caveats worth
+stating in the policy text anyway, because they are true and pre-empt questions:
+
+- The microphone uplink **is** audio leaving the device — but only to the host the user paired with,
+  encrypted, and never to us. Apple's questionnaire asks about data collected *by you or your
+  third-party partners*; streaming to the user's own machine is not collection. Saying so plainly
+  is better than staying silent about a microphone permission.
+- The apps are distributed through the App Store, so **Apple** collects its own analytics. That is
+  Apple's processing, not yours, but naming it avoids looking like an omission.
+
+---
+
+## Text to append — Deutsch
+
+> ## Die Punktfunk-Apps
+>
+> Dieser Abschnitt betrifft die Punktfunk-Apps für iPhone, iPad, Apple TV, Mac, Windows, Linux und
+> Android – im Unterschied zu den vorstehenden Abschnitten, die sich auf diese Website beziehen.
+>
+> **Die Apps erheben keine personenbezogenen Daten.** Es gibt keine Benutzerkonten, keine
+> Registrierung und keine Anmeldung. Die Apps enthalten keine Analyse-, Tracking-, Werbe- oder
+> Absturzbericht-Bibliotheken von Drittanbietern. Es findet kein Tracking im Sinne des App
+> Tracking Transparency Frameworks statt, und es werden keine Daten an uns oder an Dritte
+> übermittelt.
+>
+> **Wohin die Daten fließen.** Punktfunk verbindet Ihr Gerät direkt mit einem Host-Rechner, den Sie
+> selbst betreiben – in der Regel in Ihrem eigenen Netzwerk. Video, Ton, Maus-, Tastatur- und
+> Controller-Eingaben sowie – sofern Sie ihn einschalten – Ihr Mikrofon werden ausschließlich
+> zwischen Ihrem Gerät und diesem Host übertragen, verschlüsselt und ohne Umweg über einen Server
+> von uns. Wir betreiben für den Streaming-Betrieb keine Vermittlungs-, Relay- oder Cloud-Dienste
+> und haben zu keinem Zeitpunkt Zugriff auf die Inhalte einer Sitzung.
+>
+> **Was auf dem Gerät bleibt.** Die App speichert lokal auf Ihrem Gerät: die von Ihnen
+> hinzugefügten oder im Netzwerk gefundenen Hosts, Ihre Einstellungen und Profile sowie einen
+> kryptografischen Schlüssel, mit dem sich Ihr Gerät gegenüber einem gekoppelten Host ausweist
+> (auf Apple-Geräten im Schlüsselbund). Diese Daten verlassen Ihr Gerät nicht und werden gelöscht,
+> wenn Sie die App entfernen.
+>
+> **Berechtigungen.** Die App fragt nur Berechtigungen ab, die für den Betrieb nötig sind: den
+> Zugriff auf das lokale Netzwerk, um Hosts zu finden und sich mit ihnen zu verbinden, und – nur
+> wenn Sie die Mikrofonübertragung nutzen – das Mikrofon. Das Mikrofonsignal wird an den von Ihnen
+> gekoppelten Host übertragen, wo es als virtuelles Mikrofon erscheint; es wird nicht
+> aufgezeichnet und nicht an uns gesendet.
+>
+> **Verteilung über App-Stores.** Wenn Sie die App über den App Store oder Google Play beziehen,
+> verarbeiten Apple bzw. Google im Rahmen der Auslieferung eigene Daten (etwa Kauf-, Installations-
+> und Absturzstatistiken). Darauf haben wir keinen Einfluss; es gelten die
+> Datenschutzbestimmungen des jeweiligen Anbieters. Aggregierte Statistiken, die uns Apple oder
+> Google in ihren Entwicklerkonsolen anzeigen, lassen keinen Rückschluss auf einzelne Personen zu.
+>
+> **Der Host.** Der Punktfunk-Host ist quelloffene Software, die Sie selbst auf Ihrem eigenen
+> Rechner betreiben. Welche Daten dabei anfallen – etwa lokale Protokolldateien –, bleibt
+> vollständig unter Ihrer Kontrolle; wir erhalten davon nichts. Der Quellcode ist unter
+> git.unom.io/unom/punktfunk einsehbar.
+
+---
+
+## Text to append — English
+
+> ## The Punktfunk apps
+>
+> This section concerns the Punktfunk apps for iPhone, iPad, Apple TV, Mac, Windows, Linux, and
+> Android — as distinct from the sections above, which concern this website.
+>
+> **The apps collect no personal data.** There are no user accounts, no registration, and no sign-in.
+> The apps contain no third-party analytics, tracking, advertising, or crash-reporting libraries.
+> No tracking within the meaning of Apple's App Tracking Transparency framework takes place, and no
+> data is transmitted to us or to any third party.
+>
+> **Where your data goes.** Punktfunk connects your device directly to a host machine that you run
+> yourself, normally on your own network. Video, audio, mouse, keyboard, and controller input — and
+> your microphone, if you switch it on — travel only between your device and that host, encrypted,
+> without passing through any server of ours. We operate no brokering, relay, or cloud service for
+> streaming, and we have no access to the contents of a session at any point.
+>
+> **What stays on your device.** The app stores locally on your device: the hosts you have added or
+> discovered on your network, your settings and profiles, and a cryptographic key your device uses
+> to identify itself to a paired host (in the keychain, on Apple devices). This data does not leave
+> your device and is removed when you delete the app.
+>
+> **Permissions.** The app requests only the permissions it needs to work: access to the local
+> network, in order to find hosts and connect to them, and — only if you use microphone streaming —
+> the microphone. The microphone signal is sent to the host you paired with, where it appears as a
+> virtual microphone; it is not recorded and is not sent to us.
+>
+> **Distribution through app stores.** If you obtain the app from the App Store or Google Play,
+> Apple or Google process their own data as part of distributing it (such as purchase, installation,
+> and crash statistics). We have no influence over this, and the respective provider's privacy
+> policy applies. The aggregated statistics Apple and Google show us in their developer consoles do
+> not allow any individual to be identified.
+>
+> **The host.** The Punktfunk host is open source software that you run on your own machine. Any
+> data it produces — local log files, for instance — remains entirely under your control, and none
+> of it reaches us. The source is available at git.unom.io/unom/punktfunk.
+
+---
+
+## Also update
+
+- Bump **Stand: / Effective date:** on the page when you add this.
+- App Store Connect → App Privacy → **Data Not Collected** for all four platforms.
+- The same URL works for Google Play's Data safety declaration; the wording above already covers it.

clients/apple/store/review-notes.md

@@ -0,0 +1,132 @@
+# App Review notes
+
+## The core problem, stated plainly
+
+Punktfunk is the client half of a two-part system. Without a reachable host it shows a host list, a
+pairing sheet, and settings — and nothing else. There is **no demo or offline mode in a release
+build**: the mock-data screens in `Sources/PunktfunkClient/Screenshots/` are wrapped in `#if DEBUG`
+and are compiled out of anything you ship. A reviewer who launches the App Store build with no host
+on their network sees an empty "On this network" list.
+
+Guideline 2.1 requires you to supply whatever is needed to fully exercise the app. So you must
+attach **one** of:
+
+- **(a) A reachable demo host.** Best outcome — the reviewer sees the real thing. Requires a host
+  exposed to the internet with its UDP ports forwarded, plus a pairing PIN in the notes. The client
+  can add a host by IP or hostname, so mDNS discovery is not required for this path.
+- **(b) A demo video.** Apple accepts this for hardware- or setup-dependent apps. Less good: a
+  reviewer who cannot reproduce is a reviewer who can reject on something unrelated.
+
+**Attach (a) if you can keep a host up for the review window; (b) is the fallback.** Whichever you
+pick, fill in the placeholders before submitting — the template assumes (a) and marks the spots.
+
+> **⚠ Decide before submitting:** if you go with (b), replace the "CONNECTING TO OUR DEMO HOST"
+> section with the video URL and say explicitly that no host can be provided.
+
+---
+
+## Notes template — paste into App Store Connect
+
+The App Review Information "Notes" field caps at **4000 characters**. The block below is **3919**,
+and filling the five placeholders in shortens it further (the literal `[[FILL IN: …]]` text is
+longer than the values that replace it). If you add to it, re-check the count — an over-long note
+is silently truncated, and what gets cut is the end, where the privacy and entitlement answers
+live.
+
+```
+WHAT THIS APP IS
+
+Punktfunk is a low-latency game- and desktop-streaming client. It streams from a "host" the user
+installs on their own gaming PC (Linux, or Windows 11 22H2+), over their own network. The host is
+separate open-source software we publish at https://git.unom.io/unom/punktfunk; it is not sold,
+and this app has no purchases.
+
+This app is the client half only: it renders video and audio from the user's own machine and
+sends input back. There is no content library and no server of ours in a session.
+
+IMPORTANT: THIS APP NEEDS A HOST
+
+With no reachable host, the app can only show its host list, the pairing screen and settings --
+inherent to what it is, not an incomplete build. We have provided a live host for review.
+
+CONNECTING TO OUR DEMO HOST
+
+1. Launch Punktfunk. The main screen lists hosts on the local network. Ours is not on yours, so
+   add it by hand: "+" (top right) then "Add host"; on Apple TV, "Add host" on the main screen.
+2. Enter:  Host: [[FILL IN: hostname or IP]]   Port: [[FILL IN: port, default 47998]]
+   Name it anything, then confirm.
+3. The app connects and asks for a pairing PIN. Enter:  [[FILL IN: PIN]]
+   A one-time SPAKE2 pairing; afterwards the device is remembered and needs no PIN.
+4. The host's game library appears as a grid. Select any title to stream; video and audio start
+   within a few seconds.
+5. While streaming: stats overlay = Ctrl+Alt+Shift+S (or three-finger tap on iOS/iPadOS); release
+   mouse = Cmd+Esc or Ctrl+Alt+Shift+Q; disconnect = Ctrl+Alt+Shift+D.
+6. Settings (gear) covers decoder, bitrate, HDR, audio, controllers and profiles; the per-host
+   "Speed test" suggests a bitrate for the link.
+
+The host stays reachable throughout review. If you cannot reach it, please contact
+[[FILL IN: contact email]] and we will restore it promptly.
+
+WHY THE APP ASKS FOR WHAT IT ASKS FOR
+
+- Local Network: finds hosts via Bonjour (_punktfunk._udp) and connects to them -- the app's
+  entire purpose.
+- Microphone (optional, off by default): audio goes to the user's own paired host, appearing
+  there as a virtual microphone for voice chat. Never recorded, never sent to us.
+- networking.multicast: sends the Wake-on-LAN magic packet, which must go to a broadcast address:
+  a sleeping PC has no ARP entry, so unicast cannot reach it. Used for nothing else.
+- device.usb / device.bluetooth (macOS): the GameController framework reaches wired controllers
+  through IOHIDLibUserClient and wireless ones through startWirelessControllerDiscovery. USB also
+  drives DualSense rumble, which CoreHaptics will not. Without these, no controller input.
+- network.server (macOS): the app is outbound-only, but the App Sandbox gates bind() itself. Our
+  QUIC endpoint and UDP socket each bind a local port to receive host-to-client datagrams;
+  without this, no video, audio or rumble arrives.
+- UIBackgroundModes "audio" (iPhone/iPad): a session carries real, audible audio from the host,
+  and this keeps it alive if the user steps away briefly. Backgrounded, video decoding stops, only
+  the real audio keeps rendering, and a bounded timer disconnects automatically. We never play
+  silence to stay alive, nor use the mode outside an audible session.
+
+REGARDING BUILD 0.4.2 (3384)
+
+That build was rejected under 2.4.5(i) for a temporary-exception entitlement
+(mach-lookup.global-name, com.apple.audioanalyticsd), added on a mistaken belief about CoreHaptics
+rumble under the App Sandbox. We have since verified rumble works without it; this build carries
+no temporary exception.
+
+ACCOUNTS, PURCHASES, DATA
+
+No account, no sign-in, no in-app purchase. The app collects no personal data: no analytics,
+tracking, advertising or crash-reporting SDKs, and no connection to any server of ours during a
+session. Device identity is a keychain keypair used only to authenticate to the user's own host.
+
+Privacy policy: [[FILL IN: https://punktfunk.unom.io/legal/privacy]]
+```
+
+---
+
+## Before you submit — checklist
+
+- [ ] Fill every `[[FILL IN: …]]` placeholder. There are five.
+- [ ] Confirm the demo host is reachable **from outside your own network** — test it on cellular,
+      not on the LAN it lives on. This is the failure mode that wastes a review cycle.
+- [ ] Confirm the pairing PIN in the notes is the one the host will actually accept during the
+      review window, and that pairing is left open (it is on-demand in the web console).
+- [ ] Put at least one launchable title in the demo host's library. An empty grid after a
+      successful pairing looks like a broken app.
+- [ ] If submitting tvOS, verify the whole flow is reachable with the **Siri Remote alone**. A
+      reviewer will not have a controller paired, and "requires an accessory to navigate" is a
+      tvOS rejection.
+- [ ] Attach the demo video as a URL in the notes if you are going the (b) route.
+
+## Separately worth checking: the privacy manifest
+
+There is **no `PrivacyInfo.xcprivacy`** anywhere in `clients/apple`. The app does use
+`UserDefaults` (`HostStore` reads the `group.io.unom.punktfunk` suite), and `UserDefaults` is one of
+Apple's "required reason" APIs, which are expected to be declared in a privacy manifest. Apps
+missing a declaration typically get an automated **ITMS-91053** notice on upload.
+
+This is adjacent to the copy work rather than part of it, so nothing has been changed here — but it
+is worth adding a manifest declaring `NSPrivacyAccessedAPICategoryUserDefaults` with reason code
+`CA92.1` (access to an app group container) and `NSPrivacyTracking` set to `false`, before the next
+submission. Confirm the current reason codes against Apple's documentation rather than taking the
+code above on trust; the list has changed since it was introduced.

clients/apple/store/tvos.md

@@ -0,0 +1,145 @@
+# tvOS — App Store metadata
+
+Client only, living-room framing. Things the other platforms have that the **Apple TV does not**,
+and which the copy therefore avoids claiming:
+
+- **No microphone uplink.** There is no usable audio input on tvOS, so the "your Mac becomes the
+  headset" line does not transfer.
+- **No gamepad console shell.** `ShotScenes` builds the gamepad home/settings screens for iOS and
+  macOS only — tvOS uses the native focus engine instead.
+- **No AV1.** Apple TV 4K has no AV1 hardware decoder; HEVC and H.264 only.
+- Mouse/keyboard capture exists on tvOS but is not a living-room story, so it stays out.
+
+Kept, and genuinely tvOS-shaped: Siri Remote pointer navigation (`SiriRemotePointer`), controllers
+including the full DualSense feedback set, HDR passthrough, and Wake-on-LAN — which is the single
+best Apple TV feature, because it is what removes the trip to the other room.
+
+- **Name:** Punktfunk
+- **Subtitle (DE):** Schnell, lokal & offen.
+- **Subtitle (EN):** Fast, local & open.
+
+---
+
+## Promotional Text (DE) — max 170 characters
+
+### Primary (161)
+
+```
+Anschalten, Host wählen, spielen: Punktfunk weckt deinen Gaming-PC per Wake-on-LAN und verbindet sich, sobald er wach ist. In 4K, mit HDR, mit deinem Controller.
+```
+
+### Alternate A — leads on the picture (157)
+
+```
+Dein Gaming-PC am großen Bildschirm – in genau der Auflösung und Bildrate deines Fernsehers, mit HDR. Ohne Konto, ohne Cloud, nur über dein eigenes Netzwerk.
+```
+
+### Alternate B — leads on the DualSense (160)
+
+```
+Dein DualSense am Apple TV, vollständig: Rumble, adaptive Trigger, Lightbar, Touchpad und Gyro gehen bis ins Spiel durch. Dazu Profile pro Host und Wake-on-LAN.
+```
+
+## Promotional Text (EN) — max 170 characters
+
+### Primary (160)
+
+```
+Turn on, pick a host, play: Punktfunk wakes your gaming PC over Wake-on-LAN and connects as soon as it's up. In 4K, with HDR, with the controller in your hands.
+```
+
+### Alternate A — leads on the picture (148)
+
+```
+Your gaming PC on the big screen — at your TV's exact resolution and refresh rate, with HDR. No account, no cloud, nothing leaving your own network.
+```
+
+---
+
+## Description (DE) — max 4000 characters
+
+```
+Punktfunk macht aus deinem Apple TV die Konsole für den Gaming-PC, der ohnehin schon im Haus steht – in 4K, mit HDR, über dein eigenes Netzwerk, ohne Konto und ohne Cloud.
+
+Punktfunk besteht aus zwei Hälften: einem Host auf dem PC, von dem du streamst, und dieser App auf dem Gerät, auf dem du spielst. Der Host ist quelloffen und kostenlos, läuft auf Linux und auf Windows 11 – auch headless auf einem Rechner, an dem gar kein Monitor hängt.
+
+VOM SOFA AUS, VON ANFANG BIS ENDE
+
+Anschalten, Host auswählen, spielen. Die App findet Hosts im Netzwerk von allein. Beim ersten Mal koppelst du einmalig mit einer PIN, danach verbindet sich der Apple TV über eine gepinnte Identität – kein Konto, kein Login, kein Abtippen von IP-Adressen. Steht dein Gaming-PC im Standby, weckt ihn Punktfunk per Wake-on-LAN und verbindet sich, sobald er wach ist. Niemand muss dafür aufstehen.
+
+DAS BILD, DAS DEIN FERNSEHER WIRKLICH KANN
+
+Für den Apple TV legt der Host ein echtes virtuelles Display an – in genau der Auflösung und Bildrate, die dein Fernseher meldet, bis 4K. Kein Skalieren, keine schwarzen Balken, und die Monitore am PC werden nicht umsortiert. Dekodiert wird in Hardware über VideoToolbox (HEVC und H.264), HDR wird als PQ durchgereicht, statt es flach zu rechnen.
+
+CONTROLLER, VOLLSTÄNDIG
+
+DualSense, Xbox- und weitere MFi-kompatible Controller. Beim DualSense gehen Rumble, Lightbar, Player-LEDs, adaptive Trigger, Touchpad und Gyro bis ins Spiel durch. Welchen Typ das virtuelle Gamepad am Host annimmt, richtet sich nach dem, was bei dir wirklich in der Hand liegt. Bedienen lässt sich alles mit der Siri Remote oder komplett mit dem Controller – die Oberfläche ist für die Fernbedienung gebaut, nicht für eine Maus.
+
+DEINE BIBLIOTHEK AUF DEM FERNSEHER
+
+Installierte Steam-Titel und selbst hinzugefügte Spiele erscheinen als Raster mit Artwork und starten direkt vom Sofa aus. Mehrere Geräte können gleichzeitig streamen, jedes auf seinem eigenen Display – der Apple TV im Wohnzimmer stört also niemanden, der am Schreibtisch weiterarbeitet.
+
+SCHNELL, WEIL UNS DER GANZE WEG GEHÖRT
+
+Die nativen Apps sprechen punktfunk/1: eine QUIC-Steuerebene und eine verschlüsselte Datenebene mit Vorwärtsfehlerkorrektur. Ein gestuftes Overlay zeigt Bildrate, Bitrate und Latenz – über zwei Maschinen hinweg um den Uhrenversatz korrigiert, also eine Messung und kein Versprechen. Ein Geschwindigkeitstest pro Host schlägt eine passende Bitrate für dein Netzwerk vor.
+
+WAS DU BRAUCHST
+
+Einen Punktfunk-Host auf einem Linux-PC oder auf Windows 11 (22H2 oder neuer) im selben Netzwerk. Für die beste Erfahrung hängt der Apple TV am Kabel oder an einem guten 5-GHz-WLAN. Der Host ist quelloffen (MIT/Apache-2.0) und kostenlos – Anleitungen und Quellcode findest du auf punktfunk.unom.io.
+
+Kein Konto. Keine Cloud. Keine Telemetrie. Die App erfasst keine Daten über dich.
+```
+
+---
+
+## Description (EN) — max 4000 characters
+
+```
+Punktfunk turns your Apple TV into a console for the gaming PC you already own — in 4K, with HDR, over your own network, with no account and no cloud.
+
+Punktfunk comes in two halves: a host on the PC you stream from, and this app on the device you play on. The host is open source and free, and runs on Linux and on Windows 11 — including headless, on a machine with no monitor attached at all.
+
+FROM THE COUCH, START TO FINISH
+
+Turn on, pick a host, play. The app finds hosts on your network by itself. The first time, you pair once with a PIN; after that your Apple TV reconnects on a pinned identity — no account, no login, no typing IP addresses with a remote. If your gaming PC is asleep, Punktfunk wakes it over Wake-on-LAN and connects as soon as it is up. Nobody has to get up to make that happen.
+
+THE PICTURE YOUR TV CAN ACTUALLY SHOW
+
+For your Apple TV, the host creates a real virtual display at exactly the resolution and refresh rate your TV reports, up to 4K. No scaling, no black bars, and the monitors on your PC are left where they are. Decoding is done in hardware through VideoToolbox (HEVC and H.264), and HDR is passed through as PQ rather than flattened.
+
+CONTROLLERS, IN FULL
+
+DualSense, Xbox, and other MFi-compatible controllers. On a DualSense, rumble, lightbar, player LEDs, adaptive triggers, touchpad, and gyro all reach the game. The virtual gamepad the host presents takes its type from the controller actually in your hands. Everything is navigable with the Siri Remote or entirely with a controller — the interface is built for a remote, not for a mouse.
+
+YOUR LIBRARY ON THE BIG SCREEN
+
+Installed Steam titles and games you add yourself appear as a grid with artwork, ready to launch from the couch. Several devices can stream at once, each on its own display — so the Apple TV in the living room does not disturb anyone still working at the desk.
+
+FAST, BECAUSE WE OWN THE WHOLE PATH
+
+The native apps speak punktfunk/1: a QUIC control plane and an encrypted data plane with forward error correction. A tiered overlay shows frame rate, bitrate, and latency — corrected for clock skew across the two machines, so it is a measurement rather than a claim. A per-host speed test suggests a bitrate that matches your network.
+
+WHAT YOU NEED
+
+A Punktfunk host on a Linux PC or on Windows 11 (22H2 or later) on the same network. For the best experience, put your Apple TV on Ethernet or on good 5 GHz Wi-Fi. The host is open source (MIT/Apache-2.0) and free — guides and source at punktfunk.unom.io.
+
+No account. No cloud. No telemetry. This app collects no data about you.
+```
+
+---
+
+## Keywords — max 100 characters
+
+### DE (93)
+
+```
+streaming,spiele,gaming,controller,gamepad,wohnzimmer,fernseher,pc,linux,windows,4k,hdr,couch
+```
+
+### EN (91)
+
+```
+streaming,gaming,controller,gamepad,livingroom,tv,pc,linux,windows,4k,hdr,couch,remote,play
+```
+
+Same exclusions as macOS: no `Moonlight`, `GameStream`, `NVIDIA`, or `Steam` in the keyword field.

clients/apple/tools/screenshots.sh

@@ -11,9 +11,15 @@
 # The captured pixels are exactly App Store Connect's required sizes:
 #   mac        2880×1800   (a 1× display yields 1440×900 — also accepted)
 #   iphone-6.9 1320×2868   (portrait)  /  2868×1320 (the landscape hero)
-#   ipad-13    2064×2752   (portrait)  /  2752×2064 (the landscape hero)
+#   ipad-13    2064×2752   (portrait)
 #   appletv    1920×1080
 #
+# A `.landscape` scene rotates on iPhone but NOT on iPad: an iPad app that supports multitasking
+# is resizable, and iPadOS ignores `requestGeometryUpdate` orientation requests for it — the app
+# follows the device, and simctl cannot rotate a simulated device. The iPad set is therefore
+# portrait throughout (a valid App Store size, and uniform, which the gallery prefers). To get a
+# landscape iPad hero, rotate the Simulator by hand (⌘←) and re-run just that scene.
+#
 # Requirements:
 #   • macOS target: just the Swift toolchain (`swift build`) + a one-time Screen Recording grant
 #     for your terminal (System Settings → Privacy & Security → Screen Recording).
@@ -35,7 +41,11 @@ cd "$APPLE_DIR"
 
 OUT="${OUT:-$APPLE_DIR/screenshots}"
 BUNDLE_ID="io.unom.punktfunk"
-SCENES=(01-stream 02-hosts 03-pair 04-trust 05-settings)
+
+# The App Store set, in listing order — the first three are what most people ever see, so they are
+# the stream itself, the machines it found, and the couch/controller mode. Everything else in
+# ShotScenes.all is a dev scene; capture those with `SCENES="06-gamepad-home 10-edithost" ...`.
+SCENES=(${SCENES:-01-stream 02-hosts 06-gamepad-home 09e-waking-modal 05-settings 03-pair})
 SETTLE="${SETTLE:-4}" # seconds to let a scene lay out before capturing
 
 mkdir -p "$OUT"
@@ -89,13 +99,20 @@ shoot_macos() {
 
 # $1 device-type regex (matches both existing device names and the device-type catalog)
 # $2 scheme  $3 sdk  $4 file prefix  $5 runtime platform (iOS|tvOS — for the create fallback)
+# $6 name for a device we have to create — MUST satisfy $1 (see below)
 shoot_sim() {
   require_xcode
-  local match="$1" scheme="$2" sdk="$3" prefix="$4" platform="$5"
+  local match="$1" scheme="$2" sdk="$3" prefix="$4" platform="$5" createname="$6"
 
-  # Reuse an existing device of this type; else create a throwaway one against the newest
-  # available runtime for the platform. CI runners commonly ship a runtime but not every device
-  # (the iPhone 16 Pro Max is absent on ours), so create-on-demand is what makes it reproducible.
+  # Reuse an existing device of this type; else create one against the newest available runtime
+  # for the platform. CI runners commonly ship a runtime but not every device (the iPhone 16 Pro
+  # Max is absent on ours), so create-on-demand is what makes it reproducible.
+  #
+  # The created device is named after the DEVICE, not after this script, for two reasons. It used
+  # to be "pf-shot-<prefix>", which `$match` never matches — so every run created another
+  # simulator and none was ever reused (they piled up on the runner). And the name is user-visible:
+  # `UIDevice.current.name` is what the pairing sheet prefills as this device's name, so
+  # "pf-shot-iphone-6.9" was rendered into an App Store screenshot.
   local udid
   udid="$(xcrun simctl list devices available | grep -E "$match" | grep -oE '[0-9A-F-]{36}' | head -1 || true)"
   if [ -z "$udid" ]; then
@@ -105,8 +122,8 @@ shoot_sim() {
     rt="$(xcrun simctl list runtimes available | grep -E "^$platform " \
       | grep -oE 'com\.apple\.CoreSimulator\.SimRuntime\.[A-Za-z0-9.-]+' | tail -1 || true)"
     if [ -n "$devtype" ] && [ -n "$rt" ]; then
-      udid="$(xcrun simctl create "pf-shot-$prefix" "$devtype" "$rt" 2>/dev/null || true)"
-      [ -n "$udid" ] && log "$prefix — created Simulator $udid ($devtype)"
+      udid="$(xcrun simctl create "$createname" "$devtype" "$rt" 2>/dev/null || true)"
+      [ -n "$udid" ] && log "$prefix — created Simulator \"$createname\" $udid ($devtype)"
     fi
   fi
   [ -n "$udid" ] || die "$prefix: no Simulator matching /$match/, and none could be created
@@ -114,6 +131,11 @@ shoot_sim() {
   log "$prefix — Simulator $udid"
   xcrun simctl boot "$udid" 2>/dev/null || true
   xcrun simctl bootstatus "$udid" -b >/dev/null 2>&1 || true
+  # Every scene is a dark-mode scene. The in-app `.environment(\.colorScheme, .dark)` override
+  # does NOT cross a presentation boundary — a `.sheet` gets its own environment and follows the
+  # DEVICE appearance — so the pairing sheet came out light grey over the dark app. Set the
+  # simulator itself to dark and the whole hierarchy, presentations included, agrees.
+  xcrun simctl ui "$udid" appearance dark >/dev/null 2>&1 || true
 
   log "$prefix — building ($scheme)…"
   # PF_SHOT_DERIVED_DATA (optional): a STABLE DerivedData root, so repeat runs reuse the
@@ -150,15 +172,15 @@ pixels() { sips -g pixelWidth -g pixelHeight "$1" 2>/dev/null | awk '/pixel/{pri
 for target in "$@"; do
   case "$target" in
     macos) shoot_macos ;;
-    ios)   shoot_sim 'iPhone 16 Pro Max'   Punktfunk-iOS  iphonesimulator  iphone-6.9 iOS ;;
-    ipad)  shoot_sim 'iPad Pro 13|iPad Pro .*M4|iPad Pro \(13' Punktfunk-iOS iphonesimulator ipad-13 iOS ;;
-    tvos)  shoot_sim 'Apple TV'            Punktfunk-tvOS appletvsimulator appletv    tvOS ;;
+    ios)   shoot_sim 'iPhone 16 Pro Max'   Punktfunk-iOS  iphonesimulator  iphone-6.9 iOS 'iPhone 16 Pro Max' ;;
+    ipad)  shoot_sim 'iPad Pro 13|iPad Pro .*M4|iPad Pro \(13' Punktfunk-iOS iphonesimulator ipad-13 iOS 'iPad Pro 13-inch (M4)' ;;
+    tvos)  shoot_sim 'Apple TV'            Punktfunk-tvOS appletvsimulator appletv    tvOS 'Apple TV 4K' ;;
     all)
       shoot_macos
       if xcrun --find simctl >/dev/null 2>&1; then
-        shoot_sim 'iPhone 16 Pro Max' Punktfunk-iOS iphonesimulator iphone-6.9 iOS
-        shoot_sim 'iPad Pro 13|iPad Pro .*M4|iPad Pro \(13' Punktfunk-iOS iphonesimulator ipad-13 iOS
-        shoot_sim 'Apple TV' Punktfunk-tvOS appletvsimulator appletv tvOS
+        shoot_sim 'iPhone 16 Pro Max' Punktfunk-iOS iphonesimulator iphone-6.9 iOS 'iPhone 16 Pro Max'
+        shoot_sim 'iPad Pro 13|iPad Pro .*M4|iPad Pro \(13' Punktfunk-iOS iphonesimulator ipad-13 iOS 'iPad Pro 13-inch (M4)'
+        shoot_sim 'Apple TV' Punktfunk-tvOS appletvsimulator appletv tvOS 'Apple TV 4K'
       else
         warn "Skipping iOS/iPadOS/tvOS — full Xcode not found (Command Line Tools only)."
       fi

clients/cli/src/main.rs

@@ -41,16 +41,23 @@ mod cli {
 
     const PROBE_TIMEOUT: Duration = Duration::from_millis(2500);
 
+    /// The handshake budget `--request-access` runs on. Matches the host's `PENDING_APPROVAL_WAIT`
+    /// — the connect is PARKED for that long while an operator decides, so anything shorter would
+    /// give up while the approval prompt is still on their screen.
+    const REQUEST_ACCESS_TIMEOUT_SECS: u64 = 185;
+
     const USAGE: &str = "\
 punktfunk — the Punktfunk client, headless
 
+  punktfunk discover [--json] [--timeout SECS]
   punktfunk pair <host[:port]> [--pin N] [--name LABEL]
   punktfunk hosts list [--probe] [--json]
   punktfunk hosts add <host[:port]> [--name LABEL] [--fp HEX]
   punktfunk hosts forget <host-ref>
   punktfunk wake <host-ref> [--wait]
   punktfunk library <host-ref> [--json]
-  punktfunk launch <host-ref> [--game ID] [--profile REF] [--exec] [--fullscreen]
+  punktfunk launch <host-ref> [--game ID] [--profile REF] [--request-access]
+                              [--exec] [--fullscreen]
   punktfunk open <punktfunk://…>
   punktfunk reachable <host-ref>
   punktfunk speed-test <host-ref>
@@ -68,6 +75,24 @@ punktfunk:// link takes. Exit codes: 0 ok, 2 connect, 3 trust, 4 renderer, 5 not
     /// (what goes to stdout vs stderr, and which exit codes mean what).
     fn verb_help(verb: &str) -> Option<&'static str> {
         Some(match verb {
+            "discover" => {
+                "\
+punktfunk discover [--json] [--timeout SECS] — browse the LAN for hosts
+
+Listens for Punktfunk hosts advertising over mDNS and prints what answered:
+name TAB addr:port TAB saved|new TAB paired|unpaired. `saved` means this
+device already has a record for it, matched by fingerprint first and address
+second — the same rule every other surface joins the two lists by.
+
+  --timeout SECS  how long to browse (default 3, capped at 30) — a bounded
+                  call, so a panel can wait for it
+  --json          {\"hosts\":[{\"name\",\"addr\",\"port\",\"fp\",\"pair\",\"id\",\"mgmt\",
+                  \"os\",\"saved\",\"paired\"}]}
+
+Nothing answering is an answer, not a failure: an empty list exits 0. A host
+mDNS never sees (Tailscale, another subnet) will not appear here — save it by
+address with `punktfunk hosts add` and it shows in `hosts list --probe`."
+            }
             "pair" => {
                 "\
 punktfunk pair <host[:port]> — enrol this device with a host (PIN ceremony)
@@ -96,6 +121,13 @@ punktfunk hosts — the saved-hosts store (shared with the desktop client)
       another subnet). Without --fp it is a placeholder to pair later; with a
       64-hex fingerprint it is pinned immediately (still unpaired).
 
+      Idempotent, and keyed on the FINGERPRINT once there is one: re-running it
+      for a host already saved is a no-op, and giving a known fingerprint a new
+      address MOVES that host's record there rather than filing a second one
+      (which is how a host that changed DHCP lease stays reachable by its id).
+      A different fingerprint for an address already saved is refused, exit 3 —
+      a changed identity is a decision for a person.
+
   punktfunk hosts forget <host-ref>
       Remove a saved host, its pinned fingerprint included. A later connect
       must pair or trust it again."
@@ -119,7 +151,8 @@ this. Needs a paired host (exit 6 otherwise)."
             }
             "launch" => {
                 "\
-punktfunk launch <host-ref> [--game ID] [--profile REF] [--exec] [--fullscreen]
+punktfunk launch <host-ref> [--game ID] [--profile REF] [--request-access]
+                            [--exec] [--fullscreen]
 
 Start a stream — waking the host first if it is asleep and its MAC is known.
 The stream runs in the punktfunk-session renderer; this command supervises it
@@ -132,6 +165,16 @@ and relays its lifecycle to stderr.
   --exec         become the session process instead of supervising it — the
                  gamescope-wrapper mode, where the launched process must BE
                  the streaming one for focus and lifecycle to work
+  --request-access
+                 ask the host's operator to let this device in instead of
+                 typing a PIN. The host PARKS the connect until somebody
+                 approves it in its console or web UI (up to ~185 s), then
+                 admits it and the stream starts by itself; the host is
+                 recorded as paired once that happens, so later streams are
+                 silent. Needs the host's fingerprint pinned already
+                 (`punktfunk hosts add <addr> --fp <hex>`), and cannot be
+                 combined with --exec — under --exec there is no process
+                 left to record the approval.
 
 Exit 0 when the stream ends cleanly, 2 connect failed, 3 the host no longer
 trusts this device (re-pair), 4 the renderer could not start."
@@ -222,7 +265,7 @@ from the config directory for a true factory reset."
     fn flag_takes_value(flag: &str) -> bool {
         matches!(
             flag,
-            "--pin" | "--name" | "--fp" | "--game" | "--profile" | "--port"
+            "--pin" | "--name" | "--fp" | "--game" | "--profile" | "--port" | "--timeout"
         )
     }
 
@@ -269,6 +312,7 @@ from the config directory for a true factory reset."
             return OK;
         }
         match verb.as_str() {
+            "discover" => discover(&rest),
             "pair" => pair(&rest),
             "hosts" => hosts(&rest),
             "wake" => wake(&rest),
@@ -306,6 +350,104 @@ from the config directory for a true factory reset."
         }
     }
 
+    /// How long `discover` browses when nobody says, and the ceiling on what they can ask for.
+    /// The cap is not politeness: this verb is called from a Quick Access panel, and a typo'd
+    /// `--timeout 3000` would hang that panel with no way to cancel it.
+    const DISCOVER_DEFAULT_SECS: f64 = 3.0;
+    const DISCOVER_MAX_SECS: f64 = 30.0;
+
+    /// `discover [--json] [--timeout SECS]` — browse the LAN over mDNS and print what answered,
+    /// annotated against the saved-hosts store.
+    ///
+    /// The annotation is the point: a caller wants "can I stream this", which is a question
+    /// about BOTH lists, and joining them itself is how two surfaces end up disagreeing about
+    /// the same host. So the match rule lives here, once, and is the same one every other
+    /// surface uses — fingerprint first (survives a DHCP move), address second.
+    fn discover(args: &[String]) -> u8 {
+        let secs = value(args, "--timeout")
+            .and_then(|v| v.parse::<f64>().ok())
+            .filter(|s| *s > 0.0)
+            .unwrap_or(DISCOVER_DEFAULT_SECS)
+            .min(DISCOVER_MAX_SECS);
+        let found = pf_client_core::discovery::discover_for(Duration::from_secs_f64(secs));
+        // `read`, not `load`: this verb only LOOKS at the records to annotate what it found, and
+        // never hands their ids back. `load` would mint ids for a pre-mint store and save them —
+        // a write from a read-only verb, and one that races the `hosts list` a caller is very
+        // likely running at the same moment (the Decky panel issues both together).
+        let known = KnownHosts::read();
+        let rows: Vec<(
+            &pf_client_core::discovery::DiscoveredHost,
+            Option<&KnownHost>,
+        )> = found.iter().map(|d| (d, match_saved(&known, d))).collect();
+        if has(args, "--json") {
+            let hosts: Vec<serde_json::Value> = rows
+                .iter()
+                .map(|(d, saved)| {
+                    serde_json::json!({
+                        "name": d.name,
+                        "addr": d.addr,
+                        "port": d.port,
+                        "fp": d.fp_hex,
+                        "pair": d.pair,
+                        "id": d.advertised_id(),
+                        // 0 = not advertised, which is what a consumer's own "no mgmt port"
+                        // already means — an older host simply omits the TXT.
+                        "mgmt": d.mgmt_port.unwrap_or(0),
+                        "os": d.os,
+                        "saved": saved.is_some(),
+                        "paired": saved.is_some_and(|h| h.paired),
+                    })
+                })
+                .collect();
+            println!("{}", serde_json::json!({ "hosts": hosts }));
+        } else {
+            for (d, saved) in &rows {
+                println!(
+                    "{}\t{}:{}\t{}\t{}",
+                    d.name,
+                    d.addr,
+                    d.port,
+                    if saved.is_some() { "saved" } else { "new" },
+                    if saved.is_some_and(|h| h.paired) {
+                        "paired"
+                    } else {
+                        "unpaired"
+                    },
+                );
+            }
+        }
+        // An empty LAN is an answer, not a failure — a caller branching on the exit code is
+        // asking "did the browse run", and it did.
+        OK
+    }
+
+    /// The saved record an advert belongs to, if any: fingerprint first, address second.
+    ///
+    /// Fingerprint FIRST is deliberate and load-bearing — a host that moved to a new DHCP lease
+    /// still matches its record, and a *different* host that inherited the old address does not
+    /// inherit its pairing. This is the rule the plugin's `mergeHosts` and the shells' hosts
+    /// pages already use; keeping one copy is what stops two surfaces disagreeing about whether
+    /// the box in front of you is paired.
+    fn match_saved<'a>(
+        known: &'a KnownHosts,
+        advert: &pf_client_core::discovery::DiscoveredHost,
+    ) -> Option<&'a KnownHost> {
+        known
+            .hosts
+            .iter()
+            .find(|h| {
+                !h.fp_hex.is_empty()
+                    && !advert.fp_hex.is_empty()
+                    && h.fp_hex.eq_ignore_ascii_case(&advert.fp_hex)
+            })
+            .or_else(|| {
+                known
+                    .hosts
+                    .iter()
+                    .find(|h| h.addr == advert.addr && h.port == advert.port)
+            })
+    }
+
     /// `pair <host[:port]> [--pin N]` — the SPAKE2 ceremony. Without `--pin` it prompts, which
     /// is the interactive shape; with one it is scriptable. Refuses rather than prompting when
     /// stdin isn't a terminal and no PIN was given: a pairing that silently blocks a CI job
@@ -424,16 +566,69 @@ from the config directory for a true factory reset."
                     return UNRESOLVED;
                 };
                 let (addr, port) = split_host_port(&target);
+                let fp = value(args, "--fp").unwrap_or_default();
+                let name = value(args, "--name");
                 let mut known = KnownHosts::load();
-                if known.hosts.iter().any(|h| h.addr == addr && h.port == port) {
-                    eprintln!("{addr}:{port} is already saved");
-                    return OK;
+                if let Some(i) = known
+                    .hosts
+                    .iter()
+                    .position(|h| h.addr == addr && h.port == port)
+                {
+                    return match merge_saved_host(&mut known, i, &fp, name.as_deref()) {
+                        AddOutcome::Unchanged => {
+                            eprintln!("{addr}:{port} is already saved");
+                            OK
+                        }
+                        AddOutcome::Conflict => {
+                            eprintln!(
+                                "{addr}:{port} is already saved with a different fingerprint — \
+                                 forget it first if you really mean to replace it \
+                                 (punktfunk hosts forget {addr}:{port})"
+                            );
+                            TRUST_REJECTED
+                        }
+                        AddOutcome::Pinned => match known.save() {
+                            Ok(()) => {
+                                println!("updated {addr}:{port}");
+                                OK
+                            }
+                            Err(e) => {
+                                eprintln!("saving: {e:#}");
+                                CONNECT_FAILED
+                            }
+                        },
+                    };
+                }
+                // No record at this address — but a record carrying this exact FINGERPRINT is
+                // this same host at a new one. Re-point it rather than filing a second record:
+                // the fingerprint is the identity, and a host that changed DHCP lease is the
+                // whole reason `hosts add --fp` is idempotent in the first place. Without this a
+                // moved host accumulates one record per address it has ever held, and the one a
+                // stable id resolves to keeps the address it can no longer be reached at.
+                if let Some(i) = known
+                    .hosts
+                    .iter()
+                    .position(|h| !fp.is_empty() && h.fp_hex.eq_ignore_ascii_case(&fp))
+                {
+                    let was = format!("{}:{}", known.hosts[i].addr, known.hosts[i].port);
+                    known.hosts[i].addr = addr.clone();
+                    known.hosts[i].port = port;
+                    return match known.save() {
+                        Ok(()) => {
+                            println!("moved {was} to {addr}:{port}");
+                            OK
+                        }
+                        Err(e) => {
+                            eprintln!("saving: {e:#}");
+                            CONNECT_FAILED
+                        }
+                    };
                 }
                 known.hosts.push(KnownHost {
-                    name: value(args, "--name").unwrap_or_else(|| addr.clone()),
+                    name: name.unwrap_or_else(|| addr.clone()),
                     addr: addr.clone(),
                     port,
-                    fp_hex: value(args, "--fp").unwrap_or_default(),
+                    fp_hex: fp,
                     ..Default::default()
                 });
                 match known.save() {
@@ -475,6 +670,55 @@ from the config directory for a true factory reset."
         }
     }
 
+    /// What `hosts add` did to a record that was ALREADY saved for this address.
+    #[derive(Debug, PartialEq, Eq)]
+    enum AddOutcome {
+        /// Nothing to do — no fingerprint was offered, or the record already carries this one.
+        /// Exits 0 on purpose: a panel retrying step 1 of request access must not have to
+        /// invent an error to show for a state that is already correct.
+        Unchanged,
+        /// The record had no fingerprint and now has this one.
+        Pinned,
+        /// The record carries a DIFFERENT fingerprint. Refused, never overwritten.
+        Conflict,
+    }
+
+    /// `hosts add --fp` against an address that is already saved. The difference between these
+    /// three is a trust decision, not bookkeeping.
+    ///
+    /// Filling in an empty fingerprint is step 1 of request access (design §5): a host found by
+    /// advert is saved by address first and pinned second. Without it the `--fp` is dropped on
+    /// the floor and the launch that follows refuses for want of a pin — which is what this did
+    /// before, silently and with exit 0.
+    ///
+    /// A *different* fingerprint is refused because a changed identity is a decision for a
+    /// person, at a surface that can show them both. That is what `upsert_trusted` exists to
+    /// enforce; quietly overwriting it here would be a back door through the pinning the rest
+    /// of the client is built on.
+    fn merge_saved_host(
+        known: &mut KnownHosts,
+        i: usize,
+        fp: &str,
+        name: Option<&str>,
+    ) -> AddOutcome {
+        let existing = known.hosts[i].fp_hex.clone();
+        if fp.is_empty() || existing.eq_ignore_ascii_case(fp) {
+            return AddOutcome::Unchanged;
+        }
+        if !existing.is_empty() {
+            return AddOutcome::Conflict;
+        }
+        known.hosts[i].fp_hex = fp.to_string();
+        // Only a record still named after its own address is renamed: a label the user chose is
+        // theirs, and an advert's name must not quietly overwrite it.
+        if let Some(label) = name {
+            if known.hosts[i].name == known.hosts[i].addr {
+                known.hosts[i].name = label.to_string();
+            }
+        }
+        AddOutcome::Pinned
+    }
+
     /// `wake <host-ref> [--wait]` — a magic packet, and with `--wait` the same bounded
     /// wake-and-wait the shells run (`WakeWait`: a packet every 6 s, presence polled every
     /// second, 90 s budget).
@@ -585,6 +829,19 @@ from the config directory for a true factory reset."
             eprintln!("usage: punktfunk launch <host-ref> [--game ID] [--profile REF] [--exec]");
             return UNRESOLVED;
         };
+        let exec = has(args, "--exec");
+        let request_access = has(args, "--request-access");
+        // Refused rather than silently downgraded: under `--exec` this process BECOMES the
+        // session, so nothing survives to see `Ready` and record the approval. A launch that
+        // quietly dropped the persistence would leave hosts reading "trusted" forever with
+        // nobody able to say why.
+        if request_access && exec {
+            eprintln!(
+                "--request-access can't be combined with --exec: under --exec there is no \
+                 process left to record the host's approval"
+            );
+            return UNRESOLVED;
+        }
         let (known, i) = match resolve(&reference) {
             Ok(v) => v,
             Err(code) => return code,
@@ -597,7 +854,10 @@ from the config directory for a true factory reset."
         if has(args, "--fullscreen") {
             plan.settings.fullscreen_on_stream = true;
         }
-        run_plan(plan, has(args, "--exec"))
+        if request_access {
+            plan.connect_timeout_secs = Some(REQUEST_ACCESS_TIMEOUT_SECS);
+        }
+        run_plan(plan, exec, request_access)
     }
 
     /// `open <url>` — the `punktfunk://` grammar, headless. Same parser, same refusal rules and
@@ -622,7 +882,7 @@ from the config directory for a true factory reset."
             &trust::Settings::load(),
         );
         match outcome {
-            Ok(PlanOutcome::Connect(plan)) => run_plan(*plan, has(args, "--exec")),
+            Ok(PlanOutcome::Connect(plan)) => run_plan(*plan, has(args, "--exec"), false),
             // A URL may never pair or trust on its own — that is a decision for a person, at a
             // surface that can show them the fingerprint.
             Ok(PlanOutcome::ConfirmUnknown(u)) => {
@@ -646,7 +906,13 @@ from the config directory for a true factory reset."
     }
 
     /// Wake if needed, then run the session — supervising it, or becoming it under `--exec`.
-    fn run_plan(plan: ConnectPlan, exec: bool) -> u8 {
+    ///
+    /// `persist_paired` records the host as *paired* when the child reports ready. Only
+    /// `launch --request-access` passes true: there, the host parked the connect until an
+    /// operator approved this device, so `Ready` IS the approval arriving — the same thing
+    /// `SpawnOpts::persist_paired` means in the GTK shell. Every other launch records nothing,
+    /// which is correct: a plain connect proves reachability, not a new trust decision.
+    fn run_plan(plan: ConnectPlan, exec: bool, persist_paired: bool) -> u8 {
         if plan.host.fp_hex.is_none() {
             eprintln!(
                 "{} has no pinned fingerprint — punktfunk pair {}",
@@ -708,7 +974,24 @@ from the config directory for a true factory reset."
         let mut failure: Option<(String, bool)> = None;
         while let Ok(ev) = rx.recv() {
             match ev {
-                SessionEvent::Ready => eprintln!("streaming"),
+                SessionEvent::Ready => {
+                    eprintln!("streaming");
+                    // The pin we connected WITH, not one re-derived from the store: the record
+                    // is what we are about to rewrite, and the session proved the host holds
+                    // exactly this identity by completing a pinned handshake against it.
+                    if persist_paired {
+                        if let Some(fp_hex) = &plan.host.fp_hex {
+                            trust::persist_host(
+                                &plan.host.name,
+                                &plan.host.addr,
+                                plan.host.port,
+                                fp_hex,
+                                true,
+                            );
+                            trust::forget_placeholder(&plan.host.addr, plan.host.port);
+                        }
+                    }
+                }
                 SessionEvent::Error {
                     msg,
                     trust_rejected,
@@ -967,6 +1250,7 @@ from the config directory for a true factory reset."
         #[test]
         fn every_usage_verb_has_help() {
             for verb in [
+                "discover",
                 "pair",
                 "hosts",
                 "wake",
@@ -988,6 +1272,109 @@ from the config directory for a true factory reset."
             assert!(verb_help("bogus").is_none());
         }
 
+        fn saved(name: &str, addr: &str, fp: &str) -> KnownHost {
+            KnownHost {
+                name: name.into(),
+                addr: addr.into(),
+                port: 9777,
+                fp_hex: fp.into(),
+                ..Default::default()
+            }
+        }
+
+        /// Step 1 of request access: a host saved by address gains the fingerprint its advert
+        /// carried. Before this, `hosts add --fp` on an existing record exited 0 having done
+        /// NOTHING — the launch that followed then refused for want of a pin, and the panel had
+        /// no way to tell why.
+        #[test]
+        fn adding_a_fingerprint_to_a_placeholder_fills_it_in() {
+            let mut known = KnownHosts {
+                hosts: vec![saved("192.168.1.9", "192.168.1.9", "")],
+            };
+            assert_eq!(
+                merge_saved_host(&mut known, 0, "abc123", Some("living-room")),
+                AddOutcome::Pinned
+            );
+            assert_eq!(known.hosts[0].fp_hex, "abc123");
+            assert_eq!(
+                known.hosts[0].name, "living-room",
+                "a record still named after its address takes the offered label"
+            );
+        }
+
+        /// A label the user chose is theirs — an advert's name must not overwrite it.
+        #[test]
+        fn filling_in_a_fingerprint_keeps_a_user_chosen_name() {
+            let mut known = KnownHosts {
+                hosts: vec![saved("Basement rig", "192.168.1.9", "")],
+            };
+            merge_saved_host(&mut known, 0, "abc123", Some("living-room"));
+            assert_eq!(known.hosts[0].name, "Basement rig");
+        }
+
+        /// Idempotent: the panel may retry step 1, and re-offering the fingerprint a record
+        /// already carries is a state that is already correct, not an error to render.
+        #[test]
+        fn re_adding_the_same_fingerprint_changes_nothing() {
+            let mut known = KnownHosts {
+                hosts: vec![saved("desk", "192.168.1.9", "ABC123")],
+            };
+            assert_eq!(
+                merge_saved_host(&mut known, 0, "abc123", None),
+                AddOutcome::Unchanged,
+                "fingerprints compare case-insensitively"
+            );
+            // And a bare `hosts add` with no --fp at all leaves the pin alone.
+            assert_eq!(
+                merge_saved_host(&mut known, 0, "", None),
+                AddOutcome::Unchanged
+            );
+            assert_eq!(known.hosts[0].fp_hex, "ABC123");
+        }
+
+        /// A changed identity is a decision for a person. Never a silent overwrite — this is the
+        /// same rule `upsert_trusted` enforces, and a back door here would defeat it everywhere.
+        #[test]
+        fn a_different_fingerprint_is_refused_not_overwritten() {
+            let mut known = KnownHosts {
+                hosts: vec![saved("desk", "192.168.1.9", "abc123")],
+            };
+            assert_eq!(
+                merge_saved_host(&mut known, 0, "deadbeef", None),
+                AddOutcome::Conflict
+            );
+            assert_eq!(
+                known.hosts[0].fp_hex, "abc123",
+                "the pin must survive intact"
+            );
+        }
+
+        /// A host that changed DHCP lease is re-pointed, not filed a second time. Without this
+        /// the record a stable id resolves to keeps an address the host has left, so a launch
+        /// dials into the void while the panel shows the live one.
+        #[test]
+        fn a_known_fingerprint_at_a_new_address_moves_the_record() {
+            let mut known = KnownHosts {
+                hosts: vec![saved("desk", "192.168.1.9", "abc123")],
+            };
+            // Simulates `hosts add 192.168.1.50 --fp abc123` finding no record at that address.
+            let by_addr = known
+                .hosts
+                .iter()
+                .position(|h| h.addr == "192.168.1.50" && h.port == 9777);
+            assert!(
+                by_addr.is_none(),
+                "the new address is not yet on any record"
+            );
+            let by_fp = known
+                .hosts
+                .iter()
+                .position(|h| h.fp_hex.eq_ignore_ascii_case("abc123"));
+            assert_eq!(by_fp, Some(0), "the fingerprint still identifies the host");
+            known.hosts[0].addr = "192.168.1.50".into();
+            assert_eq!(known.hosts.len(), 1, "one host, one record");
+        }
+
         #[test]
         fn value_reads_the_argument_after_its_flag() {
             let a = argv(&["--game", "steam:570", "--exec"]);

clients/cli/tests/cli_smoke.rs

@@ -67,3 +67,21 @@ fn unknown_verbs_refuse_with_the_not_found_code() {
     let out = punktfunk(&["help", "frobnicate"]);
     assert_eq!(out.status.code(), Some(5), "unknown help topic exits 5");
 }
+
+/// `discover` and `launch --request-access` document themselves. Help only — the verbs
+/// themselves browse the LAN and dial a host, which no runner may be asked to do.
+///
+/// The Decky panel detects a too-old client by exactly the signature the test above pins
+/// (exit 5 + `unknown command`), so this is the other half of that contract: on a client new
+/// enough, `discover` is a verb with help rather than an unknown word.
+#[test]
+fn the_request_access_surfaces_document_themselves() {
+    let out = punktfunk(&["help", "discover"]);
+    assert!(out.status.success(), "discover has its own help topic");
+    let stdout = String::from_utf8_lossy(&out.stdout);
+    assert!(stdout.contains("--timeout"), "discover documents --timeout");
+    assert!(stdout.contains("--json"), "discover documents --json");
+
+    let out = punktfunk(&["launch", "--help"]);
+    assert!(String::from_utf8_lossy(&out.stdout).contains("--request-access"));
+}

clients/decky/README.md

@@ -2,49 +2,61 @@
 
 Stream to your **Steam Deck** without ever leaving Gaming Mode. This
 **[Decky Loader](https://decky.xyz/)** plugin adds a **Punktfunk** panel to the Quick Access Menu
-(the `…` button): discover hosts on your network, pair with a PIN, tweak stream settings, and launch
-a fullscreen, gamescope-focused stream — all from the couch, gamepad-navigable.
+(the `…` button): the hosts you can stream, the pinned cards you set up, and one tap into each.
 
-The video itself is the native GTK4 Linux client (the `io.unom.Punktfunk` flatpak); the plugin
-discovers, pairs, configures, and *launches it the right way* so gamescope fullscreens it — the same
-Steam-shortcut trick MoonDeck uses. Because it's built from real Steam UI primitives (`@decky/ui`),
-the panel looks and feels native to Gaming Mode.
+The plugin is a **launcher**, not a client. It doesn't decode video, browse your library, or hold
+any settings of its own — the Rust client does all of that, and the plugin's job is to start it
+*the right way* so gamescope fullscreens and focuses it (the same Steam-shortcut trick MoonDeck
+uses). Everything the panel doesn't do is one tap away in the client's own gamepad UI.
 
 ## What it does
 
-1. **Discover** — browses the LAN over mDNS for Punktfunk hosts, in both the QAM panel and a
-   fullscreen page; each host row opens a details view (address, pairing policy, certificate
-   fingerprint to cross-check against the host's log).
-2. **Pair** — for a host that requires it, a gamepad-navigable PIN keypad runs the SPAKE2 pairing
-   ceremony headlessly, then remembers the host so future streams connect silently.
-3. **Stream** — launches fullscreen via a branded "Punktfunk" Steam shortcut so gamescope focuses it.
-4. **Games** — each host row has a games button that opens its **library picker**: pin titles as
-   one-tap "Stream <Game>" rows in the QAM (jump straight into e.g. Playnite on the host), or
-   **"Open library on screen"** to launch the client's controller-driven, console-style library
-   browser (aurora backdrop + poster coverflow; A plays, B returns to Gaming Mode). Pins survive
-   plugin reinstalls (stored next to the client's config) and follow a host across IP changes
-   (matched by certificate fingerprint).
-5. **Settings** — the client's whole settings store, written to its config. Laid out like SteamOS's
-   own Settings: a left rail of categories (`SidebarNavigation`), one page each, so no page needs
-   scrolling. The categories and their order are the console settings screen's — Stream (resolution
-   / refresh / render scale / bitrate / compositor), Video (codec / decoder / GPU / HDR / 4:4:4),
-   Presentation (prioritize / smoothness buffer / V-Sync / VRR), Audio (channels / output + mic
-   device / echo cancellation), Controllers, Touch & mouse, Interface (stats overlay / auto-wake /
-   library / fullscreen). The device pickers are populated
-   from the session binary (`--list-adapters` / `--list-audio`); the GPU row appears only where
-   there is more than one adapter.
-6. **About** — plugin version, an explicit "Check for updates" button, the setup-guide link, and
-   a force-stop for a wedged stream client.
+1. **Hosts** — the hosts on your network plus the ones you've saved, in one list. Discovery is
+   mDNS; saved hosts are also probed directly, so a box reached over Tailscale or a VPN shows as
+   online even though it never advertises. Rows sort online-first, then most recently used.
+2. **Trust** — an unpaired host opens a small sheet with two ways in:
+   - **Request access** (the default) — no PIN. The host's operator approves this Deck in its
+     console or web UI and the stream starts by itself. See [Request access](#request-access).
+   - **Use a PIN instead** — the gamepad-navigable keypad, running the same SPAKE2 ceremony.
+3. **Stream** — launches fullscreen via a branded "Punktfunk" Steam shortcut so gamescope focuses
+   it. A sleeping host is woken first (the client runs the real wake-and-wait loop, then dials).
+4. **Pinned cards** — a *(host, profile)* pair renders nested under its host as `▸ <Profile name>`
+   and streams with that settings profile applied. Cards are the **shared** pinning model every
+   other client speaks, stored on the host's record — so one you make in the desktop client shows
+   up here, and vice versa. The plugin renders them; it doesn't create or edit them.
+5. **Open Punktfunk** — launches the client's **console home**: the host picker, add-host by
+   address, PIN pairing, the game library browser, and the **full settings screen**. This is where
+   everything the panel no longer does now lives.
+6. **About** — plugin version, "Check for updates", "Recreate library shortcut", and a force-stop
+   for a wedged stream.
 
 To leave a stream: the in-client controller chord (**L1 + R1 + Start + Select**), or close the
 "game" from the Steam overlay — either returns you to Gaming Mode.
 
+### Request access
+
+Request access is not a second pairing ceremony — it is a **launch**. The plugin saves the host
+with the fingerprint it **advertised**, then starts an ordinary identified connect with the
+handshake budget stretched to 185 s. The host *parks* that connection until its operator approves
+the device, then admits the same connection; the stream starts on its own, and the record flips
+to **paired** so every later stream is silent.
+
+**No advertised fingerprint, no request access.** That pinned fingerprint is the only thing
+standing between a 185-second wait and an impostor answering for the host, so a host you typed in
+by address gets the PIN path only — and the sheet says why. The plugin never trusts-on-first-use
+past a missing fingerprint.
+
 ## Install on the Deck
 
-You need **[Decky Loader](https://decky.xyz/)** and the **`io.unom.Punktfunk` flatpak**
-([`packaging/flatpak`](../../packaging/flatpak/README.md)) installed on the Deck — SteamOS `/usr` is
-read-only, so the flatpak (which bundles libadwaita/SDL3) is the canonical client. Discovery uses
-`avahi-browse`, which ships on SteamOS/Bazzite.
+You need **[Decky Loader](https://decky.xyz/)** and a **Punktfunk client** on the Deck. On a normal
+Deck that's the `io.unom.Punktfunk` flatpak ([`packaging/flatpak`](../../packaging/flatpak/README.md)) —
+SteamOS `/usr` is read-only, so the flatpak (which bundles libadwaita/SDL3) is the canonical client.
+A native install (sysext, distro package, nix profile, your own build) works too.
+
+**The client must be v0.22.0 or newer** — that is when the headless `punktfunk` CLI shipped, and
+the panel drives everything through it. An older client says so in the panel, with the update
+button that fixes it right there. (Discovery no longer needs `avahi-browse` on the Deck; the
+client's own mDNS does it.)
 
 **Recommended — install from URL** (published by CI): in Decky → Settings → **Developer Mode** →
 **Install Plugin from URL**, paste:
@@ -55,17 +67,15 @@ https://unom.io/pf-decky
 
 (short link for `https://git.unom.io/api/packages/unom/generic/punktfunk-decky/latest/punktfunk.zip`;
 for a pinned version use `https://git.unom.io/api/packages/unom/generic/punktfunk-decky/<version>/punktfunk.zip`
-directly). The plugin then **self-updates** without
-the Decky store — when a newer build exists, an **Update** button appears and drives Decky
-Loader's own (SHA-256-verified) install. Installs and updates can take a couple of minutes on some
-networks: Decky's installer also contacts its plugin store first, which may be slow or blackholed
-before the actual download proceeds.
+directly). The plugin then **self-updates** without the Decky store — when a newer build exists, an
+**Update** button appears and drives Decky Loader's own (SHA-256-verified) install. Installs and
+updates can take a couple of minutes on some networks: Decky's installer also contacts its plugin
+store first, which may be slow or blackholed before the actual download proceeds.
 
 ### Updating the client
 
 The plugin also reports — and where it can, installs — updates for the **client** it launches.
-What is possible depends on how that client was installed, and the About tab names the install
-kind so the answer is never a mystery:
+What is possible depends on how that client was installed:
 
 | Install | Update |
 | --- | --- |
@@ -88,6 +98,8 @@ pnpm install
 pnpm build                             # rollup → dist/index.js
 pnpm run package                       # → out/punktfunk/ + out/punktfunk-v<ver>.zip
 DECK=deck@<deck-ip> pnpm run deploy    # rsync → /tmp, sudo-install into the root-owned plugins dir, restart loader
+
+python3.13 scripts/test-backend.py     # backend unit checks (needs Python ≥3.10)
 ```
 
 `~/homebrew/plugins/` is root-owned (the loader runs as root), so `deploy.sh` stages to a temp dir
@@ -96,28 +108,46 @@ restart is required for an out-of-band install to appear.
 
 ## Architecture
 
+Everything below the panel is the CLI. `main.py` builds argv and maps exit codes; it parses none of
+the client's data files and re-implements none of its rules.
+
 | File | Role |
 | --- | --- |
-| `src/index.tsx` | Plugin entry: the QAM panel + route registration. |
-| `src/page.tsx` | The `/punktfunk` fullscreen page — Hosts (with per-host details) / Settings / About tabs. |
-| `src/settings.tsx` · `src/pair.tsx` | The settings screen (a `SidebarNavigation` of seven category pages over one shared settings object); the gamepad-navigable PIN-pairing modal. |
-| `src/library.tsx` | The per-host game picker (pin/unpin, "Open library on screen") + the pinned-game launch helper. |
-| `src/hostmgmt.tsx` | Add / edit host dialogs — mutate the shared known-hosts store (`client-known-hosts.json`) via the flatpak client's headless modes, so a host saved here shows up in the desktop client too. |
-| `src/ui.tsx` | Shared UI primitives for the fullscreen page + modals (right-aligned row actions, consistent Field layout). |
-| `src/hooks.ts` · `src/boundary.tsx` | Shared discovery/update/pins hooks + actions; the render error boundary. |
-| `src/steam.ts` | Steam-shortcut launch (`AddShortcut` / `SetAppLaunchOptions` / `RunGame`) — the focus-correct stream start. The shortcut's exe is `/bin/sh` with the wrapper passed as an argument, so the script never needs an exec bit (Decky's zip extraction drops it and the root-owned plugins dir can't be chmodded by the unprivileged backend). Launch extras ride env-prefix tokens: `PF_LAUNCH=<id>` (pinned game) / `PF_BROWSE=1` + `PF_MGMT=<port>` (on-screen library); ids are validated space/quote-free at pin AND launch time. |
-| `src/backend.ts` | Typed `callable` bridges to `main.py`. |
-| `bin/punktfunkrun.sh` | The launch wrapper the Steam shortcut runs (so the window is focusable); maps `PF_LAUNCH`/`PF_BROWSE`/`PF_MGMT` to `--launch`/`--browse`/`--mgmt`. An older flatpak ignores the flags harmlessly (plain stream / hosts page). |
-| `main.py` | Backend: `discover` (via `avahi-browse`) / `pair` / `library` (headless flatpak `--library`, TSV) / pins store (`decky-pinned.json`) / settings / `kill_stream` / `check_update` (with an explicit CA-bundle search — Decky's embedded Python has no usable default TLS roots on SteamOS). |
-| `scripts/test-backend.py` | Stdlib-only checks for the backend's pure parsers (TSV, error classes, avahi TXT) + the pins round trip. |
+| `src/index.tsx` | Plugin entry + the QAM panel: update banner, hosts (with nested pinned cards), the console-home door, about. |
+| `src/hooks.ts` | `useHosts` (one call merging discovery and the saved store), the update hooks, and the launch action. Also the trust-state model the rows render. |
+| `src/trust.tsx` · `src/pair.tsx` | The trust sheet (Request access / Use a PIN instead / Cancel) and the gamepad-navigable PIN keypad. |
+| `src/steam.ts` | Steam-shortcut launch (`AddShortcut` / `SetAppLaunchOptions` / `RunGame`) — the focus-correct stream start. The shortcut's exe is `/bin/sh` with the wrapper passed as an argument, so the script never needs an exec bit (Decky's zip extraction drops it and the root-owned plugins dir can't be chmodded by the unprivileged backend). |
+| `src/backend.ts` · `src/boundary.tsx` · `src/os-icon.tsx` | Typed `callable` bridges to `main.py`; the render error boundary; the host row's OS mark. |
+| `bin/punktfunkrun.sh` | The launch wrapper the Steam shortcut runs (so the window is focusable). Reads `PF_REF` / `PF_PROFILE` / `PF_REQUEST_ACCESS` / `PF_BROWSE` and runs `punktfunk launch` — or the session's `--browse` for console home. |
+| `main.py` | Backend: four thin CLI shells (`discover` / `hosts` / `pair` / `trust_host`) plus the Steam-side work only a plugin can do — `runner_info`, `shortcut_art`, `apply_controller_config`, `kill_stream`, `check_update` / `update_client` (with an explicit CA-bundle search — Decky's embedded Python has no usable default TLS roots on SteamOS). |
+| `scripts/test-backend.py` | Stdlib-only checks: argv shape, the CLI exit-code mapping, and the Steam configset editor. |
 | `plugin.json` · `update.json` | Decky manifest; CI-baked update channel. |
 
+### Why the launch goes through Steam
+
+gamescope only gives focus and fullscreen to the window tree Steam launched via `reaper` (it
+detects the "current app" by AppID — gamescope#484). A client spawned from the plugin's own
+backend comes up invisible and unfocused. So the plugin registers non-Steam shortcuts whose exe is
+`/bin/sh` running `bin/punktfunkrun.sh`, and starts them with `RunGame`.
+
+There are **two** shortcuts, both named `Punktfunk` so Steam keys them to one Steam Input
+configset (the key is the lowercase name): a hidden, stateful one that carries the stream, and the
+visible, stateless library entry that opens console home.
+
 ## Limitations / next steps
 
-- No manual "add host by IP" entry yet (discovery is mDNS-only).
-- No in-stream overlay inside the plugin — the client owns the session once launched.
-- Pairing needs the operator to **arm pairing on the host** so it shows the PIN; the plugin can't arm
-  it remotely.
+- **Profiles and pinned cards can't be created here** — the panel renders them; making one needs
+  the desktop client, or the client's own gamepad UI once that work lands. A Deck with no profiles
+  simply sees host rows, and nothing is broken.
+- **Per-game pins are on hold.** The shared model pins *host+profile*; nothing in the shared store
+  persists a pinned *game* yet. The old `decky-pinned.json` is left on disk untouched so a later
+  migration can read it.
+- Pairing with a PIN needs the operator to **arm pairing on the host** so it shows the PIN; the
+  plugin can't arm it remotely. Request access needs no arming — just an approval.
+- **A parked connect looks like a hanging one.** The plugin toasts before launching a request-access
+  stream to set expectations, which is a patch rather than a fix; teaching the session's connect
+  screen the same "waiting for approval" copy the console shell already has would pay off for every
+  shell.
 
 ## Related
 

clients/decky/bin/punktfunkrun.sh

@@ -1,33 +1,32 @@
 #!/usr/bin/env bash
-# punktfunk stream runner — the target of the hidden non-Steam shortcut the plugin creates.
+# punktfunk stream runner — the target of the non-Steam shortcuts the plugin creates.
 #
 # WHY A WRAPPER SCRIPT (load-bearing, from MoonDeck's hard-won knowledge): the stream client
 # must be a descendant of the process Steam launches via `reaper`, or gamescope never gives
 # its window focus/fullscreen in Gaming Mode (gamescope detects the "current app" by AppID,
 # which only attaches to reaper's descendants — see gamescope#484). So the Decky plugin
-# launches THIS script through SteamClient.Apps.RunGame; the script then execs the flatpak
-# client, which inherits the shortcut's AppID and is focused. Launching the flatpak directly
-# from the (root) Decky backend produces an unfocused, invisible window.
+# launches THIS script through SteamClient.Apps.RunGame; the script then runs the client,
+# which inherits the shortcut's AppID and is focused. Launching the client directly from the
+# (root) Decky backend produces an unfocused, invisible window.
 #
 # Per-session parameters arrive as environment variables, set as the shortcut's Steam launch
 # options by the plugin (SteamClient.Apps.SetAppLaunchOptions), so ONE generic shortcut serves
-# every host (and every pinned game):
-#   PF_HOST   host[:port] to connect to            (required for streaming; optional for browse)
-#   PF_LAUNCH library id to launch on connect       (optional, e.g. steam:570 — pinned games)
-#   PF_BROWSE non-empty = open the gamepad library  (optional; --browse instead of --connect)
-#   PF_MGMT   management-API port for --browse       (optional; client defaults to 47990)
-#   PF_CONNECT_TIMEOUT  connect budget in seconds    (optional; the plugin stretches it after
-#                        firing Wake-on-LAN so the connect survives the host's resume)
-#   PF_APPID  flatpak app id                        (default io.unom.Punktfunk)
-#   PF_FLATPAK  override the flatpak binary path     (default: `flatpak` on PATH)
+# every host:
+#   PF_REF     host reference — a saved host's stable id, or addr[:port]  (required to stream)
+#   PF_PROFILE settings-profile id for a pinned card                      (optional)
+#   PF_REQUEST_ACCESS  non-empty = ask the host's operator to admit this device instead of
+#                      pairing with a PIN. The connect PARKS until somebody approves it.
+#   PF_BROWSE  non-empty = open the client's console home instead of streaming
+#   PF_APPID   flatpak app id                        (default io.unom.Punktfunk)
+#   PF_FLATPAK override the flatpak binary path      (default: `flatpak` on PATH)
 #   PF_CLIENT_BIN  absolute path of a NATIVE client  (optional; set by the plugin when it
-#                  resolved a non-flatpak install — then the client is exec'd directly and
+#                  resolved a non-flatpak install — then the client is run directly and
 #                  PF_APPID/PF_FLATPAK are unused)
 #
-# Values are plain tokens (the plugin validates launch ids to space/quote-free ASCII before
-# they ever reach Steam launch options). An older flatpak without --launch/--browse ignores
-# the unknown flags harmlessly (hand-scanned argv): PF_LAUNCH degrades to the plain desktop
-# session, PF_BROWSE to the client's hosts page.
+# A REFERENCE, NEVER A VALUE. Host refs and profile ids are the only things that ride this
+# channel; no resolution, bitrate or codec ever does. The client resolves both against its own
+# stores, which is what keeps a Steam launch option from becoming a second settings surface.
+# The plugin validates them to space/quote-free ASCII before they reach Steam's tokenizer.
 #
 # Runs as the `deck` user (Steam launched it), so the --user flatpak install is visible and
 # WAYLAND_DISPLAY / XDG_RUNTIME_DIR are already correct for gamescope.
@@ -42,13 +41,22 @@ APPID="${PF_APPID:-io.unom.Punktfunk}"
 FLATPAK="${PF_FLATPAK:-flatpak}"
 
 # The client is not always the flatpak: a sysext, a .deb/.rpm, an AUR build or a nix profile
-# installs a native `punktfunk-client`, and the plugin passes its absolute path here when that
-# is what it resolved. Both kinds take the same argv and share ~/.config/punktfunk, so the only
-# difference is the prefix in front of it.
+# installs a native `punktfunk-client` with the CLI as its sibling, and the plugin passes the
+# client's absolute path here when that is what it resolved.
 #
-# exec so the client IS the game process — when it exits, Steam ends the "game" and Gaming Mode
-# reclaims focus automatically (no manual refocus needed).
-run_client() {
+# run_cli execs the HEADLESS CLI (`punktfunk`); run_session execs the GTK/console shell
+# (`punktfunk-client`). Both live in the same place in both install kinds — /app/bin inside the
+# flatpak, reachable with `--command=`, and one bindir natively.
+run_cli() {
+    if [ -n "${PF_CLIENT_BIN:-}" ]; then
+        # `${VAR%/*}` rather than `dirname`: pure parameter expansion, so this works with no
+        # PATH at all — which is the environment a Steam launch option can leave us in.
+        exec "${PF_CLIENT_BIN%/*}/punktfunk" "$@"
+    fi
+    exec "$FLATPAK" run --arch=x86_64 --command=punktfunk "$APPID" "$@"
+}
+
+run_session() {
     if [ -n "${PF_CLIENT_BIN:-}" ]; then
         exec "$PF_CLIENT_BIN" "$@"
     fi
@@ -58,40 +66,35 @@ run_client() {
 # What we are about to run, for the log line each branch prints.
 CLIENT_LABEL="${PF_CLIENT_BIN:-$APPID}"
 
-# --fullscreen: present the stream chrome-less and fullscreen (the client also auto-detects the
-# Deck/gamescope env, and ignores the flag harmlessly on older builds that predate it).
+# The console home: the client's own gamepad UI (host picker, pairing, add-host by address, the
+# library browser and the full settings screen). UNCHANGED from before this rework — the shell
+# binary already execs the session for `--browse`, so there is nothing to repoint here.
 if [ -n "${PF_BROWSE:-}" ]; then
-    # The gamepad UI. BARE `--browse` (no PF_HOST) opens the console home — the self-contained
-    # host picker + pairing + settings, gamepad-navigable — which is what the stateless, visible
-    # library shortcut launches. `--browse <host>` opens straight into that host's library (the
-    # per-host "open on screen" action). A streams a game, session end returns here, B quits.
-    if [ -z "${PF_HOST:-}" ]; then
-        echo "punktfunkrun: gamepad UI $CLIENT_LABEL --browse (console home)" >&2
-        run_client --browse --fullscreen
-    fi
-    echo "punktfunkrun: library $CLIENT_LABEL --browse $PF_HOST" >&2
-    if [ -n "${PF_MGMT:-}" ]; then
-        run_client --browse "$PF_HOST" --mgmt "$PF_MGMT" --fullscreen
-    fi
-    run_client --browse "$PF_HOST" --fullscreen
+    echo "punktfunkrun: gamepad UI $CLIENT_LABEL --browse (console home)" >&2
+    run_session --browse --fullscreen
 fi
 
-# Streaming modes need a host (browse above is the only host-less path).
-if [ -z "${PF_HOST:-}" ]; then
-    echo "punktfunkrun: PF_HOST is not set (the plugin sets it as a launch option)" >&2
+if [ -z "${PF_REF:-}" ]; then
+    echo "punktfunkrun: PF_REF is not set (the plugin sets it as a launch option)" >&2
     exit 2
 fi
-# Trailing args shared by both streaming execs. A stretched connect budget rides along when the
-# plugin set one (it just fired Wake-on-LAN, so the host may still be resuming); an older flatpak
-# without --connect-timeout ignores the flag harmlessly (hand-scanned argv).
+
 set -- --fullscreen
-if [ -n "${PF_CONNECT_TIMEOUT:-}" ]; then
-    set -- --connect-timeout "$PF_CONNECT_TIMEOUT" "$@"
+if [ -n "${PF_PROFILE:-}" ]; then
+    set -- --profile "$PF_PROFILE" "$@"
 fi
-if [ -n "${PF_LAUNCH:-}" ]; then
-    # A pinned game: the id rides the session Hello and the host launches that title.
-    echo "punktfunkrun: streaming $CLIENT_LABEL --connect $PF_HOST --launch $PF_LAUNCH" >&2
-    run_client --connect "$PF_HOST" --launch "$PF_LAUNCH" "$@"
+
+# REQUEST ACCESS RUNS SUPERVISED — no `--exec`. Under --exec the CLI BECOMES the session, so no
+# process survives to see the stream come up and record the host as paired; the CLI refuses the
+# combination outright rather than downgrading silently. This is safe for gamescope because
+# focus follows reaper's DESCENDANT TREE, not a single process, and `flatpak run`/`bwrap`
+# already sit between reaper and the client on every other path.
+if [ -n "${PF_REQUEST_ACCESS:-}" ]; then
+    echo "punktfunkrun: request access $CLIENT_LABEL launch $PF_REF (waiting for approval)" >&2
+    run_cli launch "$PF_REF" --request-access "$@"
 fi
-echo "punktfunkrun: streaming $CLIENT_LABEL --connect $PF_HOST" >&2
-run_client --connect "$PF_HOST" "$@"
+
+# The ordinary stream. `--exec` is the documented gamescope-wrapper mode: the CLI becomes the
+# session, so the process tree stays flat and Steam's "game" ends exactly when the stream does.
+echo "punktfunkrun: streaming $CLIENT_LABEL launch $PF_REF" >&2
+run_cli launch "$PF_REF" --exec "$@"