feat(clients): host/network split in every stats HUD (stats phase 2, client side)

Consumes the 0xCF host-timing plane (449a67c) on all four GUI clients: each keeps a bounded pending ring of receipt samples keyed by pts, matches the host's per-AU capture→sent reports against it, and the HUD equation becomes = host 3.1 + network 6.7 + decode 2.1 + display 2.3 falling back to the combined `= host+network …` term whenever no timing matched the window (old host / datagram loss) — same total, one split fewer, never a misleading zero. Apple additionally gains the split as the only equation line under the stage-1 fallback presenter (receipt is presenter-independent), a `nextHostTiming` wrapper with its own plane lock, and a unit-tested `HostNetworkSplitter`; Android extends the JNI stats array 16→18 doubles (0–15 unchanged); Windows/Linux thread the split through `Stats` into the HUD and the headless/debug logs. Docs updated: design/stats-unification.md Phase 2 → implemented (wire format, fallback semantics), and the docs-site matrix's Sunshine "Host processing latency" row is now a direct match (ours includes the paced send; avg vs p50). Verified here: linux client clippy -D warnings green on the live tree, windows stub check + hand-verified diff, android cargo-ndk arm64 check green, apple loopback test extended (needs the rebuilt xcframework + swift test on the mac). On-glass: pending on all platforms. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-03 21:31:49 +00:00
parent 8470419433
commit 69609945a3
19 changed files with 610 additions and 59 deletions
@@ -326,9 +326,14 @@ struct ContentView: View {
                    onCaptureChange: { [weak model] captured in
                        model?.mouseCaptured = captured
                    },
-                    onFrame: { [meter = model.meter, latency = model.latency, offset = conn.clockOffsetNs] au in
+                    onFrame: { [meter = model.meter, latency = model.latency,
+                                split = model.latencySplit, offset = conn.clockOffsetNs] au in
                        meter.note(byteCount: au.data.count)
                        latency.record(ptsNs: au.ptsNs, offsetNs: offset)
+                        // The same receipt, keyed by pts, awaiting its 0xCF host timing (the
+                        // host/network split — drained by the 1 s stats tick).
+                        split.recordReceipt(
+                            ptsNs: au.ptsNs, receivedNs: au.receivedNs, offsetNs: offset)
                    },
                    onSessionEnd: { [weak model] in
                        Task { @MainActor in model?.sessionEnded() }
@@ -69,6 +69,14 @@ final class SessionModel: ObservableObject {
    @Published var hostNetworkP95Ms = 0.0
    @Published var hostNetworkValid = false
    @Published var hostNetworkSkewCorrected = false
+    /// Phase 2 of the same stage: `host+network` split into its two terms via the host's per-AU
+    /// 0xCF timing reports (host = capture→fully-sent as the host measured it, network = the
+    /// remainder), matched to receipts by pts in `latencySplit`. `splitValid` is false whenever
+    /// no timing matched in the window — an old host that never emits the plane, or heavy 0xCF
+    /// loss — and the HUD then falls back to the combined `host+network` term.
+    @Published var hostP50Ms = 0.0
+    @Published var networkP50Ms = 0.0
+    @Published var splitValid = false
    /// End-to-end = capture→on-glass, measured directly per frame (never summed from the stages) —
    /// the HUD headline. Only the stage-2 presenter can stamp it (it owns decode + a
    /// CAMetalLayer/display-link present); stays invalid under stage-1, where the layer presents
@@ -96,6 +104,10 @@ final class SessionModel: ObservableObject {
    /// Capture→received (the host+network stage), fed per AU at receipt by the stream view's
    /// onFrame — under both presenters.
    let latency = LatencyMeter()
+    /// The host/network split of that same stage: onFrame also records (pts, interval) receipts
+    /// here, and the 1 s stats tick drains the connection's 0xCF host timings into it — under
+    /// both presenters (the receipt path is presenter-independent).
+    let latencySplit = HostNetworkSplitter()
    /// The stage-2 meters, passed to StreamView: end-to-end (capture→on-glass, stamped at
    /// present), decode (received→decoded), display (decoded→on-glass).
    let endToEnd = LatencyMeter()
@@ -296,6 +308,7 @@ final class SessionModel: ObservableObject {
        fps = 0
        mbps = 0
        hostNetworkValid = false
+        splitValid = false
        endToEndValid = false
        decodeValid = false
        displayValid = false
@@ -341,6 +354,7 @@ final class SessionModel: ObservableObject {

    private func startStatsTimer() {
        lastFramesDropped = 0 // a fresh connection's cumulative drop counter starts at 0
+        latencySplit.reset() // no stale receipts/samples from a previous session
        let timer = Timer(timeInterval: 1.0, repeats: true) { [weak self] _ in
            guard let self else { return }
            Task { @MainActor in
@@ -364,6 +378,25 @@ final class SessionModel: ObservableObject {
                } else {
                    self.hostNetworkValid = false
                }
+                // Phase 2: drain the window's per-AU host timings (0xCF) into the splitter —
+                // non-blocking, bounded (a 240 fps window is ~240 reports; the cap only guards
+                // a pathological burst). `try?` flattens (SE-0230); a throw (.closed during
+                // teardown) just ends the drain. An old host never emits any → splitValid stays
+                // false and the HUD keeps the combined host+network term.
+                if let conn = self.connection {
+                    var burst = 0
+                    while burst < 1024, let t = try? conn.nextHostTiming(timeoutMs: 0) {
+                        self.latencySplit.noteHostTiming(ptsNs: t.ptsNs, hostUs: t.hostUs)
+                        burst += 1
+                    }
+                }
+                if let s = self.latencySplit.drain() {
+                    self.hostP50Ms = s.hostP50Ms
+                    self.networkP50Ms = s.networkP50Ms
+                    self.splitValid = true
+                } else {
+                    self.splitValid = false
+                }
                if let e = self.endToEnd.drain() {
                    self.endToEndP50Ms = e.p50Ms
                    self.endToEndP95Ms = e.p95Ms
@@ -26,20 +26,34 @@ struct StreamHUDView: View {
                Text("end-to-end \(model.endToEndP50Ms, specifier: "%.1f") ms p50 · \(model.endToEndP95Ms, specifier: "%.1f") p95 · capture→on-glass\(model.endToEndSkewCorrected ? "" : " (same-host clock)")")
                    .font(.system(.caption2, design: .monospaced))
                    .foregroundStyle(.secondary)
-                // The equation: the three stages tiling the headline interval (per-window p50s —
-                // they only approximately sum to the directly-measured total).
+                // The equation: the stages tiling the headline interval (per-window p50s —
+                // they only approximately sum to the directly-measured total). With a host
+                // that reports per-AU timings (0xCF) the first term splits into host + network
+                // (phase 2); an old host keeps the combined term.
                if model.hostNetworkValid && model.decodeValid && model.displayValid {
-                    Text("= host+network \(model.hostNetworkP50Ms, specifier: "%.1f") + decode \(model.decodeP50Ms, specifier: "%.1f") + display \(model.displayP50Ms, specifier: "%.1f")")
-                        .font(.system(.caption2, design: .monospaced))
-                        .foregroundStyle(.secondary)
+                    if model.splitValid {
+                        Text("= host \(model.hostP50Ms, specifier: "%.1f") + network \(model.networkP50Ms, specifier: "%.1f") + decode \(model.decodeP50Ms, specifier: "%.1f") + display \(model.displayP50Ms, specifier: "%.1f")")
+                            .font(.system(.caption2, design: .monospaced))
+                            .foregroundStyle(.secondary)
+                    } else {
+                        Text("= host+network \(model.hostNetworkP50Ms, specifier: "%.1f") + decode \(model.decodeP50Ms, specifier: "%.1f") + display \(model.displayP50Ms, specifier: "%.1f")")
+                            .font(.system(.caption2, design: .monospaced))
+                            .foregroundStyle(.secondary)
+                    }
                }
            } else if model.hostNetworkValid {
                // Stage-1 fallback presenter: the layer decodes + presents internally with no
-                // per-frame stamp, so the honest headline ends at receipt — and there is no
-                // equation line (host+network is the whole measured interval).
+                // per-frame stamp, so the honest headline ends at receipt. The host/network
+                // split still applies there (receipt is presenter-independent) — it becomes the
+                // only equation line; without it, host+network IS the whole measured interval.
                Text("capture→received \(model.hostNetworkP50Ms, specifier: "%.1f") ms p50 · \(model.hostNetworkP95Ms, specifier: "%.1f") p95\(model.hostNetworkSkewCorrected ? "" : " (same-host clock)")")
                    .font(.system(.caption2, design: .monospaced))
                    .foregroundStyle(.secondary)
+                if model.splitValid {
+                    Text("= host \(model.hostP50Ms, specifier: "%.1f") + network \(model.networkP50Ms, specifier: "%.1f")")
+                        .font(.system(.caption2, design: .monospaced))
+                        .foregroundStyle(.secondary)
+                }
            }
            if model.lostFrames > 0 {
                // Unrecoverable network drops this window; hidden while the link is clean.