@npaw/forge-react-native 9.6.1

package/ios/ForgeApple/Sources/NPAWForgeAVPlayerAdapter/AVPlayerAdapter.swift

@@ -0,0 +1,877 @@
+/**
+ * Copyright (C) NPAW - All Rights Reserved
+ *
+ * This source code is protected under international copyright law. All rights
+ * reserved and protected by the copyright holders.
+ * This file is confidential and only available to authorized individuals with the
+ * permission of the copyright holders. If you encounter this file and do not have
+ * permission, please contact the copyright holders and delete this file.
+ *
+ *
+ * @author: Victor Soto <victor.soto@nicepeopleatwork.com>
+ * @description: AVPlayer adapter that converts player observations into typed Forge facts, anchoring start at play intent, join at real playhead advancement, and seek pairs at observed time jumps.
+ */
+
+import AVFoundation
+import Foundation
+#if canImport(NPAWForgeCore)
+import NPAWForgeCore
+#endif
+
+public final class AVPlayerAdapter: PlayerAdapter {
+    /// Serializes all mutable adapter state shared between AVFoundation KVO and
+    /// notification callbacks (arbitrary threads), the app thread (bind/unbind,
+    /// player replacement), the periodic playback tick, and the Rust ping worker
+    /// that synchronously pulls metadata snapshots through the content-metadata
+    /// provider callback.
+    private let stateLock = NSRecursiveLock()
+    /// Serializes KVO observation registration/invalidation, notification token
+    /// add/remove, and periodic time observer install/removal. Kept separate from
+    /// `stateLock` so event emission never holds it, and held across the actual
+    /// `observe()`/`invalidate()` calls because concurrent KVO (de)registration
+    /// on the same AVPlayer is not safe.
+    private let observerLock = NSRecursiveLock()
+    private var playerObservations: [NSKeyValueObservation] = []
+    private var itemObservations: [NSKeyValueObservation] = []
+    private var notificationTokens: [NSObjectProtocol] = []
+    /// Periodic playback tick used for join progression and seek detection. The
+    /// owner is remembered so removal targets the player the observer was
+    /// installed on even after `player` is replaced.
+    private var timeObserverToken: Any?
+    private var timeObserverOwner: AVPlayer?
+    private var started = false
+    private var joined = false
+    private var buffering = false
+    private var seeking = false
+    /// Whether the last observed transport intent was a user pause; the
+    /// paused → waitingToPlayAtSpecifiedRate resume spin-up must not open a
+    /// buffer window (OLD plugin-ios reports no rebuffer on resume).
+    private var paused = false
+    /// Playhead baseline captured at start intent; join fires only once the
+    /// playhead advances beyond it (OLD plugin-ios join semantics).
+    private var joinBaselinePlayheadMs: Int64?
+    /// Last playback-tick playhead sample used for seek jump detection.
+    private var lastTickPlayheadMs: Int64?
+    /// Last observed non-zero playback rate; paused ticks reuse it so rate
+    /// changes never register as seeks (OLD plugin-ios rule).
+    private var lastTickRate: Double = 1
+    /// Monotonic anchor of the in-flight seek (buffer begin when the seek
+    /// converted an active buffer), used for the explicit seek duration.
+    private var seekAnchorElapsedMs: Int64?
+    private var bufferBeginElapsedMs: Int64?
+    /// Incremented on every unregister so in-flight observer rebuilds racing an
+    /// unregister cannot resurrect stale observation entries.
+    private var observationGeneration = 0
+    /// Remote behavior hints snapshotted at view start (`registerListeners`),
+    /// never re-read mid-view. `appliedJoinMethod` is the resolved token
+    /// (`ph` or `rd`); `ff`/`auto`/unknown resolve to the playhead join.
+    private var appliedJoinMethod = AVPlayerAdapter.joinMethodPlayhead
+    private var appliedSeekHeuristicEnabled = true
+    private var appliedSeekJumpThresholdMs = AVPlayerAdapter.seekDetectionThresholdMs
+
+    /// Last known-good playback facts derived from the item's access log, all
+    /// guarded by `stateLock` and cleared per view in `resetPlaybackStateLocked`
+    /// so nothing leaks across items.
+    ///
+    /// Retention matters: AVFoundation reports every access-log metric as
+    /// negative or absent when unknown, and an event logged right after a seek
+    /// commonly reports nothing at all. Without retention those pings published
+    /// `bitrate=0` mid-view. Unknown must stay unknown (kernel default) or keep
+    /// the last real value — never collapse to zero.
+    private var lastKnownBitrate: Int64?
+    private var lastKnownThroughput: Double?
+    private var lastKnownFps: Double?
+    /// Retained as a running maximum: dropped frames and transferred bytes are
+    /// cumulative counters and must never decrease within a view.
+    private var lastKnownDroppedFrames: Int64?
+    private var lastKnownTotalBytes: Int64?
+    /// Elapsed-time stamp of the last access-log read. `snapshotMetadata` and
+    /// `snapshotQos` are invoked back-to-back with identical values by
+    /// `VideoAdapter.metadataSnapshot`, so this collapses them into one read.
+    private var lastFactsSampleElapsedMs: Int64?
+
+    /// Playback tick cadence for join progression and seek detection.
+    static let playbackTickIntervalSeconds: Double = 0.25
+    /// Minimum playhead advancement beyond the start baseline treated as real
+    /// playback progress (OLD plugin-ios epsilon).
+    static let joinAdvanceEpsilonMs: Int64 = 50
+    /// Playhead jump between consecutive ticks treated as a seek while playing
+    /// at 1x (OLD plugin-ios threshold; scaled by the observed playback rate).
+    static let seekDetectionThresholdMs: Int64 = 2_000
+    /// Seek jump threshold while buffering; higher so the playhead catch-up
+    /// after a stall never registers as a seek (OLD plugin-ios rule).
+    static let seekBufferingDetectionThresholdMs: Int64 = 10_000
+    /// Smallest reported seek duration (OLD plugin-ios clamps to 1 ms); also
+    /// keeps the kernel from deriving a -1 sentinel for zero-width pairs.
+    static let minimumSeekDurationMs: Int64 = 1
+    /// Canonical join-method token for the playhead-advance tick join.
+    static let joinMethodPlayhead = "ph"
+    /// Canonical join-method token for the ready-fallback join.
+    static let joinMethodReady = "rd"
+
+    public init(player: AVPlayer? = nil) {
+        super.init(player: player)
+        descriptor = AdapterDescriptor(
+            adapterId: "avplayer",
+            category: .player,
+            playerFamily: "AVPlayer",
+            version: "avfoundation"
+        )
+    }
+
+    public var player: AVPlayer? {
+        get { playerObject as? AVPlayer }
+        set { playerObject = newValue }
+    }
+
+    /// AVPlayer reports duration/liveness/rendition only after the HLS playlist
+    /// is parsed, so `/start` waits for those facts through the kernel
+    /// `waitForMetadata` gate by default. An explicit
+    /// `VideoOptions.waitForMetadata(false)` always wins.
+    public override var defaultWaitForMetadata: Bool { true }
+
+    public override func registerListeners() {
+        guard let player else { return }
+        observerLock.lock()
+        defer { observerLock.unlock() }
+        unregisterListeners()
+        // Remote behavior hints apply at view start only, never mid-view.
+        applyBehaviorHints(capturePlanBehaviorHints)
+        _ = fireInit(metadata: snapshotMetadata())
+        observePlayer(player)
+        observeItem(player.currentItem)
+        installTimeObserver(player)
+        handleTimeControlStatus(player.timeControlStatus)
+    }
+
+    public override func unregisterListeners() {
+        observerLock.lock()
+        defer { observerLock.unlock() }
+        removeTimeObserverLocked()
+        stateLock.lock()
+        observationGeneration += 1
+        let playerObservationsToInvalidate = playerObservations
+        let itemObservationsToInvalidate = itemObservations
+        let tokensToRemove = notificationTokens
+        playerObservations.removeAll()
+        itemObservations.removeAll()
+        notificationTokens.removeAll()
+        resetPlaybackStateLocked()
+        stateLock.unlock()
+        playerObservationsToInvalidate.forEach { $0.invalidate() }
+        itemObservationsToInvalidate.forEach { $0.invalidate() }
+        tokensToRemove.forEach(NotificationCenter.default.removeObserver)
+    }
+
+    public override func snapshotMetadata(
+        timemarkMs: Int64 = ForgeClock.nowMs(),
+        elapsedRealtimeMs: Int64 = ForgeClock.elapsedRealtimeMs()
+    ) -> PlayerMetadataSnapshot {
+        refreshPlaybackFactsFromPlayer(elapsedRealtimeMs: elapsedRealtimeMs)
+        var snapshot = PlayerMetadataSnapshot(
+            playerName: descriptor.playerFamily,
+            playerVersion: descriptor.version,
+            adapterVersion: descriptor.version,
+            resourceUrl: resourceUrl()?.absoluteString,
+            contentType: inferredContentType(),
+            playheadMs: currentPlayheadMs(),
+            durationMs: currentDurationMs(),
+            bitrate: currentBitrate(),
+            rendition: currentRendition(),
+            containerFormat: resourceUrl()?.pathExtension
+        )
+        if let error = player?.currentItem?.error ?? player?.error {
+            snapshot.errorCode = String((error as NSError).code)
+            snapshot.errorMessage = error.localizedDescription
+            snapshot.errorMetadata = (error as NSError).domain
+        }
+        return snapshot
+    }
+
+    /// QoS derived from the item's access log. `appleContentMetadata` hardcodes
+    /// throughput, totalBytes and droppedFrames to nil, so this override is the
+    /// only route by which those facts can reach the kernel on Apple — without
+    /// it the kernel emits its `-1`/`0` defaults.
+    ///
+    /// `throughput` carries `observedBitrate`, which is exactly the metric that
+    /// was previously mislabelled as `bitrate`. `latency` is deliberately
+    /// omitted: v7 gates it behind a configuration option that does not exist
+    /// on Apple `VideoOptions`, so adding it would mean new public API.
+    /// Returns nil when nothing is known so the kernel keeps its own defaults.
+    public override func snapshotQos(
+        timemarkMs: Int64 = ForgeClock.nowMs(),
+        elapsedRealtimeMs: Int64 = ForgeClock.elapsedRealtimeMs()
+    ) -> QosSnapshot? {
+        refreshPlaybackFactsFromPlayer(elapsedRealtimeMs: elapsedRealtimeMs)
+        let currentRate = player?.rate
+        stateLock.lock()
+        let throughput = lastKnownThroughput
+        let fps = lastKnownFps
+        let droppedFrames = lastKnownDroppedFrames
+        let totalBytes = lastKnownTotalBytes
+        let pausedNow = paused
+        stateLock.unlock()
+
+        var playrate: Double?
+        if pausedNow {
+            playrate = 0.0
+        } else if let currentRate, currentRate > 0 {
+            playrate = Double(currentRate)
+        }
+
+        if throughput == nil, fps == nil, droppedFrames == nil, totalBytes == nil, playrate == nil {
+            return nil
+        }
+        return QosSnapshot(
+            throughput: throughput,
+            fps: fps,
+            latency: nil,
+            playrate: playrate,
+            droppedFrames: droppedFrames,
+            totalBytes: totalBytes
+        )
+    }
+
+    private func observePlayer(_ player: AVPlayer) {
+        observerLock.lock()
+        defer { observerLock.unlock() }
+        let generation = currentObservationGeneration()
+        var observations: [NSKeyValueObservation] = []
+        observations.append(player.observe(\.timeControlStatus, options: [.new, .initial]) { [weak self] player, _ in
+            self?.handleTimeControlStatus(player.timeControlStatus)
+        })
+        observations.append(player.observe(\.rate, options: [.new]) { [weak self] player, _ in
+            self?.handleRate(player.rate)
+        })
+        observations.append(player.observe(\.currentItem, options: [.new]) { [weak self] player, _ in
+            self?.handleItemTransition(player)
+        })
+        stateLock.lock()
+        guard generation == observationGeneration else {
+            stateLock.unlock()
+            observations.forEach { $0.invalidate() }
+            return
+        }
+        playerObservations.append(contentsOf: observations)
+        stateLock.unlock()
+    }
+
+    private func observeItem(_ item: AVPlayerItem?) {
+        observerLock.lock()
+        defer { observerLock.unlock() }
+        stateLock.lock()
+        let generation = observationGeneration
+        let staleObservations = itemObservations
+        let staleTokens = notificationTokens
+        itemObservations.removeAll()
+        notificationTokens.removeAll()
+        stateLock.unlock()
+        staleObservations.forEach { $0.invalidate() }
+        staleTokens.forEach(NotificationCenter.default.removeObserver)
+        guard let item else { return }
+        var observations: [NSKeyValueObservation] = []
+        var tokens: [NSObjectProtocol] = []
+        observations.append(item.observe(\.status, options: [.new, .initial]) { [weak self] item, _ in
+            self?.handleItemStatus(item.status, error: item.error)
+        })
+        observations.append(item.observe(\.isPlaybackLikelyToKeepUp, options: [.new]) { [weak self] item, _ in
+            if item.isPlaybackLikelyToKeepUp {
+                self?.handlePlaybackLikelyToKeepUp()
+            }
+        })
+        tokens.append(NotificationCenter.default.addObserver(
+            forName: .AVPlayerItemDidPlayToEndTime,
+            object: item,
+            queue: nil
+        ) { [weak self] _ in
+            self?.handlePlaybackEnded()
+        })
+        tokens.append(NotificationCenter.default.addObserver(
+            forName: .AVPlayerItemFailedToPlayToEndTime,
+            object: item,
+            queue: nil
+        ) { [weak self] notification in
+            let error = notification.userInfo?[AVPlayerItemFailedToPlayToEndTimeErrorKey] as? NSError
+            self?.handlePlaybackFailed(error: error)
+        })
+        stateLock.lock()
+        guard generation == observationGeneration else {
+            stateLock.unlock()
+            observations.forEach { $0.invalidate() }
+            tokens.forEach(NotificationCenter.default.removeObserver)
+            return
+        }
+        itemObservations.append(contentsOf: observations)
+        notificationTokens.append(contentsOf: tokens)
+        stateLock.unlock()
+    }
+
+    private func installTimeObserver(_ player: AVPlayer) {
+        observerLock.lock()
+        defer { observerLock.unlock() }
+        removeTimeObserverLocked()
+        let generation = currentObservationGeneration()
+        let interval = CMTime(
+            seconds: Self.playbackTickIntervalSeconds,
+            preferredTimescale: CMTimeScale(NSEC_PER_SEC)
+        )
+        // Periodic observers also fire on time jumps and playback start/stop
+        // boundaries, so tick samples bracket pauses and seeks precisely.
+        let token = player.addPeriodicTimeObserver(forInterval: interval, queue: .main) { [weak self, weak player] _ in
+            guard let self, let player else { return }
+            self.processPlaybackTick(
+                playheadMs: self.currentPlayheadMs(),
+                sampleElapsedMs: ForgeClock.elapsedRealtimeMs(),
+                itemReady: player.currentItem?.status == .readyToPlay,
+                isPlaying: player.timeControlStatus == .playing,
+                rate: Double(player.rate)
+            )
+        }
+        stateLock.lock()
+        guard generation == observationGeneration else {
+            stateLock.unlock()
+            player.removeTimeObserver(token)
+            return
+        }
+        stateLock.unlock()
+        timeObserverToken = token
+        timeObserverOwner = player
+    }
+
+    private func removeTimeObserverLocked() {
+        if let token = timeObserverToken, let owner = timeObserverOwner {
+            owner.removeTimeObserver(token)
+        }
+        timeObserverToken = nil
+        timeObserverOwner = nil
+    }
+
+    /// Item finished playing. Forward the terminal stop fact, then reset playback
+    /// flags so a replay or the next queue item starts a fresh view.
+    func handlePlaybackEnded() {
+        _ = fireStop(metadata: snapshotMetadata())
+        resetPlaybackState()
+    }
+
+    /// Item failed mid-playback. Forward the fatal error fact, then reset playback
+    /// flags so a recovered or replaced item starts a fresh view.
+    func handlePlaybackFailed(error: NSError?) {
+        _ = fireFatalError(
+            errorCode: error.map { String($0.code) },
+            errorMessage: error?.localizedDescription,
+            errorMetadata: error?.domain
+        )
+        resetPlaybackState()
+    }
+
+    /// AVQueuePlayer auto-advance or replaceCurrentItem: stop the previous view if
+    /// it had started, reset playback flags, and conditionally restart for the new
+    /// item based on the current time control status.
+    func handleItemTransition(_ player: AVPlayer) {
+        stateLock.lock()
+        let wasStarted = started
+        stateLock.unlock()
+        if wasStarted {
+            _ = fireStop(metadata: snapshotMetadata())
+        }
+        resetPlaybackState()
+        observeItem(player.currentItem)
+        _ = fireMetadataUpdate(metadata: snapshotMetadata())
+        if player.currentItem != nil {
+            handleTimeControlStatus(player.timeControlStatus)
+        }
+    }
+
+    /// Snapshots the remote capture-plan behavior hints for this playback
+    /// attempt. `ff` (first frame) has no observable AVPlayer signal and is
+    /// treated as `auto`; `auto`/absent keep the playhead-advance join.
+    /// Internal for regression tests; production reads happen at
+    /// `registerListeners` (view start).
+    func applyBehaviorHints(_ behavior: ForgeCapturePlan.Behavior?) {
+        stateLock.lock()
+        appliedJoinMethod = Self.resolveJoinMethod(behavior?.joinMethod)
+        appliedSeekHeuristicEnabled = behavior?.seekHeuristicEnabled ?? true
+        appliedSeekJumpThresholdMs = max(
+            Self.minimumSeekDurationMs,
+            behavior?.seekJumpThresholdMs ?? Self.seekDetectionThresholdMs
+        )
+        stateLock.unlock()
+    }
+
+    /// Resolves the remote join-method token for AVPlayer: `rd` joins at item
+    /// readiness, while `ph`, `auto`, absent, and the AVPlayer-unsupported
+    /// `ff` keep the playhead-advance tick join.
+    static func resolveJoinMethod(_ hint: String?) -> String {
+        hint?.lowercased() == joinMethodReady ? joinMethodReady : joinMethodPlayhead
+    }
+
+    private func handleItemStatus(_ status: AVPlayerItem.Status, error: Error?) {
+        switch status {
+        case .readyToPlay:
+            // Duration/liveness/rendition become observable here; the metadata
+            // refresh releases a kernel-gated pending `/start`.
+            _ = fireMetadataUpdate(metadata: snapshotMetadata())
+            // The `rd` join method treats readiness itself as the join signal.
+            maybeJoinOnReady()
+        case .failed:
+            let nsError = error as NSError?
+            _ = fireFatalError(
+                errorCode: nsError.map { String($0.code) },
+                errorMessage: error?.localizedDescription,
+                errorMetadata: nsError?.domain
+            )
+            resetPlaybackState()
+        case .unknown:
+            break
+        @unknown default:
+            break
+        }
+    }
+
+    private func handleRate(_ rate: Float) {
+        if rate > 0 {
+            // Direct rate manipulation is also a play intent (OLD plugin-ios
+            // fires start from rate observations).
+            ensureStarted()
+            return
+        }
+        stateLock.lock()
+        let isStarted = started
+        stateLock.unlock()
+        guard isStarted else { return }
+        if player?.timeControlStatus == .paused {
+            stateLock.lock()
+            paused = true
+            stateLock.unlock()
+            _ = firePause(metadata: snapshotMetadata())
+        }
+    }
+
+    func handleTimeControlStatus(_ status: AVPlayer.TimeControlStatus) {
+        switch status {
+        case .paused:
+            stateLock.lock()
+            let shouldFirePause = started
+            if shouldFirePause {
+                paused = true
+            }
+            stateLock.unlock()
+            if shouldFirePause {
+                _ = firePause(metadata: snapshotMetadata())
+            }
+        case .waitingToPlayAtSpecifiedRate:
+            // Waiting-to-play is the earliest observable play intent on a cold
+            // start; anchoring `/start` here keeps the kernel-computed join
+            // time spanning the real startup buffering (OLD plugin-ios join
+            // semantics).
+            ensureStarted()
+            stateLock.lock()
+            let resumingFromPause = paused
+            stateLock.unlock()
+            // A paused → waiting spin-up is the user resuming, not a stall:
+            // OLD plugin-ios reports no rebuffer on pause → resume.
+            if !resumingFromPause {
+                beginBuffering()
+            }
+        case .playing:
+            ensureStarted()
+            stateLock.lock()
+            let wasJoined = joined
+            paused = false
+            stateLock.unlock()
+            // Playback resumed: an in-flight seek ends before buffer/pause
+            // bookkeeping (OLD plugin-ios ordering: seekEnd, then resume).
+            finishSeek()
+            finishBuffering()
+            if wasJoined {
+                _ = fireResume(metadata: snapshotMetadata())
+            }
+        @unknown default:
+            break
+        }
+    }
+
+    /// Fires `/start` exactly once per playback attempt at the earliest play
+    /// intent and anchors the join baseline at the intent playhead. When the
+    /// playhead is not observable yet (cold start before the item loads), the
+    /// first ready playback tick seeds the baseline instead, so the initial
+    /// HLS positioning jump never counts as playback progress. Join itself
+    /// waits for real playhead advancement observed by the playback tick.
+    func ensureStarted() {
+        stateLock.lock()
+        let needsStart = !started
+        if needsStart {
+            started = true
+            joinBaselinePlayheadMs = currentPlayheadMs()
+        }
+        stateLock.unlock()
+        if needsStart {
+            _ = fireStart(metadata: snapshotMetadata())
+        }
+    }
+
+    /// Handles one playback tick sample: join progression first, then seek jump
+    /// detection. Internal for regression tests; production ticks come from the
+    /// periodic time observer, which also fires on time jumps and playback
+    /// start/stop boundaries.
+    func processPlaybackTick(
+        playheadMs: Int64?,
+        sampleElapsedMs: Int64,
+        itemReady: Bool,
+        isPlaying: Bool,
+        rate: Double
+    ) {
+        maybeJoinOnPlayheadAdvance(playheadMs: playheadMs, itemReady: itemReady)
+        detectSeekFromTick(
+            playheadMs: playheadMs,
+            sampleElapsedMs: sampleElapsedMs,
+            isPlaying: isPlaying,
+            rate: rate
+        )
+    }
+
+    /// Join fires only when the item is ready and the playhead advanced beyond
+    /// the start baseline, so the kernel-computed join time measures real
+    /// startup instead of the readyToPlay/rate-change intent (OLD plugin-ios
+    /// join semantics). Backward playhead moves re-anchor the baseline because
+    /// AVPlayer can transiently expose the previous item's playhead right
+    /// after replaceCurrentItem.
+    private func maybeJoinOnPlayheadAdvance(playheadMs: Int64?, itemReady: Bool) {
+        stateLock.lock()
+        guard started, !joined, itemReady else {
+            stateLock.unlock()
+            return
+        }
+        if appliedJoinMethod == Self.joinMethodReady {
+            // Ready-fallback join: readiness observed by this tick is the
+            // join signal; no playhead advancement is required.
+            joined = true
+            if let playheadMs {
+                lastTickPlayheadMs = playheadMs
+            }
+            stateLock.unlock()
+            _ = fireJoin(metadata: snapshotMetadata())
+            return
+        }
+        guard let playheadMs else {
+            stateLock.unlock()
+            return
+        }
+        guard let baseline = joinBaselinePlayheadMs else {
+            joinBaselinePlayheadMs = playheadMs
+            stateLock.unlock()
+            return
+        }
+        if playheadMs + Self.joinAdvanceEpsilonMs < baseline {
+            joinBaselinePlayheadMs = playheadMs
+            stateLock.unlock()
+            return
+        }
+        guard playheadMs > baseline + Self.joinAdvanceEpsilonMs else {
+            stateLock.unlock()
+            return
+        }
+        joined = true
+        // Seed the seek sampler from the join playhead so the first joined tick
+        // never compares against a stale pre-join sample.
+        lastTickPlayheadMs = playheadMs
+        stateLock.unlock()
+        _ = fireJoin(metadata: snapshotMetadata())
+    }
+
+    /// Ready-fallback (`rd`) join from the item-status observation: readiness
+    /// itself is the join signal once `/start` fired. The playhead-tick path
+    /// keeps a mirrored branch so ready-before-start orderings still join on
+    /// the next ready tick.
+    private func maybeJoinOnReady() {
+        stateLock.lock()
+        guard appliedJoinMethod == Self.joinMethodReady, started, !joined else {
+            stateLock.unlock()
+            return
+        }
+        joined = true
+        if let playheadMs = currentPlayheadMs() {
+            lastTickPlayheadMs = playheadMs
+        }
+        stateLock.unlock()
+        _ = fireJoin(metadata: snapshotMetadata())
+    }
+
+    /// Seek detection between consecutive playback ticks (OLD plugin-ios
+    /// heuristics): detection is suppressed until content join, ticks spanning a
+    /// playback-rate change are ignored, the jump threshold scales with the
+    /// observed rate and rises while buffering, and an already-active seek is
+    /// never re-opened. A seek ends when a later tick observes active playback.
+    /// The remote behavior hints can disable the heuristic or replace the base
+    /// jump threshold for the current view.
+    private func detectSeekFromTick(
+        playheadMs: Int64?,
+        sampleElapsedMs: Int64,
+        isPlaying: Bool,
+        rate: Double
+    ) {
+        var justBeganSeek = false
+        var shouldEndSeek = false
+        stateLock.lock()
+        guard joined, appliedSeekHeuristicEnabled, let playheadMs else {
+            stateLock.unlock()
+            return
+        }
+        let baseThresholdMs = appliedSeekJumpThresholdMs
+        let currentRate = rate != 0 ? rate : lastTickRate
+        if let previousPlayheadMs = lastTickPlayheadMs {
+            if currentRate == lastTickRate {
+                let rateScaledThresholdMs = Int64((Double(baseThresholdMs) * abs(lastTickRate)).rounded())
+                let thresholdMs = buffering
+                    ? max(Self.seekBufferingDetectionThresholdMs, baseThresholdMs)
+                    : max(baseThresholdMs, rateScaledThresholdMs)
+                if abs(playheadMs - previousPlayheadMs) >= thresholdMs, !seeking {
+                    seeking = true
+                    justBeganSeek = true
+                    // An active buffer folds into the seek (the kernel converts
+                    // the pair); anchor the duration at the buffer begin so the
+                    // reported span matches OLD attribution.
+                    seekAnchorElapsedMs = buffering ? (bufferBeginElapsedMs ?? sampleElapsedMs) : sampleElapsedMs
+                    if buffering {
+                        buffering = false
+                        bufferBeginElapsedMs = nil
+                    }
+                }
+            }
+            if seeking, !justBeganSeek, isPlaying, rate > 0 {
+                shouldEndSeek = true
+            }
+        }
+        lastTickPlayheadMs = playheadMs
+        if currentRate != 0 {
+            lastTickRate = currentRate
+        }
+        stateLock.unlock()
+        if justBeganSeek {
+            _ = fireSeekBegin(metadata: snapshotMetadata())
+        }
+        if shouldEndSeek {
+            finishSeek(sampleElapsedMs: sampleElapsedMs)
+        }
+    }
+
+    /// Closes an in-flight seek with an explicit, always-positive duration.
+    /// OLD plugin-ios clamps seek durations to at least 1 ms; the explicit
+    /// value also keeps the kernel from deriving a -1 sentinel when the pair
+    /// would otherwise resolve at-or-before its begin mark.
+    func finishSeek(sampleElapsedMs: Int64 = ForgeClock.elapsedRealtimeMs()) {
+        stateLock.lock()
+        guard seeking else {
+            stateLock.unlock()
+            return
+        }
+        seeking = false
+        let anchorElapsedMs = seekAnchorElapsedMs
+        seekAnchorElapsedMs = nil
+        stateLock.unlock()
+        var snapshot = snapshotMetadata()
+        let spanMs = anchorElapsedMs.map { sampleElapsedMs - $0 } ?? 0
+        snapshot.extraParams["seekDurationMs"] = String(max(Self.minimumSeekDurationMs, spanMs))
+        _ = fireSeekEnd(metadata: snapshot)
+    }
+
+    /// Enough media is buffered to resume. While a seek is active and playback
+    /// has not resumed on its own (paused seek), this is the seek completion
+    /// signal; otherwise it closes a plain rebuffer.
+    func handlePlaybackLikelyToKeepUp() {
+        stateLock.lock()
+        let seekWasActive = seeking
+        stateLock.unlock()
+        if seekWasActive {
+            finishSeek()
+        } else {
+            finishBuffering()
+        }
+    }
+
+    private func beginBuffering() {
+        stateLock.lock()
+        // Rebuffering while a seek is active folds into the seek duration
+        // (OLD plugin-ios attribution); the kernel drops the pair anyway.
+        guard !seeking else {
+            stateLock.unlock()
+            return
+        }
+        let shouldFire = !buffering
+        buffering = true
+        if shouldFire {
+            bufferBeginElapsedMs = ForgeClock.elapsedRealtimeMs()
+        }
+        stateLock.unlock()
+        if shouldFire {
+            _ = fireBufferBegin(metadata: snapshotMetadata())
+        }
+    }
+
+    private func finishBuffering() {
+        stateLock.lock()
+        let shouldFire = buffering
+        buffering = false
+        bufferBeginElapsedMs = nil
+        stateLock.unlock()
+        if shouldFire {
+            _ = fireBufferEnd(metadata: snapshotMetadata())
+        }
+    }
+
+    private func resetPlaybackState() {
+        stateLock.lock()
+        resetPlaybackStateLocked()
+        stateLock.unlock()
+    }
+
+    private func resetPlaybackStateLocked() {
+        started = false
+        joined = false
+        buffering = false
+        seeking = false
+        paused = false
+        joinBaselinePlayheadMs = nil
+        lastTickPlayheadMs = nil
+        lastTickRate = 1
+        seekAnchorElapsedMs = nil
+        bufferBeginElapsedMs = nil
+        lastKnownBitrate = nil
+        lastKnownThroughput = nil
+        lastKnownFps = nil
+        lastKnownDroppedFrames = nil
+        lastKnownTotalBytes = nil
+        lastFactsSampleElapsedMs = nil
+    }
+
+    private func currentObservationGeneration() -> Int {
+        stateLock.lock()
+        defer { stateLock.unlock() }
+        return observationGeneration
+    }
+
+    private func resourceUrl() -> URL? {
+        (player?.currentItem?.asset as? AVURLAsset)?.url
+    }
+
+    /// Classifies live/VOD from the observable AVPlayerItem facts. Internal for
+    /// regression tests: an indefinite duration means live only once the item is
+    /// ready, because HLS duration stays indefinite until the playlist is parsed
+    /// and claiming live before readyToPlay mislabels VOD on `/init`.
+    static func classifyContentType(
+        durationIsNumeric: Bool,
+        durationIsIndefinite: Bool,
+        itemReady: Bool
+    ) -> ContentType {
+        if durationIsNumeric { return .vod }
+        guard itemReady else { return .unknown }
+        return durationIsIndefinite ? .live : .unknown
+    }
+
+    private func inferredContentType() -> ContentType {
+        guard let item = player?.currentItem else { return .unknown }
+        let duration = item.duration
+        return Self.classifyContentType(
+            durationIsNumeric: duration.isNumeric,
+            durationIsIndefinite: duration.isIndefinite,
+            itemReady: item.status == .readyToPlay
+        )
+    }
+
+    private func currentPlayheadMs() -> Int64? {
+        let seconds = player?.currentTime().seconds
+        guard let seconds, seconds.isFinite else { return nil }
+        return Int64(seconds * 1000.0)
+    }
+
+    private func currentDurationMs() -> Int64? {
+        guard let duration = player?.currentItem?.duration, duration.isNumeric else { return nil }
+        let seconds = duration.seconds
+        guard seconds.isFinite else { return nil }
+        return Int64(seconds * 1000.0)
+    }
+
+    /// The media bitrate resolved from the access log, or the last known-good
+    /// value when the newest event reports nothing.
+    ///
+    /// Never sourced from `observedBitrate`: that field is the empirical
+    /// network throughput, and publishing it here reported tens of Mbps for
+    /// low-bitrate content and swung several-fold run-to-run on byte-identical
+    /// media. Throughput is reported separately via `snapshotQos`.
+    private func currentBitrate() -> Int64? {
+        stateLock.lock()
+        defer { stateLock.unlock() }
+        return lastKnownBitrate
+    }
+
+    /// Reads the item's access log once and folds it into the cached facts.
+    /// Separated from the pure rules so the adapter wiring stays thin.
+    private func refreshPlaybackFactsFromPlayer(elapsedRealtimeMs: Int64) {
+        let events = player?.currentItem?.accessLog()?.events
+        let samples = events?.map(AVPlayerAccessLogSample.init)
+        refreshPlaybackFacts(
+            samples: samples,
+            frameRate: currentVideoFrameRate(),
+            sampleElapsedMs: elapsedRealtimeMs
+        )
+    }
+
+    /// Applies the resolution rules and the retention policy. Internal so the
+    /// regression tests can drive it without a live `AVPlayer`.
+    ///
+    /// Deduplicated on `sampleElapsedMs` because `VideoAdapter.metadataSnapshot`
+    /// calls `snapshotMetadata` and `snapshotQos` back-to-back with identical
+    /// values; without this the access log would be read twice per ping.
+    func refreshPlaybackFacts(
+        samples: [AVPlayerAccessLogSample]?,
+        frameRate: Double?,
+        sampleElapsedMs: Int64
+    ) {
+        stateLock.lock()
+        defer { stateLock.unlock() }
+        if let previous = lastFactsSampleElapsedMs, previous == sampleElapsedMs { return }
+        lastFactsSampleElapsedMs = sampleElapsedMs
+
+        if let frameRate, frameRate.isFinite, frameRate > 0 {
+            lastKnownFps = frameRate
+        }
+
+        guard let samples, let newest = samples.last else { return }
+
+        if let bitrate = AVPlayerAccessLogFacts.mediaBitrate(from: newest) {
+            lastKnownBitrate = bitrate
+        }
+        if let throughput = AVPlayerAccessLogFacts.observedThroughput(from: newest) {
+            lastKnownThroughput = throughput
+        }
+        if let dropped = AVPlayerAccessLogFacts.droppedFrames(in: samples) {
+            lastKnownDroppedFrames = max(dropped, lastKnownDroppedFrames ?? 0)
+        }
+        if let bytes = AVPlayerAccessLogFacts.totalBytes(in: samples) {
+            lastKnownTotalBytes = max(bytes, lastKnownTotalBytes ?? 0)
+        }
+    }
+
+    /// First track reporting a positive video frame rate.
+    ///
+    /// `currentVideoFrameRate` is synchronous and not deprecated, unlike the
+    /// `assetTrack`/`nominalFrameRate` pair that iOS 16 moved to async loading.
+    /// The media type is not inspected on purpose: only video tracks ever
+    /// report a positive video frame rate, so the `> 0` filter already selects
+    /// them without touching the async-loading `AVAssetTrack` surface.
+    private func currentVideoFrameRate() -> Double? {
+        guard let tracks = player?.currentItem?.tracks else { return nil }
+        for track in tracks {
+            let rate = Double(track.currentVideoFrameRate)
+            if rate.isFinite, rate > 0 { return rate }
+        }
+        return nil
+    }
+
+    private func currentRendition() -> String? {
+        guard let size = player?.currentItem?.presentationSize, size.width > 0, size.height > 0 else {
+            return nil
+        }
+        return "\(Int(size.width))x\(Int(size.height))"
+    }
+}