feat(clients): unified stats vocabulary across every client + Moonlight comparison docs

One stat model everywhere (design/stats-unification.md): four measurement
points (capture/received/decoded/displayed), three stages that tile the
interval exactly, and a HUD that shows the addition explicitly —

  end-to-end 14.2 ms p50 · 19.8 p95 · capture→on-glass
  = host+network 9.8 + decode 2.1 + display 2.3

replacing each client's ad-hoc mix of overlapping absolutes (the Apple HUD's
three arrow lines that looked sequential but weren't), mean-vs-median decode
times (Windows/Linux), missing same-host-clock flags (Windows/Linux), and
three different names for the same capture→received measurement (probe's
"reassembled", Apple/Android's "client", Windows/Linux's post-decode "lat").

Per client: Apple threads receivedNs through the VT decode via the frame
refcon bit pattern so the decode stage exists at all (stage-1 fallback
honestly degrades to a capture→received headline); Windows carries
FrameTimes through the existing frame channel to the render thread and adds
e2e p50/p95 post-Present; Linux stamps received at AU pop and rides
decoded_ns on DecodedFrame to the paintable-set site; Android pairs receipt
stamps with MediaCodec output buffers via the codec's pts round-trip (JNI
stats array 14→16 doubles, indexes 0-13 unchanged). fps now uniformly counts
received AUs; lost/(received+lost) per window, hidden at zero.

docs-site gains "Understanding the Stats Overlay": what each line means, why
the equation only approximately sums (percentiles), and a line-by-line
Moonlight/Sunshine matrix — including that Moonlight has no end-to-end
number and its "network latency" is an ENet control RTT, so punktfunk's
headline must not be compared against any single Moonlight line.

Verified here: linux client + probe + core check/clippy/fmt green, android
native cargo-ndk arm64 check green. Pending: Windows CI + on-glass, swift
test on the mac, on-device Android.

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

clients/apple/Sources/PunktfunkKit/Views/StreamView.swift

@@ -85,39 +85,45 @@ public struct StreamView: NSViewRepresentable {
     private let onCaptureChange: ((Bool) -> Void)?
     private let onFrame: (@Sendable (AccessUnit) -> Void)?
     private let onSessionEnd: (@Sendable () -> Void)?
-    private let presentMeter: LatencyMeter?
-    private let presentTailMeter: LatencyMeter?
+    private let endToEndMeter: LatencyMeter?
+    private let decodeMeter: LatencyMeter?
+    private let displayMeter: LatencyMeter?
 
     /// `onFrame`/`onSessionEnd` fire on the pump thread — hop to the main actor for UI.
     /// `captureEnabled: false` disables input capture entirely while UI (e.g. a trust
     /// prompt) is layered over the stream; flipping it to true auto-engages capture
     /// once. `onCaptureChange` (main thread) reports engage/release — drive the HUD's
-    /// "click to capture" / "⌘⎋ releases" hint with it. `presentMeter` records capture→present
-    /// and `presentTailMeter` decode→present when the stage-2 presenter is active.
+    /// "click to capture" / "⌘⎋ releases" hint with it. The meters record the unified latency
+    /// stages when the stage-2 presenter is active (design/stats-unification.md):
+    /// `endToEndMeter` capture→on-glass, `decodeMeter` received→decoded, `displayMeter`
+    /// decoded→on-glass.
     public init(
         connection: PunktfunkConnection,
         captureEnabled: Bool = true,
         onCaptureChange: ((Bool) -> Void)? = nil,
         onFrame: (@Sendable (AccessUnit) -> Void)? = nil,
         onSessionEnd: (@Sendable () -> Void)? = nil,
-        presentMeter: LatencyMeter? = nil,
-        presentTailMeter: LatencyMeter? = nil
+        endToEndMeter: LatencyMeter? = nil,
+        decodeMeter: LatencyMeter? = nil,
+        displayMeter: LatencyMeter? = nil
     ) {
         self.connection = connection
         self.captureEnabled = captureEnabled
         self.onCaptureChange = onCaptureChange
         self.onFrame = onFrame
         self.onSessionEnd = onSessionEnd
-        self.presentMeter = presentMeter
-        self.presentTailMeter = presentTailMeter
+        self.endToEndMeter = endToEndMeter
+        self.decodeMeter = decodeMeter
+        self.displayMeter = displayMeter
     }
 
     public func makeNSView(context: Context) -> StreamLayerView {
         let view = StreamLayerView()
         view.onCaptureChange = onCaptureChange
         view.captureEnabled = captureEnabled
-        view.presentMeter = presentMeter
-        view.presentTailMeter = presentTailMeter
+        view.endToEndMeter = endToEndMeter
+        view.decodeMeter = decodeMeter
+        view.displayMeter = displayMeter
         view.start(connection: connection, onFrame: onFrame, onSessionEnd: onSessionEnd)
         return view
     }
@@ -125,8 +131,9 @@ public struct StreamView: NSViewRepresentable {
     public func updateNSView(_ view: StreamLayerView, context: Context) {
         view.onCaptureChange = onCaptureChange
         view.captureEnabled = captureEnabled
-        view.presentMeter = presentMeter
-        view.presentTailMeter = presentTailMeter
+        view.endToEndMeter = endToEndMeter
+        view.decodeMeter = decodeMeter
+        view.displayMeter = displayMeter
         // SwiftUI reuses the NSView across state changes — repoint the pump only when the
         // connection identity actually changed.
         if view.connection !== connection {
@@ -141,10 +148,11 @@ public struct StreamView: NSViewRepresentable {
 
 public final class StreamLayerView: NSView {
     private let displayLayer = AVSampleBufferDisplayLayer()
-    /// Record capture→present / decode→present when the stage-2 presenter is active.
-    /// Consulted at start().
-    var presentMeter: LatencyMeter?
-    var presentTailMeter: LatencyMeter?
+    /// Record the unified latency stages (end-to-end / decode / display) when the stage-2
+    /// presenter is active. Consulted at start().
+    var endToEndMeter: LatencyMeter?
+    var decodeMeter: LatencyMeter?
+    var displayMeter: LatencyMeter?
     /// The shared presenter stack: stage-2 (CAMetalLayer sublayer + display link) with the
     /// stage-1 StreamPump → displayLayer path as the Metal-unavailable / DEBUG fallback.
     private let presenter = SessionPresenter()
@@ -571,8 +579,9 @@ public final class StreamLayerView: NSView {
         presenter.start(
             connection: connection,
             baseLayer: displayLayer,
-            presentMeter: presentMeter,
-            presentTailMeter: presentTailMeter,
+            endToEndMeter: endToEndMeter,
+            decodeMeter: decodeMeter,
+            displayMeter: displayMeter,
             makeDisplayLink: { displayLink(target: $0, selector: $1) },
             onFrame: onFrame,
             onSessionEnd: onSessionEnd)