feat(clients): an OLED palette, and split WHETHER the gamepad UI is offered from WHEN it appears

Four changes to the client interface, kept together because two of them touch the same rows
and the last is a bug the first would have made far more visible.

A thirteenth `ui_palette` entry, `oled`. The palette table is hand-mirrored in three languages
(`pf-console-ui`'s `library.rs`, `GamepadPalette.swift`, `GamepadPalette.kt`), so it goes into
all three at index 1, directly after the brand default — which keeps `PALETTES[0]` the unknown-id
fallback and keeps the dark-to-pale cycling order intact. What earns the name is arithmetic, not
a darker shade of violet: the ramp's first two stops are literally (0,0,0) and the ground is pure
black, so the shaded half of the field is pixels switched off rather than "very dark grey", and
the calm mix the form screens sit under lifts toward nothing at all. Mean cell luminance is 0.019
against Violet's 0.254. The bright corner keeps a faint indigo-to-violet ember so the backdrop is
still a field with somewhere to go, and that ember carries enough chroma at that luminance
(60 degrees of hue travel across 13 of the 16 cells) to satisfy the existing multi-tone assertion
without adding `oled` to the near-neutral exemption Graphite and Opal take. Each port gains an
`oled_is_actually_black` test that measures the claim — pure-black corner cells, a mean under half
the darkest other field's — rather than restating the table.

A new device key, `gamepad_ui_mode`. The gamepad-UI switch had been deciding two things at once:
whether to offer the controller-optimized interface at all, and that it appears only while a pad
is attached. A user asked for the second half to stop applying. `"connected"` (the default, and
exactly what the lone Bool meant) and `"always"` separate them, surfaced as a "Show it" row
directly under the switch on all five settings surfaces and built only while that switch is on —
a picker whose every option decides nothing is worse than no picker. `GamepadUIEnvironment.isActive`
takes the mode with NO default argument on purpose: a call site that forgot it would silently
strand everyone who chose Always back on "only with a controller", which is the one bug this
parameter exists to make impossible. An unrecognized value waits for a controller, so a mode a
newer client wrote can never trap an older one in a layout it has no way back out of. It stays a
device preference on both platforms, never part of a profile: which interface this device wears
has nothing to do with how a host streams to it.

The smoothness buffer is hidden under Lowest latency, not dimmed. Everywhere else already hid it
— the GTK and WinUI shells, the Apple touch and tvOS screens, the Android touch screen — because
under that intent it names a quantity that does not exist. Two surfaces disagreed: Apple's gamepad
settings screen left the row live and steppable, and the desktop console dimmed it, having no way
to drop a row from a fixed list. That list is now rebuilt each frame through a `row_applies`
filter. The concern about a vanishing row moving everything under the cursor does not apply here
and the new test says why: the row it drops sits directly BELOW the row that drops it, so the only
cursor that can be present when the list shrinks is the one on the intent row, which does not
move. Two latent hazards went with it — `apply_row` had been indexing the row list on the
assumption the cursor is always in range, and nothing re-clamped that cursor when another writer
changed the intent behind the screen's back.

Pale palettes were unreadable on tvOS, reported from the field. `GamepadInk` was never the
problem: it flips correctly for a pale field, it is not platform-gated, and every tvOS gamepad
entry point already published it. The cause is that this app sets `preferredColorScheme` nowhere
and declares no `UIUserInterfaceStyle`, so every SYSTEM-derived colour landing on those screens —
a `.secondary` placeholder, a `.bordered` button's chrome, a NavigationStack title, a material's
frost — resolved against the DEVICE appearance, which the palette cannot reach. On iPhone, iPad
and Mac a great many users sit in Light mode, so under a pale palette those colours came out dark
and the theme looked correct by accident; an Apple TV is Dark essentially always, so every one of
them rendered white on a light field. The mirror image was broken too and had simply never been
reported: a dark palette on a Light-mode iPhone was already drawing dark on dark. The scheme is
now published beside the ink, once, in `GamepadInkModifier`, because the two are halves of one
decision and publishing only the ink silently loses every colour the frameworks draw on the app's
behalf. Two structural amplifiers went with it: `ConsoleGlass` had been scoping the scheme to the
fill inside its `.background {}` on the tvOS and pre-26 branches while the 26 branch put it on the
content, so no console row's own content ever saw it on tvOS; and `LibraryView`'s navigation
chrome and its loading, error and empty states sit above `LibraryCoverflowView` and so were never
inked at all on tvOS and macOS, where that view is presented directly rather than through the
iOS-only `GamepadLibraryScreen` wrapper.

That last one exposed a second tvOS gap worth closing in the same breath: `ui_palette` had no row
in tvOS's ordinary Settings, and the gamepad settings screen that owns it everywhere else needs an
extended-profile controller to open on tvOS. An Apple TV driven by the Siri Remote alone could not
reach the palettes at all, which would now include the OLED one. `SettingsView.tvBody` carries a
Background row.

Verified: pf-console-ui builds, passes `clippy --all-targets -D warnings` and runs 74 tests clean
under linux/amd64 (a Mac `cargo check` of that crate is vacuous — every module is cfg'd to
linux/windows); `cargo fmt --check` clean for it and pf-client-core. Android `:app` runs 80 tests
with 0 failures, including four new `gamepadUiActive` cases and the palette parity table. The
Apple package builds for macOS AND tvOS and its 9 palette/gamepad-UI tests pass — the tvOS
typecheck is possible because the checked-in xcframework already carries a `tvos-arm64` slice. The
tvOS RENDERING fix is compile-verified only; an on-glass Apple TV check under a pale palette is
still owed, and is the one thing here that a build cannot answer.

clients/apple/Sources/PunktfunkClient/ContentView.swift

@@ -99,6 +99,10 @@ struct ContentView: View {
     // with no (extended) controller attached tvOS falls back to HomeView as before.
     @ObservedObject private var gamepadManager = GamepadManager.shared
     @AppStorage(DefaultsKey.gamepadUIEnabled) private var gamepadUIEnabled = true
+    /// When the switch above takes over — "connected" (default) or "always". See
+    /// `GamepadUIEnvironment`.
+    @AppStorage(DefaultsKey.gamepadUIMode) private var gamepadUIMode =
+        GamepadUIEnvironment.modeWhenConnected
     /// Auto-wake on connect (Settings → General). On (default): a dial to an offline saved host
     /// fires Wake-on-LAN up front and falls into the "Waking…" wait if the dial fails. Off: connects
     /// go straight through with no wake. The explicit "Wake Host" action is unaffected either way.
@@ -113,7 +117,8 @@ struct ContentView: View {
     @Environment(\.scenePhase) private var scenePhase
     private var gamepadUIActive: Bool {
         GamepadUIEnvironment.isActive(
-            gamepadConnected: gamepadManager.active != nil, enabledSetting: gamepadUIEnabled)
+            gamepadConnected: gamepadManager.active != nil, enabledSetting: gamepadUIEnabled,
+            mode: gamepadUIMode)
     }
 
     // The body is split in two — `driven` (the screen plus its lifecycle drivers and sheets) and

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

@@ -85,16 +85,40 @@ extension EnvironmentValues {
 }
 
 extension View {
-    /// Resolve the stored `ui_palette` and publish its ink to everything below. Applied by the
-    /// gamepad screens' common root so no individual view has to read the setting.
-    func gamepadPaletteInk() -> some View { modifier(GamepadInkModifier()) }
+    /// Resolve the stored `ui_palette` and publish its ink — AND the matching colour scheme — to
+    /// everything below. Applied by the gamepad screens' common root so no individual view has to
+    /// read the setting.
+    ///
+    /// `active` exists for the one surface that is the same view in both worlds: `LibraryView`
+    /// renders the coverflow under the gamepad UI and a plain grid without it. Passing `false`
+    /// publishes nothing, because the touch/desktop layouts sit on the SYSTEM background, where a
+    /// palette's scheme would invert their own system colours instead of matching them.
+    func gamepadPaletteInk(_ active: Bool = true) -> some View {
+        modifier(GamepadInkModifier(active: active))
+    }
 }
 
 private struct GamepadInkModifier: ViewModifier {
+    var active = true
     @AppStorage(DefaultsKey.uiPalette) private var paletteID = "violet"
+    /// The ambient scheme from ABOVE this modifier — what gets republished unchanged when the
+    /// gamepad UI isn't the one drawing, so `active: false` is a true no-op rather than a branch
+    /// that would change this view's identity.
+    @Environment(\.colorScheme) private var systemScheme
 
     func body(content: Content) -> some View {
-        content.environment(\.gamepadInk, GamepadInk.of(GamepadPalette.named(paletteID)))
+        let palette = GamepadPalette.named(paletteID)
+        return content
+            .environment(\.gamepadInk, active ? GamepadInk.of(palette) : .dark)
+            // The ink alone was never enough. Every SYSTEM-derived colour that lands on these
+            // screens — `.secondary` in a placeholder, a `.bordered` button's chrome, a
+            // NavigationStack's title, a material's frost — resolves against the DEVICE's
+            // appearance, which no part of this app had ever set. On iPhone and Mac that is often
+            // Light, so the pale palettes looked correct by accident; an Apple TV is Dark
+            // essentially always, so on tvOS every one of them came out WHITE on a pale field and
+            // the interface was unreadable. Publishing the scheme here — once, beside the ink it
+            // has to agree with — is what makes a pale palette mean "light" to UIKit too.
+            .environment(\.colorScheme, active ? (palette.light ? .light : .dark) : systemScheme)
     }
 }
 

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

@@ -32,9 +32,12 @@ struct LibraryView: View {
     // setting off) every platform keeps the plain-grid presentation of this same view.
     @ObservedObject private var gamepadManager = GamepadManager.shared
     @AppStorage(DefaultsKey.gamepadUIEnabled) private var gamepadUIEnabled = true
+    @AppStorage(DefaultsKey.gamepadUIMode) private var gamepadUIMode =
+        GamepadUIEnvironment.modeWhenConnected
     private var gamepadUIActive: Bool {
         GamepadUIEnvironment.isActive(
-            gamepadConnected: gamepadManager.active != nil, enabledSetting: gamepadUIEnabled)
+            gamepadConnected: gamepadManager.active != nil, enabledSetting: gamepadUIEnabled,
+            mode: gamepadUIMode)
     }
     #endif
 
@@ -78,6 +81,16 @@ struct LibraryView: View {
                 }
             }
             #endif
+            #if os(iOS) || os(macOS) || os(tvOS)
+            // Published HERE, not just inside the coverflow, because the coverflow is only one of
+            // four things this view renders: the loading spinner, the error state and the empty
+            // state sit above it, as do the navigation title and toolbar. On iOS those are wrapped
+            // by GamepadLibraryScreen, which inks the whole thing; tvOS and macOS present this view
+            // directly in a NavigationStack, so under a pale palette every one of them kept the
+            // system's own (dark, on an Apple TV) chrome over a light field. Off when the gamepad
+            // UI isn't drawing — the plain grid belongs to the system background.
+            .gamepadPaletteInk(gamepadUIActive)
+            #endif
     }
 
     @ViewBuilder private var content: some View {

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

@@ -81,6 +81,9 @@ struct GamepadSettingsView: View {
     @AppStorage(DefaultsKey.hudPlacement) private var hudPlacement = HUDPlacement.topTrailing.rawValue
     @AppStorage(DefaultsKey.libraryEnabled) private var libraryEnabled = true
     @AppStorage(DefaultsKey.gamepadUIEnabled) private var gamepadUIEnabled = true
+    /// When the switch above takes over — the row is only built while it is on.
+    @AppStorage(DefaultsKey.gamepadUIMode) private var gamepadUIMode =
+        GamepadUIEnvironment.modeWhenConnected
     /// The gamepad UI's background colour family — the backdrop BEHIND this screen re-colours as
     /// the row steps, which is why the picker lives here and not in a sheet.
     @AppStorage(DefaultsKey.uiPalette) private var paletteID = "violet"
@@ -659,6 +662,21 @@ struct GamepadSettingsView: View {
                 detail: "Turn off to use the touch interface even with a controller connected.",
                 value: $gamepadUIEnabled),
         ]
+        // WHEN the switch above takes over. Built only while it is on: with the switch off this
+        // screen is unreachable in the first place (no gamepad UI to open it from), so a row
+        // that decides nothing would exist purely to be found in a screenshot.
+        if gamepadUIEnabled, let at = list.firstIndex(where: { $0.id == "gamepadUI" }) {
+            list.insert(
+                choiceRow(
+                    id: "gamepadUIMode", tab: .interface, icon: "gamecontroller.circle",
+                    label: "Show it",
+                    detail: "With a controller: the touch interface comes back when the last one "
+                        + "disconnects. Always keeps this layout either way — for a device that "
+                        + "lives on a TV.",
+                    options: SettingsOptions.gamepadUIModes, current: gamepadUIMode
+                ) { gamepadUIMode = $0 },
+                at: at + 1)
+        }
         #if os(macOS)
         // The windowed safe-present toggle slots in after "Smoothness buffer" (staying inside
         // the Video tab) — macOS only, mirroring the touch SettingsView's Presentation row
@@ -707,6 +725,14 @@ struct GamepadSettingsView: View {
                 at: anchor + 1)
         }
         #endif
