fix(ios): canonical AVKit signals + sink-time payload snapshot (#385)

Two coordinated fixes to iOS metrics emission. Closes #349 and #350.

## Summary

Both issues root in the same late-evaluation pattern: payloads were
built at Task-execution time after queuing through `metricsTaskTail`, so
`Date()` and `diagnostics.state` were stamped well after the underlying
event fired. Plus `video_first_frame` was synthesized from `currentTime`
ticks instead of the canonical `AVPlayerLayer.isReadyForDisplay` signal.

### #350 — `video_first_frame` 2-3× burst

- New `Coordinator` on the `PlayerView` `UIViewControllerRepresentable`
walks `AVPlayerViewController.view.layer` to find the embedded
`AVPlayerLayer`, KVO-observes `isReadyForDisplay`, and calls
`markFirstFrameRendered(at:)` on the flip.
- iOS doesn't reliably expose the layer on initial mount (Apple's
private rendering path), so the `currentTime > 0 && state == "playing"`
synthesis is kept as a **fallback**. Shared `firstFrameReported` latch
ensures exactly one event per playback regardless of which signal wins.
- `video_start_time` migrated to the same canonical pattern via
`timeControlStatus == .playing` KVO + `markPlayingStarted(at:)`.

### #349 — `state_change` burst with frozen `last_event_at`

- Every metrics emit site now snapshots `Date()` AND builds the payload
synchronously at the firing context, then hands the immutable dict to a
Task that does only HTTP.
- New `sendPlayerMetrics(payload:)` overload. Existing
`sendPlayerMetrics(event:at:extra:)` kept as convenience that builds +
forwards.
- Sites converted (no caller deferred): every Combine sink in
`bindMetricsReporting` and `bindDiagnosticsLogging`, `timeJumpSubject`,
`handleRenditionShift`, heartbeat timer, `loadStream` (`playing`),
`mark911`, both `restart` paths, plus the canonical-signal callbacks.
- All Combine sinks receive on `DispatchQueue.main` for serialization
safety.

### Side fixes

- **Heartbeat restart on each playback period.** `startMetricsHeartbeat`
moved out of `init()` into `loadStream` so the first tick lands exactly
1 s after `playing`. No more pre-playback heartbeats during app idle.
- **Single `Date()` capture in `loadStream`** — `playbackStartAt` and
the `playing` event's `at:` stamp share one capture so
elapsed-since-start is exactly 0.
- **`markPlayingStarted(at:)` captures `firedAt` on the KVO thread**
before the `Task @MainActor` hands off, so the timestamp reflects the
true `timeControlStatus` transition instant (caught in pre-PR review).

### Observability additions (kept intentionally)

- `[METRICS event=… ts=… state=… pos=… from=… to=…]` — one print per
PATCH; greppable in `idevicesyslog` / Console.app for spotting future
bursts.
- `[FIRSTFRAME] attach: …` — prints which path won the AVPlayerLayer
discovery on each attach pass; useful for tracking iOS version
regressions.

## Guiding principle

Preserve every real state transition; only suppress true duplicates.
AVPlayer's startup flicker through paused → buffering → stalled →
buffering → playing now stamps distinct timestamps, distinct
`state_from`/`state_to`, distinct `player_state` snapshots. Each row
carries enough data to be unambiguous on the wire.

## Test plan

- [x] iOS / iPadOS simulator builds green
- [x] tvOS simulator builds green
- [x] iPad sim cold-start: one `video_first_frame` (synthesis fallback),
one `video_start_time`, three distinct `state_change` rows with walking
from/to pairs
- [x] iPad sim Reload: one `video_first_frame` (KVO won, fires before
`state == playing`), one `video_start_time`
- [x] Heartbeat starts 1 s after `playing`, no pre-playback heartbeats
- [x] Pre-PR Sonnet review run; correctness items addressed
- [ ] Apple TV physical device verification
- [ ] Soak run — confirm no regression on `rate_shift_*`, `frozen`,
`segment_stall`, `error` event flows

