feat(client/speedtest): request the host's full 3 Gbps probe ceiling

The Apple speed test asked for only 400 Mbps, capping the measured throughput there and hiding the link's real headroom. Request the host's full MAX_PROBE_KBPS (3 Gbps) instead, and raise the recommended-bitrate clamp from 500 Mbps to the host's 2 Gbps session ceiling so a fast measurement yields a usable recommendation. Also fix the stale caps left when the host clamps were raised (b8a33e2): the resolved-bitrate range and the probe doc comments (abi.rs, client.rs, regenerated header), plus the section 9 roadmap copy, now read 3 Gbps probe / 2 Gbps session. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-12 14:04:49 +02:00
parent 1c94f46be8
commit 6b4de5d738
9 changed files with 467 additions and 18 deletions
@@ -77,6 +77,7 @@ final class SessionModel: ObservableObject {
    func connect(to host: StoredHost, width: UInt32, height: UInt32, hz: UInt32,
                 compositor: PunktfunkConnection.Compositor = .auto,
                 gamepad: PunktfunkConnection.GamepadType = .auto,
+                 bitrateKbps: UInt32 = 0,
                 autoTrust: Bool = false) {
        guard phase == .idle else { return }
        phase = .connecting
@@ -93,7 +94,7 @@ final class SessionModel: ObservableObject {
                host: host.address, port: host.port,
                width: width, height: height, refreshHz: hz,
                pinSHA256: pin, identity: identity, compositor: compositor,
-                gamepad: gamepad) }
+                gamepad: gamepad, bitrateKbps: bitrateKbps) }
            await MainActor.run { [weak self] in
                guard let self else { return }
                // The user may have abandoned this attempt (window closed, another host
@@ -16,6 +16,7 @@ struct SettingsView: View {
    @AppStorage("punktfunk.hz") private var hz = 60
    @AppStorage("punktfunk.compositor") private var compositor = 0
    @AppStorage("punktfunk.gamepadType") private var gamepadType = 0
+    @AppStorage("punktfunk.bitrateKbps") private var bitrateKbps = 0
    @AppStorage("punktfunk.micEnabled") private var micEnabled = true
    @ObservedObject private var gamepads = GamepadManager.shared
    #if os(macOS)
@@ -77,11 +78,19 @@ struct SettingsView: View {
        return ScrollView {
            VStack(spacing: 16) {
                TVSelectionRow(title: "Stream mode", options: options, selection: modeTag)
+                TVSelectionRow(
+                    title: "Bitrate", options: bitrateOptions, selection: $bitrateKbps)
+                if bitrateKbps > 1_000_000 {
+                    Label(Self.gigabitWarning, systemImage: "exclamationmark.triangle.fill")
+                        .font(.caption)
+                        .foregroundStyle(.orange)
+                        .multilineTextAlignment(.center)
+                }
                TVSelectionRow(
                    title: "Compositor", options: compositors, selection: $compositor)
                Text("The host creates a virtual output at exactly this mode — native "
-                    + "resolution, no scaling. A specific compositor is honored only if "
-                    + "available on the host.")
+                    + "resolution, no scaling. \(Self.bitrateFooter) A specific compositor "
+                    + "is honored only if available on the host.")
                    .font(.caption)
                    .foregroundStyle(.secondary)
                    .multilineTextAlignment(.center)
@@ -114,6 +123,77 @@ struct SettingsView: View {
    }
    #endif

+    // 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
+
+    private 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."
+
+    private 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.
+    private 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.
+    private 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)
+            })
+    }
+
+    #if os(tvOS)
+    /// tvOS has no Slider — the focus-native control is the pushed picker (the same
+    /// pattern as the stream mode), so the rates are presets here, up to the same 3 Gbps
+    /// ceiling, plus a custom entry so a non-preset stored value stays visible.
+    private 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),
+    ]
+
+    private var bitrateOptions: [(label: String, tag: Int)] {
+        var options = Self.bitratePresets
+        if !options.contains(where: { $0.tag == bitrateKbps }) {
+            options.insert(
+                (SpeedTestSheet.mbpsLabel(kbps: bitrateKbps) + " (custom)", bitrateKbps), at: 1)
+        }
+        return options
+    }
+    #endif
+
    // MARK: - Controllers

    private static let padTypes: [(label: String, tag: Int)] = [
@@ -200,11 +280,32 @@ struct SettingsView: View {
                LabeledContent("") {
                    Button("Use this display's mode") { fillFromMainScreen() }
                }
+                // (sharedBody is unused on tvOS — its body still compiles there, and
+                // Slider doesn't exist on tvOS; the tv path has its own preset picker.)
+                #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(.caption)
+                            .foregroundStyle(.orange)
+                    }
+                }
+                #endif
            } header: {
                Text("Stream mode")
            } footer: {
                Text("The host creates a virtual output at exactly this mode — "
-                    + "native resolution, no scaling.")
+                    + "native resolution, no scaling. \(Self.bitrateFooter)")
                    .font(.caption)
                    .foregroundStyle(.secondary)
            }