+        // The smoothness buffer only decides anything under Smoothness. Every other settings
+        // surface — touch, tvOS, the GTK and WinUI shells — hides it under Lowest latency; this
+        // screen alone left it live and steppable, which is a row that thuds or silently stores
+        // a value nothing reads. Removed here rather than omitted from the literal above so the
+        // macOS safe-present insertion can still anchor on it.
+        if presentPriority != "smooth" {
+            list.removeAll { $0.id == "smoothBuffer" }
+        }
         return list + profileRows
     }
 

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

@@ -53,6 +53,14 @@ enum SettingsOptions {
     static let hudPlacements: [(label: String, tag: String)] =
         HUDPlacement.allCases.map { ($0.label, $0.rawValue) }
 
+    /// When the gamepad UI takes over (`DefaultsKey.gamepadUIMode`) — only meaningful while
+    /// `gamepadUIEnabled` is on, so every surface that offers it hides the row when the switch
+    /// is off rather than showing a picker that decides nothing.
+    static let gamepadUIModes: [(label: String, tag: String)] = [
+        ("With a controller", GamepadUIEnvironment.modeWhenConnected),
+        ("Always", GamepadUIEnvironment.modeAlways),
+    ]
+
     /// Presentation intent (`DefaultsKey.presentPriority` — the 2026-07 rebuild that replaced
     /// the visible stage picker with intent; see SessionPresenter's PresentPriority and
     /// design/apple-presentation-rebuild.md). The stage ladder survives only as the hidden

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

@@ -724,11 +724,24 @@ extension SettingsView {
             #endif
             #if !os(tvOS)
             if !inProfileScope {
-                described("With a controller connected, the host list and library switch to a "
-                    + "controller-friendly layout — larger focus targets, a swipeable cover "
-                    + "browser.") {
+                described("The host list and library switch to a controller-friendly layout — "
+                    + "larger focus targets, a swipeable cover browser.") {
                     Toggle("Gamepad-optimized browsing", isOn: $gamepadUIEnabled)
                 }
+                // Only meaningful while the switch above is on, so it is HIDDEN rather than
+                // disabled when it isn't: a picker whose every option decides nothing is worse
+                // than no picker, and this Section is short enough that nothing jumps far.
+                if gamepadUIEnabled {
+                    described("With a controller: the touch interface comes back when the last "
+                        + "one disconnects. Always keeps the controller-friendly layout either "
+                        + "way — for a device that lives on a TV.") {
+                        Picker("Show it", selection: $gamepadUIMode) {
+                            ForEach(SettingsOptions.gamepadUIModes, id: \.tag) { option in
+                                Text(option.label).tag(option.tag)
+                            }
+                        }
+                    }
+                }
             }
             #endif
             #if DEBUG && !os(tvOS)

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

@@ -75,6 +75,13 @@ struct SettingsView: View {
     @AppStorage(DefaultsKey.hudPlacement) var hudPlacement = HUDPlacement.topTrailing.rawValue
     @ObservedObject var gamepads = GamepadManager.shared
     @AppStorage(DefaultsKey.gamepadUIEnabled) var gamepadUIEnabled = true
+    /// When the switch above takes over — read (and shown) only while it is on.
+    @AppStorage(DefaultsKey.gamepadUIMode) var gamepadUIMode =
+        GamepadUIEnvironment.modeWhenConnected
+    /// The gamepad UI's background palette. Edited here on tvOS only (see `tvBody`) — every other
+    /// platform reaches it through the gamepad settings screen, which an Apple TV without a
+    /// controller cannot open.
+    @AppStorage(DefaultsKey.uiPalette) var uiPalette = "violet"
     @AppStorage(DefaultsKey.autoWake) var autoWakeEnabled = true
     @AppStorage(DefaultsKey.backgroundKeepAlive) var backgroundKeepAlive = false
     @AppStorage(DefaultsKey.backgroundTimeoutMinutes) var backgroundTimeoutMinutes = 10
@@ -488,6 +495,22 @@ struct SettingsView: View {
                 TVSelectionRow(
                     title: "Gamepad-optimized browsing",
                     options: [("On", "on"), ("Off", "off")], selection: gamepadUIEnabledTag)
+                // Hidden while the switch above is off — see the touch settings' identical gate.
+                if gamepadUIEnabled {
+                    TVSelectionRow(
+                        title: "Show it",
+                        options: SettingsOptions.gamepadUIModes, selection: $gamepadUIMode)
+                    // The Apple TV's ONLY route to the shared `ui_palette`. Everywhere else the
+                    // Background row lives on the gamepad settings screen, which is reached from
+                    // the gamepad launcher — and on tvOS that launcher needs an extended-profile
+                    // controller, so an Apple TV driven by the Siri Remote alone could not reach
+                    // the palettes at all. It belongs beside "Show it" because both describe the
+                    // same interface: this row is what that interface looks like once it is up.
+                    TVSelectionRow(
+                        title: "Background",
+                        options: GamepadPalette.all.map { (label: $0.name, tag: $0.id) },
+                        selection: $uiPalette)
+                }
                 tvCaption(Self.controllersFooter)
                 NavigationLink("About") { AboutView() }
                     .padding(.top, 8)

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

@@ -95,24 +95,19 @@ private struct ConsoleGlass<S: Shape>: ViewModifier {
     private var materialWash: Color { ink.glass(ink.isLight ? 0.55 : 0.40) }
 
     func body(content: Content) -> some View {
+        // The scheme goes on the WHOLE modified view, not just the fill inside `.background {}`.
+        // Scoped to the fill it frosts the material correctly and stops there, so a system colour
+        // in the row's own content (a `.secondary` label, a `.bordered` button) still resolved
+        // against the device appearance — which is how the pale palettes came out light-on-light
+        // on tvOS, whose appearance is always Dark. The 26 branch had it right all along; the
+        // tvOS and pre-26 branches were the odd ones out.
         #if os(tvOS)
         // ALWAYS the material fallback on tvOS: the gamepad settings list is 15+ of these
         // surfaces, and live Liquid Glass per row made the whole screen visibly laggy on the
         // Apple TV's GPU (same class of call GlassProminentButton already makes — glass fights
         // the 10-foot platform). The wash and tint ride overlays — two flat fills, no GPU cost.
-        content.background {
-            shape.fill(.ultraThinMaterial)
-                .environment(\.colorScheme, scheme)
-                .overlay { shape.fill(materialWash) }
-                .overlay {
-                    if let tint { shape.fill(tint) }
-                }
-        }
-        #else
-        if #available(iOS 26, macOS 26, *) {
-            content.glassEffect(glass, in: shape).environment(\.colorScheme, scheme)
-        } else {
-            content.background {
+        content
+            .background {
                 shape.fill(.ultraThinMaterial)
                     .environment(\.colorScheme, scheme)
                     .overlay { shape.fill(materialWash) }
@@ -120,6 +115,21 @@ private struct ConsoleGlass<S: Shape>: ViewModifier {
                         if let tint { shape.fill(tint) }
                     }
             }
+            .environment(\.colorScheme, scheme)
+        #else
+        if #available(iOS 26, macOS 26, *) {
+            content.glassEffect(glass, in: shape).environment(\.colorScheme, scheme)
+        } else {
+            content
+                .background {
+                    shape.fill(.ultraThinMaterial)
+                        .environment(\.colorScheme, scheme)
+                        .overlay { shape.fill(materialWash) }
+                        .overlay {
+                            if let tint { shape.fill(tint) }
+                        }
+                }
+                .environment(\.colorScheme, scheme)
         }
         #endif
     }
@@ -173,11 +183,14 @@ private struct ConsoleGlassBackground<S: Shape>: ViewModifier {
                     in: shape)
                 .environment(\.colorScheme, scheme)
         } else {
-            content.background {
-                shape.fill(.regularMaterial)
-                    .environment(\.colorScheme, scheme)
-                    .overlay { shape.fill(ink.glass(ink.isLight ? 0.55 : 0.40)) }
-            }
+            // Same hoist as ConsoleGlass: the content needs the scheme too, not only the frost.
+            content
+                .background {
+                    shape.fill(.regularMaterial)
+                        .environment(\.colorScheme, scheme)
+                        .overlay { shape.fill(ink.glass(ink.isLight ? 0.55 : 0.40)) }
+                }
+                .environment(\.colorScheme, scheme)
         }
     }
 }