Merge pull request 'Every NVIDIA gamescope HDR stream had red and blue swapped — and a sysext step added in a release was unreachable forever' (#143) from worktree-hdr-rb-swap-nvidia into main

Reviewed-on: #143

.gitea/workflows/deb.yml

@@ -344,10 +344,45 @@ jobs:
           apt-get update
           apt-get install -y --no-install-recommends meson ninja-build glslc git || true
           apt-get build-dep -y gamescope || true
+          # NOT best-effort. `build-dep gamescope` resolves the distro's much older packaged
+          # gamescope — where noble has one at all — so it misses what the master tree needs, and
+          # wayland-protocols is the gap that actually stops the build: meson dies in
+          # protocol/meson.build with "Neither a subproject directory nor a wayland-protocols.wrap
+          # file was found", because the tree has no wrap fallback for it. That is what happened on
+          # the v0.26.0 tag: the step warned and skipped, the job stayed green, and the release
+          # shipped with no gamescope .deb while the notes said it had one.
+          apt-get install -y --no-install-recommends wayland-protocols
+          # The remaining Arch makedepends the older packaged gamescope does not necessarily pull.
+          # Best-effort: meson falls back or does without, and a name that moves between Ubuntu
+          # releases should not fail the job. (No libstdc++ static package is needed here — g++
+          # ships libstdc++.a, which is why only Fedora tripped the sanity check.)
+          # `build-dep gamescope` gives noble almost nothing — the distro has no comparable package
+          # — so the tree's real dependency set has to be named outright. One `apt-get` per name on
+          # purpose: a single transaction aborts wholesale on one unknown package, which would
+          # install NOTHING and hide the real gap behind a name typo. Best-effort per package, with
+          # the missing one named; the end-of-job gate below is what actually decides.
+          for p in libxdamage-dev libxcomposite-dev libxrender-dev libxext-dev libxxf86vm-dev \
+                   libxtst-dev libx11-dev libxres-dev libxmu-dev libxcursor-dev libxi-dev \
+                   libxfixes-dev libxkbcommon-dev libxkbcommon-x11-dev libcap-dev libdrm-dev \
+                   libinput-dev libudev-dev libpipewire-0.3-dev libseat-dev libsdl2-dev \
+                   libluajit-5.1-dev libavif-dev libdecor-0-dev hwdata libglm-dev libbenchmark-dev \
+                   glslang-tools libvulkan-dev libwayland-dev libxcb1-dev libxcb-composite0-dev \
+                   libxcb-xfixes0-dev libxcb-res0-dev libxcb-ewmh-dev libxcb-icccm4-dev \
+                   libxcb-errors-dev libpixman-1-dev libdisplay-info-dev libgbm-dev libegl-dev \
+                   cmake xwayland; do
+            apt-get install -y --no-install-recommends "$p" \
+              || echo "::warning::no such noble package: $p (gamescope may still build without it)"
+          done
           if bash packaging/gamescope/build-punktfunk-gamescope.sh \
                --destdir "$PWD/gs-stage" --prefix /usr --jobs "$(nproc)"; then
             install -Dm0755 gs-stage/usr/bin/punktfunk-gamescope gs-cache/punktfunk-gamescope
           else
+            # Warn only, even on a tag. The hard gate moved to the END of this job: failing HERE
+            # skips the host .deb's own publish + release-attach steps below, which is how the
+            # v0.26.0 release ended up still carrying the pre-CAP_SYS_NICE host .deb from an
+            # earlier tag commit — a KDE-breaking artifact withheld from replacement by a gate
+            # meant to protect the release. Never let a missing EXTRA stop a good artifact
+            # shipping; go red afterwards instead.
             echo "::warning::punktfunk-gamescope failed to build on noble — no .deb this run (gamescope sessions stay SDR)"
           fi
 
@@ -357,6 +392,7 @@ jobs:
           if [ -x gs-cache/punktfunk-gamescope ] && gs-cache/punktfunk-gamescope --version >/dev/null 2>&1; then
             bash packaging/debian/build-gamescope-deb.sh --binary gs-cache/punktfunk-gamescope
           else
+            # Warn only — see the note on the build step. The gate is the last step of this job.
             echo "::warning::no usable punktfunk-gamescope — skipping its .deb"
           fi
 
@@ -387,6 +423,26 @@ jobs:
             upsert_asset "$RID" "$DEB"
           done
 
+      # A release must not be able to make a claim its own CI silently dropped: v0.26.0's notes and
+      # docs-site said the patched gamescope was apt-installable while no .deb had ever been built,
+      # because every failure on this path was a `::warning::` that returned 0.
+      #
+      # ⚠ LAST step on purpose. The first version of this gate failed at the build step instead, and
+      # that skipped the host .deb's own publish + attach below — so the release kept the PREVIOUS
+      # tag commit's host .deb, which still carried the CAP_SYS_NICE postinst that breaks KDE. A
+      # gate protecting the release withheld the fix for it. Everything good ships first; the job
+      # goes red afterwards.
+      - name: A stable tag must ship the gamescope .deb
+        if: startsWith(gitea.ref, 'refs/tags/v')
+        run: |
+          shopt -s nullglob
+          built=(dist/punktfunk-gamescope_*.deb)
+          if [ ${#built[@]} -eq 0 ]; then
+            echo "::error::no punktfunk-gamescope .deb was built — a stable tag must not ship without it (the release notes and docs-site say it is apt-installable). Everything else in this job published normally; see the gamescope build step above for the meson error."
+            exit 1
+          fi
+          echo "gamescope .deb present: ${built[*]}"
+
   # ---------------------------------------------------------------------------------------------
   # The aarch64 CLIENT .deb. Cross-compiled on the ordinary amd64 runner in the
   # punktfunk-rust-ci-arm64cross image (the rust-ci toolchain + an arm64 multiarch sysroot — see

.gitea/workflows/rpm.yml

@@ -206,10 +206,26 @@ jobs:
           dnf -y install dnf-plugins-core meson ninja-build glslc || true
           dnf builddep -y gamescope || true
           dnf -y install xorg-x11-server-Xwayland-devel || true
+          # NOT best-effort: build-punktfunk-gamescope.sh appends `-static-libstdc++` to LDFLAGS
+          # (so the binary still starts on SteamOS's older libstdc++ — see its comment), and
+          # without the static library meson's very FIRST sanity check dies with
+          # "cannot find -lstdc++ / have you installed the static version", so nothing builds at
+          # all. That is what happened on the v0.26.0 tag: both Fedora bases warned and skipped,
+          # the job stayed green, and the release shipped with no gamescope RPM while the notes
+          # said it had one. A rename here must be LOUD, hence no `|| true`.
+          dnf -y install libstdc++-static
+          # The rest of the Arch package's makedepends that Fedora's older packaged gamescope does
+          # not necessarily pull. Best-effort: unlike the static runtime, meson finds fallbacks or
+          # does without, and a name that moves between Fedora releases should not fail the job.
+          dnf -y install wayland-protocols-devel glm-devel cmake libXcursor-devel || true
           if bash packaging/gamescope/build-punktfunk-gamescope.sh \
                --destdir "$PWD/gs-stage" --prefix /usr --jobs "$(nproc)"; then
             install -Dm0755 gs-stage/usr/bin/punktfunk-gamescope gs-cache/punktfunk-gamescope
           else
+            # Warn only, even on a tag — the hard gate is the LAST step of this job. Failing here
+            # would skip the sysext build, the sysext feed, AND the release attach below, so a
+            # missing gamescope would also withhold the punktfunk RPMs and the .raw images that
+            # built perfectly well. deb.yml learned that the expensive way on v0.26.0.
             echo "::warning::punktfunk-gamescope failed to build for f${{ matrix.fedver }} — the sysext ships without it (gamescope sessions stay SDR)"
           fi
 
@@ -227,6 +243,7 @@ jobs:
               --binary gs-cache/punktfunk-gamescope \
               --release "$PF_RELEASE"
           else
+            # Warn only — see the note on the build step. The gate is the last step of this job.
             echo "::warning::no usable punktfunk-gamescope for f${{ matrix.fedver }} — skipping its RPM"
           fi
 
@@ -310,3 +327,26 @@ jobs:
           for raw in dist-sysext/*.raw; do
             upsert_asset "$RID" "$raw" "$(basename "$raw" .raw).f${{ matrix.fedver }}.raw"
           done
+
+      # A release must not be able to make a claim its own CI silently dropped — v0.26.0's notes
+      # said the patched gamescope was dnf-installable while both Fedora bases had skipped it on a
+      # `::warning::` (missing libstdc++-static, which the -static-libstdc++ link needs).
+      #
+      # ⚠ LAST step on purpose, matching deb.yml: failing at the build step instead would skip the
+      # sysext image, the feed publish AND the attach above, withholding the punktfunk RPMs and
+      # .raw images that built perfectly well. Everything good ships first; the job goes red after.
+      - name: A stable tag must ship the gamescope RPM
+        if: startsWith(gitea.ref, 'refs/tags/v')
+        run: |
+          shopt -s nullglob
+          built=(dist/punktfunk-gamescope-*.rpm)
+          keep=()
+          for r in "${built[@]}"; do
+            case "$r" in *debuginfo*|*debugsource*) continue;; esac
+            keep+=("$r")
+          done
+          if [ ${#keep[@]} -eq 0 ]; then
+            echo "::error::no punktfunk-gamescope RPM was built for f${{ matrix.fedver }} — a stable tag must not ship without it (the release notes and docs-site say it is installable). Everything else in this job published normally; see the gamescope build step above for the meson error."
+            exit 1
+          fi
+          echo "gamescope RPM present: ${keep[*]}"

CHANGELOG.md

@@ -14,7 +14,7 @@ with the version table of the release you are moving to, then read **Breaking ch
 
 ## v0.26.0
 
-47 commits since v0.25.0.
+52 commits since v0.25.0.
 
 ### Versions
 
@@ -290,7 +290,19 @@ same shader cores a game saturates; NVENC is immune because it has its own ASIC.
   ladder REALTIME → HIGH → no-priority, stepping only on refusal; a refused class can never fail the
   open. The extension probe reuses the `dev_ext_props` already fetched for `queue_family_foreign` and
   takes KHR or the EXT alias — the same spelling pf-zerocopy probes, so the two cannot disagree.
-  ⭐ **Needs `CAP_SYS_NICE`**, which the packaging now grants; without it the lever does nothing.
+  ⭐ **Needs `CAP_SYS_NICE`**, which the packaging granted in `0.26.0-1`; without it the lever does
+  nothing.
+  🛑 **Corrected in `0.26.0-2`: the packaging no longer grants it, and must not.** Every channel that
+  did (Arch `.install`, RPM `%caps()`, the Bazzite sysext image, the deb postinst, the NixOS
+  `security.wrappers` entry) broke desktop streaming on KDE outright — field-reported on CachyOS and
+  Bazzite as `KWin does not expose zkde_screencast_unstable_v1 to this client`. KWin identifies a
+  client by resolving its `/proc/<pid>/exe` against an installed `.desktop`, and the kernel refuses
+  that readlink to any reader whose effective set is not a superset of the target's **permitted**
+  set (`cap_ptrace_access_check`) — KWin has no capabilities, so a capability-carrying host is
+  unidentifiable and the restricted globals are never advertised. Neither `prctl(PR_SET_DUMPABLE, 1)`
+  nor systemd `AmbientCapabilities=` rescues it; only an uncapped process is identifiable. The lever
+  therefore stays wired but unexercised on a stock install (the ladder degrades to default priority),
+  and is opt-in for gamescope-only hosts, which have no such identity check.
 - **PW5 — two encoder handles.** `Encoder::Impl` owns exactly one each of `wavelet_img_high_res`,
   `bucket_buffer`, `meta_buffer`, `block_stat_buffer`, `payload_data`, `quant_buffer`, and
   `Impl::encode` *opens* by discarding them (an image barrier with `VK_IMAGE_LAYOUT_UNDEFINED` as the
@@ -414,7 +426,9 @@ emulator itself would land it outside both.
 
 ⏳ **Owed on glass:** iPhone + Bluetooth listen, Apple TV stats overlay, MacBook audio listen, the
 Deck HEVC/4:4:4 retest, a Windows wake-from-sleep cycle, and the PyroWave-under-game-load A/B on a
-Linux host with `CAP_SYS_NICE` actually granted — the number this whole wave is aimed at.
+Linux host with `CAP_SYS_NICE` actually granted — the number this whole wave is aimed at. ⚠ That
+last one now needs a **gamescope-only** host, or a hand-granted capability on a box you are not
+streaming the KDE desktop from: see the `0.26.0-2` correction under PW1 above.
 
 ---
 

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

@@ -0,0 +1,129 @@
+// "The audio output moved under us" — the one signal `SessionAudio` needs to survive a device
+// change, and the one piece of it that can be tested without a stream.
+//
+// Split out of SessionAudio deliberately. An end-to-end test of the recovery needs a live session,
+// which needs a host, and punktfunk-host does not build on macOS — so the wiring that matters most
+// (is the observer actually installed? does the identity check let the notification through?) would
+// otherwise ship unverified, and a silent failure in it costs the session ALL of its audio. On its
+// own this can be pointed at the real hardware from a unit test: see AudioDeviceWatcherTests.
+//
+// What it does NOT own: anything with session semantics. The iOS route-change steer and the
+// media-services-reset re-activation stay in SessionAudio, next to the AVAudioSession they act on.
+
+import AVFoundation
+import os
+#if os(macOS)
+import CoreAudio
+#endif
+
+private let log = Logger(subsystem: "io.unom.punktfunk", category: "audio")
+
+final class AudioDeviceWatcher {
+    /// Why the owner is being told. Only for the log line — every reason leads to the same
+    /// question, "is playback still on the device it should be on".
+    enum Reason: String {
+        /// An engine stopped itself because its IO hardware changed underneath it.
+        case engineConfiguration = "the audio hardware configuration changed"
+        /// The system's default output device moved (macOS).
+        case defaultOutputDevice = "the default output device changed"
+    }
+
+    /// Does this configuration change belong to an engine the session still owns? A retired engine
+    /// posts one last change as it is torn down, and other AVAudioEngines in the process are not
+    /// ours to restart.
+    private let isOurs: (AnyObject?) -> Bool
+    /// Delivered on the main queue.
+    private let onChange: (Reason) -> Void
+
+    private let lock = NSLock()
+    private var configObserver: NSObjectProtocol?
+    #if os(macOS)
+    private var defaultOutputListener: AudioObjectPropertyListenerBlock?
+    #endif
+
+    init(isOurs: @escaping (AnyObject?) -> Bool, onChange: @escaping (Reason) -> Void) {
+        self.isOurs = isOurs
+        self.onChange = onChange
+    }
+
+    deinit { stop() }
+
+    /// Idempotent.
+    func start() {
+        lock.lock()
+        let already = configObserver != nil
+        lock.unlock()
+        guard !already else { return }
+
+        let token = NotificationCenter.default.addObserver(
+            forName: .AVAudioEngineConfigurationChange, object: nil, queue: nil
+        ) { [weak self] note in
+            // Posted from whatever thread the IO unit noticed on. The engine is the notification's
+            // object; it is only ever compared by identity, never resurrected.
+            let posted = note.object as AnyObject?
+            DispatchQueue.main.async {
+                guard let self, self.isOurs(posted) else { return }
+                self.onChange(.engineConfiguration)
+            }
+        }
+        lock.lock()
+        configObserver = token
+        lock.unlock()
+
+        #if os(macOS)
+        // The engine notification is the direct signal, but it is delivered BY an engine — useless
+        // in the two places it is needed most: after a rebuild that could not start (no engine left
+        // to notify anyone) and on an engine topology whose notification behaviour is unverified
+        // (the voice-processing engine, which is the DEFAULT macOS configuration and which no Mac
+        // here can even initialize). The HAL is told either way.
+        let block: AudioObjectPropertyListenerBlock = { [weak self] _, _ in
+            self?.onChange(.defaultOutputDevice) // on the main queue — registered against it below
+        }
+        var address = Self.defaultOutputAddress()
+        let status = AudioObjectAddPropertyListenerBlock(
+            AudioObjectID(kAudioObjectSystemObject), &address, DispatchQueue.main, block)
+        guard status == noErr else {
+            log.warning("""
+                could not watch the default output device (\(status)) — an output device change \
+                mid-stream may need a reconnect
+                """)
+            return
+        }
+        lock.lock()
+        defaultOutputListener = block
+        lock.unlock()
+        #endif
+    }
+
+    /// Idempotent, and safe from any thread. After it returns, no further `onChange` is delivered
+    /// except one already in flight on the main queue — which the owner's own stopped-flag catches.
+    func stop() {
+        lock.lock()
+        let token = configObserver
+        configObserver = nil
+        #if os(macOS)
+        let listener = defaultOutputListener
+        defaultOutputListener = nil
+        #endif
+        lock.unlock()
+        if let token { NotificationCenter.default.removeObserver(token) }
+        #if os(macOS)
+        guard let listener else { return }
+        var address = Self.defaultOutputAddress()
+        AudioObjectRemovePropertyListenerBlock(
+            AudioObjectID(kAudioObjectSystemObject), &address, DispatchQueue.main, listener)
+        #endif
+    }
+
+    #if os(macOS)
+    /// Freshly built per call rather than held in a mutable static: the HAL takes the address
+    /// `inout` and copies it, so there is nothing to share and a shared one would only be a
+    /// mutable global.
+    private static func defaultOutputAddress() -> AudioObjectPropertyAddress {
+        AudioObjectPropertyAddress(
+            mSelector: kAudioHardwarePropertyDefaultOutputDevice,
+            mScope: kAudioObjectPropertyScopeGlobal,
+            mElement: kAudioObjectPropertyElementMain)
+    }
+    #endif
+}

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

@@ -43,8 +43,21 @@ public enum AudioDevices {
     }
 
     private static func defaultInputDevice() -> AudioDeviceID? {
+        systemDevice(kAudioHardwarePropertyDefaultInputDevice)
+    }
+
+    /// The device the system is currently playing to — what an engine with no pinned speaker UID
+    /// follows, and so what `SessionAudio` compares its live output device against when the
+    /// default moves (AirPods in or out, a headset unplugged).
+    static func defaultOutputDevice() -> AudioDeviceID? {
+        systemDevice(kAudioHardwarePropertyDefaultOutputDevice)
+    }
+
+    private static func systemDevice(
+        _ selector: AudioObjectPropertySelector
+    ) -> AudioDeviceID? {
         var address = AudioObjectPropertyAddress(
-            mSelector: kAudioHardwarePropertyDefaultInputDevice,
+            mSelector: selector,
             mScope: kAudioObjectPropertyScopeGlobal,
             mElement: kAudioObjectPropertyElementMain)
         var dev = AudioDeviceID(0)

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

@@ -21,6 +21,10 @@
 //
 // Devices are chosen by UID ("" = system default: the engine is then never pinned to a
 // concrete device and follows default-device changes).
+//
+// Surviving the hardware. An AVAudioEngine does NOT follow the audio hardware: when the output
+// device changes underneath a running engine, the engine stops itself and stays stopped. The
+// session therefore watches for that and rebuilds its engines — see "Device changes" below.
 
 import AVFoundation
 import os
@@ -79,14 +83,49 @@ public final class SessionAudio {
     /// session's activate.
     private static let sessionQueue = DispatchQueue(label: "io.unom.punktfunk.audio.session")
     #endif
-    #if os(iOS)
+    #if !os(macOS)
-    /// Live only for a `.playAndRecord` session: the token for the route-change observer that
+    /// Token for the route-change observer: it revives an engine the route change stopped, and on
-    /// keeps the BUILT-IN output on the speaker rather than the earpiece (see
+    /// iOS re-applies the earpiece steer (see `installRouteObserver`). Guarded by `stateLock`.
-    /// `steerBuiltInOutputToSpeaker`). A `.playback` session already prefers the speaker and
-    /// never needs steering, so the mic-off path installs nothing. Guarded by `stateLock`.
     private var routeObserver: NSObjectProtocol?
+    /// Token for the media-services-reset observer — the audio server restarting takes the
+    /// session's configuration and every engine with it. Guarded by `stateLock`.
+    private var mediaResetObserver: NSObjectProtocol?
     #endif
 
+    // MARK: - Device changes (see `installDeviceChangeRecovery`)
+
+    /// What `start()` was asked for, so a rebuild can put back the SAME topology the session was
+    /// started with. Main-thread confined, like the start paths that read it.
+    private var startConfig: StartConfig?
+    private struct StartConfig {
+        let speakerUID: String
+        let micUID: String
+        let micChannel: Int
+        let micEnabled: Bool
+        let echoCancel: Bool
+    }
+    /// Watches the hardware for us (see `AudioDeviceWatcher`). Guarded by `stateLock`.
+    private var deviceWatcher: AudioDeviceWatcher?
+    /// Whether the engines have been built at least once. Distinguishes "not started yet" (iOS
+    /// starts asynchronously) from "started and dead", which is what the recovery may act on.
+    /// Main-thread confined.
+    private var enginesAttempted = false
+    /// A rebuild is already on the main queue — one device switch produces a burst of triggers
+    /// and they must collapse into one restart. Main-thread confined.
+    private var rebuildQueued = false
+    /// `systemUptime` of the last rebuild, so a device that renegotiates in a loop cannot spin
+    /// the session. Main-thread confined.
+    private var lastRebuildAt: TimeInterval = 0
+    /// Let the burst of triggers from one switch land before rebuilding.
+    private static let rebuildDebounce: TimeInterval = 0.15
+    /// Floor between two rebuilds.
+    private static let rebuildFloor: TimeInterval = 0.5
+    /// Retries when a rebuild's `start()` loses the race with a device that is still going away
+    /// (0.3 s, 0.6 s, 1.2 s). A failed rebuild leaves no engine to post the next notification,
+    /// so this ladder — and, on macOS, the HAL listener — is all that stands between a mistimed
+    /// switch and a silent session.
+    private static let rebuildAttempts = 3
+
     public init(connection: PunktfunkConnection) {
         self.connection = connection
     }
@@ -96,10 +135,14 @@ public final class SessionAudio {
     /// Engine teardown still belongs to stop().
     deinit {
         flag.stop()
-        #if os(iOS)
+        // The observers only hold self weakly, so we can be deinited with them still registered;
-        // The observer only holds self weakly, so we can be deinited with it still registered;
+        // drop them here too rather than leaking them when an owner skips stop().
-        // drop the token here too rather than leaking it when an owner skips stop().
+        deviceWatcher?.stop()
+        #if !os(macOS)
         if let routeObserver { NotificationCenter.default.removeObserver(routeObserver) }
+        if let mediaResetObserver {
+            NotificationCenter.default.removeObserver(mediaResetObserver)
+        }
         #endif
     }
 
@@ -120,6 +163,12 @@ public final class SessionAudio {
         videoLatency: LatencyMeter? = nil
     ) {
         self.videoLatency = videoLatency
+        // Before any engine exists: the recovery watches the hardware, not the engines, and the
+        // config it rebuilds from has to be recorded whether or not this start succeeds.
+        startConfig = StartConfig(
+            speakerUID: speakerUID, micUID: micUID, micChannel: micChannel,
+            micEnabled: micEnabled, echoCancel: echoCancel)
+        installDeviceChangeRecovery(micEnabled: micEnabled)
         #if os(macOS)
         // No AVAudioSession on macOS — start the engines directly (caller's thread, as before).
         startEngines(
@@ -189,10 +238,10 @@ public final class SessionAudio {
             #if os(iOS)
             // Only the `.playAndRecord` session can land on the earpiece, and only it accepts an
             // output override — so the mic-off (`.playback`) path deliberately does neither.
-            if micEnabled {
+            // (The route OBSERVER that re-applies this per route is installed by
-                steerBuiltInOutputToSpeaker(session)
+            // `installDeviceChangeRecovery`, for every session — a `.playback` session steers
-                installRouteObserver()
+            // nothing but still has engines a route change can stop.)
-            }
+            if micEnabled { steerBuiltInOutputToSpeaker(session) }
             #endif
         } catch {
             log.warning("AVAudioSession setup failed: \(error.localizedDescription)")
@@ -220,11 +269,20 @@ public final class SessionAudio {
         }
     }
 
+    #endif
+
+    #if !os(macOS)
     /// Routes change under a live session: a headset connects mid-stream, or disconnects and hands
-    /// the stream back to the built-in output. iOS drops an output override whenever the route
+    /// the stream back to the built-in output. Two things follow from that.
-    /// changes — which is what lets a newly-connected headset win — so the earpiece steer is a
+    ///
-    /// property of the CURRENT route and has to be re-applied per route. Without this, dropping
+    /// iOS drops an output override whenever the route changes — which is what lets a newly-
-    /// Bluetooth mid-stream would land the game on the earpiece.
+    /// connected headset win — so the earpiece steer is a property of the CURRENT route and has to
+    /// be re-applied per route. Without it, dropping Bluetooth mid-stream lands the game on the
+    /// earpiece.
+    ///
+    /// And on every platform a route change can take the engines down with it (see
+    /// `installDeviceChangeRecovery`), which is why this is installed for `.playback` sessions and
+    /// on tvOS too, where there is no earpiece to steer away from.
     private func installRouteObserver() {
         let observer = NotificationCenter.default.addObserver(
             forName: AVAudioSession.routeChangeNotification,
@@ -235,7 +293,10 @@ public final class SessionAudio {
             // other call into it.
             SessionAudio.sessionQueue.async {
                 guard let self, !self.flag.isStopped else { return }
+                #if os(iOS)
                 self.steerBuiltInOutputToSpeaker(AVAudioSession.sharedInstance())
+                #endif
+                DispatchQueue.main.async { self.reviveStoppedEngines("the audio route changed") }
             }
         }
         stateLock.lock()
@@ -252,6 +313,7 @@ public final class SessionAudio {
     private func startEngines(
         speakerUID: String, micUID: String, micChannel: Int, micEnabled: Bool, echoCancel: Bool
     ) {
+        enginesAttempted = true // even if every path below fails — see `reviveStoppedEngines`
         #if os(tvOS)
         // No app-accessible microphone input on tvOS — playback only.
         startPlayback(speakerUID: speakerUID)
@@ -325,33 +387,27 @@ public final class SessionAudio {
     public func stop() {
         flag.stop() // before taking the engines — see stateLock's comment
         stateLock.lock()
-        let capture = captureEngine
-        captureEngine = nil
-        let playback = playbackEngine
-        playbackEngine = nil
-        let combined = combinedEngine
-        combinedEngine = nil
         let wasDraining = drainStarted
         drainStarted = false
-        #if os(iOS)
+        let watcher = deviceWatcher
+        deviceWatcher = nil
+        #if !os(macOS)
         let route = routeObserver
         routeObserver = nil
+        let mediaReset = mediaResetObserver
+        mediaResetObserver = nil
         #endif
         stateLock.unlock()
-        #if os(iOS)
+        // Every watcher goes before the engines do: a device change landing during teardown must
-        // Before the deactivate below, so a route change during teardown can't re-steer a session
+        // not schedule a rebuild of a session we are in the middle of releasing. (`flag` already
-        // we are in the middle of releasing.
+        // guards that, but not arming the trigger is better than catching it.) On iOS this is
+        // also ahead of the deactivate below, so a route change cannot re-steer a dying session.
+        watcher?.stop()
+        #if !os(macOS)
         if let route { NotificationCenter.default.removeObserver(route) }
+        if let mediaReset { NotificationCenter.default.removeObserver(mediaReset) }
         #endif
-        if let capture {
+        tearDownEngines()
-            capture.inputNode.removeTap(onBus: 0)
-            capture.stop()
-        }
-        playback?.stop()
-        if let combined {
-            combined.inputNode.removeTap(onBus: 0)
-            combined.stop()
-        }
         #if !os(macOS)
         // Release the session so audio we interrupted (Music, podcasts) gets its resume cue. Like
         // activation, setActive is synchronous/blocking — run it on the shared serial session queue
@@ -372,6 +428,234 @@ public final class SessionAudio {
         }
     }
 
+    /// Stop and release every engine we own, leaving the ring, the drain thread, the observers and
+    /// the audio session alone — the teardown half shared by `stop()` and a rebuild. Safe from any
+    /// thread; the engines are taken under the lock before any of them is touched.
+    private func tearDownEngines() {
+        stateLock.lock()
+        let capture = captureEngine
+        captureEngine = nil
+        let playback = playbackEngine
+        playbackEngine = nil
+        let combined = combinedEngine
+        combinedEngine = nil
+        stateLock.unlock()
+        if let capture {
+            capture.inputNode.removeTap(onBus: 0)
+            capture.stop()
+        }
+        playback?.stop()
+        if let combined {
+            combined.inputNode.removeTap(onBus: 0)
+            combined.stop()
+        }
+    }
+
+    // MARK: - Device changes
+
+    /// An AVAudioEngine does not follow the audio hardware. When the output device changes under a
+    /// running engine — AirPods taken out of an ear, a headset unplugged, the default switched in
+    /// System Settings — the engine's IO unit sees the new hardware, THE ENGINE STOPS ITSELF, and
+    /// it posts `AVAudioEngineConfigurationChange`. It stays stopped until somebody starts it
+    /// again. Nothing here ever did, so from that moment the session rendered silence: no audio on
+    /// the speakers the stream had just moved to, and none in the AirPods when they went back in
+    /// (that is a second stop, not a recovery), until the whole stream was restarted. Measured on
+    /// this exact topology: render callbacks go from ~94/s to zero the instant the default output
+    /// device changes, and both restarting the same engine and building a fresh one resume them.
+    ///
+    /// Three triggers feed one rebuild, because no single one of them covers the ground:
+    ///
+    ///  - the engine notification, everywhere — the direct signal, but only an engine that still
+    ///    EXISTS can post it, so it cannot report a rebuild that failed to start;
+    ///  - the HAL default-output-device listener, macOS — independent of any engine and of the
+    ///    engine's topology. It is what makes the recovery work for the voice-processing engine
+    ///    (mic + echo cancellation, the DEFAULT macOS configuration) without having to assume that
+    ///    a VPIO engine posts the notification the plain one demonstrably does;
+    ///  - the route-change and media-services-reset notifications, iOS/tvOS, where the session and
+    ///    not the device is what moves.
+    ///
+    /// `micEnabled` only decides whether the mic-bearing session observers are worth installing.
+    /// Main thread.
+    private func installDeviceChangeRecovery(micEnabled: Bool) {
+        stateLock.lock()
+        let already = deviceWatcher != nil
+        stateLock.unlock()
+        guard !already else { return } // a second start() on one SessionAudio: keep the first set
+
+        let watcher = AudioDeviceWatcher(
+            isOurs: { [weak self] posted in self?.ownsEngine(posted) ?? false },
+            onChange: { [weak self] reason in self?.hardwareMoved(reason) })
+        stateLock.lock()
+        deviceWatcher = watcher
+        stateLock.unlock()
+        watcher.start()
+
+        #if !os(macOS)
+        installRouteObserver()
+        installMediaResetObserver(micEnabled: micEnabled)
+        #endif
+    }
+
+    /// Is `posted` one of the engines this session currently owns? A retired engine posts one last
+    /// configuration change as it is torn down, and another AVAudioEngine in the process is none of
+    /// our business — identity only, the object is never resurrected.
+    private func ownsEngine(_ posted: AnyObject?) -> Bool {
+        stateLock.lock()
+        defer { stateLock.unlock() }
+        return posted === playbackEngine || posted === captureEngine || posted === combinedEngine
+    }
+
+    /// The hardware moved (main queue, from `AudioDeviceWatcher`). Both reasons ask the same
+    /// question — is playback still where it should be — but they answer it differently: an engine
+    /// that told us it stopped is definitive, while the default device moving might not concern us
+    /// at all.
+    private func hardwareMoved(_ reason: AudioDeviceWatcher.Reason) {
+        guard !flag.isStopped else { return }
+        switch reason {
+        case .engineConfiguration:
+            scheduleEngineRebuild(reason: reason.rawValue)
+        case .defaultOutputDevice:
+            #if os(macOS)
+            defaultOutputChanged()
+            #else
+            break // the watcher only raises this one on macOS
+            #endif
+        }
+    }
+
+    /// Restart the engines if — and only if — playback is down. The conservative trigger: it is
+    /// what a route change (iOS/tvOS) and the macOS backstop get to do, since a HEALTHY engine
+    /// that followed the change on its own must not be interrupted for it.
+    ///
+    /// Gated on a start having been ATTEMPTED rather than on an engine existing, which is the
+    /// difference between recovering a session whose very first `startPlayback` failed — no
+    /// output device at the moment it connected — and leaving it silent for good. On iOS the same
+    /// flag keeps this from racing the asynchronous start, where no engine yet is normal.
+    private func reviveStoppedEngines(_ reason: String) {
+        guard !flag.isStopped, enginesAttempted, !playbackIsLive else { return }
+        scheduleEngineRebuild(reason: "playback is stopped and \(reason)")
+    }
+
+    /// Is the render side actually running? Both engines can carry it (`combinedEngine` when the
+    /// voice processor is engaged, `playbackEngine` otherwise). Taken out from under `stateLock`
+    /// before asking AVAudioEngine anything — the lock guards our handles, not the framework.
+    private var playbackIsLive: Bool {
+        stateLock.lock()
+        let playback = playbackEngine
+        let combined = combinedEngine
+        stateLock.unlock()
+        return (playback?.isRunning ?? false) || (combined?.isRunning ?? false)
+    }
+
+    /// Coalesce: one device switch produces a burst — the old device leaving, the default moving,
+    /// the new device settling, and each engine we own posting its own change — and one rebuild
+    /// serves all of it. The floor between rebuilds keeps a device that renegotiates in a loop
+    /// from spinning the session. Main thread.
+    private func scheduleEngineRebuild(reason: String) {
+        guard !rebuildQueued else { return }
+        rebuildQueued = true
+        let since = ProcessInfo.processInfo.systemUptime - lastRebuildAt
+        let delay = max(Self.rebuildDebounce, Self.rebuildFloor - since)
+        log.info("\(reason) — restarting the audio engines in \(Int(delay * 1000)) ms")
+        DispatchQueue.main.asyncAfter(deadline: .now() + delay) { [weak self] in
+            self?.rebuildEngines(attempt: 0)
+        }
+    }
+
+    /// Put back the topology this session was started with, on whatever hardware is there now.
+    ///
+    /// A full rebuild rather than a `start()` on the stopped engine, because the mic side has to
+    /// follow too: `installMicTap` reads the input's live format, and the voice processor
+    /// renegotiates its own. The RING is deliberately not touched — it is the one thing carried
+    /// across (`makePlaybackChain` reuses it, `startDrain` is idempotent), so the drain thread
+    /// keeps decoding right through the switch and its overflow policy has already dropped
+    /// everything that went stale while the engine was down.
+    private func rebuildEngines(attempt: Int) {
+        rebuildQueued = false
+        guard !flag.isStopped, let config = startConfig else { return }
+        lastRebuildAt = ProcessInfo.processInfo.systemUptime
+        tearDownEngines()
+        startEngines(
+            speakerUID: config.speakerUID, micUID: config.micUID, micChannel: config.micChannel,
+            micEnabled: config.micEnabled, echoCancel: config.echoCancel)
+
+        // Did playback actually come back? A device caught mid-transition can refuse to start, and
+        // a rebuild that fails leaves no engine to post the next notification — so this is the one
+        // path that must not just give up. (`startEngines` has logged the reason already.)
+        if playbackIsLive {
+            log.info("audio engines restarted on the current device")
+            return
+        }
+        guard attempt < Self.rebuildAttempts else {
+            #if os(macOS)
+            log.error("""
+                audio did not come back after the device change — the default-output watcher will \
+                try again when a device appears
+                """)
+            #else
+            log.error("audio did not come back after the route change")
+            #endif
+            return
+        }
+        rebuildQueued = true // holds off a trigger that would only race this ladder
+        let delay = Self.rebuildDebounce * Double(1 << (attempt + 1))
+        DispatchQueue.main.asyncAfter(deadline: .now() + delay) { [weak self] in
+            self?.rebuildEngines(attempt: attempt + 1)
+        }
+    }
+
+    #if os(macOS)
+    /// The system's output device moved. Rebuild only when it actually concerns this session: the
+    /// engine is gone or stopped, or it is playing to a device that is no longer the one we should
+    /// be on. Somebody changing the default while we are pinned to a named speaker is none of our
+    /// business, and rebuilding for it would cost an audible gap for nothing. Main queue (the
+    /// listener block is registered against it).
+    private func defaultOutputChanged() {
+        guard !flag.isStopped, let config = startConfig else { return }
+        stateLock.lock()
+        let engine = combinedEngine ?? playbackEngine
+        stateLock.unlock()
+        guard let engine, engine.isRunning, let unit = engine.outputNode.audioUnit,
+              let playingOn = Self.currentDevice(of: unit)
+        else {
+            // Nothing is playing. If an engine was expected at all, this is the backstop firing.
+            reviveStoppedEngines("the default output device moved")
+            return
+        }
+        // Empty UID = follow the system default; a pinned UID only moves if that device itself
+        // came or went, which `deviceID(forUID:)` reports by resolving to a different ID or none.
+        let shouldBeOn = config.speakerUID.isEmpty
+            ? AudioDevices.defaultOutputDevice()
+            : AudioDevices.deviceID(forUID: config.speakerUID)
+        guard let shouldBeOn, shouldBeOn != playingOn else { return }
+        scheduleEngineRebuild(reason: "the output device changed under the session")
+    }
+    #endif
+
+    #if !os(macOS)
+    /// The audio server can die and restart. It takes the session's configuration and every engine
+    /// with it, and the documented recovery is to build all of it again — the same rebuild a route
+    /// change uses, with the session activation back in front of it.
+    private func installMediaResetObserver(micEnabled: Bool) {
+        let observer = NotificationCenter.default.addObserver(
+            forName: AVAudioSession.mediaServicesWereResetNotification, object: nil, queue: nil
+        ) { [weak self] _ in
+            SessionAudio.sessionQueue.async {
+                guard let self, !self.flag.isStopped else { return }
+                self.activateAudioSession(micEnabled: micEnabled)
+                DispatchQueue.main.async {
+                    self.scheduleEngineRebuild(reason: "the audio services were reset")
+                }
+            }
+        }
+        stateLock.lock()
+        let stale = mediaResetObserver
+        mediaResetObserver = observer
+        stateLock.unlock()
+        if let stale { NotificationCenter.default.removeObserver(stale) }
+    }
+    #endif
+
     /// Silence the mic uplink (no room audio leaves the device) or restore it. THE one muting
     /// mechanism: the owner composes its reasons — the user's in-stream mute and the background
     /// keep-alive's privacy mute — into one effective state and passes that here, so neither can
@@ -437,6 +721,21 @@ public final class SessionAudio {
         return Stats(bufferMS: s.bufferedMS, avOffsetMS: s.avOffsetMS)
     }
 
+    #if os(macOS)
+    /// Whether playback is rendering, and the device it is rendering to. The device-change
+    /// recovery has exactly one observable signature from outside — "running again, on the device
+    /// the system just moved to" — and nothing else here could tell the two halves apart: a
+    /// stopped engine can still name the old device, and a retargeted one can still be stopped.
+    /// Used by `AudioDeviceSwitchTests`.
+    var playbackState: (running: Bool, device: AudioDeviceID?) {
+        stateLock.lock()
+        let engine = combinedEngine ?? playbackEngine
+        stateLock.unlock()
+        guard let engine else { return (false, nil) }
+        return (engine.isRunning, engine.outputNode.audioUnit.flatMap(Self.currentDevice(of:)))
+    }
+    #endif
+
     // MARK: - Playback (host → speaker)
 
     /// The playback jitter ring + the source node draining it — shared by the plain playback

clients/apple/Tests/PunktfunkKitTests/AudioDeviceSwitchTests.swift

@@ -0,0 +1,102 @@
+// The device-switch regression, end to end against a real session.
+//
+// An AVAudioEngine does not follow the audio hardware: when the output device changes under a
+// running engine it STOPS ITSELF and stays stopped. Nothing restarted it, so a stream whose
+// output moved mid-session — AirPods taken out of an ear, a headset unplugged, the default
+// changed in System Settings — played silence from that moment on: nothing on the speakers the
+// system had just moved to, and nothing in the AirPods when they went back in, since that is a
+// second stop rather than a recovery. Only restarting the whole stream brought audio back.
+//
+// This drives the real `SessionAudio` against the loopback host and moves the system's default
+// output device out from under it, twice — out and back, the exact shape of the field report.
+// Playback-only (mic off): it is the render side that died, and a mic would drag the microphone
+// permission and the voice processor into a test that is about neither.
+//
+// Driven by clients/apple/test-loopback.sh, like its LoopbackIntegrationTests siblings.
+
+#if os(macOS)
+import AVFoundation
+import CoreAudio
+import XCTest
+
+@testable import PunktfunkKit
+
+final class AudioDeviceSwitchTests: XCTestCase {
+    /// Set the system default output device. Test-local on purpose: nothing in the app ever
+    /// changes the user's device, it only follows it.
+    private func setDefaultOutput(_ id: AudioDeviceID) -> OSStatus {
+        var address = AudioObjectPropertyAddress(
+            mSelector: kAudioHardwarePropertyDefaultOutputDevice,
+            mScope: kAudioObjectPropertyScopeGlobal,
+            mElement: kAudioObjectPropertyElementMain)
+        var dev = id
+        return AudioObjectSetPropertyData(
+            AudioObjectID(kAudioObjectSystemObject), &address, 0, nil,
+            UInt32(MemoryLayout<AudioDeviceID>.size), &dev)
+    }
+
+    /// Pump the MAIN runloop until playback is running on `device`, or the deadline passes. The
+    /// recovery lands on the main queue (a debounced hop, then possibly a retry ladder), so a
+    /// sleeping test would block the very thing it is waiting for.
+    private func waitForPlayback(
+        _ audio: SessionAudio, on device: AudioDeviceID, timeout: TimeInterval
+    ) -> Bool {
+        let deadline = Date().addingTimeInterval(timeout)
+        while Date() < deadline {
+            RunLoop.current.run(until: Date().addingTimeInterval(0.05))
+            let state = audio.playbackState
+            if state.running, state.device == device { return true }
+        }
+        return false
+    }
+
+    func testPlaybackFollowsAnOutputDeviceChange() throws {
+        guard let portStr = ProcessInfo.processInfo.environment["PUNKTFUNK_LOOPBACK_PORT"],
+              let port = UInt16(portStr)
+        else {
+            throw XCTSkip("needs a running punktfunk1-host — use clients/apple/test-loopback.sh")
+        }
+        guard let original = AudioDevices.defaultOutputDevice() else {
+            throw XCTSkip("no default output device")
+        }
+        let others = AudioDevices.outputs()
+            .compactMap { AudioDevices.deviceID(forUID: $0.uid) }
+            .filter { $0 != original }
+        guard let target = others.first else {
+            throw XCTSkip("needs a second output device to switch to")
+        }
+
+        let conn = try PunktfunkConnection(
+            host: "127.0.0.1", port: port, width: 1280, height: 720, refreshHz: 60,
+            bitrateKbps: 50_000)
+        let audio = SessionAudio(connection: conn)
+        // "" speaker UID = follow the system default, which is what the report was running and
+        // the only configuration a default-device change is supposed to move.
+        audio.start(
+            speakerUID: "", micUID: "", micChannel: 0, micEnabled: false, echoCancel: false)
+        defer {
+            audio.stop()
+            _ = setDefaultOutput(original)
+        }
+
+        XCTAssertTrue(
+            waitForPlayback(audio, on: original, timeout: 5),
+            "playback never started on the current default output device")
+
+        // Out: the device the stream was playing to goes away underneath it.
+        XCTAssertEqual(setDefaultOutput(target), noErr)
+        XCTAssertTrue(
+            waitForPlayback(audio, on: target, timeout: 10),
+            "playback did not come back after the output device changed — this is the field "
+                + "report: no sound on the device the system moved to, until the stream is "
+                + "restarted")
+
+        // And back: the second half of the report, where putting the AirPods back in produced a
+        // second stop rather than a recovery.
+        XCTAssertEqual(setDefaultOutput(original), noErr)
+        XCTAssertTrue(
+            waitForPlayback(audio, on: original, timeout: 10),
+            "playback did not come back after the output device changed back")
+    }
+}
+#endif

clients/apple/Tests/PunktfunkKitTests/AudioDeviceWatcherTests.swift

@@ -0,0 +1,121 @@
+// The trigger half of surviving a device change: does the session actually get TOLD?
+//
+// An AVAudioEngine stops itself when its output hardware changes and never restarts on its own, so
+// everything downstream of these notifications is dead code if the notification never arrives. The
+// rebuild itself needs a live session to exercise (and so a host, which does not build on macOS),
+// but the wiring does not — and the wiring is where a silent failure costs a session all of its
+// audio, which is exactly the shape of the bug this watcher exists to fix.
+
+import AVFoundation
+import XCTest
+#if os(macOS)
+import CoreAudio
+#endif
+
+@testable import PunktfunkKit
+
+final class AudioDeviceWatcherTests: XCTestCase {
+    /// The callbacks land on the main queue, so a test that slept would block the thing it waits
+    /// for. Pumps until `predicate` holds or the deadline passes.
+    private func pump(until predicate: () -> Bool, timeout: TimeInterval = 2) -> Bool {
+        let deadline = Date().addingTimeInterval(timeout)
+        while Date() < deadline {
+            if predicate() { return true }
+            RunLoop.current.run(until: Date().addingTimeInterval(0.02))
+        }
+        return predicate()
+    }
+
+    /// The identity gate is the one line that could swallow every notification silently: get it
+    /// wrong and the recovery compiles, installs, runs — and never fires.
+    func testAConfigurationChangeFromOurEngineReachesTheOwner() {
+        let engine = AVAudioEngine()
+        var reasons: [AudioDeviceWatcher.Reason] = []
+        let watcher = AudioDeviceWatcher(
+            isOurs: { $0 === engine }, onChange: { reasons.append($0) })
+        watcher.start()
+        defer { watcher.stop() }
+
+        NotificationCenter.default.post(
+            name: .AVAudioEngineConfigurationChange, object: engine)
+
+        XCTAssertTrue(
+            pump(until: { reasons.contains(.engineConfiguration) }),
+            "the session was never told its engine's configuration changed")
+    }
+
+    /// A retired engine posts one last change as it is torn down, and other AVAudioEngines in the
+    /// process are not ours to restart — rebuilding for either would interrupt healthy playback.
+    func testAConfigurationChangeFromAForeignEngineIsIgnored() {
+        let ours = AVAudioEngine()
+        let stranger = AVAudioEngine()
+        var reasons: [AudioDeviceWatcher.Reason] = []
+        let watcher = AudioDeviceWatcher(
+            isOurs: { $0 === ours }, onChange: { reasons.append($0) })
+        watcher.start()
+        defer { watcher.stop() }
+
+        NotificationCenter.default.post(
+            name: .AVAudioEngineConfigurationChange, object: stranger)
+        // Give it the same grace the positive case gets, then require silence.
+        _ = pump(until: { !reasons.isEmpty }, timeout: 0.5)
+        XCTAssertTrue(reasons.isEmpty, "a foreign engine's change was taken for ours")
+    }
+
+    func testStopSilencesTheWatcher() {
+        let engine = AVAudioEngine()
+        var reasons: [AudioDeviceWatcher.Reason] = []
+        let watcher = AudioDeviceWatcher(
+            isOurs: { $0 === engine }, onChange: { reasons.append($0) })
+        watcher.start()
+        watcher.stop()
+
+        NotificationCenter.default.post(
+            name: .AVAudioEngineConfigurationChange, object: engine)
+        _ = pump(until: { !reasons.isEmpty }, timeout: 0.5)
+        XCTAssertTrue(reasons.isEmpty, "a stopped watcher still reported")
+    }
+
+    #if os(macOS)
+    /// The backstop, against the real HAL: move the system's default output device — the thing that
+    /// happens when AirPods come out of an ear — and require that the session hears about it. This
+    /// is the trigger the recovery leans on for the voice-processing engine, whose own notification
+    /// behaviour cannot be verified here (no Mac in this project's fleet can initialize VPIO).
+    func testTheDefaultOutputDeviceMovingReachesTheOwner() throws {
+        guard let original = AudioDevices.defaultOutputDevice() else {
+            throw XCTSkip("no default output device")
+        }
+        let others = AudioDevices.outputs()
+            .compactMap { AudioDevices.deviceID(forUID: $0.uid) }
+            .filter { $0 != original }
+        guard let target = others.first else {
+            throw XCTSkip("needs a second output device to switch to")
+        }
+
+        var reasons: [AudioDeviceWatcher.Reason] = []
+        let watcher = AudioDeviceWatcher(isOurs: { _ in false }, onChange: { reasons.append($0) })
+        watcher.start()
+        defer {
+            _ = Self.setDefaultOutput(original)
+            watcher.stop()
+        }
+
+        XCTAssertEqual(Self.setDefaultOutput(target), noErr)
+        XCTAssertTrue(
+            pump(until: { reasons.contains(.defaultOutputDevice) }, timeout: 5),
+            "the session was never told the default output device moved")
+    }
+
+    /// Test-local on purpose: nothing in the app ever changes the user's device, it only follows it.
+    private static func setDefaultOutput(_ id: AudioDeviceID) -> OSStatus {
+        var address = AudioObjectPropertyAddress(
+            mSelector: kAudioHardwarePropertyDefaultOutputDevice,
+            mScope: kAudioObjectPropertyScopeGlobal,
+            mElement: kAudioObjectPropertyElementMain)
+        var dev = id
+        return AudioObjectSetPropertyData(
+            AudioObjectID(kAudioObjectSystemObject), &address, 0, nil,
+            UInt32(MemoryLayout<AudioDeviceID>.size), &dev)
+    }
+    #endif
+}

clients/apple/test-loopback.sh

@@ -26,8 +26,11 @@ mkdir -p "$CFG/open" "$CFG/paired" "$CFG/guess"
 trap 'kill "${HOST_PID:-}" "${PAIR_PID:-}" "${GUESS_PID:-}" 2>/dev/null || true' EXIT
 # The open host also scripts a feedback burst (rumble + DualSense hidout) right after the
 # handshake, so the Swift test can assert the host→client feedback planes end to end.
+# The open host outlives the others on purpose: AudioDeviceSwitchTests connects to it and then
+# spends tens of seconds moving the system's output device around, long after the 300 frames the
+# round-trip test needs.
 HOME="$CFG/open" XDG_CONFIG_HOME="$CFG/open/.config" PUNKTFUNK_TEST_FEEDBACK=1 \
-    target/release/punktfunk-host punktfunk1-host --port "$PORT" --source synthetic --frames 300 \
+    target/release/punktfunk-host punktfunk1-host --port "$PORT" --source synthetic --frames 12000 \
     --allow-tofu &
 HOST_PID=$!
 HOME="$CFG/paired" XDG_CONFIG_HOME="$CFG/paired/.config" \
@@ -61,4 +64,4 @@ cd clients/apple
 PUNKTFUNK_LOOPBACK_PORT="$PORT" PUNKTFUNK_PAIRING_PORT="$PAIR_PORT" PUNKTFUNK_PAIRING_PIN="$PIN" \
     PUNKTFUNK_GUESS_PORT="$GUESS_PORT" PUNKTFUNK_GUESS_PIN="$GUESS_PIN" \
     PUNKTFUNK_TEST_FEEDBACK=1 \
-    swift test --filter LoopbackIntegrationTests
+    swift test --filter 'LoopbackIntegrationTests|AudioDeviceSwitchTests'

crates/pf-capture/src/linux/pipewire.rs

@@ -4,6 +4,7 @@ use super::pw_cursor::{composite_cursor, update_cursor_meta, CursorState};
 use super::pw_pods::{
     build_cursor_meta_param, build_default_format_obj, build_dmabuf_buffers, build_dmabuf_format,
     build_hdr_dmabuf_format, build_mappable_buffers, build_shm_only_buffers, serialize_pod,
+    HDR_FORMAT_ORDER,
 };
 use super::{CapturedFrame, DmabufFrame, FramePayload, PixelFormat, ZeroCopyPolicy};
 use anyhow::{Context, Result};
@@ -1850,13 +1851,15 @@ pub fn pipewire_thread(
     // negotiation-timeout path latches the process-wide SDR downgrade if nothing matches.
     let format_pods: Vec<Vec<u8>> = if want_hdr {
         tracing::info!(
-            "HDR capture: offering xRGB_210LE/xBGR_210LE LINEAR dmabufs with MANDATORY \
+            "HDR capture: offering xBGR_210LE/xRGB_210LE LINEAR dmabufs with MANDATORY \
              BT.2020 + SMPTE-2084 (PQ) colorimetry (GNOME 50+ monitor stream)"
         );
-        vec![
+        // ⚠ Order is the whole fix — see the NVIDIA note on `HDR_FORMAT_ORDER`. The first
-            build_hdr_dmabuf_format(VideoFormat::xRGB_210LE, preferred)?,
+        // compatible consumer pod wins, so this is what a gamescope session actually lands on.
-            build_hdr_dmabuf_format(VideoFormat::xBGR_210LE, preferred)?,
+        HDR_FORMAT_ORDER
-        ]
+            .iter()
+            .map(|fmt| build_hdr_dmabuf_format(*fmt, preferred))
+            .collect::<Result<Vec<_>>>()?
     } else if want_dmabuf {
         let mut pods = Vec::with_capacity(if prefer_native_nv12 { 2 } else { 1 });
         if prefer_native_nv12 {

crates/pf-capture/src/linux/pw_pods.rs

@@ -121,6 +121,38 @@ pub(super) fn build_dmabuf_format(
 /// SDR — the same outcome as not offering HDR.
 const SPA_VIDEO_TRANSFER_SMPTE2084: u32 = 14;
 
+/// The two 10-bit PQ formats an HDR session offers, **in negotiation order**. The order is not a
+/// style choice — on NVIDIA it is the difference between correct colour and red/blue swapped.
+///
+/// `xBGR_210LE` (DRM `XBGR2101010`, Vulkan `A2B10G10R10_UNORM_PACK32`) comes FIRST because the
+/// first compatible consumer pod wins, and it is the only one gamescope fills correctly on every
+/// vendor:
+///
+/// * `A2R10G10B10_UNORM_PACK32` **linear-tiled storage** is an optional Vulkan feature that
+///   NVIDIA does not implement. gamescope's capture textures are mappable, hence linear, so on
+///   NVIDIA its composite `imageStore` into that image lands in XBGR order — the bytes come out
+///   byte-reversed while the buffer is still LABELLED `XRGB2101010`.
+/// * The host believes the label: `xRGB_210LE → PixelFormat::X2Rgb10 →`
+///   `NV_ENC_BUFFER_FORMAT_ARGB10`. Every mapping in that chain is individually correct, which is
+///   exactly why the bug is invisible from this side — the *content* is what's wrong.
+/// * Upstream gamescope hit the same wall and fixed it with `vulkan_get_rgb10_capture_format()`,
+///   which probes `linearTilingFeatures` for STORAGE+SAMPLED and falls back to `XBGR2101010`.
+///   That landed AFTER 3.16.25, so the pinned `punktfunk-gamescope` (3.16.25-7-g60561e2 +pfhdr4)
+///   predates it and cannot self-correct — hence fixing the preference host-side, where it ships
+///   in the host binary with no gamescope rebuild.
+///
+/// Preferring xBGR costs nothing anywhere else: `A2B10G10R10_UNORM_PACK32` is the universally
+/// supported packed-10 format (it is the standard HDR10 swapchain format), it is what upstream
+/// falls back to, and `X2Bgr10` has a first-class encoder path (NVENC `ABGR10`, VAAPI
+/// `X2BGR10LE`). `xRGB_210LE` stays as the second pod so a producer that somehow offers only it
+/// can still negotiate HDR rather than falling off to the SDR downgrade.
+///
+/// ⚠ The real fix belongs upstream in the patch set: `spa_format_to_drm()` should offer only the
+/// format `vulkan_get_rgb10_capture_format()` reports. Until the gamescope pin moves past that
+/// commit, THIS ORDER is what keeps NVIDIA HDR sessions correct — do not "tidy" it.
+pub(super) const HDR_FORMAT_ORDER: [VideoFormat; 2] =
+    [VideoFormat::xBGR_210LE, VideoFormat::xRGB_210LE];
+
 pub(super) fn build_hdr_dmabuf_format(
     format: VideoFormat,
     preferred: Option<(u32, u32, u32)>,
@@ -596,4 +628,37 @@ mod tests {
         // The minimum must not exceed what producers already serve, or the ask becomes a demand.
         const { assert!(POOL_MIN <= 2) };
     }
+
+    /// xBGR_210LE must be offered FIRST, and this is a correctness test, not a style one.
+    ///
+    /// The first compatible consumer pod wins the negotiation. Leading with `xRGB_210LE` makes an
+    /// NVIDIA gamescope session land on `XRGB2101010`, whose linear-tiled `A2R10G10B10` storage
+    /// NVIDIA does not support — gamescope's composite `imageStore` writes XBGR bytes under an
+    /// XRGB label and the whole stream comes out with red and blue swapped. Every format mapping
+    /// on the host side is individually correct, so nothing downstream can detect it.
+    ///
+    /// Field-confirmed 2026-08-09 on the RTX 5070 Ti Bazzite host with 0.26.0. See the
+    /// [`HDR_FORMAT_ORDER`] docs for the upstream fix this predates.
+    #[test]
+    fn hdr_offers_xbgr_before_xrgb() {
+        assert_eq!(
+            HDR_FORMAT_ORDER[0],
+            VideoFormat::xBGR_210LE,
+            "xBGR_210LE must be offered first — leading with xRGB_210LE swaps red and blue on \
+             every NVIDIA gamescope HDR session"
+        );
+        assert_eq!(
+            HDR_FORMAT_ORDER[1],
+            VideoFormat::xRGB_210LE,
+            "xRGB_210LE stays as the fallback pod so a producer offering only it can still \
+             negotiate HDR instead of dropping to the SDR downgrade"
+        );
+        // Both must still build: the order is a preference, never a removal.
+        for fmt in HDR_FORMAT_ORDER {
+            assert!(
+                !build_hdr_dmabuf_format(fmt, None).unwrap().is_empty(),
+                "{fmt:?} must still produce a format pod"
+            );
+        }
+    }
 }

crates/pf-encode/src/enc/pyrowave_wire.rs

@@ -65,6 +65,14 @@ pub(crate) fn stamp_color_bits(bitstream: &mut [u8], seq_offset: usize, bt2020_p
 /// repeated value is read as more blocks of the same frame. That is why PW5's alternating encoder
 /// handles need `pyrowave_encoder_set_next_sequence`, and why a test asserts this reader sees
 /// +1 mod 8 across the pair.
+///
+/// Its only caller is the Linux backend — alternating encoder handles are a Linux-side concern, and
+/// the Windows backend drives pyrowave's compat device with a single handle. The rest of this module
+/// really is shared (`packet_boundary` and `stamp_color_bits` have callers on both), so the exemption
+/// is scoped to this one item rather than the file: `dead_code` stays live on Linux, where the caller
+/// lives and where its disappearing would be a real finding. Windows builds with `-D warnings`, so
+/// without this the host and tray clippy legs fail to compile the lib at all.
+#[cfg_attr(not(target_os = "linux"), allow(dead_code))]
 pub(crate) fn wire_sequence(bitstream: &[u8], packet_offset: usize) -> Option<u8> {
     let lo = *bitstream.get(packet_offset + 2)?;
     let hi = *bitstream.get(packet_offset + 3)?;

crates/pf-vdisplay/src/vdisplay/linux/kwin.rs

@@ -13,8 +13,11 @@
 //! So an interactive Plasma session does NOT hand it to a bare client — the host packages ship
 //! `io.unom.Punktfunk.Host.desktop` (`Exec=/usr/bin/punktfunk-host`,
 //! `X-KDE-Wayland-Interfaces=zkde_screencast_unstable_v1,…`) so it is present before the host first
-//! connects. The headless test path instead exposes it to bare clients via
+//! connects. That identification is also why **the host binary must carry no file capability**: a
-//! `KWIN_WAYLAND_NO_PERMISSION_CHECKS=1`. The compositor backend must implement
+//! process holding capabilities KWin lacks is one the kernel will not let KWin resolve
+//! `/proc/<pid>/exe` for, so it can never be matched to a `.desktop` no matter how correctly the
+//! file is installed (see [`capability_denial_hint`]). The headless test path instead exposes it to
+//! bare clients via `KWIN_WAYLAND_NO_PERMISSION_CHECKS=1`. The compositor backend must implement
 //! `createVirtualOutput`: the **DRM backend** (any version) or the **VirtualBackend since KWin
 //! 6.5.6** (`kwin_wayland --virtual`); on `--virtual` < 6.5.6 the request fails with
 //! "Could not find output". We talk raw Wayland on `$WAYLAND_DISPLAY`, so the host must run inside
@@ -1071,6 +1074,107 @@ impl Drop for StopOnDrop {
     }
 }
 
+/// Extra sentence appended to every "KWin never advertised the screencast global" error when this
+/// process carries capabilities — the one cause that is completely invisible from the Wayland side.
+///
+/// KWin authorizes a restricted interface by resolving the *client's* `/proc/<pid>/exe` and
+/// matching it against an installed `.desktop`. The kernel refuses that readlink to any reader
+/// whose effective set is not a superset of the target's **permitted** set
+/// (`cap_ptrace_access_check`), and KWin has no capabilities at all. So a host binary carrying any
+/// file capability is simply unidentifiable: `executablePath()` comes back empty, no `.desktop` can
+/// match, and the global is never advertised — indistinguishable, from here, from a missing
+/// `.desktop`. Neither half of the obvious workaround helps: `prctl(PR_SET_DUMPABLE, 1)` leaves the
+/// permitted-set check failing, and moving the grant to systemd `AmbientCapabilities=` lands the
+/// capability in the same permitted set. Only an uncapped binary is identifiable.
+///
+/// This is not hypothetical: 0.26.0-1 setcap'd `cap_sys_nice` on the host for the GPU-priority
+/// lever and took out desktop streaming on every KDE box until the capability was removed again.
+fn capability_denial_hint() -> String {
+    let permitted = std::fs::read_to_string("/proc/self/status")
+        .ok()
+        .and_then(|status| permitted_caps_from_status(&status));
+    capability_denial_hint_for(permitted)
+}
+
+/// The message half of [`capability_denial_hint`], split from the `/proc/self/status` read so it is
+/// testable against a *given* mask instead of whatever the test process happens to hold.
+///
+/// That distinction is not academic: the first version of this asserted the empty case by calling
+/// the real thing and trusting the test process to be uncapped. That holds on a dev box and is
+/// false in CI, where the runner container is root with a full permitted set
+/// (`CapPrm=0x000001ffffffffff`) — so the hint fired, correctly, and the test failed on a machine
+/// where nothing was wrong. A check whose answer depends on the ambient environment tests the
+/// environment, not the code.
+fn capability_denial_hint_for(permitted: Option<u64>) -> String {
+    match permitted {
+        Some(caps) if caps != 0 => format!(
+            " — NOTE: this process carries capabilities (CapPrm={caps:#018x}), which is enough on \
+             its own to cause this: the kernel then refuses KWin the /proc/<pid>/exe read it \
+             identifies clients by, so no .desktop can match however correctly it is installed. \
+             Clear them with `sudo setcap -r /usr/bin/punktfunk-host` and restart the host"
+        ),
+        _ => String::new(),
+    }
+}
+
+/// The permitted-capability mask out of a `/proc/<pid>/status` body, or `None` if the field is
+/// absent/unparseable. The kernel prints it as a tab-separated 16-digit hex word with no `0x`
+/// (`CapPrm:\t0000000000800000` = CAP_SYS_NICE), which is what the split-and-radix-16 parse below
+/// expects — split out from [`capability_denial_hint`] purely so that shape is testable without a
+/// capability-carrying process to point at.
+fn permitted_caps_from_status(status: &str) -> Option<u64> {
+    let field = status.lines().find(|l| l.starts_with("CapPrm:"))?;
+    u64::from_str_radix(field.split_whitespace().nth(1)?, 16).ok()
+}
+
+#[cfg(test)]
+mod capability_hint_tests {
+    use super::*;
+
+    /// Verbatim from a `cap_sys_nice=ep` process on CachyOS — the case that broke 0.26.0-1.
+    const CAPPED: &str = "Name:\tpunktfunk-host\nUid:\t1000\t1000\t1000\t1000\nCapPrm:\t0000000000800000\nCapEff:\t0000000000800000\n";
+    /// ...and from the same binary with no capability, where the hint must stay silent.
+    const CLEAN: &str = "Name:\tpunktfunk-host\nUid:\t1000\t1000\t1000\t1000\nCapPrm:\t0000000000000000\nCapEff:\t0000000000000000\n";
+
+    #[test]
+    fn parses_the_kernels_permitted_mask() {
+        assert_eq!(permitted_caps_from_status(CAPPED), Some(0x0080_0000));
+        assert_eq!(permitted_caps_from_status(CLEAN), Some(0));
+        // CapPrm is not guaranteed present (older/again-different kernels): stay quiet, never panic.
+        assert_eq!(permitted_caps_from_status("Name:\tx\n"), None);
+        assert_eq!(permitted_caps_from_status("CapPrm:\tzzzz\n"), None);
+        assert_eq!(permitted_caps_from_status("CapPrm:\n"), None);
+    }
+
+    /// A capability-free host must not append the hint — the message it decorates is also printed
+    /// on genuinely missing `.desktop` files, and a spurious "you have capabilities" line would
+    /// send the reader chasing a setcap that was never there.
+    ///
+    /// Driven off an explicit mask rather than the test process's own: see
+    /// [`capability_denial_hint_for`] for why calling the real reader here fails in CI.
+    #[test]
+    fn silent_without_capabilities() {
+        assert_eq!(
+            capability_denial_hint_for(permitted_caps_from_status(CLEAN)),
+            ""
+        );
+        // Absent or unparseable field: also silent, never a panic and never a spurious hint.
+        assert_eq!(capability_denial_hint_for(None), "");
+    }
+
+    /// ...and the case that matters actually speaks, naming the mask and the repair. Without this
+    /// the test above passes just as well against a function that returns `""` unconditionally.
+    #[test]
+    fn names_the_mask_and_the_repair_when_capped() {
+        let hint = capability_denial_hint_for(permitted_caps_from_status(CAPPED));
+        assert!(
+            hint.contains("0x0000000000800000"),
+            "names the mask: {hint}"
+        );
+        assert!(hint.contains("setcap -r"), "names the repair: {hint}");
+    }
+}
+
 /// Readiness probe: connect to the KWin Wayland socket, roundtrip the registry, and confirm
 /// the privileged `zkde_screencast` global is actually advertised. This is exactly what
 /// [`run`] needs before it can create a virtual output, so a session-bringup script can poll
@@ -1090,7 +1194,8 @@ pub fn probe() -> Result<()> {
              it on the host's .desktop X-KDE-Wayland-Interfaces (install \
              io.unom.Punktfunk.Host.desktop with Exec=/usr/bin/punktfunk-host, then re-login so KWin \
              re-reads it — the grant is cached per-exe on first connect), or set \
-             KWIN_WAYLAND_NO_PERMISSION_CHECKS=1 for the headless test; needs KWin ≥ 6.5.6"
+             KWIN_WAYLAND_NO_PERMISSION_CHECKS=1 for the headless test; needs KWin ≥ 6.5.6{}",
+            capability_denial_hint()
         );
     }
     Ok(())
@@ -1134,7 +1239,9 @@ fn run_existing(
         anyhow!(
             "KWin does not expose zkde_screencast_unstable_v1 to this client — install the host's \
              .desktop (io.unom.Punktfunk.Host.desktop, X-KDE-Wayland-Interfaces) and re-login so \
-             KWin authorizes it, or run KWin with KWIN_WAYLAND_NO_PERMISSION_CHECKS=1 (headless test)"
+             KWin authorizes it, or run KWin with KWIN_WAYLAND_NO_PERMISSION_CHECKS=1 (headless \
+             test){}",
+            capability_denial_hint()
         )
     })?;
 
@@ -1223,7 +1330,9 @@ fn run(
         anyhow!(
             "KWin does not expose zkde_screencast_unstable_v1 to this client — install the host's \
              .desktop (io.unom.Punktfunk.Host.desktop, X-KDE-Wayland-Interfaces) and re-login so \
-             KWin authorizes it, or run KWin with KWIN_WAYLAND_NO_PERMISSION_CHECKS=1 (headless test)"
+             KWin authorizes it, or run KWin with KWIN_WAYLAND_NO_PERMISSION_CHECKS=1 (headless \
+             test){}",
+            capability_denial_hint()
         )
     })?;
 

docs-site/content/docs/configuration.md

@@ -241,7 +241,7 @@ notes for context.
 | `PUNKTFUNK_NVENC_SPLIT_ARBITRATE` | `1` | Opt-in: let the host change its split-encode decision **live**, mid-session, as the pixel rate moves, instead of only choosing once at session start. Currently wired on the Linux direct-NVENC path. Only interesting alongside `PUNKTFUNK_SPLIT_ENCODE=auto` at very high pixel rates. |
 | `PUNKTFUNK_GPU_PRIORITY_CLASS` | `off` · `normal` · `high` · `realtime` · `auto` | **(Windows)** GPU scheduling priority for capture/encode under a GPU-saturating game. Default `auto` (starts `high`, upgrades to `realtime` when it's safe — e.g. HAGS off); `high` pins the static pre-gate behaviour; `realtime` is the strongest lever but can freeze NVENC on some setups. |
 | `PUNKTFUNK_IDD_DEPTH` | `N` (default `2`) | **(Windows)** IDD-push pipeline depth. `1` cuts latency once GPU priority is raised; higher smooths a contended GPU. |
-| `PYROWAVE_QUEUE_PRIORITY` | `realtime` *(default)* · `high` · `off` | [PyroWave](/docs/pyrowave) sessions only. PyroWave encodes on the same GPU shader cores a game uses, so a demanding game can starve it and the frame rate drops. This asks the driver to schedule the encode ahead of the game. `realtime` tries the strongest class and falls back to `high`; `high` asks only for the middle one; `off` disables the request. A driver that refuses simply encodes at normal priority — it can never stop a session starting. The packages grant the host the `CAP_SYS_NICE` capability this needs; on a host built or installed by hand it will be refused, and the host says so once at session start. Set `off` if you see the desktop stutter while streaming. |
+| `PYROWAVE_QUEUE_PRIORITY` | `realtime` *(default)* · `high` · `off` | [PyroWave](/docs/pyrowave) sessions only. PyroWave encodes on the same GPU shader cores a game uses, so a demanding game can starve it and the frame rate drops. This asks the driver to schedule the encode ahead of the game. `realtime` tries the strongest class and falls back to `high`; `high` asks only for the middle one; `off` disables the request. A driver that refuses simply encodes at normal priority — it can never stop a session starting. This needs the `CAP_SYS_NICE` capability, which the packages deliberately do **not** grant: a host holding a capability cannot be identified by KWin and loses desktop streaming entirely (see [Running as a service](/docs/running-as-a-service#gpu-scheduling-priority)). The request is therefore refused on a stock install and the host says so once at session start. Set `off` if you see the desktop stutter while streaming. |
 
 ## Diagnostics
 

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

@@ -207,33 +207,41 @@ a Windows host, run `punktfunk-host service status` from an elevated prompt on t
 
 ## GPU scheduling priority
 
-The Linux packages give the host binary one Linux capability, `CAP_SYS_NICE`, and it is worth
+The host binary carries **no Linux capability**, and on a KDE desktop it must not.
-knowing why it is there and how to take it away.
 
 The [PyroWave](/docs/pyrowave) codec encodes on the same GPU shader cores your game is using, so a
 demanding game can crowd it out and the stream's frame rate drops with it. The fix is to ask the
 driver to schedule the encode ahead of the game, and every driver we tested gates that request on
-this capability: without it the request is simply refused and nothing changes. The other codecs use
+`CAP_SYS_NICE`. Version 0.26.0-1 granted it for that reason — and it broke desktop streaming on
-a separate video engine on the GPU and are unaffected either way.
+every KDE box, so 0.26.0-2 takes it away again. The other codecs use a separate video engine on the
+GPU and were never affected.
 
-`CAP_SYS_NICE` lets a process raise its own scheduling priority. It grants no access to files,
+The two cannot coexist. To hand the host its virtual display, KWin first has to work out *which*
-the network or other users' processes, and it is **not** the same as running as root — the host
+program is asking, which it does by reading the connecting process's `/proc/<pid>/exe` and matching
-still runs as you, under your user session.
+it against the `.desktop` file the packages install. Linux refuses that read for any process holding
+a capability the reader does not also hold — and KWin holds none. So a host with `CAP_SYS_NICE` is a
+host KWin cannot identify, and every session fails with:
 
-To check, or to take it away:
+```
-
+KWin virtual output failed: KWin does not expose zkde_screencast_unstable_v1 to this client
-```sh
-getcap /usr/bin/punktfunk-host          # shows cap_sys_nice=ep when granted
-sudo setcap -r /usr/bin/punktfunk-host  # remove it; streaming still works
 ```
 
-Removing it costs you nothing unless you stream PyroWave, and you can also just set
+which looks exactly like a missing `.desktop` file and cannot be fixed by reinstalling. Moving the
-`PYROWAVE_QUEUE_PRIORITY=off` to stop the host asking. Note that a package update replaces the
+grant into the systemd unit does not help either — same capability, same refused read.
-binary and re-applies the capability.
 
-Two side effects, if you are debugging the host: a binary carrying a capability is treated as
+If you are on 0.26.0-1, update. On the Bazzite image the `/usr` is read-only, so the only repair is
-security-sensitive by the dynamic loader, so `LD_LIBRARY_PATH` and `LD_PRELOAD` are ignored for it,
+the next image (`sudo punktfunk-sysext update`). Elsewhere you can clear it by hand:
-and it does not write core dumps by default.
+
+```sh
+getcap /usr/bin/punktfunk-host          # prints nothing when correct
+sudo setcap -r /usr/bin/punktfunk-host  # clear it, then restart the host
+```
+
+Losing the capability costs frame pacing under a GPU-bound game and nothing else — the host asks for
+the elevated priority, is refused, and encodes at the normal one. `PYROWAVE_QUEUE_PRIORITY=off`
+stops it asking at all. If you stream only with gamescope (Steam Gaming Mode) you can grant the
+capability yourself and keep the pacing, at the cost of desktop streaming; gamescope has no such
+identity check.
 
 ## Stopping and removing
 

docs/releases/v0.26.0.md

@@ -34,7 +34,7 @@ Most people need to do nothing. Check this list if any of it applies to you.
 
 - **Audio catches jitter before you can hear it.** The rule that decides how much sound to keep buffered only ever learned from failures you could already hear: it waited for three audible dropouts before deepening the buffer, and it re-tested a shallower one every few quiet seconds, paying for a wrong guess with a click, forever. It now reads the near-misses nobody hears, backs off after a probe that fails, and refills in one go rather than limping. Simulating ten minutes of a Wi-Fi power-saving pattern went from roughly two thousand audible events to nine. Update the client.
 - **A gamescope session says so when its refresh rate has been lost.** If something in the session's own configuration drops the setting that carries it, the stream still runs and still looks right while the game underneath is capped to 60 — which is exactly the kind of fault that costs a week to find. It is now one line in the log.
-- **The low-latency wavelet codec got a serious round of work on Linux hosts.** It encodes on the same graphics cores your game is using, so under heavy load it was being crowded out — the encode step measured around 2 ms idle and 15–18 ms at 95% game load, with the stream's frame rate collapsing along with it. The switch that asks the graphics driver for priority had never actually been applied on Linux; it is now, and the package grants the host the permission that switch needs. Alongside it, the encoder can now work on two frames at once and the capture path asks your desktop for enough buffers to keep up, where before it took whatever it was given and never even expressed a preference.
+- **The low-latency wavelet codec got a serious round of work on Linux hosts.** It encodes on the same graphics cores your game is using, so under heavy load it was being crowded out — the encode step measured around 2 ms idle and 15–18 ms at 95% game load, with the stream's frame rate collapsing along with it. The encoder can now work on two frames at once, and the capture path asks your desktop for enough buffers to keep up instead of taking whatever it was handed without ever expressing a preference. The switch that asks your graphics card to put that work ahead of the game's had also never been applied on Linux, and now is — though it stays dormant on an ordinary install, because switching it on requires a system privilege that turns out to stop KDE recognising the host at all. There is more on that below.
 - **Jumbo frames can now be proven rather than hoped for.** The whole path was dead code: the discovery that was supposed to find a larger packet size could never settle above the ordinary limit, so the setting that grows mid-stream was unreachable on every path that has ever existed. A network that genuinely carries big packets is now detected, and a wavelet session starts at the large size instead of never getting there — around six times fewer packets per frame. Still opt-in, on both ends.
 - **The configuration documentation caught up with 0.25**, including the jumbo-frame option and several other settings that had shipped with nothing written about them.
 
@@ -42,6 +42,7 @@ Most people need to do nothing. Check this list if any of it applies to you.
 
 - **Bluetooth headphones got no game audio on iPhone and iPad.** With the microphone on — which is the default — the app was forcing output to the phone's own speaker, and that override outranks a Bluetooth headset. Wired headphones beat it, which is why plugging in a cable made it look correct. Turning the microphone off was the accidental workaround people found. Audio now goes to whatever you have connected, and dropping a headset mid-stream no longer lands on the earpiece. Update the client.
 - **On a Steam Deck, the Steam menu and the Quick Access Menu also moved the game.** Both are driven by the same physical controller the client is forwarding, so opening either one played the game behind it at the same time — a second, invisible player picking things up and walking into walls while you browsed. Steam masks a normal game here and cannot mask this one, because the client deliberately forwards your real controller rather than Steam's stand-in, which has no gyro, trackpads or paddles. The stream now stops forwarding while an overlay has the controller, and hands it back without the button that dismissed the menu firing in the game. Update the client.
+- **Streaming a KDE desktop keeps working.** An interim build of this release gave the host an extra system privilege, so that the wavelet encoder could ask your graphics card for priority. On KDE the side effect was total: KDE decides whether it trusts a program by looking up which file it is running from, the system refuses that lookup for any program holding a privilege, and so KDE stopped recognising the host at all — desktop streaming failed outright, complaining about a missing screen-capture interface, and it survived a clean reinstall of both host and client. Reported from CachyOS on both NVIDIA and AMD. No Linux package grants that privilege any more, on any of the five ways we ship, and upgrading strips it from a machine that already has it. If a host somehow holds one anyway, the error now names it and gives you the command that undoes it, instead of blaming a missing desktop file.
 - **One capture timeout could slow a Linux host down for good.** Two very different problems shared a single switch: a graphics driver that genuinely cannot handle what your desktop produces, and a desktop that simply happened to be restarting. The second was being treated as permanently as the first, so a single moment of bad timing put that host on the slow capture path for every session until the process was restarted — including sessions against a completely different desktop that had never failed at anything, and with nothing at all in the log. The two now have the lifetimes they should, and a capture that works credits the budget back.
 - **A wavelet-codec session could quietly fall back to slow capture and log nothing whatsoever.** The warning was asking a host-wide question about a per-session decision, so a degraded host and a healthy one produced identical logs while one of them touched every pixel on the processor.
 - **"Full chroma" could cost a Steam Deck its codec.** The client advertised the feature on the strength of the setting alone, with nothing checking whether the device could decode it — and no AMD hardware can. The host grants it on HEVC only, so a Deck with the switch on lost HEVC entirely and reconnected on H.264. It looked intermittent because it is a per-profile setting: a "Work" profile lost HEVC where "Game" kept it, on the same machine and the same host. The client now asks the graphics driver the same question the decoder will, so the advertisement and what actually works cannot disagree.

packaging/arch/README.md

@@ -173,8 +173,10 @@ systemctl --user enable --now punktfunk-host     # the user unit is now under /u
 ```
 The udev rule, sysctl, and systemd **user** unit all live under `/usr/lib`, so the merged sysext
 exposes them. `systemd-sysext refresh` re-merges after a reboot. (One HDR nuance of the sysext
-path: file capabilities don't survive it, so gamescope runs without `CAP_SYS_NICE` — everything
+path: the image ships gamescope without `CAP_SYS_NICE`, so its frame pacing is marginally worse —
-works, frame pacing is marginally worse than the pacman install, whose `.install` sets the cap.)
+everything works. Note the host binary carries no capability on *either* path, deliberately: one
+would make the host unidentifiable to KWin and break desktop streaming, see
+[Running as a service](https://punktfunk.io/docs/running-as-a-service#gpu-scheduling-priority).)
 
 ## Steam Deck — the client (what the Decky plugin launches)
 

packaging/arch/build-sysext.sh

@@ -14,9 +14,17 @@
 # instead of 8-bit SDR (the host prefers that name on PATH and attempts HDR by default). Mirrors
 # the Bazzite image's fold-in, including the honesty check: the binary is verified by executing
 # its `+pfhdr` banner, never trusted by filename. Omit it and the image is exactly what it was —
-# the host then stays SDR on that backend, by design. (No CAP_SYS_NICE inside the image: file
+# the host then stays SDR on that backend, by design.
-# capabilities don't survive this squashfs path — gamescope runs without it, pacing slightly
+#
-# worse, same as the Bazzite sysext.)
+# No CAP_SYS_NICE inside the image, for either binary. ⚠ NOT because capabilities are lost on the
+# way in — that was this comment's earlier claim and it is false: mksquashfs records
+# security.capability, and the published Bazzite 0.26.0-1 image really did carry `cap_sys_nice=ep`
+# on usr/bin/punktfunk-host. It is left out on purpose. A capability on the HOST binary makes it
+# unidentifiable to KWin (which resolves a client's /proc/<pid>/exe to match it against a .desktop,
+# and cannot read it for a capability-carrying process) and kills every Desktop-mode session — see
+# packaging/bazzite/build-sysext.sh, which now hard-fails if one is staged. `punktfunk-gamescope`
+# is a compositor, not a KWin client, so it is unaffected by that rule and simply runs without the
+# capability here, pacing slightly worse.
 set -euo pipefail
 
 GAMESCOPE=""

packaging/arch/punktfunk-host.install

@@ -12,33 +12,48 @@ _ensure_punktfunk_group() {
   getent group punktfunk >/dev/null 2>&1 || groupadd --system punktfunk 2>/dev/null || true
 }
 
-# CAP_SYS_NICE on the host binary — the GPU-scheduling grant.
+# NO capability on the host binary — and an active removal of the one 0.26.0-1 granted.
 #
-# WHY: PyroWave encodes on the GPU's shader cores, so a GPU-bound game starves it (measured: the
+# 0.26.0-1 ran `setcap cap_sys_nice=ep` here, to let the encoder open an elevated global-priority
-# encode dispatch goes from ~2 ms to 15-18 ms at 95 % game load). The fix is an elevated
+# Vulkan queue (PyroWave shares the GPU's shader cores with the game; measured 2026-08-08 on an
-# global-priority Vulkan queue, which the driver gates on CAP_SYS_NICE — measured 2026-08-08 on an
+# RTX 5070 Ti, the encode dispatch goes ~2 ms -> 15-18 ms at 95 % game load without it). That grant
-# RTX 5070 Ti: WITHOUT the capability every priority class is refused, WITH it the encoder is
+# BROKE DESKTOP STREAMING ON EVERY KDE BOX, and it cannot be made to work — the two are mutually
-# granted REALTIME on the first attempt. RADV is the same. Without this line the knob exists and
+# exclusive at the kernel level:
-# does nothing. Same capability, same mechanism, as our gamescope package sets on its own binary.
 #
-# NARROW: CAP_SYS_NICE only permits raising scheduling priority (nice/ioprio/affinity/RT class). It
+#   KWin hands out its restricted Wayland protocols (zkde_screencast_unstable_v1, which mints our
-# grants no filesystem, network or user-switching privilege, and it is NOT setuid.
+#   virtual output, and org_kde_kwin_fake_input, which injects input) only to a client it can
+#   IDENTIFY, by resolving that client's /proc/<pid>/exe and matching it against an installed
+#   .desktop's Exec= (ours is io.unom.Punktfunk.Host.desktop). The kernel refuses that readlink to
+#   any reader whose effective set is not a superset of the target's PERMITTED set
+#   (cap_ptrace_access_check), and KWin holds no capabilities. So the moment this binary carries a
+#   capability it becomes unidentifiable: KWin's executablePath() is empty, nothing matches, the
+#   globals are never advertised, and every session dies with
+#   "KWin does not expose zkde_screencast_unstable_v1 to this client" after 8 retries — while
+#   looking exactly like a missing or wrong .desktop file.
 #
-# TWO CONSEQUENCES worth knowing before you debug something odd on this host:
+# Verified on CachyOS (kernel 7.1.6), same-uid reader, cap_sys_nice=ep on the target:
-#  * a file capability makes the process AT_SECURE, so the dynamic loader IGNORES LD_LIBRARY_PATH
+#   no capability .............................. readlink /proc/<pid>/exe OK
-#    and LD_PRELOAD for it. A library-path shim that used to work will silently stop.
+#   capability ................................. EPERM
-#  * core dumps are suppressed for capability-carrying binaries by default (fs.suid_dumpable).
+#   capability + prctl(PR_SET_DUMPABLE, 1) ..... EPERM   <- dumpable is NOT the gate
+#   capability dropped + PR_SET_DUMPABLE(1) .... OK      <- only a capability-free process works
 #
-# Never fails the install: a box without libcap, or a filesystem that cannot store capabilities
+# The third row also rules out the obvious "move it to the systemd unit": AmbientCapabilities= puts
-# (some overlay/NFS setups), just runs at default priority exactly as before.
+# CAP_SYS_NICE in exactly the same permitted set and fails identically. Nothing short of not having
-_grant_sched_capability() {
+# the capability restores identification, so the host does not get one. The encoder already walks
-  setcap 'cap_sys_nice=ep' usr/bin/punktfunk-host 2>/dev/null || true
+# REALTIME -> HIGH -> default when the class is refused (pf-zerocopy vulkan.rs), so this costs
+# pacing under a GPU-bound game and nothing else — 0.25.0's behaviour exactly.
+#
+# The removal below heals boxes that ran 0.26.0-1's scriptlet. A pacman upgrade writes a new inode
+# and file capabilities do not survive that, so this is belt-and-braces for reinstall/downgrade
+# paths — cheap, and the failure it prevents is an 8-retry session death with a misleading message.
+_revoke_sched_capability() {
+  setcap -r usr/bin/punktfunk-host 2>/dev/null || true
 }
 
 post_install() {
   _ensure_update_group
   _ensure_punktfunk_group
-  _grant_sched_capability
+  _revoke_sched_capability
   udevadm control --reload-rules 2>/dev/null || true
   udevadm trigger --subsystem-match=misc 2>/dev/null || true
   # Apply the UDP socket-buffer tuning now (also auto-applied at boot by systemd-sysctl).
@@ -97,8 +112,8 @@ post_upgrade() {
   # root-only, and the virtual Steam Deck pad silently unable to attach. groupadd is idempotent, so
   # this is a no-op on boxes that installed fresh.
   _ensure_punktfunk_group
-  # A replaced binary is a NEW inode — file capabilities do not survive the upgrade, so re-grant.
+  # Strip the cap_sys_nice 0.26.0-1 granted: it makes the host unidentifiable to KWin (see above).
-  _grant_sched_capability
+  _revoke_sched_capability
   udevadm control --reload-rules 2>/dev/null || true
   sysctl -p /usr/lib/sysctl.d/99-punktfunk-net.conf >/dev/null 2>&1 || true
   _warn_stale_firewall_ports

packaging/bazzite/README.md

@@ -421,11 +421,23 @@ bash /usr/share/punktfunk/bazzite/kde-desktop-setup.sh
 # then log out + back into the KDE Desktop session once (or reboot) so KWin restarts with the flag
 ```
 
-That writes `~/.config/environment.d/10-punktfunk-kwin.conf`
+That seeds the `kde-authorized` RemoteDesktop grant into `~/.local/share/flatpak/db/` — the input
-(`KWIN_WAYLAND_NO_PERMISSION_CHECKS=1`) and seeds the `kde-authorized` RemoteDesktop grant into
+half. The **video** half needs no session-wide override: the image ships
-`~/.local/share/flatpak/db/`. Gaming Mode is unaffected. To connect from Desktop Mode, switch to it
+`io.unom.Punktfunk.Host.desktop`, whose `X-KDE-Wayland-Interfaces` grants the host KWin's
-(Steam → Power → Switch to Desktop), then connect the client; switching **mid-stream** requires a
+`zkde_screencast` protocol on a normal Plasma login (least-privilege — only this binary, only that
-reconnect (the host resolves the backend per connect).
+interface). Older versions of the script wrote a session-wide
+`KWIN_WAYLAND_NO_PERMISSION_CHECKS=1` into `~/.config/environment.d/10-punktfunk-kwin.conf`; it now
+*removes* that file as an over-broad leftover. Gaming Mode is unaffected. To connect from Desktop
+Mode, switch to it (Steam → Power → Switch to Desktop), then connect the client; switching
+**mid-stream** requires a reconnect (the host resolves the backend per connect).
+
+> **On 0.26.0-1 specifically, Desktop mode is broken and no amount of this setup fixes it.** That
+> image shipped `cap_sys_nice=ep` on `/usr/bin/punktfunk-host`, and a capability-carrying process is
+> one KWin cannot identify (it resolves `/proc/<pid>/exe` to match the `.desktop`, and the kernel
+> refuses that read), so the session dies with `KWin does not expose zkde_screencast_unstable_v1 to
+> this client`. A merged sysext's `/usr` is read-only, so it cannot be repaired in place — take the
+> next image (`sudo punktfunk-sysext update`). `KWIN_WAYLAND_NO_PERMISSION_CHECKS=1` works around it
+> meanwhile by disabling the check that needs the identification.
 
 ---
 

packaging/bazzite/build-sysext.sh

@@ -130,28 +130,35 @@ SYSEXT_VERSION_ID=$PF_VR
 EXTENSION_RELOAD_MANAGER=1
 EOF
 
-# CAP_SYS_NICE on the host binary — the GPU-scheduling grant. PyroWave encodes on the GPU shader
+# NO CAP_SYS_NICE in the image — and an assertion that none crept back in.
-# cores a game saturates, and the driver gates the elevated global-priority Vulkan queue that fixes
-# it on this capability (measured 2026-08-08 on an RTX 5070 Ti: refused without it, granted REALTIME
-# with it; RADV the same). Narrow — scheduling priority only, no filesystem/network privilege, not
-# setuid.
 #
-# It has to be applied HERE, not in the merge hook: a merged sysext's /usr is a read-only squashfs,
+# 0.26.0-1 setcap'd the staged binary here for the GPU-priority lever. mksquashfs records
-# so nothing can setcap it afterwards. And it cannot ride in from the RPM either — the spec declares
+# security.capability, so the capability really did ship: verified by mounting the published
-# it with %caps, but rpm stores capabilities in its own header and `rpm2cpio | cpio` carries only
+# punktfunk-0.26.0-1-x86-64.raw, where `getcap usr/bin/punktfunk-host` reports `cap_sys_nice=ep`.
-# the payload, so the staged file arrives with no capability at all. mksquashfs DOES record
+# That broke desktop streaming on every Bazzite KDE box, field-reported as
-# security.capability (only security.selinux is excluded below), so a setcap on the staging tree is
+# "KWin does not expose zkde_screencast_unstable_v1 to this client".
-# what ends up in the image.
 #
-# Needs CAP_SETFCAP, i.e. root (or fakeroot) — a plain-user CI build cannot do it. That is not fatal:
+# KWin advertises its restricted protocols (zkde_screencast_unstable_v1 for the virtual output,
-# the image just ships as it does today and the encode runs at default GPU priority, so warn and
+# org_kde_kwin_fake_input for input) only to a client it can IDENTIFY, by resolving that client's
-# carry on rather than fail a release build over a performance lever.
+# /proc/<pid>/exe and matching it against an installed .desktop's Exec= — the image ships
-if [ -f "$STAGE/usr/bin/punktfunk-host" ]; then
+# usr/share/applications/io.unom.Punktfunk.Host.desktop for exactly that. The kernel refuses that
-  if setcap 'cap_sys_nice=ep' "$STAGE/usr/bin/punktfunk-host" 2>/dev/null; then
+# readlink to any reader whose effective set is not a superset of the target's PERMITTED set
-    echo "granted CAP_SYS_NICE to usr/bin/punktfunk-host (GPU-priority lever active)"
+# (cap_ptrace_access_check), and KWin holds no capabilities. So a capability in this image makes the
-  else
+# host unidentifiable and every Desktop-mode session dies. Full matrix, including why neither
-    echo "WARNING: could not setcap CAP_SYS_NICE (need root/CAP_SETFCAP) — the image will ship" >&2
+# prctl(PR_SET_DUMPABLE, 1) nor systemd AmbientCapabilities= rescues it, in
-    echo "         without it and PyroWave will encode at default GPU priority." >&2
+# packaging/arch/punktfunk-host.install.
+#
+# A merged sysext's /usr is a read-only squashfs, so this cannot be repaired on the box — the image
+# is the only place it can be got right. Assert it rather than trust it: the RPM payload arrives via
+# `rpm2cpio | cpio`, which carries no capabilities today, but the spec is one `%caps()` away from
+# changing that and this build would silently bake it in.
+if [ -f "$STAGE/usr/bin/punktfunk-host" ] && command -v getcap >/dev/null 2>&1; then
+  staged_caps="$(getcap "$STAGE/usr/bin/punktfunk-host" 2>/dev/null || true)"
+  if [ -n "$staged_caps" ]; then
+    echo "ERROR: staged usr/bin/punktfunk-host carries capabilities: $staged_caps" >&2
+    echo "       A capability makes the host unidentifiable to KWin and breaks every Desktop-mode" >&2
+    echo "       session on a merged image, which cannot be repaired on the box (read-only /usr)." >&2
+    exit 1
   fi
 fi
 

packaging/bazzite/punktfunk-sysext.sh

@@ -55,7 +55,9 @@ sy5uhYGZD6lMJ4uZAQC7W81H2gHlTDTA2Nq35HKW9IOU+Ll2c9fqa7fAIKf9Bg==
 usage() {
   sed -n 's/^#\( \|$\)//p' "$0" | sed -n '1,20p'
   echo "usage: punktfunk-sysext install [--channel stable|canary] [--from-file X.raw]"
-  echo "       punktfunk-sysext update [--from-file X.raw] | status | remove"
+  echo "       punktfunk-sysext update [--from-file X.raw] | reapply | status | remove"
+  echo "       reapply: re-run the host-state steps a sysext image cannot carry (groups, /etc"
+  echo "                mirrors, udev, sysctl, modules) without reinstalling the image."
   exit "${1:-0}"
 }
 need_root() { [ "$(id -u)" = 0 ] || { echo "run as root (sudo)" >&2; exit 1; }; }
@@ -174,6 +176,17 @@ post_merge() {
   # 'input': writing 'attach' materialises an arbitrary emulated USB device (review 2026-08-05 M-4),
   # so it stays a group users join on purpose — see `ujust add-user-to-input-group` for the other one.
   getent group punktfunk >/dev/null 2>&1 || groupadd --system punktfunk 2>/dev/null || :
+  # Creating the group is necessary but NOT sufficient, and the difference is invisible until a
+  # stream fails: `pf-dm-helper` gates on MEMBERSHIP, so a host whose user never joined gets
+  # "stopping the display manager needs privilege" on every managed takeover — sddm's autologin
+  # Relogin loop then churns logind sessions for the whole stream. Joining stays opt-in (writing
+  # vhci `attach` materialises an arbitrary emulated USB device), so say so instead of doing it.
+  local _pf_user="${SUDO_USER:-}"
+  if [ -n "$_pf_user" ] && ! id -nG "$_pf_user" 2>/dev/null | tr ' ' '\n' | grep -qx punktfunk; then
+    echo "!! $_pf_user is not in the 'punktfunk' group — the managed gamescope takeover cannot stop"
+    echo "!! the display manager, and the virtual Steam Deck pad cannot attach. To opt in:"
+    echo "!!     sudo usermod -aG punktfunk $_pf_user"
+  fi
   modprobe vhci-hcd 2>/dev/null || :
   # Re-fire the vhci rule against the (possibly already-present) controller so attach/detach pick up
   # the input-group ownership even when the module's original add event predated the reloaded rule.
@@ -265,7 +278,22 @@ cmd_update() {
   [ -n "$l" ] || { echo "no image in the feed $(feed_url)" >&2; exit 1; }
   ver="${l%% *}"
   if [ "$ver" = "$cur" ] && merged; then
-    echo "already on $cur (channel $(channel)) — nothing to do."
+    # NOT "nothing to do": re-run post_merge. Every step in it is idempotent, and skipping it here
+    # is how host state silently rots one release behind the image.
+    #
+    # The trap, field-proven on a Bazzite host that took 0.25.0 -> 0.26.0 (2026-08-09): an upgrade
+    # is driven by the script from the OLD image — this file is replaced by the very
+    # `systemd-sysext refresh` that runs mid-upgrade — so a post_merge step ADDED in the new
+    # release is executed by nobody. The old script doesn't have it, and the new script never gets
+    # a turn, because from then on `update` matches this branch and returns. The step is then
+    # permanently unreachable on exactly the installs that need it.
+    #
+    # That cost the `punktfunk` group (added to post_merge in 0.26.0): it was never created, so
+    # `pf-dm-helper` refused every caller — it gates on membership — and every managed gamescope
+    # takeover fell back to "stopping the display manager needs privilege", leaving sddm's autologin
+    # Relogin loop churning for the whole stream.
+    echo "already on $cur (channel $(channel)) — re-applying host state."
+    post_merge
     return
   fi
   echo "updating: ${cur:-<none>} -> $ver"
@@ -311,6 +339,7 @@ cmd_remove() {
 case "${1:-}" in
   install) shift; cmd_install "$@" ;;
   update)  shift; cmd_update "$@" ;;
+  reapply) shift; need_root; post_merge ;;
   status)  shift; cmd_status ;;
   remove)  shift; cmd_remove ;;
   *) usage ;;

packaging/debian/build-deb.sh

@@ -294,16 +294,23 @@ if [ "$1" = "configure" ]; then
     # primitive that must not ride on the group users are told to join for gamepads
     # (security-review 2026-08-05 M-4).
     getent group punktfunk >/dev/null 2>&1 || addgroup --system punktfunk 2>/dev/null || true
-    # CAP_SYS_NICE — the GPU-scheduling grant. PyroWave encodes on the shader cores a game
+    # NO capability on the host binary — and an active removal of the one 0.26.0-1 granted here.
-    # saturates, and the driver gates the elevated global-priority Vulkan queue that fixes it on
+    #
-    # this capability: measured 2026-08-08 on an RTX 5070 Ti, WITHOUT it every priority class is
+    # 0.26.0-1 ran `setcap cap_sys_nice=ep` at this point for the GPU-priority lever, and that broke
-    # refused and WITH it the encoder is granted REALTIME first try (RADV behaves the same).
+    # desktop streaming on every KDE box. KWin advertises its restricted protocols
-    # Without this line the knob exists and does nothing. Narrow: it permits raising scheduling
+    # (zkde_screencast_unstable_v1 for the virtual output, org_kde_kwin_fake_input for input) only
-    # priority only — no filesystem, network or user-switching privilege, and no setuid. Note a
+    # to a client it can IDENTIFY, by resolving that client's /proc/<pid>/exe and matching it
-    # capability-carrying binary is AT_SECURE, so the loader ignores LD_LIBRARY_PATH/LD_PRELOAD for
+    # against an installed .desktop's Exec=. The kernel refuses that readlink to any reader whose
-    # it and core dumps are suppressed by default. Best-effort: a box without libcap, or a
+    # effective set is not a superset of the target's PERMITTED set (cap_ptrace_access_check), and
-    # filesystem that cannot store capabilities, just runs at default priority as before.
+    # KWin holds no capabilities — so a capability here makes the host unidentifiable and the
-    setcap 'cap_sys_nice=ep' /usr/bin/punktfunk-host 2>/dev/null || true
+    # session dies with "KWin does not expose zkde_screencast_unstable_v1 to this client". Full
+    # matrix (and why PR_SET_DUMPABLE and AmbientCapabilities= both fail to rescue it) in
+    # packaging/arch/punktfunk-host.install.
+    #
+    # Costs pacing only: pf-zerocopy walks REALTIME -> HIGH -> default when a class is refused.
+    # postinst runs on upgrade too, so this heals boxes that installed 0.26.0-1. `setcap -r` exits
+    # non-zero on a file that has no capability, hence the redirect and `|| true`.
+    setcap -r /usr/bin/punktfunk-host 2>/dev/null || true
     # Pick up the /dev/uinput rule without a reboot (best-effort, no-op in containers).
     udevadm control --reload-rules 2>/dev/null || true
     udevadm trigger --subsystem-match=misc 2>/dev/null || true

packaging/nix/nixos-module.nix

@@ -356,25 +356,25 @@ in
         allowedUDPPorts = nativeUDP ++ optionals cfg.host.gamestream gamestreamUDP;
       };
 
-      # CAP_SYS_NICE — the GPU-scheduling grant. PyroWave encodes on the GPU shader cores a game
+      # NO CAP_SYS_NICE wrapper here — deliberately. 0.26.0-1 gave the host a
-      # saturates; the elevated global-priority Vulkan queue that fixes it is gated on this
+      # `security.wrappers.punktfunk-host` carrying `cap_sys_nice=ep` for the GPU-priority lever,
-      # capability (measured 2026-08-08, RTX 5070 Ti: without it EVERY priority class is refused,
+      # and that broke desktop streaming on every KDE box.
-      # with it the encoder gets REALTIME on the first attempt; RADV behaves the same).
       #
-      # NixOS cannot `setcap` a store path — it is read-only and shared — so this goes through
+      # KWin advertises its restricted Wayland protocols (zkde_screencast_unstable_v1 for the
-      # `security.wrappers`, which builds a small setcap'd wrapper in /run/wrappers/bin. The unit's
+      # virtual output, org_kde_kwin_fake_input for input) only to a client it can IDENTIFY, by
-      # ExecStart points at the wrapper below; everything else about the host is unchanged.
+      # resolving that client's /proc/<pid>/exe and matching it against an installed .desktop's
+      # Exec= (packages.nix substitutes ours to the store path). The kernel refuses that readlink to
+      # any reader whose effective set is not a superset of the target's PERMITTED set
+      # (cap_ptrace_access_check), and KWin holds no capabilities.
       #
-      # Narrow: CAP_SYS_NICE permits raising scheduling priority only — no filesystem, network or
+      # A NixOS wrapper does not dodge this. It raises the capability into its AMBIENT set before
-      # user-switching privilege, and the wrapper is capability-based, NOT setuid. Two side effects
+      # exec'ing the store binary, precisely so the capability survives — which lands CAP_SYS_NICE
-      # to know: the wrapped binary is AT_SECURE (the loader ignores LD_LIBRARY_PATH/LD_PRELOAD for
+      # in the exec'd process's permitted set and fails the readlink identically. Measured: an
-      # it) and core dumps are suppressed by default.
+      # ambient-only grant (dumpable=1, CapPrm set) is refused exactly like a file capability. See
-      security.wrappers.punktfunk-host = {
+      # packaging/arch/punktfunk-host.install for the full matrix.
-        source = "${cfg.host.package}/bin/punktfunk-host";
+      #
-        capabilities = "cap_sys_nice=ep";
+      # Costs pacing only: pf-zerocopy walks REALTIME -> HIGH -> default when a priority class is
-        owner = "root";
+      # refused, and pf-frame's thread nice is a best-effort no-op — 0.25.0's behaviour exactly.
-        group = "root";
-      };
 
       systemd.user.services.punktfunk-host = {
         description = "punktfunk GameStream + punktfunk/1 streaming host";
@@ -394,12 +394,12 @@ in
         # PUNKTFUNK_GAMESCOPE_BIN so an operator's own override of that env still wins.
         ++ optional cfg.host.gamescopeHdr cfg.host.gamescopePackage;
         serviceConfig = {
-          # Through the wrapper (see `security.wrappers.punktfunk-host` above), NOT the store path
+          # The store path DIRECTLY — not a capability wrapper. /proc/<pid>/exe then resolves to the
-          # directly — the store path carries no capability and the GPU-priority lever would be
+          # very path packages.nix substituted into io.unom.Punktfunk.Host.desktop's Exec=, which is
-          # inert. `config.security.wrapperDir` rather than a hard-coded /run/wrappers/bin so an
+          # what lets KWin identify the host and grant it the screencast/fake-input protocols (see
-          # operator who has moved it is still correct.
+          # the note above the firewall block).
           ExecStart =
-            "${config.security.wrapperDir}/punktfunk-host serve" + optionalString cfg.host.gamestream " --gamestream";
+            "${cfg.host.package}/bin/punktfunk-host serve" + optionalString cfg.host.gamestream " --gamestream";
           Restart = "on-failure";
           RestartSec = 2;
           EnvironmentFile =

packaging/rpm/punktfunk.spec

@@ -477,15 +477,28 @@ install -Dm0644 scripts/punktfunk-scripting.service %{buildroot}%{_userunitdir}/
 %files
 %license LICENSE-MIT LICENSE-APACHE THIRD-PARTY-NOTICES.txt
 %doc README.md packaging/README.md
-# CAP_SYS_NICE — the GPU-scheduling grant, declared the RPM-native way so rpm applies it at
+# NO %caps() on the host binary. 0.26.0-1 declared `%caps(cap_sys_nice=ep)` here for the
-# install, restores it on upgrade, and VERIFIES it (a plain %post setcap does none of those).
+# GPU-priority lever and that BROKE DESKTOP STREAMING ON EVERY KDE BOX — on Fedora and, via
-# PyroWave encodes on the shader cores a game saturates; the elevated global-priority Vulkan queue
+# rpm-ostree layering, on Bazzite, where it was field-reported as
-# that fixes it is gated on this capability. Measured 2026-08-08 on an RTX 5070 Ti: without it
+# "KWin does not expose zkde_screencast_unstable_v1 to this client".
-# every priority class is refused, with it the encoder gets REALTIME first try (RADV the same).
+#
-# Narrow — scheduling priority only, no filesystem/network/user-switching privilege, not setuid.
+# KWin hands out its restricted Wayland protocols (zkde_screencast_unstable_v1 for the virtual
-# Consequences: the binary becomes AT_SECURE, so the loader ignores LD_LIBRARY_PATH/LD_PRELOAD for
+# output, org_kde_kwin_fake_input for input) only to a client it can IDENTIFY, by resolving that
-# it, and core dumps are suppressed by default.
+# client's /proc/<pid>/exe and matching it against an installed .desktop's Exec= — ours is the
-%caps(cap_sys_nice=ep) %{_bindir}/punktfunk-host
+# io.unom.Punktfunk.Host.desktop installed below. The kernel refuses that readlink to any reader
+# whose effective set is not a superset of the target's PERMITTED set (cap_ptrace_access_check),
+# and KWin holds no capabilities. So a capability here makes the host unidentifiable: KWin's
+# executablePath() is empty, no .desktop can match, and the globals are never advertised.
+# Measured on kernel 7.1.6 — see packaging/arch/punktfunk-host.install for the full matrix, incl.
+# why neither prctl(PR_SET_DUMPABLE, 1) nor systemd AmbientCapabilities= rescues it.
+#
+# The cost of not having it is pacing only: pf-zerocopy walks REALTIME -> HIGH -> default when a
+# priority class is refused, and pf-frame's thread nice is a best-effort no-op. That is exactly
+# how 0.25.0 behaved, which is the behaviour that worked.
+#
+# rpm applies file capabilities from package metadata, so a package built WITHOUT %caps() installs
+# the binary with none and an upgrade from 0.26.0-1 clears it — no scriptlet needed.
+%{_bindir}/punktfunk-host
 %{_bindir}/punktfunk-tray
 %{_udevrulesdir}/60-punktfunk.rules
 %dir %{_libexecdir}/punktfunk

scripts/steamdeck/install.sh

@@ -344,24 +344,23 @@ if [ "$SUDO_OK" = 1 ]; then
         warn "(everything else works; the pad arrives as a generic Xbox 360 controller). By hand:"
         warn "  sudo groupadd --system punktfunk; sudo usermod -aG punktfunk $USER"
     fi
-    # CAP_SYS_NICE on the host binary — the GPU-scheduling grant, and the Deck is the box that
+    # NO CAP_SYS_NICE on the host binary — and a removal of the one 0.26.0-1 granted here.
-    # needs it most: a Van Gogh APU shares one small GPU between the game and PyroWave's encode
-    # dispatch. The driver gates the elevated global-priority Vulkan queue on this capability
-    # (measured 2026-08-08 on an RTX 5070 Ti: refused without it, granted REALTIME with it; RADV
-    # behaves the same), so without this the knob exists and does nothing.
     #
-    # The binary lives under $HOME, not /usr — so unlike the /etc drop-ins above this survives a
+    # 0.26.0-1 setcap'd this binary for the GPU-priority lever, which on a Van Gogh APU is a real
-    # SteamOS A/B update on its own and needs no atomic-keep entry. It DOES need re-applying after
+    # win. It also broke Desktop-mode streaming outright. Just above, this installer writes
-    # every rebuild, because a fresh binary is a new inode; re-running this installer does that.
+    # ~/.local/share/applications/io.unom.Punktfunk.Host.desktop with Exec=$BIN so KWin will grant
+    # the host its restricted protocols — and KWin makes that grant by resolving the client's
+    # /proc/<pid>/exe and matching it against that Exec=. The kernel refuses that readlink to any
+    # reader whose effective set is not a superset of the target's PERMITTED set
+    # (cap_ptrace_access_check), and KWin holds no capabilities. So the capability silently voided
+    # the .desktop written six lines earlier, and every Desktop-mode session died with
+    # "KWin does not expose zkde_screencast_unstable_v1 to this client". Gaming Mode (gamescope) is
+    # unaffected — it has no such gate. Full matrix in packaging/arch/punktfunk-host.install.
     #
-    # Narrow (scheduling priority only, no filesystem/network privilege, not setuid) and
+    # Costs pacing only: pf-zerocopy walks REALTIME -> HIGH -> default when a class is refused.
-    # best-effort — a failure just means the encode runs at default priority as it does today.
+    # `setcap -r` exits non-zero on a file that has no capability, hence the redirect.
     if [ -x "$BIN" ]; then
-        if sudo setcap 'cap_sys_nice=ep' "$BIN" 2>/dev/null; then
+        sudo setcap -r "$BIN" 2>/dev/null || true
-            ok "granted CAP_SYS_NICE (PyroWave encode can outrank a GPU-bound game)"
-        else
-            warn "could not grant CAP_SYS_NICE to $BIN — PyroWave encode stays at default GPU priority"
-        fi
     fi
     # SteamOS A/B updates rebuild /etc and DROP everything not on Valve's keep list — verified
     # live: an OS update stripped the udev rule + vhci autoload + UDP sysctl (gamepads silently

web/bun.lock

@@ -10,7 +10,7 @@
         "@tanstack/react-router": "^1.170.18",
         "@tanstack/react-start": "^1.168.32",
         "@unom/style": "^0.4.4",
-        "@unom/ui": "^0.8.16",
+        "@unom/ui": "^0.9.2",
         "class-variance-authority": "^0.7.1",
         "clsx": "^2.1.1",
         "lucide-react": "^0.469.0",
@@ -982,7 +982,7 @@
 
     "@unom/style": ["@unom/style@0.4.4", "https://git.unom.io/api/packages/unom/npm/%40unom%2Fstyle/-/0.4.4/style-0.4.4.tgz", { "peerDependencies": { "motion": "^12" } }, "sha512-M45nihK+LGyxwy2mmHYRKggaocTt+EKNVFNaMpTvTaIUpozi7bmKIkbM2/enMYS0/UYTaZrBSZs/a0nPXqkAKw=="],
 
-    "@unom/ui": ["@unom/ui@0.8.16", "https://git.unom.io/api/packages/unom/npm/%40unom%2Fui/-/0.8.16/ui-0.8.16.tgz", { "dependencies": { "@tanstack/react-router": "^1.170.11", "@tsdown/css": "^0.22.1", "clsx": "^2.1.1", "howler": "^2.2.4", "sonner": "^2.0.7", "tailwind-merge": "^3.6.0" }, "peerDependencies": { "@payloadcms/richtext-lexical": "^3.85.0", "@tanstack/react-virtual": "^3.14.2", "@unom/style": "^0.4.4", "class-variance-authority": "^0.7.1", "embla-carousel-react": "^8.6.0", "lucide-react": "^1.17.0", "motion": "^12.40.0", "radix-ui": "^1.4.3", "react": "^19.2.7", "react-dom": "^19.2.7", "typescript": "^6.0.3", "zod": "^4.4.3" } }, "sha512-ZH7VOyaRDT81VY8nm1hmx8a4CeObykP8egZbnV4Nju6kE8rQ28wdpBo0X+Zsdu8WvTEmHZGwPR53NHWJULyciw=="],
+    "@unom/ui": ["@unom/ui@0.9.2", "https://git.unom.io/api/packages/unom/npm/%40unom%2Fui/-/0.9.2/ui-0.9.2.tgz", { "dependencies": { "@tanstack/react-router": "^1.170.11", "@tsdown/css": "^0.22.1", "clsx": "^2.1.1", "howler": "^2.2.4", "sonner": "^2.0.7", "tailwind-merge": "^3.6.0" }, "peerDependencies": { "@payloadcms/richtext-lexical": "^3.85.0", "@tanstack/react-virtual": "^3.14.2", "@unom/style": "^0.4.4", "class-variance-authority": "^0.7.1", "embla-carousel-react": "^8.6.0", "lucide-react": "^1.17.0", "motion": "^12.40.0", "radix-ui": "^1.4.3", "react": "^19.2.7", "react-dom": "^19.2.7", "typescript": "^6.0.3", "zod": "^4.4.3" } }, "sha512-UbpNQEu6zRNMkAxsINRj6HvT53ty7+/QxN3TZv6WgQd/rLiLe767mjz4Zh765ASc3NY7EguHqVNuWX6L7V9TLA=="],
 
     "@vercel/nft": ["@vercel/nft@1.10.2", "", { "dependencies": { "@mapbox/node-pre-gyp": "^2.0.0", "@rollup/pluginutils": "^5.1.3", "acorn": "^8.6.0", "acorn-import-attributes": "^1.9.5", "async-sema": "^3.1.1", "bindings": "^1.4.0", "estree-walker": "2.0.2", "glob": "^13.0.0", "graceful-fs": "^4.2.9", "node-gyp-build": "^4.2.2", "picomatch": "^4.0.2", "resolve-from": "^5.0.0" }, "bin": { "nft": "out/cli.js" } }, "sha512-w+WyX5Ulmj4dtTZrxaulqrjaLZHSbnPzx75SJsTNYmotKsqn1JlLnDJa+lz5hn90HJofhl/2MAtw0mCrgM3qYw=="],
 

web/bun.nix

@@ -1902,10 +1902,10 @@
     hash = "sha512-M45nihK+LGyxwy2mmHYRKggaocTt+EKNVFNaMpTvTaIUpozi7bmKIkbM2/enMYS0/UYTaZrBSZs/a0nPXqkAKw==";
     name = "style-0.4.4.tgz";
   };
-  "@unom/ui@0.8.16" = fetchurl {
+  "@unom/ui@0.9.2" = fetchurl {
-    url = "https://git.unom.io/api/packages/unom/npm/%40unom%2Fui/-/0.8.16/ui-0.8.16.tgz";
+    url = "https://git.unom.io/api/packages/unom/npm/%40unom%2Fui/-/0.9.2/ui-0.9.2.tgz";
-    hash = "sha512-ZH7VOyaRDT81VY8nm1hmx8a4CeObykP8egZbnV4Nju6kE8rQ28wdpBo0X+Zsdu8WvTEmHZGwPR53NHWJULyciw==";
+    hash = "sha512-UbpNQEu6zRNMkAxsINRj6HvT53ty7+/QxN3TZv6WgQd/rLiLe767mjz4Zh765ASc3NY7EguHqVNuWX6L7V9TLA==";
-    name = "ui-0.8.16.tgz";
+    name = "ui-0.9.2.tgz";
   };
   "@vercel/nft@1.10.2" = fetchurl {
     url = "https://registry.npmjs.org/@vercel/nft/-/nft-1.10.2.tgz";

web/package.json

@@ -1,75 +1,75 @@
 {
-  "name": "punktfunk-web",
+	"name": "punktfunk-web",
-  "private": true,
+	"private": true,
-  "type": "module",
+	"type": "module",
-  "description": "punktfunk management console \u2014 TanStack Start + React Query (orval) + @unom/ui + Paraglide i18n",
+	"description": "punktfunk management console — TanStack Start + React Query (orval) + @unom/ui + Paraglide i18n",
-  "scripts": {
+	"scripts": {
-    "prepare": "bun run codegen",
+		"prepare": "bun run codegen",
-    "postinstall": "bun2nix -o bun.nix",
+		"postinstall": "bun2nix -o bun.nix",
-    "codegen": "orval --config orval.config.ts && paraglide-js compile --project ./project.inlang --outdir ./src/paraglide && node tools/check-i18n.mjs",
+		"codegen": "orval --config orval.config.ts && paraglide-js compile --project ./project.inlang --outdir ./src/paraglide && node tools/check-i18n.mjs",
-    "predev": "orval --config orval.config.ts",
+		"predev": "orval --config orval.config.ts",
-    "dev": "vite dev --port 47992",
+		"dev": "vite dev --port 47992",
-    "prebuild": "orval --config orval.config.ts",
+		"prebuild": "orval --config orval.config.ts",
-    "build": "vite build",
+		"build": "vite build",
-    "postbuild": "node tools/check-i18n.mjs",
+		"postbuild": "node tools/check-i18n.mjs",
-    "start": "bun run .output/server/index.mjs",
+		"start": "bun run .output/server/index.mjs",
-    "api:gen": "orval --config orval.config.ts",
+		"api:gen": "orval --config orval.config.ts",
-    "lint": "tsc --noEmit",
+		"lint": "tsc --noEmit",
-    "test": "bun test server/",
+		"test": "bun test server/",
-    "storybook": "storybook dev -p 6006",
+		"storybook": "storybook dev -p 6006",
-    "build-storybook": "storybook build",
+		"build-storybook": "storybook build",
-    "screenshots": "node tools/screenshots.mjs",
+		"screenshots": "node tools/screenshots.mjs",
-    "screenshots:build": "bun run build-storybook && node tools/screenshots.mjs"
+		"screenshots:build": "bun run build-storybook && node tools/screenshots.mjs"
-  },
+	},
-  "dependencies": {
+	"dependencies": {
-    "@fontsource-variable/geist": "^5.3.0",
+		"@fontsource-variable/geist": "^5.3.0",
-    "@tanstack/react-query": "^5.101.4",
+		"@tanstack/react-query": "^5.101.4",
-    "@tanstack/react-router": "^1.170.18",
+		"@tanstack/react-router": "^1.170.18",
-    "@tanstack/react-start": "^1.168.32",
+		"@tanstack/react-start": "^1.168.32",
-    "@unom/style": "^0.4.4",
+		"@unom/style": "^0.4.4",
-    "@unom/ui": "^0.8.16",
+		"@unom/ui": "^0.9.2",
-    "class-variance-authority": "^0.7.1",
+		"class-variance-authority": "^0.7.1",
-    "clsx": "^2.1.1",
+		"clsx": "^2.1.1",
-    "lucide-react": "^0.469.0",
+		"lucide-react": "^0.469.0",
-    "motion": "^12.42.2",
+		"motion": "^12.42.2",
-    "radix-ui": "^1.6.4",
+		"radix-ui": "^1.6.4",
-    "react": "^19.2.8",
+		"react": "^19.2.8",
-    "react-dom": "^19.2.8",
+		"react-dom": "^19.2.8",
-    "recharts": "^3.10.0",
+		"recharts": "^3.10.0",
-    "tailwind-merge": "^2.6.1",
+		"tailwind-merge": "^2.6.1",
-    "zod": "^4.4.3"
+		"zod": "^4.4.3"
-  },
+	},
-  "devDependencies": {
+	"devDependencies": {
-    "@biomejs/biome": "^2.5.5",
+		"@biomejs/biome": "^2.5.5",
-    "@inlang/paraglide-js": "^2.22.0",
+		"@inlang/paraglide-js": "^2.22.0",
-    "@inlang/plugin-message-format": "^4.4.0",
+		"@inlang/plugin-message-format": "^4.4.0",
-    "@storybook/react-vite": "^10.5.3",
+		"@storybook/react-vite": "^10.5.3",
-    "@tailwindcss/vite": "^4.3.3",
+		"@tailwindcss/vite": "^4.3.3",
-    "@tanstack/nitro-v2-vite-plugin": "^1.155.0",
+		"@tanstack/nitro-v2-vite-plugin": "^1.155.0",
-    "@types/node": "^22.20.1",
+		"@types/node": "^22.20.1",
-    "@types/react": "^19.2.17",
+		"@types/react": "^19.2.17",
-    "@types/react-dom": "^19.2.3",
+		"@types/react-dom": "^19.2.3",
-    "@vitejs/plugin-react": "^5.2.0",
+		"@vitejs/plugin-react": "^5.2.0",
-    "bun2nix": "2.1.2",
+		"bun2nix": "2.1.2",
-    "orval": "^8.22.0",
+		"orval": "^8.22.0",
-    "playwright": "^1.61.1",
+		"playwright": "^1.61.1",
-    "storybook": "^10.5.3",
+		"storybook": "^10.5.3",
-    "tailwindcss": "^4.3.3",
+		"tailwindcss": "^4.3.3",
-    "tw-animate-css": "^1.4.0",
+		"tw-animate-css": "^1.4.0",
-    "typescript": "^5.9.3",
+		"typescript": "^5.9.3",
-    "vite": "^7.3.6",
+		"vite": "^7.3.6",
-    "vite-tsconfig-paths": "^5.1.4"
+		"vite-tsconfig-paths": "^5.1.4"
-  },
+	},
-  "overrides": {
+	"overrides": {
-    "tar": "^7.5.21",
+		"tar": "^7.5.21",
-    "dompurify": "^3.4.12",
+		"dompurify": "^3.4.12",
-    "linkify-it": "^5.0.2",
+		"linkify-it": "^5.0.2",
-    "sharp": "^0.35.3",
+		"sharp": "^0.35.3",
-    "fast-uri": "^3.1.5",
+		"fast-uri": "^3.1.5",
-    "immutable": "^4.3.9",
+		"immutable": "^4.3.9",
-    "undici": "^7.29.0",
+		"undici": "^7.29.0",
-    "postcss": "^8.5.25",
+		"postcss": "^8.5.25",
-    "js-yaml": "^4.3.0",
+		"js-yaml": "^4.3.0",
-    "brace-expansion": "^5.0.9"
+		"brace-expansion": "^5.0.9"
-  }
+	}
 }

web/src/components/ui/card.tsx

@@ -27,13 +27,37 @@ const Card = ({
 );
 Card.displayName = "Card";
 
+/**
+ * The card inset, as ONE utility.
+ *
+ * It used to be `p-4 sm:p-6`, and that responsive pair is what made every padding override in this
+ * codebase unreliable: tailwind-merge resolves conflicts only *within* a variant, so a call-site
+ * `pt-6` beat the base `pt-0` and lost to `sm:pt-0` — correct on mobile, zero on desktop. Seven call
+ * sites had grown their own compensation for that in five different dialects.
+ *
+ * A single-variant token cannot half-lose. `--spacing-padding-card` is also what @unom/ui's own
+ * `Card` uses, so nested cards finally agree on their inset.
+ */
+const INSET = "p-padding-card";
+
+/**
+ * Body/footer padding, minus the top when something already sits above.
+ *
+ * The old code hard-coded `pt-0` because "a CardHeader supplies the top inset" — an assumption about
+ * a SIBLING that nothing enforced. Delete the header (exactly what tabbing a page does, since the
+ * tab label replaces the card title) and the top inset silently vanished at ≥640px. Asking the DOM
+ * instead of the author makes it self-correcting: first child keeps its inset, later children drop
+ * it.
+ */
+const INSET_AFTER_SIBLING = `${INSET} [&:not(:first-child)]:pt-0`;
+
 const CardHeader = React.forwardRef<
 	HTMLDivElement,
 	React.HTMLAttributes<HTMLDivElement>
 >(({ className, ...props }, ref) => (
 	<div
 		ref={ref}
-		className={cn("flex flex-col space-y-1.5 p-4 sm:p-6", className)}
+		className={cn("flex flex-col space-y-1.5", INSET, className)}
 		{...props}
 	/>
 ));
@@ -67,11 +91,12 @@ CardDescription.displayName = "CardDescription";
  * Card body. Pass `flush` for content that should meet the card's edges — a full-bleed table, most
  * commonly — instead of trying to cancel the padding from the outside.
  *
- * `className="p-0"` does NOT work for that: tailwind-merge only resolves conflicts *within the same
+ * Do NOT reach for `className="p-0"`: `flush` exists precisely so that intent is expressed as a prop
- * variant*, so `p-0` cancels `p-4` but leaves `sm:p-6` standing, and the padding silently returns at
+ * the component honours, rather than as a utility that has to out-argue the one already there.
- * ≥640px. Every call site that tried it ended up with a doubled inset once a `CardHeader` (which
+ *
- * brings its own `sm:p-6`) was nested inside — visible as one card whose title sits 24px further in
+ * Conversely, you no longer need to ADD top padding when there is no header — that is automatic now.
- * than its neighbours'.
+ * If you find yourself writing `pt-*` on a CardContent, the layout is telling you something else is
+ * wrong.
  */
 const CardContent = React.forwardRef<
 	HTMLDivElement,
@@ -79,7 +104,7 @@ const CardContent = React.forwardRef<
 >(({ className, flush = false, ...props }, ref) => (
 	<div
 		ref={ref}
-		className={cn(!flush && "p-4 pt-0 sm:p-6 sm:pt-0", className)}
+		className={cn(!flush && INSET_AFTER_SIBLING, className)}
 		{...props}
 	/>
 ));
@@ -91,7 +116,7 @@ const CardFooter = React.forwardRef<
 >(({ className, ...props }, ref) => (
 	<div
 		ref={ref}
-		className={cn("flex items-center p-4 pt-0 sm:p-6 sm:pt-0", className)}
+		className={cn("flex items-center", INSET_AFTER_SIBLING, className)}
 		{...props}
 	/>
 ));

web/src/sections/Dashboard/view.tsx

@@ -62,7 +62,7 @@ export const DashboardView: FC<{
 								    only the GameStream certs read as "0 paired" on a host every
 								    one of whose clients was in fact paired. */}
 								<Card>
-									<CardContent className="flex flex-1 items-center justify-between p-4 sm:pt-6">
+									<CardContent className="flex flex-1 items-center justify-between">
 										<span className="text-sm text-muted-foreground">
 											{m.status_paired_count()}
 										</span>
@@ -72,7 +72,7 @@ export const DashboardView: FC<{
 									</CardContent>
 								</Card>
 								<Card>
-									<CardContent className="flex flex-1 items-center justify-between p-4 sm:pt-6">
+									<CardContent className="flex flex-1 items-center justify-between">
 										<span className="text-sm text-muted-foreground">
 											{m.status_pin_pending()}
 										</span>
@@ -206,7 +206,10 @@ export const DashboardView: FC<{
  * else except the host log.
  */
 const AudioWiringCard: FC<{ audio: AudioWiring }> = ({ audio }) => {
-	const badge: { variant: "success" | "secondary" | "destructive"; text: string } =
+	const badge: {
+		variant: "success" | "secondary" | "destructive";
+		text: string;
+	} =
 		audio.readiness === "full"
 			? { variant: "success", text: m.audio_ready() }
 			: audio.readiness === "audio_only"
@@ -257,7 +260,7 @@ const StatCard: FC<{ icon: ReactNode; label: string; on: boolean }> = ({
 	on,
 }) => (
 	<Card>
-		<CardContent className="flex flex-1 items-center justify-between p-4 sm:pt-6">
+		<CardContent className="flex flex-1 items-center justify-between">
 			<span className="flex items-center gap-2 text-sm text-muted-foreground">
 				{icon}
 				{label}

web/src/sections/Displays/DisplayCard.tsx

@@ -41,9 +41,10 @@ import { QueryState } from "@/components/query-state";
 import { Stagger } from "@/components/stagger";
 import { Badge } from "@/components/ui/badge";
 import { Button } from "@/components/ui/button";
-import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
+import { Card, CardContent } from "@/components/ui/card";
 import { InputNumber } from "@/components/ui/input-number";
 import { Label } from "@/components/ui/label";
+import { Tabs, TabsContent, TabsList, TabsTrigger } from "@/components/ui/tabs";
 import { apiErrorMessage } from "@/lib/errors";
 import { cn } from "@/lib/utils";
 import { m } from "@/paraglide/messages";
@@ -177,17 +178,11 @@ export const DisplaySection: FC = () => {
 	});
 
 	return (
-		<div className="flex flex-col gap-card">
+		<DisplayTabs
-			<Card>
+			dirty={dirty}
-				<CardHeader>
+			live={<LiveDisplays />}
-					<div className="flex flex-wrap items-center justify-between gap-2">
+			configuration={
-						<CardTitle>{m.display_config_title()}</CardTitle>
+				<>
-						{/* Visible without scrolling to the save button — the card is taller than the
-						    viewport, which is exactly how the pending edits went unnoticed. */}
-						{dirty && <Badge variant="warning">{m.display_unsaved()}</Badge>}
-					</div>
-				</CardHeader>
-				<CardContent className="space-y-4">
 					<p className="max-w-prose text-sm text-muted-foreground">
 						{m.host_displays_help()}
 					</p>
@@ -226,20 +221,64 @@ export const DisplaySection: FC = () => {
 							/>
 						)}
 					</QueryState>
-				</CardContent>
+				</>
-			</Card>
+			}
-			<Card>
+		/>
-				<CardHeader>
-					<CardTitle>{m.display_live()}</CardTitle>
-				</CardHeader>
-				<CardContent>
-					<LiveDisplays />
-				</CardContent>
-			</Card>
-		</div>
 	);
 };
 
+/**
+ * The page's tab shell: **Configuration** and **Live displays** as the same pill strip the plugin
+ * UIs use, over a card per tab.
+ *
+ * Tabs rather than two stacked cards because the configuration card alone is taller than the
+ * viewport — which is how pending edits went unnoticed — and the live list sat below it, effectively
+ * off screen.
+ *
+ * Presentational on purpose, taking both panes as nodes: `DisplaySection` cannot be rendered in
+ * Storybook (it calls `useBlocker`, which needs a router), so putting the strip here is what keeps
+ * it reachable from a story. That matters more than usual on this page — `Displays.stories.tsx`
+ * exists to pin the MOTION NESTING of the preset grid, and inserting tabs changes that ancestor
+ * chain, so the story has to render the real one.
+ */
+export const DisplayTabs: FC<{
+	dirty: boolean;
+	configuration: ReactNode;
+	live: ReactNode;
+}> = ({ dirty, configuration, live }) => (
+	<Tabs defaultValue="configuration" className="gap-card">
+		<TabsList>
+			<TabsTrigger value="configuration">
+				{m.display_config_title()}
+				{/* The dirty marker rides the TAB, not the card header. It used to sit inside a card
+				    taller than the viewport; behind a tab it would vanish altogether while the Live
+				    tab was open. On the trigger it survives both — and the Custom block keeps its
+				    own inline badge, so nothing is lost when this tab IS open. */}
+				{dirty && (
+					<span
+						role="status"
+						aria-label={m.display_unsaved()}
+						className="ml-1.5 size-2 shrink-0 rounded-full bg-[var(--warning)]"
+					/>
+				)}
+			</TabsTrigger>
+			<TabsTrigger value="live">{m.display_live()}</TabsTrigger>
+		</TabsList>
+
+		<TabsContent value="configuration">
+			<Card>
+				<CardContent className="space-y-4">{configuration}</CardContent>
+			</Card>
+		</TabsContent>
+
+		<TabsContent value="live">
+			<Card>
+				<CardContent>{live}</CardContent>
+			</Card>
+		</TabsContent>
+	</Tabs>
+);
+
 /**
  * The gate on anything that would throw unsaved Custom fields away — asked from three places (a
  * preset click, applying a saved preset, and leaving the page), so it is written once. A function

web/src/sections/Host/ConflictsCard.tsx

@@ -28,7 +28,7 @@ export const ConflictsCard: FC = () => {
 	if (conflicts.length === 0) return null;
 	return (
 		<Card className="border-amber-600/40 dark:border-amber-500/40">
-			<CardContent className="flex items-start gap-3 p-card pt-card sm:pt-card">
+			<CardContent className="flex items-start gap-3">
 				<AlertTriangle className="mt-0.5 size-5 shrink-0 text-amber-600 dark:text-amber-500" />
 				<div className="min-w-0 flex-1 space-y-2">
 					<p className="text-sm font-medium text-amber-600 dark:text-amber-500">

web/src/sections/Logs/LogsCard.tsx

@@ -238,13 +238,10 @@ export const LogsCard: FC<{
 
 	return (
 		<Card>
-			{/* This card has no CardHeader, so it has to put the top padding back itself — and it
+			{/* No CardHeader here, and that no longer needs saying: CardContent keeps its top inset
-			    must do so at BOTH breakpoints. `CardContent` is `p-4 pt-0 sm:p-6 sm:pt-0`, and
+			    unless something precedes it. This card used to restore it by hand at both
-			    tailwind-merge only resolves conflicts within the same variant: a bare `pt-6` cancels
+			    breakpoints. */}
-			    `pt-0` but leaves `sm:pt-0` standing, so the padding was 24px on a phone and 0 on a
+			<CardContent className="flex flex-col gap-3">
-			    desktop, with the filter row touching the card's edge. (Same trap the `p-0` note in
-			    components/ui/card.tsx describes, in the other direction.) */}
-			<CardContent className="flex flex-col gap-3 pt-4 sm:pt-6">
 				<div className="flex flex-wrap items-center gap-2">
 					<div className="flex items-center gap-1">
 						{LEVELS.map((l) => (

web/src/sections/Pairing/PairedDevices.tsx

@@ -135,7 +135,7 @@ export const PairedDevices: FC<{
 			<h2 className="text-lg font-medium">{m.pairing_native_devices()}</h2>
 		</CardHeader>
 
-		<CardContent className="p-6">
+		<CardContent>
 			<QueryState isLoading={isLoading} error={error} refetch={refetch}>
 				{rows.length === 0 ? (
 					m.pairing_native_empty()

web/src/sections/Store/JobProgress.tsx

@@ -55,7 +55,7 @@ export const JobProgressSection: FC<{
 		if (!job.isError) return null;
 		return (
 			<Card className="ring-2 ring-destructive/60">
-				<CardContent className="flex items-start gap-3 p-card pt-card sm:pt-card">
+				<CardContent className="flex items-start gap-3">
 					<XCircle className="mt-0.5 size-5 shrink-0 text-destructive" />
 					<div className="min-w-0 flex-1">
 						<p className="text-sm font-medium">{m.store_job_lost()}</p>
@@ -92,7 +92,7 @@ export const JobProgressCard: FC<{
 			className={failed ? "ring-2 ring-destructive/60" : undefined}
 			aria-live="polite"
 		>
-			<CardContent className="space-y-3 p-card pt-card sm:pt-card">
+			<CardContent className="space-y-3">
 				<div className="flex items-start gap-3">
 					{running ? (
 						<Spinner className="mt-0.5 size-5 shrink-0" />

web/src/stories/Card.stories.tsx

@@ -21,6 +21,42 @@ const meta = {
 export default meta;
 type Story = StoryObj<typeof meta>;
 
+/**
+ * The inset contract — the thing this card got wrong most often.
+ *
+ * `CardContent` drops its top padding only when something already sits above it. The pair below is
+ * the regression guard: both cards must show the same inset on every side, and the headerless one
+ * must not have its first line touching the top edge.
+ *
+ * It used to be wrong invisibly, and only on desktop. The padding was `p-4 pt-0 sm:p-6 sm:pt-0`, so
+ * a headerless card had to restore the top inset itself — and a call-site `pt-6` beat the base
+ * `pt-0` while losing to `sm:pt-0`, because tailwind-merge resolves conflicts only within a variant.
+ * Right on a phone, zero on a desktop. Seven call sites had grown their own workaround for it.
+ *
+ * ⚠ Check this at BOTH viewport widths. A single width cannot show that class of bug.
+ */
+export const InsetWithAndWithoutHeader: Story = {
+	render: () => (
+		<div className="grid gap-4 sm:grid-cols-2">
+			<Card>
+				<CardHeader>
+					<CardTitle>With a header</CardTitle>
+				</CardHeader>
+				<CardContent className="text-sm text-muted-foreground">
+					The body drops its top inset because the header above already supplied
+					one.
+				</CardContent>
+			</Card>
+			<Card>
+				<CardContent className="text-sm text-muted-foreground">
+					No header, so the body keeps its own top inset — automatically, with
+					nothing for the call site to remember.
+				</CardContent>
+			</Card>
+		</div>
+	),
+};
+
 export const HostCard: Story = {
 	render: () => (
 		<Card className="max-w-sm">

web/src/stories/Displays.stories.tsx

@@ -1,9 +1,8 @@
 import type { Meta, StoryObj } from "@storybook/react-vite";
 import { useState } from "react";
+import { userEvent, within } from "storybook/test";
 import type { DisplayPolicy } from "@/api/gen/model/displayPolicy";
-import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
+import { DisplayForm, DisplayTabs } from "@/sections/Displays/DisplayCard";
-import { m } from "@/paraglide/messages";
-import { DisplayForm } from "@/sections/Displays/DisplayCard";
 import {
 	displayCustomPresets,
 	displayEffective,
@@ -19,17 +18,29 @@ import {
  * frame while every other grid in the console staggered. It is invisible in a diff and invisible to
  * `tsc`; only a rendered page shows it.
  *
- * So the `<Card>` wrapper below is NOT decoration. It reproduces the page's motion nesting, which is
+ * So the wrapper below is NOT decoration. It reproduces the page's motion nesting, which is the
- * the thing under test — dropping it would make the story pass for the wrong reason.
+ * thing under test — dropping it would make the story pass for the wrong reason. It renders the
+ * page's real `DisplayTabs` shell for exactly that reason: the tabs sit between the page `<Section>`
+ * and the card, so they are part of the ancestor chain this story exists to pin.
  */
-const Harness = ({ seed }: { seed: DisplayPolicy }) => {
+const Harness = ({
+	seed,
+	dirty = false,
+}: {
+	seed: DisplayPolicy;
+	dirty?: boolean;
+}) => {
 	const [draft, setDraft] = useState<DisplayPolicy>(seed);
 	return (
-		<Card>
+		<DisplayTabs
-			<CardHeader>
+			dirty={dirty}
-				<CardTitle>{m.display_config_title()}</CardTitle>
+			live={
-			</CardHeader>
+				<p className="text-sm text-muted-foreground">
-			<CardContent className="space-y-4">
+					The live list reads `/display/state`, so it is not part of this story
+					— see the tab strip and the Configuration pane.
+				</p>
+			}
+			configuration={
 				<DisplayForm
 					draft={draft}
 					setDraft={setDraft}
@@ -41,11 +52,11 @@ const Harness = ({ seed }: { seed: DisplayPolicy }) => {
 					applyAxis={(patch) => setDraft({ ...draft, ...patch })}
 					saveDraft={() => {}}
 					busy={false}
-					dirty={false}
+					dirty={dirty}
 					revert={() => {}}
 				/>
-			</CardContent>
+			}
-		</Card>
+		/>
 	);
 };
 
@@ -70,11 +81,10 @@ export const CustomFields: Story = {
 export const NoCustomPresets: Story = {
 	args: { seed: displayPolicy },
 	render: (args) => (
-		<Card>
+		<DisplayTabs
-			<CardHeader>
+			dirty={false}
-				<CardTitle>{m.display_config_title()}</CardTitle>
+			live={null}
-			</CardHeader>
+			configuration={
-			<CardContent className="space-y-4">
 				<DisplayForm
 					draft={args.seed}
 					setDraft={() => {}}
@@ -89,7 +99,22 @@ export const NoCustomPresets: Story = {
 					dirty={false}
 					revert={() => {}}
 				/>
-			</CardContent>
+			}
-		</Card>
+		/>
 	),
 };
+
+/**
+ * Unsaved Custom edits, with the Configuration tab NOT open.
+ *
+ * The dirty marker has to survive being on the other tab — the whole reason it moved off the card
+ * header and onto the trigger. If this story ever shows a bare "Configuration" label, the warning
+ * has gone silent exactly when it matters most.
+ */
+export const UnsavedOnOtherTab: Story = {
+	args: { seed: { ...displayPolicy, preset: "custom" }, dirty: true },
+	play: async ({ canvasElement }) => {
+		const canvas = within(canvasElement);
+		await userEvent.click(await canvas.findByRole("tab", { name: /Live/i }));
+	},
+};