Merge pull request '0.27.0' (#159) from worktree-release-0270 into main

chore(release): bump workspace version to 0.27.0

87 commits since v0.26.0. C ABI 17 -> 18 (additive), so a minor rather than a 0.26.x patch.

The one red check is nix.yml's `flake` job: `bun run build` for punktfunk-web was OOM-killed
(exit 137) inside the nix sandbox, twice, on two different runner hosts. It is not this diff --
main built the identical web sources in 32s, and this commit touches no file under web/ or
packaging/nix/. nix.yml does not run on tags, so it cannot affect the release. Tracked as a
memory-headroom problem in the gate #158 added.

CHANGELOG.md

@@ -12,10 +12,42 @@ with the version table of the release you are moving to, then read **Breaking ch
 
 ---
 
-## v0.27.0 — in development
+## v0.27.0
 
-Sections accumulate here as work lands. The version table and the commit count are written at the
-version bump, alongside `docs/releases/v0.27.0.md` — see `docs/releases/README.md`.
+87 commits since v0.26.0.
+
+### Versions
+
+| | v0.26.0 | v0.27.0 | Notes |
+|---|---|---|---|
+| Wire protocol | 2 | **2** | unchanged |
+| C ABI | 17 | **18** | `punktfunk_connection_next_rumble_cmd2` **added**; nothing removed or changed |
+| Workspace crate dirs | 26 | **27** | `crates/punktfunk-encode-worker` (39 members; two `tools/` crates deliberately *excluded*) |
+| Virtual-display driver protocol | 6 | **6** | unchanged (minimum accepted still 3) |
+| Windows virtual-gamepad channel | 3 | **3** | unchanged — three `device_type`s added additively |
+| Plugin index schema | 1 | **1** | unchanged |
+| `api/openapi.json` | 0.25.0 | **0.25.0** | unchanged — no management-API edits this release |
+| gamescope patch level (`+pfhdrN`) | 4 | **5** | 6 patches → 7 (the PipeWire use-after-free); `pkgrel` resets 3 → 1 |
+| `@punktfunk/host` (SDK) | 0.1.4 | **0.1.4** | unchanged |
+| `@punktfunk/plugin-kit` | 0.4.0 | **0.4.0** | unchanged |
+
+⚠ **`crates/pf-driver-proto` is no longer byte-identical to the previous release.** It was through
+both v0.25.0 and v0.26.0, so if you ship the virtual-display driver or the gamepad channel and have
+been skipping this crate, stop skipping it here. The change is purely additive — three `device_type`
+constants, no field moved, no size changed.
+
+### ⚠ Breaking changes
+
+**None** for embedders or the wire. Every embedder, packager and plugin that works against v0.26.0
+works against v0.27.0 unchanged; the C ABI moves, but by addition only (below).
+
+Two things change shape for **packagers** and one **default** flips:
+
+- **A second installed binary**, `punktfunk-encode-worker` — see the section below. It is the only
+  file that may carry `cap_sys_nice=ep`, and it must be a separate file.
+- **`PUNKTFUNK_XBOX_BACKEND` now defaults to `hid`** on Windows, so an Xbox pad is built as a real
+  HID device rather than the XUSB companion. `=xusb` is the escape hatch.
+- **NixOS `scripting.autoStart` now defaults ON**, matching every other packaging (detailed below).
 
 ### `punktfunk-encode-worker` — the GPU-priority capability moves off the host
 
@@ -123,8 +155,160 @@ instantiation runs them and the existing `--no-build` leg is enough. `punktfunk-
 `build-gamescope` dispatch input — it is on the critical path of every host build yet nothing
 compiled it, and it tracks nixpkgs' gamescope, so a `flake.lock` bump is what breaks it.
 
+### C ABI 17 → 18
+
+**`punktfunk_connection_next_rumble_cmd2` is new.** The `0xCA` rumble plane carries the two Xbox
+impulse-trigger motors (v3, below) and `punktfunk_connection_next_rumble_cmd`'s fixed out-params
+have no room for them:
+
+```c
+PunktfunkStatus punktfunk_connection_next_rumble_cmd2(
+    PunktfunkConnection *c, uint16_t *pad, uint16_t *low, uint16_t *high,
+    uint16_t *left_trigger, uint16_t *right_trigger,
+    uint32_t *backstop_ms, uint32_t timeout_ms);
+```
+
+**Added, not widened.** `_cmd` keeps its signature *and* its values bit-identical for handle-only
+traffic; all four rumble entry points remain exported. An exported parameter list is part of the
+contract, and growing one in place breaks every out-of-tree embedder at once — with a
+stack-corruption signature rather than a link error. This follows the existing
+`next_rumble` → `next_rumble2` precedent.
+
+⚠ **One behavioural delta on the old symbol**, documented in `abi.rs` and pinned by a test: against
+a host driving the trigger motors, a `_cmd` caller now receives commands with `low == high == 0`
+where the demux previously dropped the update entirely. They are idempotent handle stops — the
+command as a whole is not silent, so redundant-stop suppression cannot fold them. Zero cost today:
+nothing sources non-zero trigger levels yet.
+
+**Render trigger levels only on a pad that has trigger motors.** Do not fold them into the handles —
+impulse-trigger content is continuous, so folding it drones the handle motors flat-out. Query
+`SDL_PROP_GAMEPAD_CAP_TRIGGER_RUMBLE_BOOLEAN` or `GCDeviceHaptics.supportedLocalities`.
+
+🛑 **This delivery path is deliberately built ahead of its producer and nothing here claims
+otherwise.** Exactly one backend can ever source these levels — the Windows HID Xbox pad's output
+report `0x03` — because `XINPUT_VIBRATION` and evdev `FF_RUMBLE` both have two members. That
+producer is reachable only through GameInput, which does not enumerate an `xinputhid`-promoted Xbox
+pad at all (measured against a real Microsoft Elite, equally invisible there while classic XInput
+reads it live). The wire, the engine and this entry point are exercised by synthetic levels only.
+
+### Gamepads
+
+- **`PUNKTFUNK_GAMEPAD_XBOXELITE = 11`** — a new `GamepadPref` wire byte, appended to
+  `Hello`/`Welcome`. The `Auto` sentinel in the round-trip test moved 11 → 12. An older peer
+  degrades an unknown byte to `Auto`, so this is graceful in both directions.
+- **`XboxOne` is now a distinct HID identity on Windows** (`045E:02FD`, Bluetooth Xbox One S)
+  through the UMDF minidriver. It used to fold to `Xbox360` there, because the only Windows Xbox
+  backend was the XUSB companion, which presents one fixed 360 identity and cannot vary it.
+- **Three new `pf_driver_proto::gamepad` device types**, contiguous and sharing one report
+  descriptor byte for byte (they are the same pad in HID terms; the descriptor is the report
+  *shape*, the identity is what the OS keys mappings off):
+
+  | const | value | identity |
+  |---|---|---|
+  | `DEVTYPE_XBOX` | 4 | `045E:0B13` Xbox Wireless Controller |
+  | `DEVTYPE_XBOX_ONE_S` | 5 | `045E:02FD` Xbox Wireless Controller (One S) |
+  | `DEVTYPE_XBOX_ELITE` | 6 | `045E:0B22` Xbox Elite Wireless Controller Series 2 |
+
+  ⚠ The Xbox input report is **not** 64 bytes like its siblings — it is `XBOX_INPUT_REPORT_LEN`
+  (16). The driver serves per-identity report lengths, because hidclass sizes its buffer from the
+  descriptor and refuses an over-long source.
+- ⚠ **Elite paddles are not implemented.** `BTN_PADDLE1..4` still fold or drop exactly as on the
+  other Xbox classes. `DualSenseEdge` remains the only virtual pad with native back-button slots.
+- **All three Xbox identities install `pfGamepadXbox`**, their own DDInstall section, which attaches
+  the `xinputhid` bus filter. Merging it back into the shared `pfGamepad` section is a one-line edit
+  that looks like tidying and would hand a DualSense, DualShock 4, Edge and Steam Deck to
+  Microsoft's Xbox translator. `only_the_xbox_identity_installs_the_xinputhid_section` asserts the
+  split in both directions.
+
+**What actually promotes the pad — two registry values, and the pairing is the whole finding.**
+`UpperFilters=xinputhid` is a `.HW` AddReg (hardware key); `DevicePropertyFlags=1` is a DDInstall
+AddReg (software key). A one-value A/B on real hardware: removing `DevicePropertyFlags` alone
+reverts everything — no `IG_00`, no XUSB interface, no XInput, no WGI entry — while `UpperFilters`
+alone is completely inert. `1` = `BusDevice`, which Microsoft's own comment glosses as "a focused
+bus filter driver for the IG_ problem". **This retracts an earlier in-tree conclusion that the
+filter should never ship**: it was never broken, it had simply never been switched on.
+⚠ Microsoft's allow-list contains `02D1, 02DD, 02E3, 02EA, 0B00, 0B0A, 0B13, 02FF` — neither `02FD`
+nor `0B22` is on it, and promotion happens anyway, because it comes from our own AddReg.
+
+### Wire (no version change)
+
+**The `0xCA` rumble datagram gains a v3 form**, `PUNKTFUNK_RUMBLE_V3_LEN = 14`:
+
+```
+v1   7 B: [0xCA][u16 pad][u16 low][u16 high]
+v2  10 B: … [u8 seq][u16 ttl_ms]
+v3  14 B: … [u16 left_trigger][u16 right_trigger]
+```
+
+v3 is built *from* v2's bytes, so the prefix relationship is structural rather than a convention two
+encoders must keep agreeing on, and every reader gates with `>=`. All four levels share one `seq`
+and one TTL deliberately: they are one statement of the pad's feedback at one instant, so the entire
+v2 apparatus — renewal cadence, stop burst, the client's seq gate, the lease clamp — governs the
+triggers with no new code. The new `RumbleUpdate` fields are plain `u16`, not `Option`: on a
+level-triggered plane "absent" must mean zero, because "absent → keep the previous value" is the
+stuck-rumble bug in a new costume.
+
+⚠ **The two trigger `enable`-mask bits remain conjecture.** Bits 2/3 (the handles) are measured;
+bits 0/1 are inferred from field order and nothing else. No test asserts them. XInput cannot settle
+this; it has two motors.
+
+### Packaging
+
+- **gamescope pin `8c676c39` → `5fb8dce4`** (3.16.25-1 → 3.16.25-11), all six patches rebased, plus
+  a **seventh**: the PipeWire use-after-free that aborted a session on every connect. The marker
+  moves `+pfhdr4` → **`+pfhdr5`**, so `pkgrel` resets to 1.
+- **Patch 0001 offers `xBGR_210LE` before `xRGB_210LE`.** ⚠ Deliberately *not* done by calling
+  upstream's `vulkan_get_rgb10_capture_format()` — that symbol landed after 3.16.25 and would break
+  `packaging/nix/gamescope.nix` with an opaque C++ error instead of a patch conflict.
+- **Every `punktfunk-gamescope` RPM ever published was unsigned.** `Sign RPMs` runs right after
+  `Build RPM`, while the gamescope RPM is built ~90 steps later behind its own cache, so it missed
+  the signing pass entirely — and the repo file we ship carries `gpgcheck=1`. A second pass signs it
+  before publish, fail-closed on a tag.
+- ⚠ **The v0.26.0 gamescope gate failed the job at the *build* step**, which in `deb.yml` runs before
+  both the apt publish and the release attach — so a missing *extra* withheld the host `.deb` itself,
+  and the `.deb` published on v0.26.0 still carries the `CAP_SYS_NICE` grant. `rpm.yml` had the
+  identical latent bug. Both now warn at build/package time and gate as the **last** step of the job.
+- **`driver uninstall --audio`** — a third Inno `[UninstallRun]` entry that removes the MEDIA-class
+  devnodes the host mints at runtime. Marker-matched, never name-matched: our instances are
+  name-identical to Steam's, and a `ROOT\` enumeration guard means a marker-shaped value on a real
+  sound card can never cost the user their hardware.
+- **The sysext `post_merge` step re-runs when already current, plus a new `reapply` verb.** A sysext
+  upgrade is driven by the script from the **old** image, so a `post_merge` step added in a release
+  is executed by nobody, permanently, on exactly the installs that need it.
+
+### Host
+
+- **HDR capture offers `xBGR_210LE` before `xRGB_210LE`.** gamescope's capture textures are
+  mappable, hence linear-tiled, and NVIDIA does not implement linear-tiled STORAGE for
+  `A2R10G10B10_UNORM_PACK32` — so `imageStore` lands in XBGR order while the buffer is still
+  *labelled* `XRGB2101010`. Every mapping on both ends audits clean because the label was right and
+  only the content was wrong. Fixed host-side because the deployed gamescope cannot self-correct.
+- **One NVENC open failure no longer kills every session on the box**, and the 10-bit capability
+  probe no longer wedges a direct-SDK host process-wide with `NV_ENC_ERR_INVALID_VERSION`.
+- **`/api/v1/local/summary` reports the resolution the session actually got**, not the negotiated
+  one it was seeded with.
+
+### Workspace
+
+`crates/punktfunk-encode-worker` joins as a member (above). Two bring-your-own-hardware measurement
+tools are added and **excluded** in the root manifest, so `cargo build --workspace` and CI never see
+them: `tools/hid-descriptor-dump` (dumps and decodes a real HID report descriptor; pulls `hidapi`)
+and `tools/win-input-matrix` (asks each Windows input API what it can see — ⚠ `wake_wgi()` is not
+optional there: both WGI collections return a cache a console app has never started filling, so
+without subscribing first they come back empty with real controllers attached).
+
 ### Host and client environment variables
 
+- **`PUNKTFUNK_XBOX_BACKEND`** *(new, host, Windows)* — `hid` (the new **default**) or `xusb` (the
+  escape hatch). The HID pad is now a superset of the XUSB companion: it keeps classic XInput while
+  gaining Steam, SDL, RawInput, DirectInput, `joy.cpl` and WGI, plus rumble, which XUSB could not
+  source at all. The escape hatch stays because promotion leans on Microsoft's inbox
+  `xinputhid.inf`; if a servicing update changes it, one env var restores the old behaviour with no
+  reinstall. An unrecognised value takes the **default**, not the opt-out, so a typo cannot silently
+  drop a user onto the path with no HID collection.
+- **`PUNKTFUNK_GAMESCOPE_BIND`** *(new, host, Linux)* — unset = auto, `0` = never, `1` = force.
+  Governs whether the host binds the patched gamescope over the distribution's `/usr/bin/gamescope`
+  inside a session's mount namespace.
 - **`PUNKTFUNK_ENCODE_WORKER`** *(new, host, Linux)* — where to find the encode worker. Resolution
   order: this variable → alongside `/proc/self/exe` → `PATH`. `off` forces the in-process encoder,
   the debug escape hatch that makes the A/B a one-line change. Load-bearing on NixOS (above).

Cargo.lock

@@ -994,7 +994,7 @@ dependencies = [
 
 [[package]]
 name = "cursor-probe"
-version = "0.26.0"
+version = "0.27.0"
 dependencies = [
  "anyhow",
  "pf-capture",
@@ -1114,7 +1114,7 @@ dependencies = [
 
 [[package]]
 name = "display-disturb"
-version = "0.26.0"
+version = "0.27.0"
 dependencies = [
  "windows 0.62.2 (registry+https://github.com/rust-lang/crates.io-index)",
 ]
@@ -2358,7 +2358,7 @@ dependencies = [
 
 [[package]]
 name = "latency-probe"
-version = "0.26.0"
+version = "0.27.0"
 
 [[package]]
 name = "lazy_static"
@@ -2463,7 +2463,7 @@ dependencies = [
 
 [[package]]
 name = "libvpl-sys"
-version = "0.26.0"
+version = "0.27.0"
 dependencies = [
  "bindgen",
  "cmake",
@@ -2498,7 +2498,7 @@ checksum = "0ceec5bc11778974d1bcb055b18002eba7f4b3518b6a0081b3af5f21666da9ad"
 
 [[package]]
 name = "loss-harness"
-version = "0.26.0"
+version = "0.27.0"
 dependencies = [
  "punktfunk-core",
 ]
@@ -2988,7 +2988,7 @@ checksum = "9b4f627cb1b25917193a259e49bdad08f671f8d9708acfd5fe0a8c1455d87220"
 
 [[package]]
 name = "pf-bitstream"
-version = "0.26.0"
+version = "0.27.0"
 dependencies = [
  "cros-codecs",
  "tracing",
@@ -2996,7 +2996,7 @@ dependencies = [
 
 [[package]]
 name = "pf-capture"
-version = "0.26.0"
+version = "0.27.0"
 dependencies = [
  "anyhow",
  "ashpd",
@@ -3017,7 +3017,7 @@ dependencies = [
 
 [[package]]
 name = "pf-client-core"
-version = "0.26.0"
+version = "0.27.0"
 dependencies = [
  "anyhow",
  "ash",
@@ -3052,7 +3052,7 @@ dependencies = [
 
 [[package]]
 name = "pf-clipboard"
-version = "0.26.0"
+version = "0.27.0"
 dependencies = [
  "anyhow",
  "ashpd",
@@ -3070,7 +3070,7 @@ dependencies = [
 
 [[package]]
 name = "pf-console-ui"
-version = "0.26.0"
+version = "0.27.0"
 dependencies = [
  "anyhow",
  "ash",
@@ -3091,7 +3091,7 @@ dependencies = [
 
 [[package]]
 name = "pf-dxvadec"
-version = "0.26.0"
+version = "0.27.0"
 dependencies = [
  "cros-codecs",
  "pf-bitstream",
@@ -3101,7 +3101,7 @@ dependencies = [
 
 [[package]]
 name = "pf-encode"
-version = "0.26.0"
+version = "0.27.0"
 dependencies = [
  "anyhow",
  "ash",
@@ -3127,7 +3127,7 @@ dependencies = [
 
 [[package]]
 name = "pf-frame"
-version = "0.26.0"
+version = "0.27.0"
 dependencies = [
  "anyhow",
  "libc",
@@ -3139,7 +3139,7 @@ dependencies = [
 
 [[package]]
 name = "pf-gpu"
-version = "0.26.0"
+version = "0.27.0"
 dependencies = [
  "anyhow",
  "pf-host-config",
@@ -3153,11 +3153,11 @@ dependencies = [
 
 [[package]]
 name = "pf-host-config"
-version = "0.26.0"
+version = "0.27.0"
 
 [[package]]
 name = "pf-inject"
-version = "0.26.0"
+version = "0.27.0"
 dependencies = [
  "anyhow",
  "ashpd",
@@ -3186,14 +3186,14 @@ dependencies = [
 
 [[package]]
 name = "pf-paths"
-version = "0.26.0"
+version = "0.27.0"
 dependencies = [
  "tracing",
 ]
 
 [[package]]
 name = "pf-presenter"
-version = "0.26.0"
+version = "0.27.0"
 dependencies = [
  "anyhow",
  "ash",
@@ -3208,7 +3208,7 @@ dependencies = [
 
 [[package]]
 name = "pf-update"
-version = "0.26.0"
+version = "0.27.0"
 dependencies = [
  "serde",
  "serde_json",
@@ -3216,7 +3216,7 @@ dependencies = [
 
 [[package]]
 name = "pf-update-check"
-version = "0.26.0"
+version = "0.27.0"
 dependencies = [
  "anyhow",
  "base64",
@@ -3228,7 +3228,7 @@ dependencies = [
 
 [[package]]
 name = "pf-vaadec"
-version = "0.26.0"
+version = "0.27.0"
 dependencies = [
  "cros-codecs",
  "pf-bitstream",
@@ -3237,7 +3237,7 @@ dependencies = [
 
 [[package]]
 name = "pf-vdisplay"
-version = "0.26.0"
+version = "0.27.0"
 dependencies = [
  "anyhow",
  "ashpd",
@@ -3270,7 +3270,7 @@ dependencies = [
 
 [[package]]
 name = "pf-vkdecode"
-version = "0.26.0"
+version = "0.27.0"
 dependencies = [
  "ash",
  "cros-codecs",
@@ -3281,7 +3281,7 @@ dependencies = [
 
 [[package]]
 name = "pf-win-display"
-version = "0.26.0"
+version = "0.27.0"
 dependencies = [
  "anyhow",
  "pf-paths",
@@ -3293,7 +3293,7 @@ dependencies = [
 
 [[package]]
 name = "pf-zerocopy"
-version = "0.26.0"
+version = "0.27.0"
 dependencies = [
  "anyhow",
  "ash",
@@ -3516,7 +3516,7 @@ dependencies = [
 
 [[package]]
 name = "punktfunk-cli"
-version = "0.26.0"
+version = "0.27.0"
 dependencies = [
  "pf-client-core",
  "punktfunk-core",
@@ -3527,7 +3527,7 @@ dependencies = [
 
 [[package]]
 name = "punktfunk-client-android"
-version = "0.26.0"
+version = "0.27.0"
 dependencies = [
  "android_logger",
  "jni",
@@ -3545,7 +3545,7 @@ dependencies = [
 
 [[package]]
 name = "punktfunk-client-linux"
-version = "0.26.0"
+version = "0.27.0"
 dependencies = [
  "anyhow",
  "async-channel",
@@ -3562,7 +3562,7 @@ dependencies = [
 
 [[package]]
 name = "punktfunk-client-session"
-version = "0.26.0"
+version = "0.27.0"
 dependencies = [
  "anyhow",
  "pf-client-core",
@@ -3577,7 +3577,7 @@ dependencies = [
 
 [[package]]
 name = "punktfunk-client-windows"
-version = "0.26.0"
+version = "0.27.0"
 dependencies = [
  "async-channel",
  "mdns-sd",
@@ -3596,7 +3596,7 @@ dependencies = [
 
 [[package]]
 name = "punktfunk-core"
-version = "0.26.0"
+version = "0.27.0"
 dependencies = [
  "aes-gcm",
  "bytes",
@@ -3628,7 +3628,7 @@ dependencies = [
 
 [[package]]
 name = "punktfunk-encode-worker"
-version = "0.26.0"
+version = "0.27.0"
 dependencies = [
  "pf-encode",
  "tracing",
@@ -3637,7 +3637,7 @@ dependencies = [
 
 [[package]]
 name = "punktfunk-host"
-version = "0.26.0"
+version = "0.27.0"
 dependencies = [
  "aes",
  "aes-gcm",
@@ -3722,7 +3722,7 @@ dependencies = [
 
 [[package]]
 name = "punktfunk-probe"
-version = "0.26.0"
+version = "0.27.0"
 dependencies = [
  "anyhow",
  "mdns-sd",
@@ -3736,7 +3736,7 @@ dependencies = [
 
 [[package]]
 name = "punktfunk-tray"
-version = "0.26.0"
+version = "0.27.0"
 dependencies = [
  "anyhow",
  "ksni",
@@ -3759,7 +3759,7 @@ checksum = "d55d956fa96f5ec02be2e13af0e20391a5aa83d6a074e3ad368959d0fab299ea"
 
 [[package]]
 name = "pyrowave-sys"
-version = "0.26.0"
+version = "0.27.0"
 dependencies = [
  "bindgen",
  "cmake",

Cargo.toml

@@ -65,7 +65,7 @@ exclude = [
 ndk = { path = "clients/android/native/vendor/ndk" }
 
 [workspace.package]
-version = "0.26.0"
+version = "0.27.0"
 edition = "2021"
 rust-version = "1.82"
 license = "MIT OR Apache-2.0"

docs-site/content/docs/running-as-a-service.md

@@ -249,9 +249,11 @@ KWin virtual output failed: KWin does not expose zkde_screencast_unstable_v1 to
 ```
 
 which reads exactly like a missing or mis-installed `.desktop` file and survives reinstalling both
-ends. Version 0.26.0-1 granted the host the capability for the reason above and shipped precisely
-this, on every Linux channel; 0.26.0-2 revoked it everywhere. If you ever see that error, check the
-binaries before anything else — the host's own message names the capability when it finds one:
+ends. The first 0.26.0 packages granted the host the capability for the reason above and shipped
+precisely this, on every Linux channel; the grant was revoked everywhere later the same day, and
+0.27.0 is the first release whose version number carries that revocation to a machine that already
+installed one of them. If you ever see that error, check the binaries before anything else — the
+host's own message names the capability when it finds one:
 
 ```sh
 getcap /usr/bin/punktfunk-host              # correct output is nothing at all

docs/releases/v0.27.0.md

@@ -1,28 +1,74 @@
-<!--
-  Accumulating ahead of the version bump, per docs/releases/README.md: entries are added as work
-  lands, and the lead-in, the TL;DR and any "Before you update" section are written at the bump,
-  when the shape of the whole release is known. The angle-bracket lines below are the TEMPLATE.md
-  placeholders and must be replaced before the tag is pushed. docs/releases/whatsnew/v0.27.0.txt is
-  still owed and is a hard gate on the android job.
--->
+Wire-compatible with 0.26.x — everything you have already paired keeps working, and you can update one side at a time. Nothing here changes how a host and a client agree on what to send each other, so an old client on a new host, or the other way round, streams exactly as it does today.
 
-Wire-compatible with 0.26.x — everything you have already paired keeps working, and you can update one side at a time. <one sentence on how older/newer clients negotiate or fall back, so nobody fears updating.>
-
-<Lead-in: one or two sentences naming the headline change of this release — everything above the first `##` is what the Discord #releases embed shows, so make it read as a standalone summary.>
+This release does three things. Streaming performance on Linux finally gets the graphics-card priority it has been asking for since 0.25, without the privilege that broke KDE. An Xbox controller on a Windows host becomes a real controller that games can actually see, with rumble for the first time. And the controller interface on iPad, Apple TV and Mac becomes something you can drive end to end with a controller in your hands — including pairing, which used to be a dead end. Alongside all of it, everything 0.26.0 got wrong in the field is repaired.
 
 ## TL;DR
 
-- **<The one thing you would tell someone in a sentence.>**
-- **<Second. Anything that needs the reader to ACT goes here too, and in `## Before you update`.>**
-- **<Third. Three to six bullets, one line each. This is what a reader sees instead of giving up.>**
+- **The wavelet codec can ask your graphics card for priority again**, on every Linux desktop, with the privilege moved to a small separate program so the host never holds one. Worth about a third off the worst frames under a demanding game. Nothing to switch on.
+- **An Xbox controller on a Windows host was invisible to games** — not Steam, not the Windows controller panel, not most modern titles. It is a real controller now, and it rumbles. Update the host.
+- **HDR streams from an NVIDIA host had red and blue swapped.** Every one of them, on every client. Update the host.
+- **A gamescope session crashed on essentially every connect**, black screen, until the machine gave up and came back on the unpatched compositor. Update the host.
+- **On NixOS the host could not detect a running desktop at all**, so streaming a desktop never worked. Update the host.
+- **You can now pair, trust a host and answer every prompt with a controller** on iPad, Apple TV and Mac — and drive the whole interface from a keyboard. Update the client.
+
+## Before you update
+
+Most people need to do nothing. Check this list if any of it applies to you.
+
+- **Any Linux host you installed on 9 August:** the very first 0.26.0 packages gave the host a system privilege that stops KDE recognising it, and desktop streaming failed outright as a result. Corrected packages went out the same day under the *same* version number, so a machine that installed an early one was never offered the fix. This release carries a new version number and therefore actually reaches it. If you are unsure, `getcap /usr/bin/punktfunk-host` should print nothing at all.
+- **Never grant that privilege to the host yourself.** Not by hand, not through a service file, not through a NixOS wrapper. The small helper program beside it is the thing that needs one, and your packages already gave it one.
+- **Fedora or Nobara, if the patched compositor refused to install:** `punktfunk-gamescope` was never signed, so installing it failed on every Fedora and Nobara machine even though the package was sitting right there in the repository. It is signed now. Install it again.
+- **Fedora or Nobara, if every connect gives you a black screen:** Game Mode needs your user to be in the `punktfunk` group, and nothing said so — the host blamed a missing permission rule instead, and neither remedy it suggested added anyone to a group. Run `sudo usermod -aG punktfunk "$USER"` and log back in. The host now checks this at startup and tells you plainly.
+- **Bazzite, if 0.26.0 seemed to change nothing:** the system-extension upgrade is driven by the *old* release's script, so a step added in 0.26.0 was executed by nobody, and every check afterwards reported there was nothing to do. Among the casualties was that same `punktfunk` group. Run `sudo punktfunk-sysext update`, or `sudo punktfunk-sysext reapply` to re-run those steps without reinstalling the image.
+- **NixOS:** the plugin runner now starts by default, matching every other packaging. If you do not want it, set `scripting.autoStart = false`.
+- **Windows, if you stream with an Xbox controller:** the new controller is the default now. Nothing to do, but if a title behaves oddly with it, `PUNKTFUNK_XBOX_BACKEND=xusb` restores the old one without reinstalling anything.
+
+## New
+
+- **An Xbox controller on a Windows host is a real controller.** Until now it existed only as a companion device, visible to the oldest of Windows' controller interfaces and to nothing else — so Steam, the Windows game controller panel and everything a modern title actually uses could not see it at all. One report spent two weeks on a controller that was, from every angle that mattered, simply absent. It is now built as genuine hardware and promoted by Windows exactly as a real Xbox pad is, so everything that can see a controller sees this one.
+- **That controller rumbles.** It never had rumble of any kind — nothing was listening for it. Games now drive it through the ordinary Windows path.
+- **Three Xbox models to choose from:** Xbox Wireless Controller, Xbox Wireless Controller (One S), and Xbox Elite Wireless Controller Series 2, so glyphs and the name a game shows match what you picked. The Elite is reachable by setting it explicitly; no client offers it in a menu yet, and its four paddles are not wired up.
+- **Pairing you can do with a controller.** On iPhone, iPad and Mac the pairing sheet is a form with text fields, which a controller cannot reach, type into, or submit — so for anyone using the controller interface, the one thing standing between a fresh install and a first stream was a dead end. It is fully pad-driven now. The trust prompt that appears mid-connect takes controller input too, and so do the alerts and confirmations along the way, which were all dead ends for the same reason.
+- **Drive the interface from a keyboard.** Asked for by an iPad user on a Magic Keyboard: arrow keys move, Return launches. A couch Mac gets the same.
+- **A Shortcut or a home-screen widget can jump straight into a host's library** on Apple devices, landing in whichever view the current mode uses.
+- **The controls legend is clickable.** Every hint that names an action is a real button on iPhone, iPad and Mac, so an iPad on a stand or a Mac driven by trackpad can use the interface it was reading.
 
 ## Improved
 
 - **The wavelet codec can ask your graphics card for priority again — on every desktop this time.** Under a demanding game it encodes on the same graphics cores the game is using and gets crowded out, and asking the driver to put that work first is worth about a third off the worst frames. It needs a system privilege, and 0.26 could not use it: an interim build gave that privilege to the host, KDE stopped recognising the host as a result, and desktop streaming failed outright — so the privilege was taken away everywhere and the switch sat dormant. The encoding now happens in a small separate program installed alongside the host, and the privilege is granted to **that** program rather than to the host. The host still holds nothing at all, so KDE keeps recognising it, and the priority request works on KDE, GNOME, gamescope and everything else alike. Nothing to switch on. There is also nothing to grant by hand — in particular, do not give the host that privilege yourself, which is still the one thing that takes KDE desktop streaming away. Linux hosts, wavelet-codec sessions only.
 - **A host that cannot start that helper simply carries on.** If the program is missing, refuses to start, is a mismatched version, or stops mid-session, the host does the encoding itself exactly as it did before, notes one line in the log, and the stream keeps running. The same is true if the privilege was never granted: the request is refused, the encoding runs at normal priority, and the only cost is frame pacing under a game that is already saturating the graphics card.
+- **The controller interface is sized for an iPad.** It had two sizes — Apple TV, and everything else — so a 13" iPad Pro drew its rows, tabs and legend at phone scale across a very large display. There is a size between them now, and the controls pill sits in the display's corner instead of floating well above it.
+- **The interface remembers which controller is yours.** The button hints read the live controller, so the moment a DualSense slept or ran flat every ✕/◯ turned into A/B under its owner's hands. They now stay as the pad you actually own.
+- **The OLED palette is called Eclipse.** Every other background is named for a place or a material, and "OLED" was a spec sheet sitting among them.
+- **When Game Mode cannot take over the screen, the host says exactly why.** It used to discard the one message that explained it and guess instead, naming a permission rule that was installed and working, and offering two remedies that could not have helped. The real reason now comes through word for word, and a startup check raises it before you are mid-stream rather than during one.
+- **The console is on the current design system**, and card spacing is fixed at the root rather than worked around in seven places. Dropdowns were the visible casualty of the old one: a near-white border and focus ring, with a chevron and placeholder text so dark they all but disappeared.
+- **The Virtual displays page has tabs** — Configuration and Live displays. The configuration card alone is taller than most screens, so the list of live displays was in practice off the bottom of the page.
+
+## Fixed
+
+- **A gamescope session crashed on essentially every connect.** Eleven crashes in three minutes on the machine that surfaced it, until the session supervisor ran out of retries and brought the box up on the unpatched compositor instead — so the visible symptom was a black screen, and then a machine quietly running something other than what you installed.
+- **Streaming a desktop never worked on NixOS.** The host works out whether a desktop is running by asking the system what each program is called, and on NixOS essentially every graphical program is wrapped, so the name it gets back is the wrapper's — which matched nothing. Every check answered "no desktop here" on a perfectly ordinary running desktop, and nothing downstream could recover: naming your compositor explicitly turned the miss into a hard error instead. Sway and river escaped by accident.
+- **Every HDR stream from an NVIDIA host had red and blue swapped.** The compositor writes those pixels in its own order on NVIDIA hardware while labelling them with the ordinary one, so the host believed a label that was correct at every step while the contents underneath it were reversed — which is why this survived a full trace of both ends. Confirmed against two unrelated clients, so it was never a client fault. Ordinary streams were never affected.
+- **Game Mode could never start on Fedora and Nobara.** Nobara's session script names the system compositor outright and ignores every way we have of pointing it somewhere else, so it ran the unpatched one and the host refused it. Once that was solved a second fault appeared behind it: the graphics layer shipped with the distribution speaks a different dialect to the compositor we ship, and it was killing every graphical program before anything could draw, so Steam never appeared. Black screen, no error. Both are handled, and the machine can no longer end up dumped on the plain desktop with a leftover setting that also breaks the next boot.
+- **Taking over the screen barred the way back into Game Mode.** The takeover switches off the machine's own session supervisor so it cannot restart underneath the stream, and only switched it back on when the client disconnected — so for the whole stream the button the user was most likely to press did nothing.
+- **Connecting to a host paused your music, and resuming it silenced the stream.** The audio session was claiming exclusive use, so it evicted whatever was playing on connect, and handing it back later left the stream mute for good. Both halves were the same defect.
+- **Changing your audio device mid-stream killed the sound on a Mac.** Starting a stream with AirPods in and taking them out gave you nothing on the speakers; putting them back in gave you nothing in the AirPods either, and only restarting the whole stream brought it back. The audio engine stops itself when the hardware underneath it changes and nothing was starting it again. It now rebuilds on whatever device is there, including when the microphone and echo cancellation are on, which is the default on a Mac.
+- **The library's hide button was invisible and clickable at the same time.** Hiding a title shipped in 0.26.0 and was in practice unusable: the operator reported there was no button, then found it by clicking the empty corner of a poster — which meant anyone could drop a game from their library by accident and never know how.
+- **One failure to start the video encoder could take down every session on the machine**, not just the one that failed. Separately, the check that asks whether your card can encode 10-bit was itself enough to wedge every later attempt on an NVIDIA host using the direct path.
+- **`punktfunk-gamescope` could not be installed on Fedora or Nobara.** Every copy ever published was unsigned, and the repository we tell you to add requires signatures — so it failed on every machine while both the release notes and the documentation said it was available.
+- **Uninstalling on Windows left its audio devices behind forever.** "Punktfunk Speakers", "Punktfunk Microphone" and a per-controller entry stayed in your sound settings after the host was gone, because they are created while it runs rather than installed. Uninstalling now takes them with it, restores whatever playback device you had before if a stream left it switched, and matches only its own — Steam's identically named devices are untouched.
+- **A Bazzite system-extension update could report success and change nothing.** Because the old release's script drives the upgrade, a step added in a new release is run by nobody, and every check afterwards said there was nothing to do. That is why 0.26.0 quietly failed to create the group Game Mode needs. Those steps are re-run now, and a `reapply` command re-applies them on demand.
+- **The console reported the resolution the client asked for, not the one it got.** When the two differ — and they do, whenever a mode is adjusted on the way up — the number on screen was the request rather than the result.
+- **The controller interface's cards flashed once as they settled**, sat at the wrong fill for the whole entrance, and the selected settings tab was white on light grey in one palette.
+- **A controller that could not be created blamed the drivers.** When a live stream already held that controller slot — which is entirely legitimate — the host told you to reinstall or repair the drivers, which was never the problem and never helped. It now names what is actually holding the slot.
+- **On NixOS three service settings had quietly diverged** from the ones every other packaging ships, including one that could leave the web console permanently stopped if it was enabled before the host's first run.
 
 ## For developers
 
-Protocol, ABI, driver and add-on detail — including the version table and any breaking changes — is in [CHANGELOG.md](https://git.unom.io/unom/punktfunk/src/tag/v0.27.0/CHANGELOG.md).
+Protocol, ABI, driver and add-on detail — the version table, the new environment variables and what did *not* move — is in [CHANGELOG.md](https://git.unom.io/unom/punktfunk/src/tag/v0.27.0/CHANGELOG.md).
+
+The short version: **nothing breaks.** The wire protocol stays at 2. The C ABI moves 17 → 18, and it moves by *addition* — one new entry point for four-motor rumble, alongside the existing one, which keeps its signature and the values it reports. An embedder that ignores the new symbol behaves exactly as it does today.
 
 If you package Punktfunk, one thing changes shape: there is a second installed binary, `punktfunk-encode-worker`, and it is the **only** file that may carry `cap_sys_nice=ep`. It must stay a separate file — never a hardlink to `punktfunk-host`, never a subcommand of it — because a shared inode shares the file capability and re-creates the KDE breakage. `punktfunk-host` carries no capability, on any channel, ever.
+
+The shared virtual-display and gamepad definitions have also changed for the first time in three releases: three new Xbox controller identities, all additive.

docs/releases/whatsnew/v0.27.0.txt

@@ -0,0 +1,2 @@
+• The OLED colour scheme is called Eclipse now — the same black-with-a-violet-ember palette, under a name that belongs beside Nebula and Abyss. Your saved choice carries over.
+• The rest of this release is on the computer you stream from. Once it updates: HDR streams from an NVIDIA machine no longer have red and blue swapped, and Linux hosts hold their frame rate far better under a demanding game.