@@ -324,3 +425,10 @@ struct SettingsView: View {
        #endif
    }
 }
+
+extension Double {
+    /// The log-scale slider mapping needs a bounded input (Automatic stores 0).
+    fileprivate func clamped(_ lo: Double, _ hi: Double) -> Double {
+        Swift.min(Swift.max(self, lo), hi)
+    }
+}
@@ -0,0 +1,237 @@
+// Network speed-test sheet (roadmap §9): connect to the host, ask it to burst probe
+// filler over the real data plane (FEC-encoded UDP, video paused — the measurement IS the
+// streaming path), poll the measurement, and recommend a bitrate (~70% of the measured
+// goodput, headroom for encoder burstiness). "Use N Mbps" writes the bitrate setting; it
+// applies from the next session.
+//
+// Runs only while idle (the host serves one session at a time, so it can't share the wire
+// with a live stream — the host-card grid is the idle UI anyway). Trust: a pinned host is
+// verified as usual; an unpinned one is probed trust-on-first-use WITHOUT persisting
+// anything — a bandwidth number doesn't justify a trust decision.
+
+import Foundation
+import PunktfunkKit
+import SwiftUI
+
+/// Dismissal must abandon the in-flight probe: the connect/poll loop runs detached and
+/// checks this flag, closing the connection itself. Only the flag is shared; it is safe
+/// to read/write from the loop and the main actor (single Bool, torn reads harmless).
+private final class ProbeToken: @unchecked Sendable {
+    var cancelled = false
+}
+
+/// What the host is asked to burst: the host's full probe ceiling (it clamps to ≤ 3 Gbps),
+/// so the measurement surfaces the link's real ceiling instead of an artificial cap —
+/// bursting ABOVE what the link can carry is how the probe finds where delivery falls off.
+/// Two seconds rides out scheduler jitter. File-scope so the detached probe task reads them
+/// without crossing into the view's main actor.
+private let probeTargetKbps: UInt32 = 3_000_000
+private let probeDurationMs: UInt32 = 2_000
+
+struct SpeedTestSheet: View {
+    @Environment(\.dismiss) private var dismiss
+    let host: StoredHost
+
+    @AppStorage("punktfunk.width") private var width = 1920
+    @AppStorage("punktfunk.height") private var height = 1080
+    @AppStorage("punktfunk.hz") private var hz = 60
+    @AppStorage("punktfunk.bitrateKbps") private var bitrateKbps = 0
+
+    private enum Phase: Equatable {
+        case connecting
+        case probing(partial: PunktfunkConnection.ProbeResult?)
+        case done(PunktfunkConnection.ProbeResult)
+        case failed(String)
+    }
+
+    @State private var phase: Phase = .connecting
+    @State private var token = ProbeToken()
+
+    var body: some View {
+        VStack(spacing: 20) {
+            Label("Speed test — \(host.displayName)", systemImage: "gauge.with.needle")
+                .font(.headline)
+                .foregroundStyle(.tint)
+
+            switch phase {
+            case .connecting:
+                ProgressView("Connecting…")
+                    .padding(.vertical, 12)
+            case .probing(let partial):
+                VStack(spacing: 8) {
+                    ProgressView("Measuring — the host is bursting probe data…")
+                    if let partial, partial.throughputKbps > 0 {
+                        Text("~\(Self.mbpsLabel(kbps: Int(partial.throughputKbps))) so far")
+                            .font(.callout.monospacedDigit())
+                            .foregroundStyle(.secondary)
+                    }
+                }
+                .padding(.vertical, 12)
+            case .done(let result):
+                resultView(result)
+            case .failed(let message):
+                Text(message)
+                    .font(.callout)
+                    .foregroundStyle(.red)
+                    .multilineTextAlignment(.center)
+            }
+
+            HStack(spacing: 24) {
+                Button(phaseIsFinal ? "Close" : "Cancel", role: .cancel) {
+                    token.cancelled = true
+                    dismiss()
+                }
+                #if !os(tvOS)
+                .keyboardShortcut(.cancelAction)
+                #endif
+                if case .done(let result) = phase, let rec = Self.recommendedKbps(result) {
+                    Button("Use \(Self.mbpsLabel(kbps: rec))") {
+                        bitrateKbps = rec
+                        dismiss()
+                    }
+                    .buttonStyle(.borderedProminent)
+                    #if !os(tvOS)
+                    .keyboardShortcut(.defaultAction)
+                    #endif
+                }
+                if case .failed = phase {
+                    Button("Retry") { run() }
+                        .buttonStyle(.borderedProminent)
+                }
+            }
+        }
+        #if os(tvOS)
+        .frame(maxWidth: 1000)
+        .padding(60)
+        #else
+        .padding(24)
+        #endif
+        #if os(macOS)
+        .frame(width: 420)
+        .fixedSize(horizontal: false, vertical: true)
+        #endif
+        .onAppear { run() }
+        .onDisappear { token.cancelled = true }
+    }
+
+    private var phaseIsFinal: Bool {
+        switch phase {
+        case .done, .failed: return true
+        case .connecting, .probing: return false
+        }
+    }
+
+    private func resultView(_ result: PunktfunkConnection.ProbeResult) -> some View {
+        VStack(spacing: 10) {
+            Text(Self.mbpsLabel(kbps: Int(result.throughputKbps)))
+                .font(.system(.largeTitle, design: .rounded).weight(.semibold))
+                .monospacedDigit()
+            Grid(alignment: .leading, horizontalSpacing: 16, verticalSpacing: 4) {
+                GridRow {
+                    Text("Loss").foregroundStyle(.secondary)
+                    Text(String(format: "%.1f %%", result.lossPct)).monospacedDigit()
+                }
+                GridRow {
+                    Text("Received").foregroundStyle(.secondary)
+                    Text("\(ByteCountFormatter.string(fromByteCount: Int64(result.recvBytes), countStyle: .binary)) in \(result.elapsedMs) ms")
+                        .monospacedDigit()
+                }
+            }
+            .font(.callout)
+            if let rec = Self.recommendedKbps(result) {
+                Text("Recommended bitrate: \(Self.mbpsLabel(kbps: rec)) "
+                    + "(~70% of measured, headroom for encoder bursts).")
+                    .font(.caption)
+                    .foregroundStyle(.secondary)
+                    .multilineTextAlignment(.center)
+            } else {
+                Text("Too little data made it through to recommend a bitrate — "
+                    + "check the network and retry.")
+                    .font(.caption)
+                    .foregroundStyle(.secondary)
+                    .multilineTextAlignment(.center)
+            }
+        }
+    }
+
+    /// ~70% of the measured goodput, whole Mbps, clamped to the host's session bitrate
+    /// ceiling (2 Gbps — it clamps any session request above that, so recommending more is
+    /// pointless). nil when the measurement carried too little signal to recommend anything.
+    static func recommendedKbps(_ result: PunktfunkConnection.ProbeResult) -> Int? {
+        guard result.throughputKbps >= 2_000 else { return nil }
+        let raw = Int(result.throughputKbps) * 7 / 10
+        let wholeMbps = max(raw / 1_000, 2)
+        return min(wholeMbps, 2_000) * 1_000
+    }
+
+    static func mbpsLabel(kbps: Int) -> String {
+        if kbps >= 1_000_000 {
+            let gbps = Double(kbps) / 1_000_000
+            return gbps == gbps.rounded()
+                ? "\(Int(gbps)) Gbps"
+                : String(format: "%.1f Gbps", gbps)
+        }
+        return kbps % 1_000 == 0
+            ? "\(kbps / 1_000) Mbps"
+            : String(format: "%.1f Mbps", Double(kbps) / 1_000)
+    }
+
+    private func run() {
+        phase = .connecting
+        let token = token
+        let address = host.address
+        let port = host.port
+        let pin = host.pinnedSHA256
+        let (w, h, fps) = (UInt32(clamping: width), UInt32(clamping: height), UInt32(clamping: hz))
+        Task.detached(priority: .userInitiated) {
+            // Connect (blocking) — same identity/trust as a session, but TOFU results are
+            // NOT persisted from here.
+            let identity = (try? ClientIdentityStore.shared.load())?.identity
+            let conn: PunktfunkConnection
+            do {
+                conn = try PunktfunkConnection(
+                    host: address, port: port, width: w, height: h, refreshHz: fps,
+                    pinSHA256: pin, identity: identity)
+            } catch {
+                await MainActor.run {
+                    guard !token.cancelled else { return }
+                    phase = .failed(
+                        "Could not connect to \(address):\(port) — is punktfunk-host "
+                        + "running and not mid-session?")
+                }
+                return
+            }
+            defer { conn.close() }
+
+            conn.startSpeedTest(targetKbps: probeTargetKbps, durationMs: probeDurationMs)
+            await MainActor.run { if !token.cancelled { phase = .probing(partial: nil) } }
+
+            // Poll until the host's end-of-burst report lands (or a generous deadline —
+            // the host clamps the burst to ≤ 5 s).
+            let deadline = Date().addingTimeInterval(Double(probeDurationMs) / 1000 + 8)
+            var final: PunktfunkConnection.ProbeResult?
+            while !token.cancelled, Date() < deadline {
+                try? await Task.sleep(nanoseconds: 200_000_000)
+                guard let r = conn.probeResult() else { break } // closed underneath us
+                if r.done {
+                    final = r
+                    break
+                }
+                await MainActor.run {
+                    if !token.cancelled { phase = .probing(partial: r) }
+                }
+            }
+            let result = final
+            await MainActor.run {
+                guard !token.cancelled else { return }
+                if let result {
+                    phase = .done(result)
+                } else {
+                    phase = .failed(
+                        "The measurement never completed — the connection may have "
+                        + "dropped mid-probe. Retry?")
+                }
+            }
+        }
+    }
+}
@@ -202,6 +202,11 @@ public final class PunktfunkConnection {
    /// machines. `0` = no correction (an older host that didn't answer, or synchronized clocks).
    public private(set) var clockOffsetNs: Int64 = 0

+    /// The video encoder bitrate (kbps) the host actually configured — the requested
+    /// `bitrateKbps` clamped to the host's range ([500, 2 000 000] kbps), or its default
+    /// (20 000) when 0 was requested. `0` = an older host that didn't report it.
+    public private(set) var resolvedBitrateKbps: UInt32 = 0
+
    /// Connect and start a session at the requested mode (the host creates a native virtual
    /// output at exactly this size/refresh). Blocks up to `timeoutMs`.
    ///
@@ -218,6 +223,10 @@ public final class PunktfunkConnection {
    ///
    /// `gamepad`: which virtual pad the host creates for this session's controllers (see
    /// `GamepadType`; `.auto` = host decides). Check `resolvedGamepad` afterwards.
+    ///
+    /// `bitrateKbps`: requested video encoder bitrate (0 = host default; the host clamps
+    /// to its supported range). Check `resolvedBitrateKbps` afterwards — a speed test
+    /// (`startSpeedTest`) is how a client picks an informed value.
    public init(
        host: String, port: UInt16 = 9777,
        width: UInt32, height: UInt32, refreshHz: UInt32,
@@ -225,6 +234,7 @@ public final class PunktfunkConnection {
        identity: ClientIdentity? = nil,
        compositor: Compositor = .auto,
        gamepad: GamepadType = .auto,
+        bitrateKbps: UInt32 = 0,
        timeoutMs: UInt32 = 10_000
    ) throws {
        if let pin = pinSHA256, pin.count != 32 { throw PunktfunkClientError.invalidPin }
@@ -234,16 +244,16 @@ public final class PunktfunkConnection {
                withOptionalCString(identity?.keyPEM) { key in
                    if let pin = pinSHA256 {
                        return pin.withUnsafeBytes { p in
-                            punktfunk_connect_ex2(
+                            punktfunk_connect_ex3(
                                cs, port, width, height, refreshHz, compositor.rawValue,
-                                gamepad.rawValue,
+                                gamepad.rawValue, bitrateKbps,
                                p.bindMemory(to: UInt8.self).baseAddress, &observed,
                                cert, key, timeoutMs)
                        }
                    }
-                    return punktfunk_connect_ex2(
+                    return punktfunk_connect_ex3(
                        cs, port, width, height, refreshHz, compositor.rawValue,
-                        gamepad.rawValue,
+                        gamepad.rawValue, bitrateKbps,
                        nil, &observed, cert, key, timeoutMs)
                }
            }
@@ -261,6 +271,54 @@ public final class PunktfunkConnection {
        var offset: Int64 = 0
        _ = punktfunk_connection_clock_offset_ns(handle, &offset)
        clockOffsetNs = offset
+        var br: UInt32 = 0
+        _ = punktfunk_connection_bitrate(handle, &br)
+        resolvedBitrateKbps = br
+    }
+
+    /// A bandwidth speed-test measurement (see `startSpeedTest`). Partial until `done`.
+    public struct ProbeResult: Sendable, Equatable {
+        /// The host's end-of-burst report arrived — the numbers are final.
+        public let done: Bool
+        /// Probe payload bytes / packets the client received.
+        public let recvBytes: UInt64
+        public let recvPackets: UInt32
+        /// Probe payload bytes / packets the host reported sending.
+        public let hostBytes: UInt64
+        public let hostPackets: UInt32
+        /// Client-measured receive window (first→last probe AU), milliseconds.
+        public let elapsedMs: UInt32
+        /// Measured goodput, kilobits per second.
+        public let throughputKbps: UInt32
+        /// Delivery loss `(hostBytes − recvBytes) / hostBytes`, percent (0 if unknown).
+        public let lossPct: Float
+    }
+
+    /// Start a bandwidth speed test: the host bursts filler over the data plane at
+    /// `targetKbps` of goodput for `durationMs` (clamped host-side to ≤ 3 Gbps / ≤ 5 s),
+    /// briefly pausing video. Non-blocking — poll `probeResult()` until `done`. Starting
+    /// a probe resets any prior measurement. Silently dropped after close.
+    public func startSpeedTest(targetKbps: UInt32, durationMs: UInt32) {
+        abiLock.lock()
+        defer { abiLock.unlock() }
+        guard let h = handle, !closeRequested else { return }
+        _ = punktfunk_connection_speed_test(h, targetKbps, durationMs)
+    }
+
+    /// The current speed-test measurement (zeros before any probe; partial until `done`).
+    /// Safe to poll from any thread; nil after close.
+    public func probeResult() -> ProbeResult? {
+        abiLock.lock()
+        defer { abiLock.unlock() }
+        guard let h = handle, !closeRequested else { return nil }
+        var out = PunktfunkProbeResult()
+        guard punktfunk_connection_probe_result(h, &out) == statusOK else { return nil }
+        return ProbeResult(
+            done: out.done != 0,
+            recvBytes: out.recv_bytes, recvPackets: out.recv_packets,
+            hostBytes: out.host_bytes, hostPackets: out.host_packets,
+            elapsedMs: out.elapsed_ms, throughputKbps: out.throughput_kbps,
+            lossPct: out.loss_pct)
    }

    /// Ask the host to switch the live session to a new mode (window resized) — no
@@ -509,6 +567,17 @@ public extension PunktfunkInputEvent {
    static func mouseMove(dx: Int32, dy: Int32) -> PunktfunkInputEvent {
        make(PUNKTFUNK_INPUT_KIND_MOUSE_MOVE.rawValue, code: 0, x: dx, y: dy)
    }
+    /// Absolute cursor position in client-surface pixels — the host places its cursor
+    /// there (same letterbox mapping and `flags` surface-dims packing as the touch events).
+    /// Used by the iPad pointer fallback when the scene can't pointer-lock and GCMouse's
+    /// relative deltas aren't available; the surface dimensions must each fit in 16 bits.
+    static func mouseMoveAbs(
+        x: Int32, y: Int32, surfaceWidth: UInt32, surfaceHeight: UInt32
+    ) -> PunktfunkInputEvent {
+        make(
+            PUNKTFUNK_INPUT_KIND_MOUSE_MOVE_ABS.rawValue, code: 0, x: x, y: y,
+            flags: ((surfaceWidth & 0xFFFF) << 16) | (surfaceHeight & 0xFFFF))
+    }
    /// GameStream button ids: 1=left 2=middle 3=right 4=X1 5=X2 (host maps to evdev BTN_*).
    static func mouseButton(_ button: UInt32, down: Bool) -> PunktfunkInputEvent {
        make(