feat(apple): gamepad UI v2 — controller settings + add host, aurora, macOS

Sources reorganized (client: Home/Session/Settings/Stores/Support/Trust; kit:
Audio/Connection/Gamepad/Input/Support/Video/Views) with the big files split
along the same seams.

The gamepad mode is couch-complete, and now on macOS too (the living-room
Mac case), not just iOS/iPadOS:

- GamepadSettingsView: a console-style, fully controller-navigable settings
  screen (X from the launcher) — up/down moves focus, left/right steps values
  (clamped, boundary thud), A cycles/toggles, B closes; the focused row shows a
  one-line description. Backed by GamepadMenuList, the vertical sibling of
  GamepadCarousel, and SettingsOptions — the option lists hoisted out of
  SettingsView statics and shared by the touch, tvOS and gamepad settings.
- GamepadAddHostView + GamepadKeyboard: register a host end to end with a pad
  — field rows open an on-screen controller keyboard (dpad grid, A types,
  X backspaces, B done); the launcher carousel ends in an Add Host tile, so
  the dead-end "add one with touch first" empty state is gone.
- Launcher polish: contextual hint bar with the pad's real button glyphs,
  controller name + battery chip, one shared console chrome.
- GamepadScreenBackground: an animated aurora (TimelineView-driven drifting
  blobs in the brand's violet family, breathing radii, slow hue shift,
  legibility scrim; freezes under Reduce Motion). Pure SwiftUI on purpose — a
  .metal library only bundles reliably in one of the two build systems (SPM vs
  the xcodeproj's synced folders) these sources compile under.
- macOS port: settings/add-host/library present as sized sheets (a macOS sheet
  takes its content's IDEAL size, and the GeometryReader-driven screens
  collapsed to nothing), NSScreen-based mode lists, scroll indicators .never
  (the "always show scroll bars" setting overrides .hidden), tray scrims so
  scrolled rows dim under the pinned title/hints, extra title clearance, and a
  PUNKTFUNK_FORCE_GAMEPAD_UI=1 dev hook — launcher/settings/add-host/keyboard/
  library render-verified live on a real Mac + LAN hosts.
- GamepadMenuInput: X button support, and (re)start now snapshots held buttons
  so a controller handoff press never fires twice (the B that closed the
  keyboard no longer also cancels the screen underneath).
- Cleanups: one "Connection failed" alert in ContentView instead of one per
  home screen; HostDiscovery.advertises/unsaved shared by both home screens.
- host: can_encode_444 stub for the non-Linux/Windows host build (the macOS
  synthetic-source loopback used by the Swift tests).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

clients/apple/Sources/PunktfunkClient/ContentView.swift

@@ -55,9 +55,9 @@ struct ContentView: View {
     #if !os(macOS)
     @State private var showSettings = false
     #endif
-    #if os(iOS)
+    #if os(iOS) || os(macOS)
     // A connected controller (+ the Settings toggle) swaps the whole home screen for
-    // GamepadHomeView instead of retrofitting HomeView's touch UI — see `home` below.
+    // GamepadHomeView instead of retrofitting HomeView's touch/desktop UI — see `home` below.
     @ObservedObject private var gamepadManager = GamepadManager.shared
     @AppStorage(DefaultsKey.gamepadUIEnabled) private var gamepadUIEnabled = true
     private var gamepadUIActive: Bool {
@@ -137,12 +137,16 @@ struct ContentView: View {
         // The library is a full-screen presentation, not a sheet: on iPad a sheet is a centered page
         // card, but the gamepad coverflow is meant to be an immersive, full-bleed screen (and the
         // launcher behind it stops consuming the controller — see GamepadHomeView's `isActive`).
-        // macOS has no `fullScreenCover`, so it keeps the sheet there.
+        // macOS has no `fullScreenCover`, so it keeps the sheet there — with an explicit size: a
+        // macOS sheet takes its content's IDEAL size, and both library layouts are geometry-driven
+        // (the coverflow is a GeometryReader, ideal ≈ zero), so without a frame it collapses to a
+        // tiny panel.
         #if os(macOS)
         .sheet(item: $libraryTarget) { host in
             NavigationStack {
                 LibraryView(store: store, host: host, onLaunch: { launchTitle(host, $0) })
             }
+            .frame(minWidth: 940, minHeight: 620)
         }
         #else
         .fullScreenCover(item: $libraryTarget) { host in
@@ -176,6 +180,18 @@ struct ContentView: View {
                 + "device in the host's web console (port 3000 → Pairing) — no PIN needed. Or "
                 + "pair with the 4-digit PIN it can display.")
         }
+        // One "Connection failed" surface for every home screen (touch grid, gamepad launcher) and
+        // platform — SessionModel funnels all connect/session errors into `errorMessage`.
+        .alert(
+            "Connection failed",
+            isPresented: Binding(
+                get: { model.errorMessage != nil },
+                set: { if !$0 { model.errorMessage = nil } })
+        ) {
+            Button("OK", role: .cancel) {}
+        } message: {
+            Text(model.errorMessage ?? "")
+        }
         // The delegated-approval wait: the host holds the connection open until the operator
         // approves it. Cancel returns the UI at once; the in-flight connect is left to time out
         // and its late result is discarded by SessionModel's connect guard (disconnect resets the
@@ -197,12 +213,21 @@ struct ContentView: View {
 
     private var home: some View {
         #if os(macOS)
-        HomeView(
-            store: store, model: model, discovery: discovery,
-            showAddHost: $showAddHost, pairingTarget: $pairingTarget,
-            speedTestTarget: $speedTestTarget, libraryTarget: $libraryTarget,
-            connect: { connect($0) }, connectDiscovered: connectDiscovered,
-            onPaired: handlePaired, onLaunchTitle: launchTitle)
+        Group {
+            if gamepadUIActive {
+                GamepadHomeView(
+                    store: store, model: model, discovery: discovery,
+                    libraryTarget: $libraryTarget,
+                    connect: { connect($0) }, connectDiscovered: connectDiscovered)
+            } else {
+                HomeView(
+                    store: store, model: model, discovery: discovery,
+                    showAddHost: $showAddHost, pairingTarget: $pairingTarget,
+                    speedTestTarget: $speedTestTarget, libraryTarget: $libraryTarget,
+                    connect: { connect($0) }, connectDiscovered: connectDiscovered,
+                    onPaired: handlePaired, onLaunchTitle: launchTitle)
+            }
+        }
         #elseif os(iOS)
         Group {
             if gamepadUIActive {
@@ -308,7 +333,8 @@ struct ContentView: View {
                     onSessionEnd: { [weak model] in
                         Task { @MainActor in model?.sessionEnded() }
                     },
-                    presentMeter: model.presentLatency
+                    presentMeter: model.presentLatency,
+                    presentTailMeter: model.presentTail
                 )
                 .overlay(alignment: placement.alignment) {
                     if captureEnabled && hudEnabled {
@@ -565,23 +591,3 @@ private struct ApprovalRequest {
     let host: StoredHost
     let advertisedFingerprint: Data?
 }
-
-private extension Data {
-    /// Parse an even-length hex string into bytes; nil on any non-hex character or odd length.
-    /// Used to turn an mDNS-advertised cert fingerprint into a connect pin.
-    init?(hexString: String) {
-        let chars = Array(hexString)
-        guard chars.count.isMultiple(of: 2) else { return nil }
-        var bytes = [UInt8]()
-        bytes.reserveCapacity(chars.count / 2)
-        var i = 0
-        while i < chars.count {
-            guard let hi = chars[i].hexDigitValue, let lo = chars[i + 1].hexDigitValue else {
-                return nil
-            }
-            bytes.append(UInt8(hi << 4 | lo))
-            i += 2
-        }
-        self = Data(bytes)
-    }
-}

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

@@ -0,0 +1,234 @@
+// The gamepad-driven "Add Host" screen (iOS/iPadOS/macOS) — the controller counterpart of
+// AddHostSheet, reached from the launcher's Add Host tile. Three field rows (name / address /
+// port) plus the Add action, navigated with the same vertical focus list as the gamepad settings;
+// A on a field opens GamepadKeyboard in a bottom tray, so a host can be registered end to end
+// without touching the screen. Field edits are live (the row shows every keystroke); B closes the
+// keyboard first, then cancels the screen — the same "back peels one layer" rule as a console UI.
+
+import PunktfunkKit
+import SwiftUI
+#if os(iOS) || os(macOS)
+
+struct GamepadAddHostView: View {
+    @Environment(\.dismiss) private var dismiss
+    let onAdd: (StoredHost) -> Void
+
+    #if os(iOS)
+    /// `.compact` in a landscape phone window — tighter chrome so the keyboard tray still fits.
+    @Environment(\.verticalSizeClass) private var vSizeClass
+
+    private var compact: Bool { vSizeClass == .compact }
+    #else
+    private let compact = false // no size classes on macOS; the sheet is sized to fit the tray
+    #endif
+    @State private var name = ""
+    @State private var address = ""
+    @State private var port = "9777"
+    @State private var focusID: String?
+    /// The field row the keyboard tray is editing; nil ⇒ the row list owns the controller.
+    @State private var editing: String?
+
+    var body: some View {
+        GamepadMenuList(
+            items: rows,
+            focusID: $focusID,
+            onActivate: { activate(id: $0.id) },
+            onBack: { dismiss() },
+            isActive: editing == nil
+        ) { row, focused in
+            rowView(row, focused: focused)
+                .frame(maxWidth: 620)
+                .padding(.horizontal, 24)
+        }
+        .frame(maxWidth: .infinity)
+        .safeAreaInset(edge: .top, spacing: 0) {
+            VStack(spacing: 4) {
+                Text("Add Host")
+                    .font(.geist(compact ? 20 : 30, .bold, relativeTo: .title))
+                    .foregroundStyle(.white)
+                if !compact {
+                    Text("Hosts on this network appear automatically — add one by address "
+                        + "for everything else.")
+                        .font(.geist(13, relativeTo: .caption))
+                        .foregroundStyle(.white.opacity(0.55))
+                        .multilineTextAlignment(.center)
+                        .frame(maxWidth: 440)
+                }
+            }
+            .padding(.top, gamepadTitleTopPadding(compact: compact))
+            .padding(.bottom, compact ? 4 : 8)
+            .frame(maxWidth: .infinity)
+            .overlay(alignment: .topTrailing) { closeButton.padding(.trailing, 20) }
+            .background { GamepadTrayScrim(edge: .top) }
+        }
+        .safeAreaInset(edge: .bottom, spacing: 0) {
+            bottomTray
+                .padding(.horizontal, 22)
+                .padding(.vertical, compact ? 6 : 10)
+                .background { GamepadTrayScrim(edge: .bottom) }
+        }
+        .background { GamepadScreenBackground() }
+        // A port can't exceed 5 digits — cap while typing so the row can't grow absurd.
+        .onChange(of: port) { _, value in
+            if value.count > 5 { port = String(value.prefix(5)) }
+        }
+    }
+
+    /// The keyboard tray while editing, the controls legend otherwise.
+    @ViewBuilder private var bottomTray: some View {
+        if let editing {
+            VStack(spacing: 10) {
+                GamepadKeyboard(
+                    text: editingBinding(editing),
+                    allowed: allowedCharacters(editing),
+                    onDone: { closeKeyboard() })
+                    // Fresh keyboard per field: a touch user can retarget the tray by tapping
+                    // another field row, and the keyboard's input wiring captured the previous
+                    // binding on appear — new identity forces a rewire to the new field.
+                    .id(editing)
+                GamepadHintBar(hints: [
+                    .init(glyph: buttonGlyph(\.buttonA, fallback: "a.circle"), text: "Type"),
+                    .init(glyph: buttonGlyph(\.buttonX, fallback: "x.circle"), text: "Delete"),
+                    .init(glyph: buttonGlyph(\.buttonB, fallback: "b.circle"), text: "Done"),
+                ])
+                .frame(maxWidth: .infinity, alignment: .leading)
+            }
+            .transition(.move(edge: .bottom).combined(with: .opacity))
+        } else {
+            GamepadHintBar(hints: [
+                .init(glyph: buttonGlyph(\.buttonA, fallback: "a.circle"), text: "Select"),
+                .init(glyph: buttonGlyph(\.buttonB, fallback: "b.circle"), text: "Cancel"),
+            ])
+            .frame(maxWidth: .infinity, alignment: .leading)
+        }
+    }
+
+    /// Touch/click fallback for closing — the controller path is B, a hardware keyboard's Esc
+    /// rides the cancel action.
+    private var closeButton: some View {
+        Button { dismiss() } label: {
+            Image(systemName: "xmark")
+                .font(.system(size: 14, weight: .semibold))
+                .foregroundStyle(.white)
+                .frame(width: 34, height: 34)
+                .glassBackground(Circle(), interactive: true)
+                .contentShape(Circle())
+        }
+        .buttonStyle(.plain)
+        .keyboardShortcut(.cancelAction)
+        .accessibilityLabel("Cancel")
+    }
+
+    // MARK: - Rows
+
+    private struct Row: Identifiable {
+        let id: String
+        let label: String
+        var value = ""
+        var placeholder = ""
+        var isAction = false
+    }
+
+    private var rows: [Row] {
+        [
+            Row(id: "name", label: "Name", value: name, placeholder: "Optional — e.g. Living Room"),
+            Row(id: "address", label: "Address", value: address, placeholder: "IP or hostname"),
+            Row(id: "port", label: "Port", value: port, placeholder: "9777"),
+            Row(id: "add", label: "Add Host", isAction: true),
+        ]
+    }
+
+    private func rowView(_ row: Row, focused: Bool) -> some View {
+        HStack(spacing: 14) {
+            if row.isAction {
+                Label("Add Host", systemImage: "plus.circle.fill")
+                    .font(.geist(16, .semibold, relativeTo: .body))
+                    .foregroundStyle(canAdd ? Color.brand : .white.opacity(0.35))
+                    .frame(maxWidth: .infinity)
+            } else {
+                Text(row.label)
+                    .font(.geist(16, .semibold, relativeTo: .body))
+                    .foregroundStyle(.white)
+                Spacer(minLength: 12)
+                Text(row.value.isEmpty ? row.placeholder : row.value)
+                    .font(.geistFixed(15, .medium))
+                    .foregroundStyle(row.value.isEmpty ? .white.opacity(0.35) : .white)
+                    .lineLimit(1)
+                    .truncationMode(.head) // keep the end of a long address visible while typing
+                if editing == row.id {
+                    // The live-edit caret: this row is what the keyboard tray is typing into.
+                    Rectangle()
+                        .fill(Color.brand)
+                        .frame(width: 2, height: 18)
+                }
+            }
+        }
+        .padding(.horizontal, 16)
+        .padding(.vertical, 13)
+        .background {
+            RoundedRectangle(cornerRadius: 14, style: .continuous)
+                .fill(.white.opacity(focused || editing == row.id ? 0.1 : 0))
+        }
+        .overlay {
+            RoundedRectangle(cornerRadius: 14, style: .continuous)
+                .strokeBorder(
+                    editing == row.id ? Color.brand.opacity(0.7) : .white.opacity(focused ? 0.22 : 0),
+                    lineWidth: 1)
+        }
+        .scaleEffect(focused ? 1.0 : 0.98)
+        .animation(.smooth(duration: 0.18), value: focused)
+    }
+
+    // MARK: - Actions
+
+    private func activate(id: String) {
+        switch id {
+        case "add":
+            guard canAdd else {
+                // Not addable yet — jump straight to what's missing instead of a dead press.
+                focusID = "address"
+                openKeyboard("address")
+                return
+            }
+            onAdd(StoredHost(
+                name: name.trimmingCharacters(in: .whitespaces),
+                address: address.trimmingCharacters(in: .whitespaces),
+                port: UInt16(port) ?? 9777))
+            dismiss()
+        default:
+            openKeyboard(id)
+        }
+    }
+
+    private var canAdd: Bool {
+        !address.trimmingCharacters(in: .whitespaces).isEmpty
+            && UInt16(port).map { $0 > 0 } == true
+    }
+
+    private func openKeyboard(_ id: String) {
+        withAnimation(.spring(response: 0.32, dampingFraction: 0.86)) { editing = id }
+    }
+
+    private func closeKeyboard() {
+        withAnimation(.spring(response: 0.32, dampingFraction: 0.86)) { editing = nil }
+    }
+
+    private func editingBinding(_ id: String) -> Binding<String> {
+        switch id {
+        case "name": return $name
+        case "port": return $port
+        default: return $address
+        }
+    }
+
+    /// What the keyboard may type per field: a port is digits, an address never contains spaces;
+    /// a name is free-form.
+    private func allowedCharacters(_ id: String) -> CharacterSet? {
+        switch id {
+        case "port": return CharacterSet(charactersIn: "0123456789")
+        case "address": return CharacterSet(charactersIn: " ").inverted
+        default: return nil
+        }
+    }
+}
+#endif

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

@@ -1,6 +1,6 @@
 // The one piece of gamepad-menu machinery shared by the host launcher (GamepadHomeView) and the
 // library coverflow (LibraryCoverflowView): a horizontal, center-snapping carousel driven entirely
-// by a controller (iOS/iPadOS only).
+// by a controller (iOS/iPadOS/macOS).
 //
 // The scrolling is pure native SwiftUI — `.scrollTargetLayout()` + `.scrollTargetBehavior(.viewAligned)`
 // snap exactly one item to center, and symmetric `.safeAreaPadding(.horizontal)` (sized off the live
@@ -24,8 +24,7 @@
 
 import PunktfunkKit
 import SwiftUI
-#if os(iOS)
-import UIKit
+#if os(iOS) || os(macOS)
 
 struct GamepadCarousel<Item: Identifiable, Card: View>: View where Item.ID: Hashable {
     let items: [Item]
@@ -40,6 +39,8 @@ struct GamepadCarousel<Item: Identifiable, Card: View>: View where Item.ID: Hash
     let onActivate: (Item) -> Void
     /// Y → the screen's secondary action (e.g. open a host's library); nil disables it.
     var onSecondary: (() -> Void)?
+    /// X → the screen's tertiary action (e.g. open settings); nil disables it.
+    var onTertiary: (() -> Void)?
     /// B → back/dismiss; nil disables it (e.g. the root launcher has nowhere to go back to).
     var onBack: (() -> Void)?
     /// L1/R1 → jump this many items at once (clamped to the ends); 0 disables the shoulders.
@@ -94,7 +95,9 @@ struct GamepadCarousel<Item: Identifiable, Card: View>: View where Item.ID: Hash
             }
             .scrollPosition(id: $scrolledID)
             .scrollTargetBehavior(.viewAligned)
-            .scrollIndicators(.hidden)
+            // .never, not .hidden — macOS's "always show scroll bars" setting overrides .hidden
+            // and paints a scroller across the console strip.
+            .scrollIndicators(.never)
             .scrollClipDisabled() // let the focused card scale up past the strip bounds
             .safeAreaPadding(.horizontal, inset)
             .offset(x: bumpOffset)
@@ -147,6 +150,7 @@ struct GamepadCarousel<Item: Identifiable, Card: View>: View where Item.ID: Hash
         input.onMove = { move($0) }
         input.onConfirm = { activate() }
         input.onSecondary = onSecondary
+        input.onTertiary = onTertiary
         input.onBack = onBack
         input.onShoulder = shoulderJump > 0 ? { shoulder(right: $0) } : nil
     }

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

@@ -0,0 +1,232 @@
+// Chrome shared by the gamepad-driven screens (GamepadHomeView, GamepadSettingsView,
+// GamepadAddHostView, LibraryCoverflowView): the full-bleed console backdrop, the
+// controller-glyph hint bar, and the connected-controller status chip. One look across every
+// screen is what makes the gamepad UI read as a coherent mode rather than a set of themed pages.
+// iOS/iPadOS and macOS (the couch Mac-mini case); tvOS keeps its native focus engine instead.
+
+import PunktfunkKit
+import SwiftUI
+#if os(iOS) || os(macOS)
+import GameController
+
+/// The active controller's real glyph for a button (Xbox "A", DualSense ✕, …) via
+/// `sfSymbolsName`; a generic fallback before a controller profile resolves.
+/// @MainActor: GamepadManager is main-actor-bound (inside a View body this was implicit).
+@MainActor
+func buttonGlyph(
+    _ button: KeyPath<GCExtendedGamepad, GCControllerButtonInput>, fallback: String
+) -> String {
+    GamepadManager.shared.active?.controller.extendedGamepad?[keyPath: button].sfSymbolsName
+        ?? fallback
+}
+
+/// Top padding for a gamepad screen's pinned title. macOS gets extra clearance — the launcher
+/// title sits right under the window titlebar and the settings/add-host sheets have no titlebar
+/// at all, so the iOS value hugs the top edge there.
+func gamepadTitleTopPadding(compact: Bool) -> CGFloat {
+    #if os(macOS)
+    26
+    #else
+    compact ? 4 : 10
+    #endif
+}
+
+/// One glyph + label cell in a hint bar.
+struct GamepadHint: Identifiable {
+    let glyph: String
+    let text: String
+    var id: String { glyph + text }
+}
+
+/// The pinned controls legend every gamepad screen shows bottom-leading (via `.safeAreaInset`).
+/// Same font/spacing everywhere so the legend reads as system chrome, not per-screen decoration.
+struct GamepadHintBar: View {
+    let hints: [GamepadHint]
+
+    var body: some View {
+        HStack(spacing: 18) {
+            ForEach(hints) { hint in
+                HStack(spacing: 7) {
+                    Image(systemName: hint.glyph)
+                        .font(.system(size: 19))
+                        .foregroundStyle(.white)
+                    Text(hint.text)
+                }
+                .fixedSize() // keep glyph + label together; never truncate a hint mid-word
+            }
+        }
+        .font(.geist(14, .semibold, relativeTo: .subheadline))
+        .foregroundStyle(.white.opacity(0.85))
+    }
+}
+
+/// The console backdrop: a living "aurora" field in the brand's violet family — soft color blobs
+/// drifting on slow Lissajous paths over black, in the direction of Apple Music's animated player
+/// background but calmer (long 30–90 s periods, muted opacities, a legibility scrim on top, so it
+/// reads as ambience behind the cards, never as content). Deliberately pure SwiftUI rather than a
+/// .metal shader: these sources are built both by SwiftPM (`swift run`/tests) and by the Xcode
+/// project's synchronized folders, and a compiled metallib is only reliably bundled in one of the
+/// two — radial gradients driven by a TimelineView give the same look with none of that risk.
+///
+/// Applied via `.background { }` — NOT as a ZStack sibling — so the `.ignoresSafeArea()` here
+/// can't inflate the caller's layout past the safe area (see the layout discipline note in
+/// GamepadHomeView's header). Honors Reduce Motion by freezing the field at a fixed phase.
+struct GamepadScreenBackground: View {
+    @Environment(\.accessibilityReduceMotion) private var reduceMotion
+
+    /// One drifting color blob: a base position + drift ellipse (unit coordinates), angular
+    /// speeds (rad/s — periods of 30–90 s), and a radius that slowly breathes.
+    private struct Blob {
+        let color: Color
+        let center: CGPoint
+        let drift: CGSize
+        let speed: (x: Double, y: Double)
+        let phase: (x: Double, y: Double)
+        /// Radius as a fraction of the view's larger dimension (+ breathing amplitude/speed).
+        let radius: CGFloat
+        let breathe: (amount: CGFloat, speed: Double)
+        let opacity: Double
+    }
+
+    /// The brand violet, a deeper indigo, a warmer plum, and a cool blue — related hues so the
+    /// field shifts within one temperature instead of strobing through the rainbow.
+    private static let blobs: [Blob] = [
+        Blob(color: Color(red: 0.53, green: 0.47, blue: 0.96), // brand violet
+             center: CGPoint(x: 0.30, y: 0.24), drift: CGSize(width: 0.16, height: 0.10),
+             speed: (0.111, 0.083), phase: (0.0, 1.9),
+             radius: 0.52, breathe: (0.07, 0.061), opacity: 0.52),
+        Blob(color: Color(red: 0.24, green: 0.20, blue: 0.72), // deep indigo
+             center: CGPoint(x: 0.78, y: 0.66), drift: CGSize(width: 0.13, height: 0.14),
+             speed: (0.071, 0.096), phase: (2.4, 0.7),
+             radius: 0.58, breathe: (0.08, 0.049), opacity: 0.55),
+        Blob(color: Color(red: 0.62, green: 0.30, blue: 0.80), // plum
+             center: CGPoint(x: 0.16, y: 0.82), drift: CGSize(width: 0.12, height: 0.09),
+             speed: (0.089, 0.067), phase: (4.1, 3.2),
+             radius: 0.44, breathe: (0.09, 0.078), opacity: 0.42),
+        Blob(color: Color(red: 0.22, green: 0.38, blue: 0.86), // cool blue
+             center: CGPoint(x: 0.70, y: 0.12), drift: CGSize(width: 0.10, height: 0.08),
+             speed: (0.059, 0.104), phase: (1.2, 5.0),
+             radius: 0.40, breathe: (0.06, 0.055), opacity: 0.38),
+    ]
+
+    var body: some View {
+        Group {
+            if reduceMotion {
+                field(at: 0)
+            } else {
+                // 30 Hz is plenty for centimeters-per-minute drift, and halves the redraw cost
+                // of a battery-fed couch device vs. the default display rate.
+                TimelineView(.animation(minimumInterval: 1.0 / 30.0)) { context in
+                    field(at: context.date.timeIntervalSinceReferenceDate)
+                }
+            }
+        }
+        .ignoresSafeArea()
+    }
+
+    private func field(at t: TimeInterval) -> some View {
+        GeometryReader { geo in
+            let side = max(geo.size.width, geo.size.height)
+            ZStack {
+                Color.black
+                ZStack {
+                    ForEach(Self.blobs.indices, id: \.self) { i in
+                        blobView(Self.blobs[i], at: t, in: geo.size, side: side)
+                    }
+                }
+                // ±10° over ~5 min — the whole field very slowly warms and cools.
+                .hueRotation(.degrees(sin(t * 0.021) * 10))
+                // Composite the additive blobs offscreen once instead of per-layer.
+                .drawingGroup()
+                // Legibility scrim: the title (top) and detail/hints (bottom) always sit on
+                // near-black, whatever the blobs are doing behind them.
+                LinearGradient(
+                    stops: [
+                        .init(color: .black.opacity(0.55), location: 0),
+                        .init(color: .black.opacity(0.15), location: 0.35),
+                        .init(color: .black.opacity(0.20), location: 0.65),
+                        .init(color: .black.opacity(0.60), location: 1),
+                    ],
+                    startPoint: .top, endPoint: .bottom)
+            }
+        }
+    }
+
+    private func blobView(_ blob: Blob, at t: TimeInterval, in size: CGSize, side: CGFloat) -> some View {
+        let x = blob.center.x + blob.drift.width * CGFloat(sin(t * blob.speed.x + blob.phase.x))
+        let y = blob.center.y + blob.drift.height * CGFloat(cos(t * blob.speed.y + blob.phase.y))
+        let r = side * blob.radius
+            * (1 + blob.breathe.amount * CGFloat(sin(t * blob.breathe.speed + blob.phase.x)))
+        return Circle()
+            .fill(RadialGradient(
+                colors: [blob.color, blob.color.opacity(0)],
+                center: .center, startRadius: 0, endRadius: r / 2))
+            .frame(width: r, height: r)
+            .position(x: x * size.width, y: y * size.height)
+            .opacity(blob.opacity)
+            .blendMode(.plusLighter)
+    }
+}
+
+/// A darkening scrim behind a pinned tray (a screen title, the hints/detail bar, the keyboard
+/// tray): scrollable rows pass beneath those insets, so without this the tray text and the row
+/// underneath render interleaved. Fades toward the content so it reads as depth, not a bar.
+struct GamepadTrayScrim: View {
+    let edge: VerticalEdge
+
+    var body: some View {
+        LinearGradient(
+            stops: [
+                .init(color: .black.opacity(0.92), location: 0),
+                .init(color: .black.opacity(0.85), location: 0.55),
+                .init(color: .black.opacity(0), location: 1),
+            ],
+            startPoint: edge == .top ? .top : .bottom,
+            endPoint: edge == .top ? .bottom : .top)
+            // Grow past the tray so the fade-to-clear happens OUTSIDE its bounds — the tray's own
+            // text always sits on the near-opaque part, rows dim before they reach it.
+            .padding(edge == .top ? .bottom : .top, -32)
+            .ignoresSafeArea()
+    }
+}
+
+/// "Which pad is driving this UI" — the active controller's name and battery, worn as a quiet
+/// chip in the launcher's top bar. Callers observe GamepadManager already, so this re-renders
+/// when the pad or its battery state changes.
+struct ControllerStatusChip: View {
+    let controller: GamepadManager.DiscoveredController
+
+    var body: some View {
+        HStack(spacing: 7) {
+            Image(systemName: controller.hasTouchpadAndMotion
+                ? "playstation.logo" : "gamecontroller.fill")
+                .font(.system(size: 12))
+            Text(controller.name)
+                .lineLimit(1)
+            if let level = controller.batteryLevel {
+                Image(systemName: batterySymbol(level))
+                    .font(.system(size: 12))
+                    .foregroundStyle(level <= 0.2 && !controller.isCharging
+                        ? AnyShapeStyle(.red) : AnyShapeStyle(.white.opacity(0.7)))
+            }
+        }
+        .font(.geist(12, .medium, relativeTo: .caption))
+        .foregroundStyle(.white.opacity(0.7))
+        .padding(.horizontal, 12)
+        .padding(.vertical, 7)
+        .background(Capsule().fill(.white.opacity(0.08)))
+        .overlay(Capsule().strokeBorder(.white.opacity(0.12), lineWidth: 1))
+    }
+
+    private func batterySymbol(_ level: Float) -> String {
+        if controller.isCharging { return "battery.100.bolt" }
+        switch level {
+        case ..<0.125: return "battery.0"
+        case ..<0.375: return "battery.25"
+        case ..<0.625: return "battery.50"
+        case ..<0.875: return "battery.75"
+        default: return "battery.100"
+        }
+    }
+}
+#endif

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

@@ -1,8 +1,9 @@
 // The gamepad-driven home screen (iOS/iPadOS only): a distinct, "10-foot" console-style host
 // launcher shown INSTEAD of HomeView while GamepadUIEnvironment is active — a separate screen built
 // around a center-snapping carousel of hosts, driven from the couch with a controller. No touch is
-// required (a tap still works as a fallback). Scope: browse saved + discovered hosts, connect, and
-// — when the library flag is on — jump into a saved host's library (Y).
+// required anywhere: A connects, Y opens a saved host's library (when the flag is on), X opens the
+// gamepad settings screen, and the carousel always ends in an Add Host tile that opens the
+// controller-keyboard add flow. (A tap still works as a fallback for all of it.)
 //
 // All the scrolling/snapping/navigation/haptics live in GamepadCarousel; this file is the launcher's
 // chrome. Layout discipline (so nothing is EVER clipped, portrait or landscape): the gradient is a
@@ -11,18 +12,21 @@
 // status bar / home indicator. As a background it draws behind without affecting layout, so the
 // GeometryReader is sized to the safe area. The title and the controller-glyph hints are pinned with
 // `.safeAreaInset` (top / bottom-leading) — guaranteed inside the safe area and out of the carousel's
-// vertical budget — and the card is sized off the remaining height. tvOS/macOS never mount this view.
+// vertical budget — and the card is sized off the remaining height. macOS mounts it too (the
+// couch Mac-mini case) — same screen, with the settings/add-host covers presented as sheets
+// (macOS has no fullScreenCover). tvOS never mounts this view (native focus engine instead).
 
 import PunktfunkKit
 import SwiftUI
-#if os(iOS)
+#if os(iOS) || os(macOS)
 import GameController
 
-/// One navigable tile: a saved host or a discovered-but-unsaved one. Hashable so it can be the
-/// carousel's scroll-position identity.
+/// One navigable tile: a saved host, a discovered-but-unsaved one, or the trailing Add Host
+/// action. Hashable so it can be the carousel's scroll-position identity.
 private enum GamepadHomeTarget: Hashable {
     case saved(UUID)
     case discovered(String)
+    case addHost
 }
 
 /// A fully-resolved launcher tile — display fields + the activate action, built fresh each render
@@ -31,13 +35,17 @@ private struct HomeTile: Identifiable {
     let id: GamepadHomeTarget
     let title: String
     let subtitle: String
-    let isOnline: Bool
-    let isPaired: Bool
-    let isConnecting: Bool
-    /// Saved (solid monogram) vs. discovered-but-unsaved (tinted outline).
-    let filled: Bool
+    var isOnline = false
+    var isPaired = false
+    var isConnecting = false
+    /// Saved (solid monogram) vs. discovered-but-unsaved / action (tinted outline).
+    var filled = false
     /// Only saved hosts have a library (matches the touch grid's context-menu gate).
-    let hasLibrary: Bool
+    var hasLibrary = false
+    /// Shows this SF symbol in the badge instead of the title monogram (the Add Host tile).
+    var icon: String?
+    /// Whether the detail panel shows the online/paired pill (hosts yes, actions no).
+    var showsStatus = true
     let activate: () -> Void
 }
 
@@ -51,12 +59,18 @@ struct GamepadHomeView: View {
 
     /// Same experimental gate the touch grid's "Browse Library…" context-menu item uses.
     @AppStorage(DefaultsKey.libraryEnabled) private var libraryEnabled = false
+    #if os(iOS)
     /// `.compact` in a landscape phone window — drives tighter chrome so everything still fits.
     @Environment(\.verticalSizeClass) private var vSizeClass
-    @State private var selection: GamepadHomeTarget?
-    @State private var breathe = false
 
     private var compact: Bool { vSizeClass == .compact }
+    #else
+    private let compact = false // no size classes on macOS; the window minimum keeps room
+    #endif
+    @ObservedObject private var gamepads = GamepadManager.shared
+    @State private var selection: GamepadHomeTarget?
+    @State private var showSettings = false
+    @State private var showAddHost = false
 
     var body: some View {
         GeometryReader { geo in
@@ -64,97 +78,70 @@ struct GamepadHomeView: View {
         }
         // Pinned inside the safe area, out of the carousel's vertical budget — never clipped.
         .safeAreaInset(edge: .top, spacing: 0) {
-            titleView
-                .padding(.top, compact ? 4 : 10)
+            titleBar
+                .padding(.top, gamepadTitleTopPadding(compact: compact))
                 .padding(.bottom, compact ? 4 : 8)
-                .frame(maxWidth: .infinity)
         }
         .safeAreaInset(edge: .bottom, alignment: .leading, spacing: 0) {
-            if !tiles.isEmpty {
-                hintBar
-                    .padding(.leading, 22)
-                    .padding(.vertical, compact ? 6 : 10)
-            }
-        }
-        .background { background }
-        .onAppear {
-            discovery.start()
-            withAnimation(.easeInOut(duration: 4).repeatForever(autoreverses: true)) { breathe = true }
+            GamepadHintBar(hints: hints)
+                .padding(.leading, 22)
+                .padding(.vertical, compact ? 6 : 10)
         }
+        .background { GamepadScreenBackground() }
+        .onAppear { discovery.start() }
         .onDisappear { discovery.stop() }
-        .alert(
-            "Connection failed",
-            isPresented: Binding(
-                get: { model.errorMessage != nil },
-                set: { if !$0 { model.errorMessage = nil } })
-        ) {
-            Button("OK", role: .cancel) {}
-        } message: {
-            Text(model.errorMessage ?? "")
+        // The settings / add-host screens take over the controller (the carousel's `isActive`
+        // gate above). iOS presents them full screen — the immersive console feel; macOS has no
+        // fullScreenCover, so they become generously sized sheets over the dimmed launcher.
+        #if os(macOS)
+        .sheet(isPresented: $showSettings) {
+            GamepadSettingsView()
+                .frame(width: 720, height: 640)
         }
+        .sheet(isPresented: $showAddHost) {
+            GamepadAddHostView { store.add($0) }
+                .frame(width: 660, height: 620)
+        }
+        .frame(minWidth: 640, minHeight: 420)
+        #else
+        .fullScreenCover(isPresented: $showSettings) { GamepadSettingsView() }
+        .fullScreenCover(isPresented: $showAddHost) {
+            GamepadAddHostView { store.add($0) }
+        }
+        #endif
     }
 
     // MARK: - Hero (carousel + detail), sized to fit the space between the pinned title and hints
 
     @ViewBuilder private func hero(for size: CGSize) -> some View {
-        if tiles.isEmpty {
-            emptyState.frame(maxWidth: .infinity, maxHeight: .infinity)
-        } else {
-            let cardWidth = min(340, size.width * 0.84)
-            // 96 ≈ the carousel's own vertical breathing (+40) plus the detail line (~54); clamp so
-            // the strip + detail always fit the region the safe-area insets leave.
-            let cardHeight = min(compact ? 170 : 210, max(118, size.height - 96))
-            VStack(spacing: compact ? 8 : 10) {
-                Spacer(minLength: 0)
-                carousel(cardWidth: cardWidth, cardHeight: cardHeight)
-                detailPanel
-                Spacer(minLength: 0)
-            }
-            .frame(maxWidth: .infinity, maxHeight: .infinity)
+        let cardWidth = min(340, size.width * 0.84)
+        // 96 ≈ the carousel's own vertical breathing (+40) plus the detail line (~54); clamp so
+        // the strip + detail always fit the region the safe-area insets leave.
+        let cardHeight = min(compact ? 170 : 210, max(118, size.height - 96))
+        VStack(spacing: compact ? 8 : 10) {
+            Spacer(minLength: 0)
+            carousel(cardWidth: cardWidth, cardHeight: cardHeight)
+            detailPanel
+            Spacer(minLength: 0)
         }
+        .frame(maxWidth: .infinity, maxHeight: .infinity)
     }
 
     // MARK: - Chrome
 
-    private var background: some View {
-        ZStack {
-            LinearGradient(
-                colors: [.black, Color.brand.opacity(0.22), .black],
-                startPoint: .top, endPoint: .bottom)
-            // A soft brand orb behind the strip gives the flat gradient depth; it breathes slowly.
-            Circle()
-                .fill(RadialGradient(
-                    colors: [Color.brand.opacity(0.55), .clear],
-                    center: .center, startRadius: 0, endRadius: 300))
-                .frame(width: 560, height: 560)
-                .blur(radius: 70)
-                .scaleEffect(breathe ? 1.08 : 0.92)
-                .opacity(breathe ? 0.5 : 0.32)
-                .offset(y: -20)
-        }
-        .ignoresSafeArea()
-    }
-
-    private var titleView: some View {
+    private var titleBar: some View {
         Text("Select a Host")
             .font(.geist(compact ? 20 : 30, .bold, relativeTo: .title))
             .foregroundStyle(.white)
-    }
-
-    private var emptyState: some View {
-        VStack(spacing: 14) {
-            Image(systemName: "gamecontroller")
-                .font(.system(size: 46, weight: .light))
-                .foregroundStyle(Color.brand)
-            Text("No hosts yet")
-                .font(.geist(20, .semibold, relativeTo: .title3))
-                .foregroundStyle(.white)
-            Text("Add one with touch first — it'll show up here for the controller.")
-                .font(.geist(15, relativeTo: .body))
-                .foregroundStyle(.white.opacity(0.6))
-                .multilineTextAlignment(.center)
-                .frame(maxWidth: 320)
-        }
+            .frame(maxWidth: .infinity)
+            .overlay(alignment: .trailing) {
+                // Which pad is driving this UI (name + battery) — quiet, and only where there's
+                // room; a compact-height phone gives the pixels to the carousel instead.
+                if !compact, let active = gamepads.active {
+                    ControllerStatusChip(controller: active)
+                        .padding(.trailing, 20)
+                }
+            }
     }
 
     // MARK: - Carousel
@@ -167,9 +154,10 @@ struct GamepadHomeView: View {
             spacing: 30,
             onActivate: { $0.activate() },
             onSecondary: { openLibraryForSelected() },
-            // Stop consuming the controller while the library is presented on top — otherwise the
-            // launcher navigates behind it (invisibly on iPhone, visibly on iPad's page sheet).
-            isActive: libraryTarget == nil
+            onTertiary: { showSettings = true },
+            // Stop consuming the controller while another screen is presented on top — otherwise
+            // the launcher navigates behind it (invisibly on iPhone, visibly on iPad's page sheet).
+            isActive: libraryTarget == nil && !showSettings && !showAddHost
         ) { tile in
             hostCard(tile, size: CGSize(width: cardWidth, height: cardHeight))
         }
@@ -211,7 +199,7 @@ struct GamepadHomeView: View {
                 Text(tile?.subtitle ?? " ")
                     .font(.geist(13, relativeTo: .caption))
                     .foregroundStyle(.white.opacity(0.6))
-                if let tile {
+                if let tile, tile.showsStatus {
                     statusPill(online: tile.isOnline, paired: tile.isPaired)
                 }
             }
@@ -236,71 +224,52 @@ struct GamepadHomeView: View {
 
     // MARK: - Hint bar (pinned bottom-leading via safeAreaInset)
 
-    private var hintBar: some View {
-        HStack(spacing: 18) {
-            hint(glyph: buttonGlyph(\.buttonA, fallback: "a.circle"), text: "Connect")
-            if showsLibraryHint {
-                hint(glyph: buttonGlyph(\.buttonY, fallback: "y.circle"), text: "Library")
-            }
+    private var hints: [GamepadHint] {
+        let selected = tiles.first { $0.id == selection }
+        var hints = [GamepadHint(
+            glyph: buttonGlyph(\.buttonA, fallback: "a.circle"),
+            text: selected?.id == .addHost ? "Add Host" : "Connect")]
+        if libraryEnabled, selected?.hasLibrary == true {
+            hints.append(.init(glyph: buttonGlyph(\.buttonY, fallback: "y.circle"), text: "Library"))
         }
-        .font(.geist(14, .semibold, relativeTo: .subheadline))
-        .foregroundStyle(.white.opacity(0.85))
-    }
-
-    private func hint(glyph: String, text: String) -> some View {
-        HStack(spacing: 7) {
-            Image(systemName: glyph)
-                .font(.system(size: 19))
-                .foregroundStyle(.white)
-            Text(text)
-        }
-        .fixedSize() // keep glyph + label together; never truncate a hint mid-word
-    }
-
-    private var showsLibraryHint: Bool {
-        guard libraryEnabled else { return false }
-        return tiles.first { $0.id == selection }?.hasLibrary ?? false
-    }
-
-    /// The active controller's real glyph for a button (Xbox "A", DualSense ✕, …) via
-    /// `sfSymbolsName`; a generic fallback before a controller profile resolves.
-    private func buttonGlyph(
-        _ button: KeyPath<GCExtendedGamepad, GCControllerButtonInput>, fallback: String
-    ) -> String {
-        GamepadManager.shared.active?.controller.extendedGamepad?[keyPath: button].sfSymbolsName
-            ?? fallback
+        hints.append(.init(glyph: buttonGlyph(\.buttonX, fallback: "x.circle"), text: "Settings"))
+        return hints
     }
 
     // MARK: - Data + actions
 
     /// Built fresh each render from the live stores (no stale value capture) — saved hosts first,
-    /// then discovered-but-unsaved ones.
+    /// then discovered-but-unsaved ones, then the Add Host action tile (so the strip is never
+    /// empty and manual entry is always one press away).
     private var tiles: [HomeTile] {
         let saved = store.hosts.map { host in
             HomeTile(
                 id: .saved(host.id),
                 title: host.displayName,
                 subtitle: "\(host.address):\(String(host.port))",
-                isOnline: isOnline(host),
+                isOnline: discovery.advertises(host),
                 isPaired: host.pinnedSHA256 != nil,
                 isConnecting: model.phase == .connecting && model.activeHost?.id == host.id,
                 filled: true,
                 hasLibrary: true,
                 activate: { connect(host) })
         }
-        let discovered = discoveredUnsaved.map { d in
+        let discovered = discovery.unsaved(among: store.hosts).map { d in
             HomeTile(
                 id: .discovered(d.id),
                 title: d.name,
                 subtitle: "\(d.host):\(String(d.port))",
                 isOnline: true,
-                isPaired: false,
-                isConnecting: false,
-                filled: false,
-                hasLibrary: false,
                 activate: { connectDiscovered(d) })
         }
-        return saved + discovered
+        let add = HomeTile(
+            id: .addHost,
+            title: "Add Host",
+            subtitle: "Register a host by address",
+            icon: "plus",
+            showsStatus: false,
+            activate: { showAddHost = true })
+        return saved + discovered + [add]
     }
 
     /// Only saved hosts have a library — matches the touch grid, where "Browse Library…" is a
@@ -311,14 +280,6 @@ struct GamepadHomeView: View {
         else { return }
         libraryTarget = host
     }
-
-    private func isOnline(_ host: StoredHost) -> Bool {
-        discovery.hosts.contains { host.matches($0) }
-    }
-
-    private var discoveredUnsaved: [DiscoveredHost] {
-        discovery.hosts.filter { d in !store.hosts.contains { $0.matches(d) } }
-    }
 }
 
 /// One "console tile" in the host carousel — a dark-glass landscape card, bigger and bolder than the
@@ -381,6 +342,10 @@ private struct GamepadHostTile: View {
                 : AnyShapeStyle(Color.brand.opacity(0.16)))
             if tile.isConnecting {
                 ProgressView().tint(.white)
+            } else if let icon = tile.icon {
+                Image(systemName: icon)
+                    .font(.system(size: 24, weight: .semibold))
+                    .foregroundStyle(Color.brand)
             } else {
                 Text(monogram(tile.title))
                     .font(.geistFixed(25, .bold))

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

@@ -0,0 +1,182 @@
+// A controller-driven on-screen keyboard for the gamepad UI's text fields (iOS/iPadOS only) —
+// iOS has no system keyboard a game controller can drive (the tvOS fullscreen entry doesn't
+// exist here), so without this, adding a host from the couch would end with "now touch the
+// screen". Dpad/stick moves a key cursor over a fixed grid, A types, X backspaces, B/Y confirms.
+// Lowercase + digits + the hostname/address punctuation is deliberately the whole character set:
+// these fields hold names, addresses and ports, not prose.
+//
+// Edits are applied to the binding live (the caller's field row shows every keystroke), so
+// closing the keyboard is always "done" — there is no separate cancel/commit step to get wrong.
+// Touch stays a fallback: every keycap is tappable.
+
+import PunktfunkKit
+import SwiftUI
+#if os(iOS) || os(macOS)
+
+struct GamepadKeyboard: View {
+    @Binding var text: String
+    /// Restricts typed characters (e.g. digits for a port field); backspace always works.
+    var allowed: CharacterSet?
+    /// B / Y / the Done key — the binding already holds the final text.
+    let onDone: () -> Void
+
+    @State private var input = GamepadMenuInput(manager: .shared)
+    @State private var haptics = MenuHaptics(manager: .shared)
+    @State private var cursor = GridPos(row: 1, col: 0) // opens on "q"
+    @State private var pressTick = 0
+    @State private var boundaryTick = 0
+    #if os(iOS)
+    /// `.compact` (landscape phone): shorter keycaps so the tray leaves room for the field rows.
+    @Environment(\.verticalSizeClass) private var vSizeClass
+
+    private var compact: Bool { vSizeClass == .compact }
+    #else
+    private let compact = false // no size classes on macOS; the sheet is sized generously
+    #endif
+
+    private struct GridPos: Hashable {
+        var row: Int
+        var col: Int
+    }
+
+    private enum Key: Hashable {
+        case char(Character)
+        case space
+        case backspace
+        case done
+    }
+
+    /// Digits first (addresses/ports), then letters; the last char column carries the
+    /// hostname/address punctuation.
+    private static let rows: [[Key]] = [
+        Array("1234567890").map(Key.char),
+        Array("qwertyuiop").map(Key.char),
+        Array("asdfghjkl-").map(Key.char),
+        Array("zxcvbnm._:").map(Key.char),
+        [.space, .backspace, .done],
+    ]
+
+    var body: some View {
+        VStack(spacing: compact ? 5 : 7) {
+            ForEach(Self.rows.indices, id: \.self) { r in
+                HStack(spacing: compact ? 5 : 7) {
+                    ForEach(Self.rows[r].indices, id: \.self) { c in
+                        keycap(Self.rows[r][c], focused: cursor == GridPos(row: r, col: c))
+                            .onTapGesture {
+                                cursor = GridPos(row: r, col: c)
+                                press(Self.rows[r][c])
+                            }
+                    }
+                }
+            }
+        }
+        .frame(maxWidth: 560)
+        .padding(compact ? 10 : 14)
+        .background {
+            RoundedRectangle(cornerRadius: 22, style: .continuous)
+                .fill(.ultraThinMaterial)
+                .environment(\.colorScheme, .dark)
+        }
+        .overlay {
+            RoundedRectangle(cornerRadius: 22, style: .continuous)
+                .strokeBorder(.white.opacity(0.12), lineWidth: 1)
+        }
+        .sensoryFeedback(.selection, trigger: cursor)
+        .sensoryFeedback(.impact(weight: .light), trigger: pressTick)
+        .sensoryFeedback(.impact(flexibility: .rigid, intensity: 0.7), trigger: boundaryTick)
+        .onAppear {
+            wire()
+            input.start()
+        }
+        .onDisappear {
+            input.stop()
+            haptics.stop()
+        }
+    }
+
+    // MARK: - Keycaps
+
+    @ViewBuilder private func keycap(_ key: Key, focused: Bool) -> some View {
+        Group {
+            switch key {
+            case .char(let c):
+                Text(String(c)).font(.geistFixed(18, .medium))
+            case .space:
+                Image(systemName: "space")
+            case .backspace:
+                Image(systemName: "delete.left")
+            case .done:
+                Label("Done", systemImage: "checkmark")
+                    .font(.geist(15, .semibold, relativeTo: .callout))
+            }
+        }
+        .foregroundStyle(focused ? Color.black : .white)
+        .frame(maxWidth: .infinity, minHeight: compact ? 34 : 42)
+        .background {
+            RoundedRectangle(cornerRadius: 9, style: .continuous)
+                .fill(focused ? AnyShapeStyle(Color.brand) : AnyShapeStyle(.white.opacity(0.08)))
+        }
+        .animation(.smooth(duration: 0.12), value: focused)
+        .contentShape(Rectangle())
+    }
+
+    // MARK: - Input
+
+    private func wire() {
+        input.onMove = { move($0) }
+        input.onConfirm = { press(Self.rows[cursor.row][cursor.col]) }
+        input.onTertiary = { press(.backspace) }
+        input.onSecondary = onDone
+        input.onBack = onDone
+    }
+
+    private func move(_ direction: GamepadMenuInput.Direction) {
+        var next = cursor
+        switch direction {
+        case .left: next.col -= 1
+        case .right: next.col += 1
+        case .up, .down:
+            let row = cursor.row + (direction == .down ? 1 : -1)
+            guard row >= 0, row < Self.rows.count else { return refuse() }
+            // Map the column proportionally between rows of different widths, so e.g. Done
+            // (rightmost of 3) goes up to the rightmost letters, not to "e".
+            let from = max(1, Self.rows[cursor.row].count - 1)
+            let to = Self.rows[row].count - 1
+            next = GridPos(
+                row: row,
+                col: Int((Double(cursor.col) * Double(to) / Double(from)).rounded()))
+        }
+        guard next.row >= 0, next.row < Self.rows.count,
+              next.col >= 0, next.col < Self.rows[next.row].count
+        else { return refuse() }
+        cursor = next
+        haptics.move()
+    }
+
+    private func press(_ key: Key) {
+        switch key {
+        case .char(let c):
+            if let allowed, !c.unicodeScalars.allSatisfy(allowed.contains) { return refuse() }
+            text.append(c)
+        case .space:
+            if let allowed, !allowed.contains(" ") { return refuse() }
+            text.append(" ")
+        case .backspace:
+            guard !text.isEmpty else { return refuse() }
+            text.removeLast()
+        case .done:
+            haptics.confirm()
+            onDone()
+            return
+        }
+        pressTick &+= 1
+        haptics.move()
+    }
+
+    /// Refused input (edge of the grid, a disallowed character, deleting nothing).
+    private func refuse() {
+        boundaryTick &+= 1
+        haptics.boundary()
+    }
+}
+#endif

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

@@ -0,0 +1,178 @@
+// The vertical sibling of GamepadCarousel (iOS/iPadOS/macOS): a controller-driven focus list for
+// the gamepad UI's form-like screens (GamepadSettingsView, GamepadAddHostView). Up/down moves a
+// focus bar through the rows, left/right adjusts the focused row's value, A activates it, B backs
+// out. The CALLER owns each row's look (it gets the focused flag); this component owns the focus
+// cursor, controller polling, haptics, and keeping the focused row scrolled into view.
+//
+// Unlike the carousel there is no snapping and no `.scrollPosition` two-way binding to fight: the
+// cursor is plainly authoritative, the scroll view just chases it with `scrollTo`. Touch stays a
+// first-class fallback — tapping a row focuses AND activates it (rows are always fully visible, so
+// the carousel's "first tap re-centers" step would only add friction here), and free finger
+// scrolling is never hijacked back to the focused row until the next controller move.
+//
+// Feedback is dual-channel like the carousel: `.sensoryFeedback` ticks the DEVICE Taptic engine,
+// `MenuHaptics` ticks the CONTROLLER. Moves and value changes get the crisp detent; a refused
+// move at either end gets the dull boundary thud plus a short vertical recoil.
+
+import PunktfunkKit
+import SwiftUI
+#if os(iOS) || os(macOS)
+
+struct GamepadMenuList<Item: Identifiable, Row: View>: View where Item.ID: Hashable {
+    let items: [Item]
+    /// Output only: the list WRITES the focused item's id here (e.g. for a caller's hint bar).
+    @Binding var focusID: Item.ID?
+    /// Left/right on the focused row. Return whether the value actually changed — true plays the
+    /// move detent, false the boundary thud (end of a clamped range, or nothing to adjust).
+    var onAdjust: ((Item, Int) -> Bool)?
+    /// A → activate the focused row (toggle it, open it, run it — the caller decides).
+    let onActivate: (Item) -> Void
+    /// B → back/dismiss; nil disables it.
+    var onBack: (() -> Void)?
+    /// Whether this list currently owns controller input — same handoff contract as
+    /// GamepadCarousel's `isActive` (a covered screen must stop polling the shared pad).
+    var isActive: Bool = true
+    @ViewBuilder let row: (Item, _ focused: Bool) -> Row
+
+    @State private var input = GamepadMenuInput(manager: .shared)
+    @State private var haptics = MenuHaptics(manager: .shared)
+    /// Authoritative focus cursor (index into `items`).
+    @State private var cursor = 0
+    /// A short vertical recoil when a move is refused at a list end.
+    @State private var bumpOffset: CGFloat = 0
+    /// `.sensoryFeedback` counters (see GamepadCarousel): device ticks for activate / value-change
+    /// / end-stop events; moves trigger on `cursor` itself.
+    @State private var activateTick = 0
+    @State private var adjustTick = 0
+    @State private var boundaryTick = 0
+
+    var body: some View {
+        ScrollViewReader { proxy in
+            ScrollView(.vertical) {
+                LazyVStack(spacing: 6) {
+                    ForEach(Array(items.enumerated()), id: \.element.id) { idx, item in
+                        row(item, idx == cursor && isActive)
+                            .contentShape(Rectangle())
+                            .onTapGesture { tap(idx) }
+                            .id(item.id)
+                    }
+                }
+                .padding(.vertical, 10)
+            }
+            // .never, not .hidden — macOS's "always show scroll bars" setting overrides .hidden.
+            .scrollIndicators(.never)
+            .offset(y: bumpOffset)
+            .onChange(of: cursor) { _, newValue in
+                guard newValue >= 0, newValue < items.count else { return }
+                withAnimation(.easeOut(duration: 0.2)) {
+                    proxy.scrollTo(items[newValue].id)
+                }
+            }
+        }
+        .sensoryFeedback(.selection, trigger: cursor)
+        .sensoryFeedback(.selection, trigger: adjustTick)
+        .sensoryFeedback(.impact(weight: .medium), trigger: activateTick)
+        .sensoryFeedback(.impact(flexibility: .rigid, intensity: 0.7), trigger: boundaryTick)
+        .onAppear {
+            reconcile()
+            wire()
+            if isActive { input.start() }
+        }
+        .onDisappear {
+            input.stop()
+            haptics.stop()
+        }
+        .onChange(of: isActive) { _, active in
+            if active {
+                wire()
+                input.start()
+            } else {
+                input.stop()
+                haptics.stop()
+            }
+        }
+        // Re-seed a dropped focus AND re-wire the input callbacks so they capture the current
+        // `items` value (a plain array — it would otherwise go stale in the stored closures).
+        .onChange(of: items.map(\.id)) { _, _ in
+            reconcile()
+            wire()
+        }
+    }
+
+    // MARK: - Input wiring
+
+    private func wire() {
+        input.onMove = { direction in
+            switch direction {
+            case .up: step(by: -1)
+            case .down: step(by: 1)
+            case .left: adjust(by: -1)
+            case .right: adjust(by: 1)
+            }
+        }
+        input.onConfirm = { activate() }
+        input.onBack = onBack
+    }
+
+    private func step(by delta: Int) {
+        guard !items.isEmpty else { return }
+        let target = cursor + delta
+        guard target >= 0, target < items.count else { return boundaryBump(forward: delta > 0) }
+        cursor = target
+        focusID = items[target].id
+        haptics.move()
+    }
+
+    private func adjust(by delta: Int) {
+        guard let onAdjust, cursor >= 0, cursor < items.count else { return }
+        if onAdjust(items[cursor], delta) {
+            adjustTick &+= 1
+            haptics.move()
+        } else {
+            boundaryTick &+= 1
+            haptics.boundary()
+        }
+    }
+
+    private func activate() {
+        guard cursor >= 0, cursor < items.count else { return }
+        activateTick &+= 1
+        haptics.confirm()
+        onActivate(items[cursor])
+    }
+
+    /// Touch fallback: a tap focuses the row and activates it in one go.
+    private func tap(_ idx: Int) {
+        guard idx >= 0, idx < items.count else { return }
+        if cursor != idx {
+            cursor = idx
+            focusID = items[idx].id
+        }
+        activate()
+    }
+
+    /// Keep `cursor`/`focusID` consistent with `items`: seed on appear; on a list change keep the
+    /// same focused item when it survives, else clamp the cursor into range.
+    private func reconcile() {
+        guard !items.isEmpty else {
+            cursor = 0
+            if focusID != nil { focusID = nil }
+            return
+        }
+        if let id = focusID, let idx = items.firstIndex(where: { $0.id == id }) {
+            cursor = idx
+        } else {
+            cursor = min(max(cursor, 0), items.count - 1)
+            focusID = items[cursor].id
+        }
+    }
+
+    private func boundaryBump(forward: Bool) {
+        boundaryTick &+= 1
+        haptics.boundary()
+        let recoil: CGFloat = forward ? -14 : 14
+        withAnimation(.spring(response: 0.16, dampingFraction: 0.42)) { bumpOffset = recoil }
+        withAnimation(.spring(response: 0.34, dampingFraction: 0.7).delay(0.1)) { bumpOffset = 0 }
+    }
+}
+#endif

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

@@ -137,17 +137,6 @@ struct HomeView: View {
         }
         #endif
         #endif
-        .alert(
-            "Connection failed",
-            isPresented: Binding(
-                get: { model.errorMessage != nil },
-                set: { if !$0 { model.errorMessage = nil } }
-            )
-        ) {
-            Button("OK", role: .cancel) {}
-        } message: {
-            Text(model.errorMessage ?? "")
-        }
     }
 
     // MARK: - Cards
@@ -156,7 +145,7 @@ struct HomeView: View {
         let onBrowseLibrary: (() -> Void)? = libraryEnabled ? { libraryTarget = host } : nil
         return HostCardView(
             host: host,
-            isOnline: isOnline(host),
+            isOnline: discovery.advertises(host),
             isConnecting: model.phase == .connecting && model.activeHost?.id == host.id,
             isMostRecent: host.id == mostRecentHostID,
             isBusy: model.isBusy,
@@ -186,18 +175,10 @@ struct HomeView: View {
         .padding(.top, store.hosts.isEmpty ? 0 : 8)
     }
 
-    /// A saved host is "online" iff a live mDNS advert currently matches it (see
-    /// `StoredHost.matches`). Recomputed on every discovery change (the @Published set), so the
-    /// dot tracks hosts appearing/leaving the network live.
-    private func isOnline(_ host: StoredHost) -> Bool {
-        discovery.hosts.contains { host.matches($0) }
-    }
-
-    /// Discovered hosts not already saved — the saved grid shows the rest, so this section only
-    /// surfaces genuinely-new hosts on the network. Same match as the online dot, so a saved host
-    /// whose IP changed (still fingerprint-matched) doesn't also appear here as a stranger.
+    /// Discovered hosts not already saved (see `HostDiscovery.unsaved` — shared with the gamepad
+    /// launcher so both screens classify hosts identically).
     private var discoveredUnsaved: [DiscoveredHost] {
-        discovery.hosts.filter { d in !store.hosts.contains { $0.matches(d) } }
+        discovery.unsaved(among: store.hosts)
     }
 
     /// The host of the most recent session — its card carries the accent ring.

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

@@ -1,4 +1,4 @@
-// The gamepad-driven presentation of the game library (iOS/iPadOS only — see LibraryView's
+// The gamepad-driven presentation of the game library (iOS/iPadOS/macOS — see LibraryView's
 // `gamepadUIActive` branch): a classic coverflow instead of the touch grid. All the
 // scrolling/snapping/navigation/haptics live in GamepadCarousel; this file is the coverflow card
 // (poster + the 3D recede treatment via `.scrollTransition`), the "now focused" detail panel, and
@@ -15,9 +15,8 @@
 
 import PunktfunkKit
 import SwiftUI
-#if os(iOS)
+#if os(iOS) || os(macOS)
 import GameController
-import UIKit
 
 struct LibraryCoverflowView: View {
     let games: [GameEntry]
@@ -27,27 +26,26 @@ struct LibraryCoverflowView: View {
     /// Close button already covers that); this is what makes gamepad-only exit possible.
     var onDismiss: (() -> Void)?
 
+    #if os(iOS)
     /// `.compact` in a landscape phone window — drives a tighter poster so everything still fits.
     @Environment(\.verticalSizeClass) private var vSizeClass
-    @State private var selection: String?
 
     private var compact: Bool { vSizeClass == .compact }
+    #else
+    private let compact = false // no size classes on macOS
+    #endif
+    @State private var selection: String?
 
     var body: some View {
         GeometryReader { geo in
             content(for: geo.size)
         }
         .safeAreaInset(edge: .bottom, alignment: .leading, spacing: 0) {
-            hintBar
+            GamepadHintBar(hints: hints)
                 .padding(.leading, 22)
                 .padding(.vertical, compact ? 6 : 10)
         }
-        .background {
-            LinearGradient(
-                colors: [.black, Color.brand.opacity(0.16), .black],
-                startPoint: .top, endPoint: .bottom)
-                .ignoresSafeArea()
-        }
+        .background { GamepadScreenBackground() }
     }
 
     @ViewBuilder private func content(for size: CGSize) -> some View {
@@ -138,34 +136,13 @@ struct LibraryCoverflowView: View {
 
     // MARK: - Hint bar (pinned bottom-leading via safeAreaInset)
 
-    private var hintBar: some View {
-        HStack(spacing: 18) {
-            if onLaunch != nil {
-                hint(glyph: buttonGlyph(\.buttonA, fallback: "a.circle"), text: "Launch")
-            }
-            hint(glyph: buttonGlyph(\.buttonB, fallback: "b.circle"), text: "Close")
+    private var hints: [GamepadHint] {
+        var hints: [GamepadHint] = []
+        if onLaunch != nil {
+            hints.append(.init(glyph: buttonGlyph(\.buttonA, fallback: "a.circle"), text: "Launch"))
         }
-        .font(.geist(14, .semibold, relativeTo: .subheadline))
-        .foregroundStyle(.white.opacity(0.85))
-    }
-
-    private func hint(glyph: String, text: String) -> some View {
-        HStack(spacing: 7) {
-            Image(systemName: glyph)
-                .font(.system(size: 19))
-                .foregroundStyle(.white)
-            Text(text)
-        }
-        .fixedSize() // keep glyph + label together; never truncate a hint mid-word
-    }
-
-    /// The active controller's real glyph for a button (Xbox "B", DualSense ◯, …) via
-    /// `sfSymbolsName`; a generic fallback before a controller profile resolves.
-    private func buttonGlyph(
-        _ button: KeyPath<GCExtendedGamepad, GCControllerButtonInput>, fallback: String
-    ) -> String {
-        GamepadManager.shared.active?.controller.extendedGamepad?[keyPath: button].sfSymbolsName
-            ?? fallback
+        hints.append(.init(glyph: buttonGlyph(\.buttonB, fallback: "b.circle"), text: "Close"))
+        return hints
     }
 }
 #endif

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

@@ -5,11 +5,6 @@
 
 import PunktfunkKit
 import SwiftUI
-#if canImport(UIKit)
-import UIKit
-#elseif canImport(AppKit)
-import AppKit
-#endif
 
 struct LibraryView: View {
     @ObservedObject var store: HostStore
@@ -26,9 +21,9 @@ struct LibraryView: View {
     /// list fetch, reused across every poster in the grid). Built alongside `games` in `load()`;
     /// torn down on disappear since it isn't one-shot like `LibraryClient.fetch`'s own session.
     @State private var imageSession: URLSession?
-    #if os(iOS)
-    // Gamepad-driven browsing is iOS/iPadOS-only — see HomeView's identical gate. tvOS keeps its
-    // existing plain-grid presentation of this same view unchanged.
+    #if os(iOS) || os(macOS)
+    // Gamepad-driven browsing (iOS/iPadOS/macOS) — see ContentView's identical gate. tvOS keeps
+    // its existing plain-grid presentation of this same view unchanged.
     @ObservedObject private var gamepadManager = GamepadManager.shared
     @AppStorage(DefaultsKey.gamepadUIEnabled) private var gamepadUIEnabled = true
     private var gamepadUIActive: Bool {
@@ -74,7 +69,7 @@ struct LibraryView: View {
         } else if games.isEmpty {
             emptyState
         } else {
-            #if os(iOS)
+            #if os(iOS) || os(macOS)
             if gamepadUIActive {
                 LibraryCoverflowView(
                     games: games, imageSession: imageSession, onLaunch: onLaunch,
@@ -202,88 +197,3 @@ private struct GameCard: View {
         }
     }
 }
-
-/// The store-provenance badge (Steam vs. a user-curated custom entry) overlaid on a poster —
-/// shared by the touch grid's `GameCard` and the gamepad coverflow's cover cell.
-struct StoreBadge: View {
-    let isCustom: Bool
-
-    var body: some View {
-        Text(isCustom ? "Custom" : "Steam")
-            .font(.geist(11, .semibold, relativeTo: .caption2))
-            .padding(.horizontal, 6)
-            .padding(.vertical, 3)
-            .background(.ultraThinMaterial, in: Capsule())
-            .padding(6)
-    }
-}
-
-#if canImport(UIKit)
-private typealias PlatformImage = UIImage
-#elseif canImport(AppKit)
-private typealias PlatformImage = NSImage
-#endif
-
-private extension Image {
-    init(platformImage: PlatformImage) {
-        #if canImport(UIKit)
-        self.init(uiImage: platformImage)
-        #elseif canImport(AppKit)
-        self.init(nsImage: platformImage)
-        #endif
-    }
-}
-
-/// Sequentially tries cover-art URLs over `session` (so a paired client can reach the host's own
-/// art proxy, not just public CDNs — see `LibraryImageLoader`), advancing past any that fail to
-/// load, then a placeholder. The loaded image is hard-clipped to fill the card's actual frame
-/// regardless of its own aspect ratio: a portrait capsule fills it as intended, but a fallback
-/// banner (wide hero/header art, used when a title has no portrait capsule) would otherwise report
-/// a much wider intrinsic size than the card and overflow into neighboring cards. Not `private` —
-/// the gamepad coverflow (`LibraryCoverflowView`) reuses it directly rather than re-fetching art.
-struct PosterImage: View {
-    let candidates: [URL]
-    let title: String
-    let session: URLSession?
-    @State private var index = 0
-    @State private var image: PlatformImage?
-
-    var body: some View {
-        Group {
-            if let image {
-                Image(platformImage: image)
-                    .resizable()
-                    .scaledToFill()
-            } else if index < candidates.count {
-                ZStack { placeholder; ProgressView() }
-            } else {
-                placeholder
-            }
-        }
-        .frame(maxWidth: .infinity, maxHeight: .infinity)
-        .clipped()
-        .task(id: index) { await loadCurrent() }
-    }
-
-    private func loadCurrent() async {
-        guard index < candidates.count else { return }
-        guard let session, let data = try? await session.data(from: candidates[index]).0,
-              let loaded = PlatformImage(data: data)
-        else {
-            index += 1 // advance to the next candidate (or past the end → placeholder)
-            return
-        }
-        image = loaded
-    }
-
-    private var placeholder: some View {
-        ZStack {
-            Rectangle().fill(.quaternary)
-            Text(title)
-                .font(.geist(17, .semibold, relativeTo: .headline))
-                .multilineTextAlignment(.center)
-                .foregroundStyle(.secondary)
-                .padding(8)
-        }
-    }
-}

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

@@ -0,0 +1,95 @@
+// Reusable library widgets, shared by the touch grid (LibraryView's `GameCard`) and the gamepad
+// coverflow (LibraryCoverflowView's cover cell).
+
+import PunktfunkKit
+import SwiftUI
+#if canImport(UIKit)
+import UIKit
+#elseif canImport(AppKit)
+import AppKit
+#endif
+
+/// The store-provenance badge (Steam vs. a user-curated custom entry) overlaid on a poster —
+/// shared by the touch grid's `GameCard` and the gamepad coverflow's cover cell.
+struct StoreBadge: View {
+    let isCustom: Bool
+
+    var body: some View {
+        Text(isCustom ? "Custom" : "Steam")
+            .font(.geist(11, .semibold, relativeTo: .caption2))
+            .padding(.horizontal, 6)
+            .padding(.vertical, 3)
+            .background(.ultraThinMaterial, in: Capsule())
+            .padding(6)
+    }
+}
+
+#if canImport(UIKit)
+private typealias PlatformImage = UIImage
+#elseif canImport(AppKit)
+private typealias PlatformImage = NSImage
+#endif
+
+private extension Image {
+    init(platformImage: PlatformImage) {
+        #if canImport(UIKit)
+        self.init(uiImage: platformImage)
+        #elseif canImport(AppKit)
+        self.init(nsImage: platformImage)
+        #endif
+    }
+}
+
+/// Sequentially tries cover-art URLs over `session` (so a paired client can reach the host's own
+/// art proxy, not just public CDNs — see `LibraryImageLoader`), advancing past any that fail to
+/// load, then a placeholder. The loaded image is hard-clipped to fill the card's actual frame
+/// regardless of its own aspect ratio: a portrait capsule fills it as intended, but a fallback
+/// banner (wide hero/header art, used when a title has no portrait capsule) would otherwise report
+/// a much wider intrinsic size than the card and overflow into neighboring cards. Not `private` —
+/// the gamepad coverflow (`LibraryCoverflowView`) reuses it directly rather than re-fetching art.
+struct PosterImage: View {
+    let candidates: [URL]
+    let title: String
+    let session: URLSession?
+    @State private var index = 0
+    @State private var image: PlatformImage?
+
+    var body: some View {
+        Group {
+            if let image {
+                Image(platformImage: image)
+                    .resizable()
+                    .scaledToFill()
+            } else if index < candidates.count {
+                ZStack { placeholder; ProgressView() }
+            } else {
+                placeholder
+            }
+        }
+        .frame(maxWidth: .infinity, maxHeight: .infinity)
+        .clipped()
+        .task(id: index) { await loadCurrent() }
+    }
+
+    private func loadCurrent() async {
+        guard index < candidates.count else { return }
+        guard let session, let data = try? await session.data(from: candidates[index]).0,
+              let loaded = PlatformImage(data: data)
+        else {
+            index += 1 // advance to the next candidate (or past the end → placeholder)
+            return
+        }
+        image = loaded
+    }
+
+    private var placeholder: some View {
+        ZStack {
+            Rectangle().fill(.quaternary)
+            Text(title)
+                .font(.geist(17, .semibold, relativeTo: .headline))
+                .multilineTextAlignment(.center)
+                .foregroundStyle(.secondary)
+                .padding(8)
+        }
+    }
+}

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

@@ -0,0 +1,35 @@
+// The HUD-corner model persisted by Settings and read wherever the overlay is placed
+// (ContentView, StreamHUDView).
+
+import SwiftUI
+
+/// Which corner the HUD overlay occupies (persisted as `DefaultsKey.hudPlacement`). The raw
+/// values are stable on disk — rename the cases freely, never the strings.
+enum HUDPlacement: String, CaseIterable, Identifiable {
+    case topLeading, topTrailing, bottomLeading, bottomTrailing
+
+    var id: String { rawValue }
+
+    /// SwiftUI overlay alignment for `.overlay(alignment:)`.
+    var alignment: Alignment {
+        switch self {
+        case .topLeading: return .topLeading
+        case .topTrailing: return .topTrailing
+        case .bottomLeading: return .bottomLeading
+        case .bottomTrailing: return .bottomTrailing
+        }
+    }
+
+    /// The HUD's own stack hugs the screen edge it sits against, so its text aligns outward.
+    var isTrailing: Bool { self == .topTrailing || self == .bottomTrailing }
+
+    /// User-facing corner label.
+    var label: String {
+        switch self {
+        case .topLeading: return "Top Left"
+        case .topTrailing: return "Top Right"
+        case .bottomLeading: return "Bottom Left"
+        case .bottomTrailing: return "Bottom Right"
+        }
+    }
+}

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

@@ -74,6 +74,11 @@ final class SessionModel: ObservableObject {
     @Published var presentLatencyP95Ms = 0.0
     @Published var presentLatencyValid = false
     @Published var presentLatencySkewCorrected = false
+    /// Decode-completion→present (the "present tail": ring wait + render + vsync) — the term the
+    /// stage-2 presenter exists to shorten. Both instants are client-side, so no skew applies.
+    @Published var presentTailP50Ms = 0.0
+    @Published var presentTailP95Ms = 0.0
+    @Published var presentTailValid = false
     /// Mirrors StreamView's capture state (it owns the input capture; this drives the
     /// HUD's "click to capture" / "⌘⎋ releases" hint).
     @Published var mouseCaptured = false
@@ -82,6 +87,8 @@ final class SessionModel: ObservableObject {
     let latency = LatencyMeter()
     /// Fed by the stage-2 presenter's display link (capture→present). Passed to StreamView.
     let presentLatency = LatencyMeter()
+    /// Fed by the same present stamp (decode-completion→present). Passed to StreamView.
+    let presentTail = LatencyMeter()
     private var statsTimer: Timer?
     private var audio: SessionAudio?
     private var gamepadCapture: GamepadCapture?
@@ -337,6 +344,13 @@ final class SessionModel: ObservableObject {
                 } else {
                     self.presentLatencyValid = false
                 }
+                if let t = self.presentTail.drain() {
+                    self.presentTailP50Ms = t.p50Ms
+                    self.presentTailP95Ms = t.p95Ms
+                    self.presentTailValid = true
+                } else {
+                    self.presentTailValid = false
+                }
             }
         }
         // .common so the HUD keeps updating during window drags / menu tracking.

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

@@ -4,37 +4,6 @@
 import PunktfunkKit
 import SwiftUI
 
-/// Which corner the HUD overlay occupies (persisted as `DefaultsKey.hudPlacement`). The raw
-/// values are stable on disk — rename the cases freely, never the strings.
-enum HUDPlacement: String, CaseIterable, Identifiable {
-    case topLeading, topTrailing, bottomLeading, bottomTrailing
-
-    var id: String { rawValue }
-
-    /// SwiftUI overlay alignment for `.overlay(alignment:)`.
-    var alignment: Alignment {
-        switch self {
-        case .topLeading: return .topLeading
-        case .topTrailing: return .topTrailing
-        case .bottomLeading: return .bottomLeading
-        case .bottomTrailing: return .bottomTrailing
-        }
-    }
-
-    /// The HUD's own stack hugs the screen edge it sits against, so its text aligns outward.
-    var isTrailing: Bool { self == .topTrailing || self == .bottomTrailing }
-
-    /// User-facing corner label.
-    var label: String {
-        switch self {
-        case .topLeading: return "Top Left"
-        case .topTrailing: return "Top Right"
-        case .bottomLeading: return "Bottom Left"
-        case .bottomTrailing: return "Bottom Right"
-        }
-    }
-}
-
 struct StreamHUDView: View {
     @ObservedObject var model: SessionModel
     let connection: PunktfunkConnection
@@ -63,6 +32,13 @@ struct StreamHUDView: View {
                     .font(.system(.caption2, design: .monospaced))
                     .foregroundStyle(.secondary)
             }
+            if model.presentTailValid {
+                // Decode→present (the client-local "present tail": ring wait + render + vsync) —
+                // the term the stage-2 presenter shortens; no skew applies (one clock).
+                Text("decode→present \(model.presentTailP50Ms, specifier: "%.1f")/\(model.presentTailP95Ms, specifier: "%.1f") ms p50/p95")
+                    .font(.system(.caption2, design: .monospaced))
+                    .foregroundStyle(.secondary)
+            }
             // While captured the cursor is hidden+frozen, so the button is keyboard-only
             // (⌘⎋ or Cmd+Tab release the cursor; released, it's clickable again).
             #if os(macOS)
@@ -71,11 +47,6 @@ struct StreamHUDView: View {
                 : "Click the stream to capture input")
                 .font(.geist(11, relativeTo: .caption2))
                 .foregroundStyle(.secondary)
-            // The client-side cursor (⌘⇧C) draws the local cursor over the stream instead of
-            // capturing it — the only accurate cursor for gamescope, whose capture has none.
-            Text("⌘⇧C toggles the on-screen cursor")
-                .font(.geist(11, relativeTo: .caption2))
-                .foregroundStyle(.secondary)
             #elseif os(iOS)
             // Touch always plays directly; ⌘⎋ (hardware keyboard) toggles kb/mouse.
             Text(model.mouseCaptured

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

@@ -0,0 +1,357 @@
+// The gamepad-driven settings screen (iOS/iPadOS/macOS): the couch-relevant subset of SettingsView,
+// restyled as a console settings page and fully navigable with a controller — up/down moves the
+// focus bar, left/right steps the focused value, A cycles/toggles it, B closes. Shown from the
+// gamepad home launcher (X); the touch SettingsView remains the full-fidelity editor (custom
+// resolutions, the log bitrate slider, debug tools), and both write the same DefaultsKey storage,
+// so values round-trip freely between the two.
+//
+// Rows are rebuilt from live @AppStorage on every render; the focus list dispatches adjust/
+// activate back here BY ROW ID (see `adjust`/`activate`), so a stored input callback can never act
+// on stale captured state. Left/right CLAMPS at a choice list's ends (the dull boundary thud tells
+// the thumb it's the last option); A always cycles forward, wrapping, so every option is reachable
+// with one button. Toggles read left = off, right = on — refusing a no-op with the same thud.
+
+import PunktfunkKit
+import SwiftUI
+#if os(iOS) || os(macOS)
+import GameController
+
+struct GamepadSettingsView: View {
+    @Environment(\.dismiss) private var dismiss
+    @AppStorage(DefaultsKey.streamWidth) private var width = 1920
+    @AppStorage(DefaultsKey.streamHeight) private var height = 1080
+    @AppStorage(DefaultsKey.streamHz) private var hz = 60
+    @AppStorage(DefaultsKey.compositor) private var compositor = 0
+    @AppStorage(DefaultsKey.gamepadType) private var gamepadType = 0
+    @AppStorage(DefaultsKey.bitrateKbps) private var bitrateKbps = 0
+    @AppStorage(DefaultsKey.audioChannels) private var audioChannels = 2
+    @AppStorage(DefaultsKey.hdrEnabled) private var hdrEnabled = true
+    @AppStorage(DefaultsKey.enable444) private var enable444 = true
+    @AppStorage(DefaultsKey.codec) private var codec = "auto"
+    @AppStorage(DefaultsKey.micEnabled) private var micEnabled = true
+    @AppStorage(DefaultsKey.hudEnabled) private var hudEnabled = true
+    @AppStorage(DefaultsKey.hudPlacement) private var hudPlacement = HUDPlacement.topTrailing.rawValue
+    @AppStorage(DefaultsKey.libraryEnabled) private var libraryEnabled = false
+    @AppStorage(DefaultsKey.gamepadUIEnabled) private var gamepadUIEnabled = true
+    @ObservedObject private var gamepads = GamepadManager.shared
+
+    #if os(iOS)
+    /// `.compact` in a landscape phone window — tighter chrome so more rows fit.
+    @Environment(\.verticalSizeClass) private var vSizeClass
+
+    private var compact: Bool { vSizeClass == .compact }
+    #else
+    private let compact = false // no size classes on macOS; the sheet is sized generously
+    #endif
+    @State private var focusID: String?
+
+    var body: some View {
+        GamepadMenuList(
+            items: rows,
+            focusID: $focusID,
+            onAdjust: { row, delta in adjust(id: row.id, by: delta) },
+            onActivate: { activate(id: $0.id) },
+            onBack: { dismiss() }
+        ) { row, focused in
+            rowView(row, focused: focused)
+                .frame(maxWidth: 620)
+                .padding(.horizontal, 24)
+        }
+        .frame(maxWidth: .infinity)
+        .safeAreaInset(edge: .top, spacing: 0) {
+            Text("Settings")
+                .font(.geist(compact ? 20 : 30, .bold, relativeTo: .title))
+                .foregroundStyle(.white)
+                .padding(.top, gamepadTitleTopPadding(compact: compact))
+                .padding(.bottom, compact ? 4 : 8)
+                .frame(maxWidth: .infinity)
+                .overlay(alignment: .trailing) { closeButton.padding(.trailing, 20) }
+                .background { GamepadTrayScrim(edge: .top) }
+        }
+        .safeAreaInset(edge: .bottom, alignment: .leading, spacing: 0) {
+            VStack(alignment: .leading, spacing: 8) {
+                Text(focusedDetail)
+                    .font(.geist(13, relativeTo: .caption))
+                    .foregroundStyle(.white.opacity(0.55))
+                    .lineLimit(2, reservesSpace: true)
+                    .animation(.smooth(duration: 0.2), value: focusID)
+                GamepadHintBar(hints: [
+                    .init(glyph: "arrow.left.and.right", text: "Adjust"),
+                    .init(glyph: buttonGlyph(\.buttonA, fallback: "a.circle"), text: "Change"),
+                    .init(glyph: buttonGlyph(\.buttonB, fallback: "b.circle"), text: "Done"),
+                ])
+            }
+            .padding(.leading, 22)
+            .padding(.trailing, 22)
+            .padding(.vertical, compact ? 6 : 10)
+            .frame(maxWidth: .infinity, alignment: .leading)
+            .background { GamepadTrayScrim(edge: .bottom) }
+        }
+        .background { GamepadScreenBackground() }
+        .onAppear {
+            gamepads.refresh()
+            gamepads.startDiscovery()
+        }
+        .onDisappear { gamepads.stopDiscovery() }
+    }
+
+    /// Touch/click fallback for closing — the controller path is B, a hardware keyboard's Esc
+    /// rides the cancel action.
+    private var closeButton: some View {
+        Button { dismiss() } label: {
+            Image(systemName: "xmark")
+                .font(.system(size: 14, weight: .semibold))
+                .foregroundStyle(.white)
+                .frame(width: 34, height: 34)
+                .glassBackground(Circle(), interactive: true)
+                .contentShape(Circle())
+        }
+        .buttonStyle(.plain)
+        .keyboardShortcut(.cancelAction)
+        .accessibilityLabel("Close settings")
+    }
+
+    // MARK: - Row rendering
+
+    private func rowView(_ row: Row, focused: Bool) -> some View {
+        VStack(alignment: .leading, spacing: 6) {
+            if let header = row.header {
+                Text(header)
+                    .font(.geist(12, .semibold, relativeTo: .caption))
+                    .tracking(1.4)
+                    .foregroundStyle(.white.opacity(0.45))
+                    .padding(.leading, 16)
+                    .padding(.top, 14)
+            }
+            HStack(spacing: 14) {
+                Image(systemName: row.icon)
+                    .font(.system(size: 17))
+                    .foregroundStyle(focused ? Color.brand : .white.opacity(0.55))
+                    .frame(width: 28)
+                Text(row.label)
+                    .font(.geist(16, .semibold, relativeTo: .body))
+                    .foregroundStyle(.white)
+                    .lineLimit(1)
+                Spacer(minLength: 12)
+                HStack(spacing: 9) {
+                    Image(systemName: "chevron.left")
+                        .font(.system(size: 12, weight: .semibold))
+                        .foregroundStyle(.white.opacity(focused ? 0.6 : 0))
+                    Text(row.value)
+                        .font(.geist(15, .medium, relativeTo: .callout))
+                        .foregroundStyle(focused ? .white : .white.opacity(0.6))
+                        .lineLimit(1)
+                    Image(systemName: "chevron.right")
+                        .font(.system(size: 12, weight: .semibold))
+                        .foregroundStyle(.white.opacity(focused ? 0.6 : 0))
+                }
+            }
+            .padding(.horizontal, 16)
+            .padding(.vertical, 13)
+            .background {
+                RoundedRectangle(cornerRadius: 14, style: .continuous)
+                    .fill(.white.opacity(focused ? 0.1 : 0))
+            }
+            .overlay {
+                RoundedRectangle(cornerRadius: 14, style: .continuous)
+                    .strokeBorder(.white.opacity(focused ? 0.22 : 0), lineWidth: 1)
+            }
+            .scaleEffect(focused ? 1.0 : 0.98)
+            .animation(.smooth(duration: 0.18), value: focused)
+        }
+    }
+
+    private var focusedDetail: String {
+        rows.first { $0.id == focusID }?.detail ?? " "
+    }
+
+    // MARK: - Row model
+
+    private struct Row: Identifiable {
+        let id: String
+        /// Section header drawn above this row (the first row of each group carries it).
+        var header: String?
+        let icon: String
+        let label: String
+        let value: String
+        /// One-line explanation shown near the hint bar while this row is focused.
+        let detail: String
+        /// Left/right step; returns whether the value actually changed (false ⇒ boundary thud).
+        let adjust: (Int) -> Bool
+        /// A — cycle forward (wrapping) / flip.
+        let activate: () -> Void
+    }
+
+    /// Dispatch by id so the focus list's stored input callbacks always act on freshly built rows
+    /// (never on state captured at wire time).
+    private func adjust(id: String, by delta: Int) -> Bool {
+        rows.first { $0.id == id }?.adjust(delta) ?? false
+    }
+
+    private func activate(id: String) {
+        rows.first { $0.id == id }?.activate()
+    }
+
+    private var rows: [Row] {
+        let resolution = resolutionOptions
+        let refresh = SettingsOptions.refreshRates(including: hz)
+            .map { (label: "\($0) Hz", tag: $0) }
+        let bitrate = SettingsOptions.bitrateOptions(current: bitrateKbps)
+        let controllers = SettingsOptions.controllerOptions(gamepads)
+        return [
+            choiceRow(
+                id: "resolution", header: "Stream", icon: "aspectratio",
+                label: "Resolution",
+                detail: "The host creates a virtual display at exactly this size — no scaling.",
+                options: resolution, current: "\(width)x\(height)"
+            ) { tag in
+                let parts = tag.split(separator: "x").compactMap { Int($0) }
+                guard parts.count == 2 else { return }
+                width = parts[0]
+                height = parts[1]
+            },
+            choiceRow(
+                id: "refresh", icon: "gauge.with.needle", label: "Refresh rate",
+                detail: "Rates this display can actually show.",
+                options: refresh, current: hz
+            ) { hz = $0 },
+            choiceRow(
+                id: "bitrate", icon: "speedometer", label: "Bitrate",
+                detail: "Automatic uses the host's default (20 Mbps). "
+                    + "Run a speed test from the touch UI for an informed value.",
+                options: bitrate, current: bitrateKbps
+            ) { bitrateKbps = $0 },
+            choiceRow(
+                id: "compositor", icon: "macwindow", label: "Compositor",
+                detail: "Which compositor drives the virtual output — honored only if "
+                    + "available on the host.",
+                options: SettingsOptions.compositors, current: compositor
+            ) { compositor = $0 },
+
+            choiceRow(
+                id: "codec", header: "Video", icon: "film", label: "Video codec",
+                detail: "A preference — the host falls back if it can't encode this one "
+                    + "(10-bit and 4:4:4 are HEVC-only).",
+                options: SettingsOptions.codecs, current: codec
+            ) { codec = $0 },
+            toggleRow(
+                id: "hdr", icon: "sun.max", label: "10-bit HDR",
+                detail: "HDR10 — engages when the host sends HDR content and this display "
+                    + "supports it.",
+                value: $hdrEnabled),
+            toggleRow(
+                id: "chroma", icon: "textformat", label: "Full chroma (4:4:4)",
+                detail: "Sharper text and UI at more bandwidth — needs host opt-in and "
+                    + "hardware decode.",
+                value: $enable444),
+
+            choiceRow(
+                id: "audio", header: "Audio", icon: "speaker.wave.2", label: "Audio channels",
+                detail: "The speaker layout requested from the host.",
+                options: SettingsOptions.audioChannels, current: audioChannels
+            ) { audioChannels = $0 },
+            toggleRow(
+                id: "mic", icon: "mic", label: "Microphone",
+                detail: "Send this device's microphone to the host's virtual mic.",
+                value: $micEnabled),
+
+            choiceRow(
+                id: "pad", header: "Controller", icon: "gamecontroller", label: "Use controller",
+                detail: "Which pad is forwarded to the host, as player 1.",
+                options: controllers, current: gamepads.preferredID
+            ) { gamepads.preferredID = $0 },
+            choiceRow(
+                id: "padType", icon: "dpad", label: "Controller type",
+                detail: "The virtual pad the host creates — Automatic matches this controller.",
+                options: SettingsOptions.padTypes, current: gamepadType
+            ) { gamepadType = $0 },
+
+            toggleRow(
+                id: "hud", header: "Interface", icon: "chart.bar", label: "Statistics overlay",
+                detail: "Resolution, frame rate, throughput and latency while streaming.",
+                value: $hudEnabled),
+            choiceRow(
+                id: "hudPlacement", icon: "rectangle.inset.topright.filled", label: "Overlay position",
+                detail: "Which corner the statistics overlay sits in.",
+                options: SettingsOptions.hudPlacements, current: hudPlacement
+            ) { hudPlacement = $0 },
+            toggleRow(
+                id: "library", icon: "square.grid.2x2", label: "Game library",
+                detail: "Browse and launch the host's games with \(buttonName(\.buttonY, "Y")) "
+                    + "(experimental).",
+                value: $libraryEnabled),
+            toggleRow(
+                id: "gamepadUI", icon: "hand.tap", label: "Controller-optimized UI",
+                detail: "Turn off to use the touch interface even with a controller connected.",
+                value: $gamepadUIEnabled),
+        ]
+    }
+
+    /// Resolution choices as "WxH" tags — the current size is inserted when it's a custom mode
+    /// (set via the touch settings), so cycling starts from it instead of jumping.
+    private var resolutionOptions: [(label: String, tag: String)] {
+        var options = SettingsOptions.resolutionModes()
+            .map { (label: "\($0.name) · \($0.w) × \($0.h)", tag: "\($0.w)x\($0.h)") }
+        let current = "\(width)x\(height)"
+        if !options.contains(where: { $0.tag == current }) {
+            options.insert((label: "Custom · \(width) × \(height)", tag: current), at: 0)
+        }
+        return options
+    }
+
+    /// The active controller's user-facing name for a button (for detail strings).
+    private func buttonName(
+        _ button: KeyPath<GCExtendedGamepad, GCControllerButtonInput>, _ fallback: String
+    ) -> String {
+        gamepads.active?.controller.extendedGamepad?[keyPath: button].localizedName ?? fallback
+    }
+
+    // MARK: - Row builders
+
+    private func choiceRow<T: Equatable>(
+        id: String, header: String? = nil, icon: String, label: String, detail: String,
+        options: [(label: String, tag: T)], current: T, write: @escaping (T) -> Void
+    ) -> Row {
+        let index = options.firstIndex { $0.tag == current }
+        return Row(
+            id: id, header: header, icon: icon, label: label,
+            value: index.map { options[$0].label } ?? "—",
+            detail: detail,
+            adjust: { delta in
+                // Unknown current value: snap to the first option on any step.
+                guard let index else {
+                    guard let first = options.first else { return false }
+                    write(first.tag)
+                    return true
+                }
+                let target = index + delta
+                guard target >= 0, target < options.count else { return false }
+                write(options[target].tag)
+                return true
+            },
+            activate: {
+                guard let index else { return write(options.first?.tag ?? current) }
+                write(options[(index + 1) % options.count].tag)
+            })
+    }
+
+    private func toggleRow(
+        id: String, header: String? = nil, icon: String, label: String, detail: String,
+        value: Binding<Bool>
+    ) -> Row {
+        Row(
+            id: id, header: header, icon: icon, label: label,
+            value: value.wrappedValue ? "On" : "Off",
+            detail: detail,
+            adjust: { delta in
+                // Directional semantics: left = off, right = on; a no-op reads as a boundary.
+                let target = delta > 0
+                guard value.wrappedValue != target else { return false }
+                value.wrappedValue = target
+                return true
+            },
+            activate: { value.wrappedValue.toggle() })
+    }
+}
+
+#endif

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

@@ -0,0 +1,60 @@
+// SettingsView's navigation and presentation helpers: the iOS settings categories, the iPad
+// sheet sizing, and the bounded-slider clamp.
+
+import SwiftUI
+
+#if os(iOS)
+/// The settings groups, mirroring the macOS preference tabs. On iPad each is a sidebar row that
+/// drives the detail pane; on iPhone the same list collapses to pushed sub-pages. Internal (not
+/// private) so the screenshot harness can open SettingsView on a specific category.
+enum SettingsCategory: String, CaseIterable, Identifiable {
+    case general, display, audio, controllers, advanced, about
+
+    var id: Self { self }
+
+    var title: String {
+        switch self {
+        case .general: return "General"
+        case .display: return "Display"
+        case .audio: return "Audio"
+        case .controllers: return "Controllers"
+        case .advanced: return "Advanced"
+        case .about: return "About"
+        }
+    }
+
+    var symbol: String {
+        switch self {
+        case .general: return "gearshape"
+        case .display: return "display"
+        case .audio: return "speaker.wave.2"
+        case .controllers: return "gamecontroller"
+        case .advanced: return "slider.horizontal.3"
+        case .about: return "info.circle"
+        }
+    }
+}
+
+extension View {
+    /// Present the settings sheet large on iPad so the NavigationSplitView has room for its
+    /// sidebar + detail — a default form sheet is too narrow and the split view would collapse to
+    /// the iPhone push list. No-op on iPhone (the standard sheet is already right) and on iOS 17
+    /// (no `presentationSizing` — it falls back to the default sheet, which still degrades cleanly
+    /// to the push list).
+    @ViewBuilder
+    func settingsSheetSizing() -> some View {
+        if UIDevice.current.userInterfaceIdiom == .pad, #available(iOS 18, *) {
+            presentationSizing(.page)
+        } else {
+            self
+        }
+    }
+}
+#endif
+
+extension Double {
+    /// The log-scale slider mapping needs a bounded input (Automatic stores 0).
+    func clamped(_ lo: Double, _ hi: Double) -> Double {
+        Swift.min(Swift.max(self, lo), hi)
+    }
+}

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

@@ -0,0 +1,147 @@
+// The option lists every settings surface renders from — one source of truth shared by the
+// touch/desktop SettingsView (Pickers), the tvOS pushed selection rows, and the gamepad settings
+// screen (GamepadSettingsView's left/right cycling). Pure data + small pure helpers; anything that
+// reads live view state (e.g. the bitrate slider mapping) stays on SettingsView.
+
+#if os(macOS)
+import AppKit
+#endif
+import PunktfunkKit
+import SwiftUI
+
+enum SettingsOptions {
+    /// Compositor choices — the `tag` is the wire value (`PunktfunkConnection.Compositor` raw).
+    static let compositors: [(label: String, tag: Int)] = [
+        ("Automatic", 0),
+        ("KWin (KDE Plasma)", 1),
+        ("wlroots (Sway / Hyprland)", 2),
+        ("Mutter (GNOME)", 3),
+        ("gamescope", 4),
+    ]
+
+    static let audioChannels: [(label: String, tag: Int)] = [
+        ("Stereo", 2),
+        ("5.1 Surround", 6),
+        ("7.1 Surround", 8),
+    ]
+
+    /// Virtual-pad types — the `tag` is the wire value (`PunktfunkConnection.GamepadType` raw).
+    static let padTypes: [(label: String, tag: Int)] = [
+        ("Automatic", 0),
+        ("Xbox 360", 1),
+        ("Xbox One", 3),
+        ("DualSense", 2),
+        ("DualShock 4", 4),
+    ]
+
+    static let hudPlacements: [(label: String, tag: String)] =
+        HUDPlacement.allCases.map { ($0.label, $0.rawValue) }
+
+    /// Video-codec preference (`DefaultsKey.codec`) — a soft preference the host falls back from.
+    /// No AV1: this client's VideoToolbox path decodes H.264/HEVC only (hosts don't emit AV1 on
+    /// the native path yet).
+    static let codecs: [(label: String, tag: String)] = [
+        ("Automatic", "auto"),
+        ("HEVC (H.265)", "hevc"),
+        ("H.264 (AVC)", "h264"),
+    ]
+
+    // MARK: - Bitrate
+
+    /// Discrete bitrate steps for the surfaces with no Slider (tvOS pushed pickers, the gamepad
+    /// settings' left/right cycling), up to the same 3 Gbps ceiling the slider has.
+    static let bitratePresets: [(label: String, tag: Int)] = [
+        ("Automatic", 0),
+        ("10 Mbps", 10_000),
+        ("20 Mbps", 20_000),
+        ("40 Mbps", 40_000),
+        ("80 Mbps", 80_000),
+        ("150 Mbps", 150_000),
+        ("300 Mbps", 300_000),
+        ("500 Mbps", 500_000),
+        ("1 Gbps", 1_000_000),
+        ("1.5 Gbps", 1_500_000),
+        ("2 Gbps", 2_000_000),
+        ("3 Gbps", 3_000_000),
+    ]
+
+    /// The presets plus the currently stored value when it isn't one of them (set via the touch
+    /// slider or a synced device) — so the current choice stays visible/selectable.
+    static func bitrateOptions(current: Int) -> [(label: String, tag: Int)] {
+        var options = bitratePresets
+        if !options.contains(where: { $0.tag == current }) {
+            options.insert(
+                (SpeedTestSheet.mbpsLabel(kbps: current) + " (custom)", current), at: 1)
+        }
+        return options
+    }
+
+    // MARK: - Controllers
+
+    /// "Use controller" choices: Automatic, every forwardable controller, and — so a stale pin
+    /// stays visible instead of leaving the selection tag-less — any pinned id that is NOT among
+    /// the selectable (extended) entries, present-but-unusable included.
+    @MainActor
+    static func controllerOptions(_ gamepads: GamepadManager) -> [(label: String, tag: String)] {
+        let selectable = gamepads.controllers.filter(\.isExtended)
+        var options: [(label: String, tag: String)] = [("Automatic", "")]
+        options += selectable.map { ($0.name, $0.id) }
+        if !gamepads.preferredID.isEmpty,
+           !selectable.contains(where: { $0.id == gamepads.preferredID }) {
+            options.append(("Unavailable controller", gamepads.preferredID))
+        }
+        return options
+    }
+
+    #if os(iOS) || os(macOS)
+    // MARK: - Stream mode (iOS + macOS pickers; tvOS builds its own preset list)
+
+    /// 16:9 then ultrawide presets; the device's native mode is prepended by `resolutionModes`.
+    static let resolutionPresets: [(name: String, w: Int, h: Int)] = [
+        ("720p", 1280, 720),
+        ("1080p", 1920, 1080),
+        ("1440p", 2560, 1440),
+        ("4K", 3840, 2160),
+        ("Ultrawide 1080p", 2560, 1080),
+        ("Ultrawide 1440p", 3440, 1440),
+        ("Super ultrawide", 5120, 1440),
+    ]
+
+    /// This device's native mode first, then the presets, deduped by dimensions (native wins a
+    /// tie).
+    @MainActor
+    static func resolutionModes() -> [(name: String, w: Int, h: Int)] {
+        var native: [(name: String, w: Int, h: Int)] = []
+        #if os(iOS)
+        let bounds = UIScreen.main.nativeBounds // portrait-oriented pixels
+        native = [("This device",
+                   Int(max(bounds.width, bounds.height)),
+                   Int(min(bounds.width, bounds.height)))]
+        #else
+        if let screen = NSScreen.main {
+            let scale = screen.backingScaleFactor
+            native = [("This display",
+                       Int(screen.frame.width * scale),
+                       Int(screen.frame.height * scale))]
+        }
+        #endif
+        var seen = Set<String>()
+        return (native + resolutionPresets).filter { seen.insert("\($0.w)x\($0.h)").inserted }
+    }
+
+    /// Refresh rates the device can actually display (no point asking the host to render frames
+    /// the screen can't show), plus any stored custom value so it stays selectable.
+    @MainActor
+    static func refreshRates(including current: Int) -> [Int] {
+        #if os(iOS)
+        let maxHz = UIScreen.main.maximumFramesPerSecond
+        #else
+        let maxHz = NSScreen.main?.maximumFramesPerSecond ?? 60
+        #endif
+        var rates = [60, 120, 240].filter { $0 <= maxHz }
+        if rates.isEmpty { rates = [maxHz] }
+        if !rates.contains(current) { rates.append(current) }
+        return rates.sorted()
+    }
+    #endif
+}

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

@@ -0,0 +1,385 @@
+// SettingsView's shared sections — each setting's Section is defined exactly once here and
+// composed by the per-platform bodies in SettingsView.swift.
+
+import PunktfunkKit
+import SwiftUI
+
+extension SettingsView {
+    // MARK: - Sections (shared)
+
+    @ViewBuilder var streamModeSection: some View {
+        Section {
+            #if os(iOS)
+            // Touch-first: a rotating wheel of common resolutions (this device's own mode first) and
+            // a segmented refresh-rate control — the same family as the Clock/Timer pickers. The host
+            // renders a virtual output at exactly the chosen mode, so these are real pixel sizes. The
+            // last wheel row, "Custom…", reveals width/height/refresh fields for an arbitrary mode.
+            VStack(alignment: .leading, spacing: 4) {
+                Text("Resolution")
+                    .font(.geist(15, relativeTo: .subheadline))
+                    .foregroundStyle(.secondary)
+                Picker("Resolution", selection: resolutionSelection) {
+                    ForEach(resolutionChoices, id: \.tag) { choice in
+                        Text(choice.label).tag(choice.tag)
+                    }
+                }
+                .labelsHidden()
+                .pickerStyle(.wheel)
+                .frame(maxHeight: 140)
+            }
+            if isCustomResolution {
+                // Arbitrary entry: type the exact width × height (and refresh) the host should drive.
+                HStack {
+                    TextField("Width", value: $width, format: .number.grouping(.never))
+                        .keyboardType(.numberPad)
+                    Text("×")
+                    TextField("Height", value: $height, format: .number.grouping(.never))
+                        .labelsHidden()
+                        .keyboardType(.numberPad)
+                }
+                // A row built from an HStack of TextFields otherwise insets its bottom separator to
+                // the inner content, clipping the hairline under "Width"; pin it to the cell edge.
+                .alignmentGuide(.listRowSeparatorLeading) { _ in 0 }
+                LabeledContent("Refresh rate") {
+                    TextField("Hz", value: $hz, format: .number.grouping(.never))
+                        .keyboardType(.numberPad)
+                        .multilineTextAlignment(.trailing)
+                }
+            } else if refreshChoices.count > 1 {
+                VStack(alignment: .leading, spacing: 6) {
+                    Text("Refresh rate")
+                        .font(.geist(15, relativeTo: .subheadline))
+                        .foregroundStyle(.secondary)
+                    Picker("Refresh rate", selection: $hz) {
+                        ForEach(refreshChoices, id: \.self) { rate in
+                            Text("\(rate) Hz").tag(rate)
+                        }
+                    }
+                    .labelsHidden()
+                    .pickerStyle(.segmented)
+                }
+            } else {
+                // A device with a single supported rate (e.g. 60 Hz) has nothing to pick.
+                LabeledContent("Refresh rate") {
+                    Text("\(hz) Hz").foregroundStyle(.secondary)
+                }
+            }
+            Button("Use this display's mode") { fillFromMainScreen() }
+            #elseif os(macOS)
+            HStack {
+                TextField("Resolution", value: $width, format: .number.grouping(.never))
+                Text("×")
+                TextField("", value: $height, format: .number.grouping(.never))
+                    .labelsHidden()
+            }
+            TextField("Refresh rate (Hz)", value: $hz, format: .number.grouping(.never))
+            LabeledContent("") {
+                Button("Use this display's mode") { fillFromMainScreen() }
+            }
+            #endif
+            #if !os(tvOS)
+            Toggle("Automatic bitrate", isOn: automaticBitrate)
+            if bitrateKbps != 0 {
+                HStack(spacing: 12) {
+                    Slider(value: bitrateSlider, in: 0...1) {
+                        Text("Bitrate")
+                    }
+                    Text(SpeedTestSheet.mbpsLabel(kbps: bitrateKbps))
+                        .monospacedDigit()
+                        .foregroundStyle(.secondary)
+                        .frame(minWidth: 76, alignment: .trailing)
+                }
+                if bitrateKbps > 1_000_000 {
+                    Label(Self.gigabitWarning, systemImage: "exclamationmark.triangle.fill")
+                        .font(.geist(12, relativeTo: .caption))
+                        .foregroundStyle(.orange)
+                }
+            }
+            #endif
+        } header: {
+            Text("Stream mode")
+        } footer: {
+            Text("The host creates a virtual output at exactly this mode — "
+                + "native resolution, no scaling. \(Self.bitrateFooter)")
+                .font(.geist(12, relativeTo: .caption))
+                .foregroundStyle(.secondary)
+        }
+    }
+
+    #if os(iOS)
+    // MARK: - Stream mode (iOS wheel)
+
+    /// Sentinel wheel tag for the "Custom…" row. Real tags are "WxH" (digits + "x"), so this can't
+    /// collide with a resolution.
+    private static let customResolutionTag = "custom"
+
+    /// Wheel rows: the resolution modes (device native first — see `SettingsOptions`), then a
+    /// "Custom…" row that reveals the numeric fields.
+    private var resolutionChoices: [(label: String, tag: String)] {
+        SettingsOptions.resolutionModes()
+            .map { (label: "\($0.name)  ·  \($0.w) × \($0.h)", tag: "\($0.w)x\($0.h)") }
+            + [(label: "Custom…", tag: Self.customResolutionTag)]
+    }
+
+    private var presetResolutionTags: Set<String> {
+        Set(SettingsOptions.resolutionModes().map { "\($0.w)x\($0.h)" })
+    }
+
+    /// True when the editable custom fields should show: the wheel is parked on "Custom…" (sticky),
+    /// or the stored size simply isn't one of the presets (e.g. a value synced from a Mac) — so a
+    /// non-preset mode stays editable across relaunches without a persisted flag.
+    private var isCustomResolution: Bool {
+        customMode || !presetResolutionTags.contains("\(width)x\(height)")
+    }
+
+    /// The wheel works in "WxH" tags so one selection drives both width and height; the custom
+    /// sentinel toggles `customMode` instead of writing a size.
+    private var resolutionSelection: Binding<String> {
+        Binding(
+            get: { isCustomResolution ? Self.customResolutionTag : "\(width)x\(height)" },
+            set: { tag in
+                if tag == Self.customResolutionTag {
+                    customMode = true
+                    return
+                }
+                customMode = false
+                let parts = tag.split(separator: "x").compactMap { Int($0) }
+                guard parts.count == 2 else { return }
+                width = parts[0]
+                height = parts[1]
+            })
+    }
+
+    /// Refresh rates this device can display, plus any stored custom value (see `SettingsOptions`).
+    private var refreshChoices: [Int] {
+        SettingsOptions.refreshRates(including: hz)
+    }
+    #endif
+
+    @ViewBuilder var audioSection: some View {
+        Section {
+            Picker("Audio channels", selection: $audioChannels) {
+                ForEach(SettingsOptions.audioChannels, id: \.tag) { option in
+                    Text(option.label).tag(option.tag)
+                }
+            }
+            #if os(macOS)
+            Picker("Speaker", selection: $speakerUID) {
+                Text("System default").tag("")
+                ForEach(outputDevices) { device in
+                    Text(device.name).tag(device.uid)
+                }
+                if !speakerUID.isEmpty,
+                   !outputDevices.contains(where: { $0.uid == speakerUID }) {
+                    Text("Unavailable device").tag(speakerUID)
+                }
+            }
+            #endif
+            Toggle("Send microphone to the host", isOn: $micEnabled)
+            #if os(macOS)
+            Picker("Microphone", selection: $micUID) {
+                Text("System default").tag("")
+                ForEach(inputDevices) { device in
+                    Text(device.name).tag(device.uid)
+                }
+                if !micUID.isEmpty,
+                   !inputDevices.contains(where: { $0.uid == micUID }) {
+                    Text("Unavailable device").tag(micUID)
+                }
+            }
+            .disabled(!micEnabled)
+            #endif
+        } header: {
+            Text("Audio")
+        } footer: {
+            Text("Host audio plays through the speaker; the microphone feeds the "
+                + "host's virtual mic. System default follows macOS device changes. "
+                + "Applies from the next session.")
+                .font(.geist(12, relativeTo: .caption))
+                .foregroundStyle(.secondary)
+        }
+    }
+
+    #if os(iOS)
+    /// iPad-only pointer-capture toggle: lock the mouse/trackpad for relative movement (games) vs
+    /// forward an absolute cursor position (desktop). Empty on iPhone (no hardware-pointer lock —
+    /// the mouse path there is always the absolute fallback).
+    @ViewBuilder var pointerSection: some View {
+        if UIDevice.current.userInterfaceIdiom == .pad {
+            Section {
+                Toggle("Capture pointer for games", isOn: $pointerCapture)
+            } header: {
+                Text("Pointer")
+            } footer: {
+                Text("With a mouse or trackpad connected, lock the pointer and send relative "
+                    + "movement — the expected behavior for games (mouse-look). Turn this off for "
+                    + "desktop use to keep the pointer free and send its absolute position instead. "
+                    + "The lock needs the stream full-screen and frontmost; it falls back to the "
+                    + "absolute pointer automatically (Stage Manager, Slide Over). Finger touch is "
+                    + "unaffected. Applies from the next session.")
+                    .font(.geist(12, relativeTo: .caption))
+                    .foregroundStyle(.secondary)
+            }
+        }
+    }
+    #endif
+
+    @ViewBuilder var compositorSection: some View {
+        Section {
+            Picker("Compositor", selection: $compositor) {
+                ForEach(SettingsOptions.compositors, id: \.tag) { option in
+                    Text(option.label).tag(option.tag)
+                }
+            }
+        } header: {
+            Text("Host compositor")
+        } footer: {
+            Text("Which compositor drives the virtual output on the host. A specific "
+                + "choice is honored only if that backend is available there — "
+                + "otherwise the host falls back to auto-detection.")
+                .font(.geist(12, relativeTo: .caption))
+                .foregroundStyle(.secondary)
+        }
+    }
+
+    @ViewBuilder var windowSection: some View {
+        #if os(macOS)
+        Section {
+            Toggle("Fullscreen while streaming", isOn: $fullscreenWhileStreaming)
+        } header: {
+            Text("Window")
+        } footer: {
+            Text("Take the window fullscreen when a session starts and restore it on the host "
+                + "list, so only the stream is fullscreen — not the picker.")
+                .font(.geist(12, relativeTo: .caption))
+                .foregroundStyle(.secondary)
+        }
+        #endif
+    }
+
+    // Stage-2 (Metal/VTDecompressionSession) is the default and only user-visible presenter — it
+    // recovers from a wedged decoder, where stage-1's AVSampleBufferDisplayLayer freezes hard on a
+    // lost HEVC reference. Stage-1 is kept reachable as a DEBUG-only override for diagnostics, like
+    // the controller test. Empty in release builds (no presenter UI; stage-2 always).
+    @ViewBuilder var presenterSection: some View {
+        #if DEBUG
+        Section {
+            Picker("Presenter", selection: $presenter) {
+                Text("Stage 2 (default)").tag("stage2")
+                Text("Stage 1 (debug)").tag("stage1")
+            }
+        } header: {
+            Text("Video presenter · debug")
+        } footer: {
+            Text("Stage 2 (default) decodes explicitly and presents through Metal with a display "
+                + "link — it adds a capture→present (glass-to-glass) latency line in the HUD and "
+                + "self-recovers from decode stalls. Stage 1 feeds compressed video straight to the "
+                + "system display layer; it freezes on a lost HEVC reference frame, so it's a debug "
+                + "fallback only. Applies from the next session.")
+                .font(.geist(12, relativeTo: .caption))
+                .foregroundStyle(.secondary)
+        }
+        #endif
+    }
+
+    @ViewBuilder var hdrSection: some View {
+        Section {
+            Picker("Video codec", selection: $codec) {
+                ForEach(SettingsOptions.codecs, id: \.tag) { option in
+                    Text(option.label).tag(option.tag)
+                }
+            }
+            Toggle("10-bit HDR", isOn: $hdrEnabled)
+            Toggle("Full chroma (4:4:4)", isOn: $enable444)
+        } header: {
+            Text("Video quality")
+        } footer: {
+            Text("Codec is a preference — the host falls back if it can't encode the one you pick "
+                + "(and 10-bit/4:4:4 are HEVC-only). HDR requests a 10-bit BT.2020 PQ (HDR10) stream — "
+                + "it only engages when the host is sending HDR content AND this display supports HDR. "
+                + "4:4:4 requests full chroma (sharper text/UI, more bandwidth) — it only engages when "
+                + "this device can hardware-decode it AND the host opted in. Otherwise the stream stays "
+                + "8-bit 4:2:0 SDR. Applies from the next session.")
+                .font(.geist(12, relativeTo: .caption))
+                .foregroundStyle(.secondary)
+        }
+    }
+
+    @ViewBuilder var statisticsSection: some View {
+        Section {
+            Toggle("Show statistics overlay", isOn: $hudEnabled)
+            Picker("Position", selection: $hudPlacement) {
+                ForEach(HUDPlacement.allCases) { placement in
+                    Text(placement.label).tag(placement.rawValue)
+                }
+            }
+            .disabled(!hudEnabled)
+        } header: {
+            Text("Statistics")
+        } footer: {
+            Text(Self.statisticsFooter)
+                .font(.geist(12, relativeTo: .caption))
+                .foregroundStyle(.secondary)
+        }
+    }
+
+    @ViewBuilder var experimentalSection: some View {
+        Section {
+            Toggle("Show game library", isOn: $libraryEnabled)
+        } header: {
+            Text("Experimental")
+        } footer: {
+            Text("Adds a “Browse Library…” action to each host that lists its games "
+                + "(Steam + custom) via the host's management API; tap a title to launch it. "
+                + "Works once you've paired with the host — the library is authorized by this "
+                + "device's certificate, with no extra host setup.")
+                .font(.geist(12, relativeTo: .caption))
+                .foregroundStyle(.secondary)
+        }
+    }
+
+    @ViewBuilder var controllersSection: some View {
+        Section {
+            if gamepads.controllers.isEmpty {
+                Text("No controllers detected")
+                    .foregroundStyle(.secondary)
+            } else {
+                ForEach(gamepads.controllers) { controller in
+                    controllerRow(controller)
+                }
+            }
+            Picker("Use controller", selection: $gamepads.preferredID) {
+                ForEach(controllerOptions, id: \.tag) { option in
+                    Text(option.label).tag(option.tag)
+                }
+            }
+            Picker("Controller type", selection: $gamepadType) {
+                ForEach(SettingsOptions.padTypes, id: \.tag) { option in
+                    Text(option.label).tag(option.tag)
+                }
+            }
+            #if !os(tvOS)
+            Toggle("Gamepad-optimized browsing", isOn: $gamepadUIEnabled)
+            #endif
+            #if DEBUG && !os(tvOS)
+            Button("Test Controller…") { showControllerTest = true }
+                .disabled(gamepads.active == nil)
+                .sheet(isPresented: $showControllerTest) { ControllerTestView() }
+            #endif
+        } header: {
+            Text("Controllers")
+        } footer: {
+            // The gamepad-UI blurb is appended here, not merged into the shared
+            // `controllersFooter` constant — tvOS's `tvBody` reuses that exact string (line ~348)
+            // for its own footer and has no such toggle to describe.
+            VStack(alignment: .leading, spacing: 6) {
+                Text(Self.controllersFooter)
+                #if !os(tvOS)
+                Text(Self.gamepadUIFooter)
+                #endif
+            }
+            .font(.geist(12, relativeTo: .caption))
+            .foregroundStyle(.secondary)
+        }
+    }
+}

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

@@ -0,0 +1,153 @@
+// SettingsView's footers and stateful helpers, used by both the section builders
+// (SettingsView+Sections.swift) and the per-platform bodies (SettingsView.swift). The option
+// LISTS live in SettingsOptions — they're shared with the gamepad settings screen too.
+
+#if os(macOS)
+import AppKit
+#endif
+import PunktfunkKit
+import SwiftUI
+
+extension SettingsView {
+    // MARK: - Bitrate
+
+    /// Slider domain, log-scale: the useful range spans three orders of magnitude
+    /// (a few Mbps … 3 Gbps) — linear would cram everything below 100 Mbps into the
+    /// first pixels.
+    private static let minSliderKbps = 2_000.0
+    private static let maxSliderKbps = 3_000_000.0
+
+    static let bitrateFooter =
+        "Automatic uses the host's default bitrate (20 Mbps); the host clamps any choice "
+        + "to its supported range. Run a speed test from a host card's context menu to "
+        + "pick an informed value. Applies from the next session."
+
+    static let gigabitWarning =
+        "Above 1 Gbps — test the network speed first (a host card's context menu → "
+        + "Test Network Speed…). A bitrate beyond what the link sustains causes loss "
+        + "and stutter."
+
+    /// `bitrateKbps == 0` is Automatic; switching to manual lands on the host default.
+    var automaticBitrate: Binding<Bool> {
+        Binding(
+            get: { bitrateKbps == 0 },
+            set: { bitrateKbps = $0 ? 0 : 20_000 })
+    }
+
+    /// Slider position 0...1 ↔ kbps on the log scale, snapped to two significant figures
+    /// so the readout shows round numbers instead of 47_322.
+    var bitrateSlider: Binding<Double> {
+        Binding(
+            get: {
+                let v = Double(bitrateKbps).clamped(Self.minSliderKbps, Self.maxSliderKbps)
+                return log(v / Self.minSliderKbps)
+                    / log(Self.maxSliderKbps / Self.minSliderKbps)
+            },
+            set: { pos in
+                let raw = Self.minSliderKbps
+                    * pow(Self.maxSliderKbps / Self.minSliderKbps, pos)
+                let mag = pow(10, floor(log10(raw)) - 1)
+                bitrateKbps = Int((raw / mag).rounded() * mag)
+            })
+    }
+
+    // MARK: - Statistics
+
+    static var statisticsFooter: String {
+        let base = "The overlay shows resolution, frame rate, throughput and latency while "
+            + "streaming, in the chosen corner."
+        #if os(macOS) || os(iOS)
+        return base + " Toggle it any time with ⌘⇧S."
+        #else
+        return base
+        #endif
+    }
+
+    // MARK: - Controllers
+
+    static let controllersFooter =
+        "One controller is forwarded to the host, as player 1 — Automatic picks the most "
+        + "recently connected one. The type is the virtual pad the host creates: Automatic "
+        + "matches the controller (a DualSense gets adaptive triggers, lightbar, touchpad "
+        + "and motion; a DualShock 4 the same minus adaptive triggers), and changes apply "
+        + "from the next session. Two identical controllers may swap a manual selection "
+        + "after reconnecting."
+
+    #if !os(tvOS)
+    static let gamepadUIFooter =
+        "When a controller is connected, the host list and game library switch to a "
+        + "controller-friendly layout — larger focus targets, controller-navigable settings, "
+        + "and a swipeable cover browser for the library. Turn this off to always use the "
+        + "standard layout. (The system may still move basic focus with a controller "
+        + "connected even with this off — that's outside the app's control.)"
+    #endif
+
+    /// "Use controller" choices for this view's manager (see `SettingsOptions.controllerOptions`).
+    var controllerOptions: [(label: String, tag: String)] {
+        SettingsOptions.controllerOptions(gamepads)
+    }
+
+    func controllerRow(_ controller: GamepadManager.DiscoveredController) -> some View {
+        HStack(spacing: 10) {
+            Image(systemName: controller.hasTouchpadAndMotion ? "playstation.logo" : "gamecontroller.fill")
+                .foregroundStyle(.secondary)
+            VStack(alignment: .leading, spacing: 2) {
+                Text(controller.name)
+                HStack(spacing: 8) {
+                    if !controller.isExtended {
+                        Text(controller.productCategory)
+                    }
+                    if controller.hasAdaptiveTriggers {
+                        Image(systemName: "r2.button.roundedtop.horizontal")
+                    }
+                    if controller.hasLight {
+                        Image(systemName: "lightbulb.fill")
+                    }
+                    if controller.hasMotion {
+                        Image(systemName: "gyroscope")
+                    }
+                    if controller.hasHaptics {
+                        Image(systemName: "waveform")
+                    }
+                    if let level = controller.batteryLevel {
+                        Text("\(Int(level * 100))%")
+                        if controller.isCharging {
+                            Image(systemName: "bolt.fill")
+                        }
+                    }
+                }
+                .font(.geist(11, relativeTo: .caption2))
+                .foregroundStyle(.secondary)
+            }
+            Spacer()
+            if gamepads.active?.id == controller.id {
+                Text("In use")
+                    .font(.geist(11, .semibold, relativeTo: .caption2))
+                    .padding(.horizontal, 8)
+                    .padding(.vertical, 3)
+                    .background(Capsule().fill(.green.opacity(0.2)))
+                    .foregroundStyle(.green)
+            }
+        }
+    }
+
+    func fillFromMainScreen() {
+        #if os(macOS)
+        guard let screen = NSScreen.main else { return }
+        let scale = screen.backingScaleFactor
+        width = Int(screen.frame.width * scale)
+        height = Int(screen.frame.height * scale)
+        hz = screen.maximumFramesPerSecond
+        #else
+        // nativeBounds is portrait-oriented pixels — streams are landscape.
+        let bounds = UIScreen.main.nativeBounds
+        width = Int(max(bounds.width, bounds.height))
+        height = Int(min(bounds.width, bounds.height))
+        hz = UIScreen.main.maximumFramesPerSecond
+        #if os(iOS)
+        // The native mode is the "This device" wheel row, so leave Custom mode if it was on.
+        customMode = false
+        #endif
+        #endif
+    }
+}

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

@@ -0,0 +1,369 @@
+// App settings. The host creates a native virtual output at exactly the chosen size/refresh —
+// there is no scaling anywhere in the pipeline.
+//
+// Navigation differs per platform, but all three group the same categories (General, Display,
+// Audio, Controllers, Advanced, About): macOS uses a tabbed preferences window; iOS/iPadOS uses
+// an adaptive NavigationSplitView — a category sidebar + detail pane on iPad, auto-collapsing to
+// a hierarchical push list on iPhone (the system Settings idiom on each); tvOS uses a
+// focus-native pushed-picker layout. The individual sections (`streamModeSection`,
+// `audioSection`, …) are shared across all three so a setting is defined exactly once — they
+// live in SettingsView+Sections.swift, with their helpers in SettingsView+Support.swift.
+
+#if os(macOS)
+import AppKit
+#endif
+import PunktfunkKit
+import SwiftUI
+
+@MainActor
+struct SettingsView: View {
+    @Environment(\.dismiss) private var dismiss
+    @AppStorage(DefaultsKey.streamWidth) var width = 1920
+    @AppStorage(DefaultsKey.streamHeight) var height = 1080
+    @AppStorage(DefaultsKey.streamHz) var hz = 60
+    @AppStorage(DefaultsKey.compositor) var compositor = 0
+    @AppStorage(DefaultsKey.gamepadType) var gamepadType = 0
+    @AppStorage(DefaultsKey.bitrateKbps) var bitrateKbps = 0
+    @AppStorage(DefaultsKey.presenter) var presenter = "stage2"
+    @AppStorage(DefaultsKey.hdrEnabled) var hdrEnabled = true
+    @AppStorage(DefaultsKey.enable444) var enable444 = true
+    @AppStorage(DefaultsKey.libraryEnabled) var libraryEnabled = false
+    @AppStorage(DefaultsKey.fullscreenWhileStreaming) var fullscreenWhileStreaming = true
+    @AppStorage(DefaultsKey.micEnabled) var micEnabled = true
+    @AppStorage(DefaultsKey.audioChannels) var audioChannels = 2
+    @AppStorage(DefaultsKey.codec) var codec = "auto"
+    @AppStorage(DefaultsKey.hudEnabled) var hudEnabled = true
+    @AppStorage(DefaultsKey.hudPlacement) var hudPlacement = HUDPlacement.topTrailing.rawValue
+    @ObservedObject var gamepads = GamepadManager.shared
+    #if !os(tvOS)
+    @AppStorage(DefaultsKey.gamepadUIEnabled) var gamepadUIEnabled = true
+    #endif
+    #if DEBUG && !os(tvOS)
+    @State var showControllerTest = false
+    #endif
+    #if os(iOS)
+    @AppStorage(DefaultsKey.pointerCapture) var pointerCapture = true
+    // The sidebar selection drives the detail pane on iPad and the pushed sub-page on iPhone.
+    // Width class decides the initial value: nil on iPhone (show the category list first),
+    // General on iPad (a two-column layout should never open with an empty detail).
+    @Environment(\.horizontalSizeClass) private var horizontalSizeClass
+    @State private var settingsSelection: SettingsCategory?
+    // Tracked so the detail can show its own Done whenever the sidebar (and its Done) is off screen
+    // — not just on iPhone, but on any iPad layout that collapses the sidebar to an overlay. Starts
+    // .doubleColumn so iPad reliably opens with the sidebar (and its Done) visible.
+    @State private var columnVisibility: NavigationSplitViewVisibility = .doubleColumn
+    // Sticky once the wheel lands on "Custom…", so editing a width/height that briefly equals a
+    // preset doesn't snap the wheel back off Custom. A stored non-preset value reads as custom even
+    // when this is false (see `isCustomResolution`), so it survives relaunches without persisting.
+    @State var customMode = false
+    #endif
+    #if os(macOS)
+    @AppStorage(DefaultsKey.speakerUID) var speakerUID = ""
+    @AppStorage(DefaultsKey.micUID) var micUID = ""
+    @State var outputDevices: [AudioDevice] = []
+    @State var inputDevices: [AudioDevice] = []
+    #endif
+
+    #if os(iOS)
+    /// `initialCategory` is nil in the app (the list opens un-selected on iPhone; iPad lands on
+    /// General via `onAppear`). The screenshot harness passes an explicit category so the captured
+    /// shot opens on a real settings page (a populated detail) rather than the bare category list.
+    init(initialCategory: SettingsCategory? = nil) {
+        _settingsSelection = State(initialValue: initialCategory)
+    }
+    #endif
+
+    var body: some View {
+        #if os(tvOS)
+        // Native tv pattern: no inline text entry (typing numbers with a remote is
+        // miserable and the inline field chrome fights the focus system). Modes are
+        // preset pickers that push selection lists like the system Settings app.
+        tvBody
+        #elseif os(macOS)
+        macBody
+        #else
+        iosBody
+        #endif
+    }
+
+    // MARK: - macOS: tabbed preferences
+
+    #if os(macOS)
+    private var macBody: some View {
+        TabView {
+            Form {
+                streamModeSection
+                compositorSection
+            }
+            .formStyle(.grouped)
+            .tabItem { Label("General", systemImage: "gearshape") }
+
+            Form {
+                presenterSection
+                hdrSection
+                windowSection
+                statisticsSection
+            }
+            .formStyle(.grouped)
+            .tabItem { Label("Display", systemImage: "display") }
+
+            Form {
+                audioSection
+            }
+            .formStyle(.grouped)
+            .onAppear {
+                outputDevices = AudioDevices.outputs()
+                inputDevices = AudioDevices.inputs()
+            }
+            .tabItem { Label("Audio", systemImage: "speaker.wave.2") }
+
+            Form {
+                controllersSection
+            }
+            .formStyle(.grouped)
+            .onAppear {
+                gamepads.refresh()
+                gamepads.startDiscovery()
+            }
+            .onDisappear { gamepads.stopDiscovery() }
+            .tabItem { Label("Controllers", systemImage: "gamecontroller") }
+
+            Form {
+                experimentalSection
+            }
+            .formStyle(.grouped)
+            .tabItem { Label("Advanced", systemImage: "slider.horizontal.3") }
+
+            AcknowledgementsView()
+                .tabItem { Label("About", systemImage: "info.circle") }
+        }
+        .frame(width: 480, height: 460)
+    }
+    #endif
+
+    // MARK: - iOS / iPadOS: adaptive split view
+
+    #if os(iOS)
+    private var iosBody: some View {
+        NavigationSplitView(columnVisibility: $columnVisibility) {
+            List(selection: $settingsSelection) {
+                ForEach(SettingsCategory.allCases) { category in
+                    // On iPhone the split view collapses to a push list, but a selection List
+                    // draws no disclosure indicator of its own — add one in compact width for the
+                    // expected drill-in affordance. On iPad the selected row highlights instead, so
+                    // the chevron is omitted there.
+                    HStack {
+                        Label(category.title, systemImage: category.symbol)
+                        if horizontalSizeClass == .compact {
+                            Spacer()
+                            Image(systemName: "chevron.forward")
+                                .font(.footnote.weight(.semibold))
+                                .foregroundStyle(.tertiary)
+                                // Purely a drill-in affordance — the row's button trait already
+                                // conveys "opens"; keep it out of the VoiceOver announcement.
+                                .accessibilityHidden(true)
+                        }
+                    }
+                    .tag(category)
+                }
+            }
+            .navigationTitle("Settings")
+            .toolbar {
+                ToolbarItem(placement: .confirmationAction) {
+                    Button("Done") { dismiss() }
+                }
+            }
+        } detail: {
+            // NavigationSplitView hosts the detail in its own navigation context (its title bar),
+            // so no inner NavigationStack — that would double the bar on iPad. On iPhone the split
+            // view collapses to one stack and pushes this when a row is tapped. `?? .general` only
+            // backs the brief pre-selection window; the list never auto-pushes on a nil selection.
+            settingsDetail(settingsSelection ?? .general)
+                // Keep a Done on the detail whenever the sidebar (and its Done) isn't on screen: the
+                // iPhone push, or any iPad layout that collapsed the sidebar to an overlay. When the
+                // sidebar is showing, its Done is the only one — so this stays hidden to avoid two.
+                .toolbar {
+                    if horizontalSizeClass == .compact || columnVisibility == .detailOnly {
+                        ToolbarItem(placement: .confirmationAction) {
+                            Button("Done") { dismiss() }
+                        }
+                    }
+                }
+        }
+        .onAppear {
+            if horizontalSizeClass == .regular, settingsSelection == nil {
+                settingsSelection = .general
+            }
+            gamepads.refresh()
+            gamepads.startDiscovery()
+        }
+        // A regular→regular launch sets the default above; this catches a compact→regular change
+        // (e.g. an iPad leaving narrow split-screen multitasking) so the detail pane fills in.
+        .onChange(of: horizontalSizeClass) { _, newValue in
+            if newValue == .regular, settingsSelection == nil {
+                settingsSelection = .general
+            }
+        }
+        .onDisappear { gamepads.stopDiscovery() }
+    }
+
+    @ViewBuilder
+    private func settingsDetail(_ category: SettingsCategory) -> some View {
+        switch category {
+        case .general:
+            Form {
+                streamModeSection
+                pointerSection
+                compositorSection
+            }
+            .formStyle(.grouped)
+            .navigationTitle("General")
+            .navigationBarTitleDisplayMode(.inline)
+        case .display:
+            Form {
+                presenterSection
+                hdrSection
+                statisticsSection
+            }
+            .formStyle(.grouped)
+            .navigationTitle("Display")
+            .navigationBarTitleDisplayMode(.inline)
+        case .audio:
+            Form { audioSection }
+                .formStyle(.grouped)
+                .navigationTitle("Audio")
+                .navigationBarTitleDisplayMode(.inline)
+        case .controllers:
+            Form { controllersSection }
+                .formStyle(.grouped)
+                .navigationTitle("Controllers")
+                .navigationBarTitleDisplayMode(.inline)
+        case .advanced:
+            Form { experimentalSection }
+                .formStyle(.grouped)
+                .navigationTitle("Advanced")
+                .navigationBarTitleDisplayMode(.inline)
+        case .about:
+            // Already a full scrollable view that sets its own "Acknowledgements" title; pin the
+            // display mode inline to match the five sibling detail pages (it would otherwise inherit
+            // the large title from the "Settings" sidebar root).
+            AcknowledgementsView()
+                .navigationBarTitleDisplayMode(.inline)
+        }
+    }
+    #endif
+
+    // MARK: - tvOS
+
+    #if os(tvOS)
+    private static let presets: [(label: String, tag: String)] = [
+        ("720p @ 60", "1280x720x60"),
+        ("1080p @ 60", "1920x1080x60"),
+        ("4K @ 60", "3840x2160x60"),
+    ]
+
+    private var modeTag: Binding<String> {
+        Binding(
+            get: { "\(width)x\(height)x\(hz)" },
+            set: { tag in
+                let parts = tag.split(separator: "x").compactMap { Int($0) }
+                guard parts.count == 3 else { return }
+                width = parts[0]
+                height = parts[1]
+                hz = parts[2]
+            })
+    }
+
+    private var hudEnabledTag: Binding<String> {
+        Binding(get: { hudEnabled ? "on" : "off" }, set: { hudEnabled = $0 == "on" })
+    }
+
+    private var hdrEnabledTag: Binding<String> {
+        Binding(get: { hdrEnabled ? "on" : "off" }, set: { hdrEnabled = $0 == "on" })
+    }
+
+    private var tvBody: some View {
+        let currentTag = "\(width)x\(height)x\(hz)"
+        let bounds = UIScreen.main.nativeBounds
+        let nativeTag = "\(Int(max(bounds.width, bounds.height)))x"
+            + "\(Int(min(bounds.width, bounds.height)))x\(UIScreen.main.maximumFramesPerSecond)"
+        var options = Self.presets
+        if !options.contains(where: { $0.tag == nativeTag }) {
+            options.insert(("This TV (native)", nativeTag), at: 0)
+        }
+        if !options.contains(where: { $0.tag == currentTag }) {
+            options.insert(("Custom (\(width)×\(height) @ \(hz))", currentTag), at: 0)
+        }
+        return ScrollView {
+            VStack(spacing: 16) {
+                TVSelectionRow(title: "Stream mode", options: options, selection: modeTag)
+                TVSelectionRow(
+                    title: "Bitrate",
+                    options: SettingsOptions.bitrateOptions(current: bitrateKbps),
+                    selection: $bitrateKbps)
+                TVSelectionRow(
+                    title: "Audio channels",
+                    options: SettingsOptions.audioChannels,
+                    selection: $audioChannels)
+                if bitrateKbps > 1_000_000 {
+                    Label(Self.gigabitWarning, systemImage: "exclamationmark.triangle.fill")
+                        .font(.geist(12, relativeTo: .caption))
+                        .foregroundStyle(.orange)
+                        .multilineTextAlignment(.center)
+                }
+                TVSelectionRow(
+                    title: "Compositor", options: SettingsOptions.compositors,
+                    selection: $compositor)
+                #if DEBUG
+                TVSelectionRow(
+                    title: "Presenter (debug)",
+                    options: [("Stage 2 (default)", "stage2"), ("Stage 1 (debug)", "stage1")],
+                    selection: $presenter)
+                #endif
+                TVSelectionRow(
+                    title: "10-bit HDR",
+                    options: [("On", "on"), ("Off", "off")], selection: hdrEnabledTag)
+                Text("The host creates a virtual output at exactly this mode — native "
+                    + "resolution, no scaling. \(Self.bitrateFooter) A specific compositor "
+                    + "is honored only if available on the host.")
+                    .font(.geist(12, relativeTo: .caption))
+                    .foregroundStyle(.secondary)
+                    .multilineTextAlignment(.center)
+                    .padding(.top, 8)
+                TVSelectionRow(
+                    title: "Statistics overlay",
+                    options: [("On", "on"), ("Off", "off")], selection: hudEnabledTag)
+                TVSelectionRow(
+                    title: "Statistics position", options: SettingsOptions.hudPlacements,
+                    selection: $hudPlacement)
+                ForEach(gamepads.controllers) { controller in
+                    controllerRow(controller)
+                        .padding(.horizontal, 24)
+                }
+                TVSelectionRow(
+                    title: "Use controller", options: controllerOptions,
+                    selection: $gamepads.preferredID)
+                TVSelectionRow(
+                    title: "Controller type", options: SettingsOptions.padTypes,
+                    selection: $gamepadType)
+                Text(Self.controllersFooter)
+                    .font(.geist(12, relativeTo: .caption))
+                    .foregroundStyle(.secondary)
+                    .multilineTextAlignment(.center)
+                    .padding(.top, 8)
+                NavigationLink("Acknowledgements") { AcknowledgementsView() }
+                    .padding(.top, 8)
+            }
+            .frame(maxWidth: 1000)
+            .frame(maxWidth: .infinity)
+            .padding(60)
+        }
+        .navigationTitle("Settings")
+        .onAppear {
+            gamepads.refresh()
+            gamepads.startDiscovery()
+        }
+        .onDisappear { gamepads.stopDiscovery() }
+    }
+    #endif
+}

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

@@ -46,9 +46,24 @@ extension StoredHost {
     }
 }
 
-private extension Data {
-    /// Lowercase hex, no separators — to compare a pinned fingerprint against the mDNS `fp`.
-    var hexLower: String { map { String(format: "%02x", $0) }.joined() }
+/// The two joins of live mDNS discovery against the saved-host store, shared by the touch grid
+/// (HomeView) and the gamepad launcher (GamepadHomeView) so both screens classify hosts the same
+/// way. LAN-scoped like the underlying match: a host that isn't advertising here is "not seen",
+/// not proven off.
+extension HostDiscovery {
+    /// A saved host is "online" iff a live advert currently matches it (see `StoredHost.matches`).
+    /// Recomputed on every discovery change (the @Published set), so it tracks hosts
+    /// appearing/leaving the network live.
+    func advertises(_ host: StoredHost) -> Bool {
+        hosts.contains { host.matches($0) }
+    }
+
+    /// Discovered hosts not already saved — the saved list shows the rest, so this only surfaces
+    /// genuinely-new hosts on the network. Same match as `advertises`, so a saved host whose IP
+    /// changed (still fingerprint-matched) doesn't also appear as a stranger.
+    func unsaved(among saved: [StoredHost]) -> [DiscoveredHost] {
+        hosts.filter { d in !saved.contains { $0.matches(d) } }
+    }
 }
 
 @MainActor

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

@@ -0,0 +1,27 @@
+// Hex encode/decode for the trust surface — pinned certificate fingerprints and the mDNS `fp`
+// TXT value travel as lowercase hex.
+
+import Foundation
+
+extension Data {
+    /// Lowercase hex, no separators — to compare a pinned fingerprint against the mDNS `fp`.
+    var hexLower: String { map { String(format: "%02x", $0) }.joined() }
+
+    /// Parse an even-length hex string into bytes; nil on any non-hex character or odd length.
+    /// Used to turn an mDNS-advertised cert fingerprint into a connect pin.
+    init?(hexString: String) {
+        let chars = Array(hexString)
+        guard chars.count.isMultiple(of: 2) else { return nil }
+        var bytes = [UInt8]()
+        bytes.reserveCapacity(chars.count / 2)
+        var i = 0
+        while i < chars.count {
+            guard let hi = chars[i].hexDigitValue, let lo = chars[i + 1].hexDigitValue else {
+                return nil
+            }
+            bytes.append(UInt8(hi << 4 | lo))
+            i += 2
+        }
+        self = Data(bytes)
+    }
+}

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

@@ -70,7 +70,7 @@ struct TrustCardView: View {
 
     /// 64 hex chars → four groups per line, two lines — easy to eyeball against the log.
     private static func format(fingerprint: Data) -> String {
-        let hex = fingerprint.map { String(format: "%02x", $0) }.joined()
+        let hex = fingerprint.hexLower
         let groups = stride(from: 0, to: hex.count, by: 8).map { i -> String in
             let start = hex.index(hex.startIndex, offsetBy: i)
             let end = hex.index(start, offsetBy: min(8, hex.count - i))