## Follow-ups (not in this PR)

- Investigate `player_metrics_event_time` vs
`player_metrics_last_event_at` redundancy (both fields carry the
identical timestamp literal today).
- Optional: wire `AVPlayerItem.isPlaybackLikelyToKeepUp` as a richer
startup-quality signal.
- Maybe rename `playing` → `playback_initiated` since it fires at
`loadStream` start, not when video shows.
- Consider gating heartbeat on active playback only (currently runs
whenever a `loadStream` has happened, even after stop).

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: jonathaneoliver

apple/InfiniteStreamPlayer/InfiniteStreamPlayer/PlaybackScreen.swift

@@ -22,7 +22,8 @@ struct PlaybackScreen: View {
                 onRetry: { vm.retry() },
                 onReload: { vm.reload() },
                 onMark911: { vm.mark911() },
-                onOpenSettings: { vm.setSettingsOpen(true) }
+                onOpenSettings: { vm.setSettingsOpen(true) },
+                onFirstFrame: { at in vm.markFirstFrameRendered(at: at) }
             )
             .id(vm.playerEpoch)
             .ignoresSafeArea()

apple/InfiniteStreamPlayer/InfiniteStreamPlayer/PlayerView.swift

@@ -17,6 +17,15 @@ struct PlayerView: UIViewControllerRepresentable {
     var onReload: (() -> Void)? = nil
     var onMark911: (() -> Void)? = nil
     var onOpenSettings: (() -> Void)? = nil
+    /// Fired exactly once per playback when the embedded `AVPlayerLayer`
+    /// reports `isReadyForDisplay = true`. The closure receives the
+    /// instant the flip was observed; the consumer (PlayerViewModel)
+    /// is responsible for idempotency (resetting on item replace).
+    var onFirstFrame: ((Date) -> Void)? = nil
+
+    func makeCoordinator() -> Coordinator {
+        Coordinator()
+    }
 
     func makeUIViewController(context: Context) -> AVPlayerViewController {
         let controller = AVPlayerViewController()
@@ -27,13 +36,21 @@ struct PlayerView: UIViewControllerRepresentable {
         #else
         controller.showsPlaybackControls = false
         #endif
+        context.coordinator.onFirstFrame = onFirstFrame
+        context.coordinator.attach(to: controller, player: player)
         return controller
     }
 
+    static func dismantleUIViewController(_ uiViewController: AVPlayerViewController, coordinator: Coordinator) {
+        coordinator.detach()
+    }
+
     func updateUIViewController(_ uiViewController: AVPlayerViewController, context: Context) {
         if uiViewController.player !== player {
             uiViewController.player = player
         }
+        context.coordinator.onFirstFrame = onFirstFrame
+        context.coordinator.attach(to: uiViewController, player: player)
         #if os(tvOS)
         // Rebuild every update so each UIAction closure captures the
         // freshest callback (the parent passes closures that reference
@@ -69,5 +86,112 @@ struct PlayerView: UIViewControllerRepresentable {
         uiViewController.transportBarCustomMenuItems = actions
         #endif
     }
+
+    /// Holds the AVPlayerLayer KVO state across SwiftUI re-renders.
+    /// AVPlayerViewController doesn't expose its embedded `AVPlayerLayer`
+    /// directly, so we walk `view.layer.sublayers` to find it. The walk
+    /// re-runs on player swap (Reload / Retry recreates AVPlayer) and on
+    /// item replace, so the observer always tracks the live layer.
+    final class Coordinator: NSObject {
+        var onFirstFrame: ((Date) -> Void)?
+
+        private weak var observedPlayer: AVPlayer?
+        private weak var observedLayer: AVPlayerLayer?
+        private var readyObservation: NSKeyValueObservation?
+        private var sublayerObservation: NSKeyValueObservation?
+        private var didReportForCurrentLayer: Bool = false
+
+        func attach(to controller: AVPlayerViewController, player: AVPlayer) {
+            // Player swap = brand-new AVPlayerLayer underneath.
+            // Tear down the old observer and start fresh.
+            if observedPlayer !== player {
+                detachLayer()
+                observedPlayer = player
+            }
+            // The AVPlayerLayer can be added to the controller's view
+            // hierarchy after `makeUIViewController` returns. If we
+            // can't find it yet, install a one-shot KVO on the parent
+            // layer's `sublayers` and retry when it appears.
+            // AVPlayerViewController on iOS doesn't reliably expose
+            // its embedded AVPlayerLayer as a sublayer of view.layer
+            // on initial mount — Apple uses a private rendering path.
+            // After Reload (when the controller's view tree has
+            // settled), the layer is sometimes findable. The fallback
+            // synthesis in PlayerViewModel's $currentTime sink covers
+            // cold-start where this KVO never fires. Debug prints
+            // tagged `[FIRSTFRAME]` show which path won for each
+            // mount — useful for spotting regressions / OS changes.
+            if let layer = findAVPlayerLayer(in: controller.view.layer) {
+                print("[FIRSTFRAME] attach: found AVPlayerLayer immediately depth=\(layerDepth(of: layer, in: controller.view.layer)) ready=\(layer.isReadyForDisplay)")
+                installReadyObserver(on: layer)
+            } else if sublayerObservation == nil {
+                let topSubs = controller.view.layer.sublayers?.count ?? 0
+                print("[FIRSTFRAME] attach: no AVPlayerLayer yet — topSubs=\(topSubs) — installing sublayer KVO")
+                let parent = controller.view.layer
+                sublayerObservation = parent.observe(\.sublayers, options: [.new]) { [weak self, weak controller] _, _ in
+                    guard let self, let controller else { return }
+                    if let layer = self.findAVPlayerLayer(in: controller.view.layer) {
+                        print("[FIRSTFRAME] sublayer KVO fired: AVPlayerLayer appeared, ready=\(layer.isReadyForDisplay)")
+                        self.installReadyObserver(on: layer)
+                        self.sublayerObservation?.invalidate()
+                        self.sublayerObservation = nil
+                    }
+                }
+            }
+        }
+
+        private func layerDepth(of target: CALayer, in root: CALayer, depth: Int = 0) -> Int {
+            if root === target { return depth }
+            for sub in root.sublayers ?? [] {
+                let d = layerDepth(of: target, in: sub, depth: depth + 1)
+                if d >= 0 { return d }
+            }
+            return -1
+        }
+
+        func detach() {
+            detachLayer()
+            observedPlayer = nil
+        }
+
+        private func detachLayer() {
+            readyObservation?.invalidate()
+            readyObservation = nil
+            sublayerObservation?.invalidate()
+            sublayerObservation = nil
+            observedLayer = nil
+            didReportForCurrentLayer = false
+        }
+
+        private func installReadyObserver(on layer: AVPlayerLayer) {
+            if observedLayer === layer { return }
+            readyObservation?.invalidate()
+            observedLayer = layer
+            didReportForCurrentLayer = false
+            // `.initial` lets us fire immediately if the layer is
+            // already ready (e.g. SwiftUI re-rendered after first frame
+            // already landed).
+            readyObservation = layer.observe(\.isReadyForDisplay, options: [.new, .initial]) { [weak self] observed, _ in
+                guard let self, observed.isReadyForDisplay, !self.didReportForCurrentLayer else { return }
+                self.didReportForCurrentLayer = true
+                let now = Date()
+                if Thread.isMainThread {
+                    self.onFirstFrame?(now)
+                } else {
+                    DispatchQueue.main.async { [weak self] in
+                        self?.onFirstFrame?(now)
+                    }
+                }
+            }
+        }
+
+        private func findAVPlayerLayer(in layer: CALayer) -> AVPlayerLayer? {
+            if let avLayer = layer as? AVPlayerLayer { return avLayer }
+            for sub in layer.sublayers ?? [] {
+                if let found = findAVPlayerLayer(in: sub) { return found }
+            }
+            return nil
+        }
+    }
 }