react-native-queue-player 1.0.0

package/ios/TrackPlayer.swift

@@ -0,0 +1,4766 @@
+import AVFoundation
+import NitroModules
+import UIKit
+
+/// iOS TrackPlayer — Nitro HybridObject holding the AVQueuePlayer
+/// instance + runtime config. Lifecycle (configure / destroy),
+/// transport, queue mutation, skip, gapless, events, audio session,
+/// and lookahead-cache methods all live here.
+class TrackPlayer: HybridTrackPlayerSpec {
+  // MARK: - Stored state
+
+  /// Periodic-time-observer firing rate for the progress event. Two
+  /// ticks per second matches the JS-side onProgress contract and
+  /// keeps backgrounded playback updates flowing without burning
+  /// power on a faster cadence.
+  private static let progressIntervalSeconds: Double = 0.5
+
+  /// Tolerance for "the loaded range has reached duration" — rounding can leave
+  /// a sub-second gap when a track is fully downloaded.
+  private static let fullyBufferedEpsilonSeconds: Double = 1.0
+
+  /// Sleep-timer tick cadence. 0.5s keeps the 10s linear fade smooth while
+  /// staying cheap enough to run whether playback is playing or paused.
+  private static let sleepTimerTickInterval: TimeInterval = 0.5
+
+  /// The underlying AVQueuePlayer. `nil` before configure(), torn down
+  /// on destroy(). AVQueuePlayer specifically (not AVPlayer) because
+  /// it owns queue management + gapless transitions — see
+  /// NOTES.md §5 + plan §3.2.
+  internal var player: AVQueuePlayer?
+  /// Strategy-pattern engine wrapping the active player. Owns
+  /// the underlying `AVQueuePlayer`. JS-facing transport (play,
+  /// pause, stop) and config (setVolume, setPlaybackSpeed) route
+  /// through this surface. Paths intentionally still on
+  /// `self.player?` in this file: queue mutation (`setQueue` +
+  /// `addToQueue` + `removeFromQueue` + `moveInQueue` +
+  /// `clearQueue` + `shuffleQueue` queue-rebuild via
+  /// `AVQueueBuilder` + `replaceCurrentItem` / `removeAllItems`),
+  /// skip (`skipToIndex` / `skipToNext` / `skipToPrevious` use
+  /// `fullRebuildPlayerQueue` because AVQueuePlayer is forward-
+  /// only and engine `seek(toIndex:)` requires the caller to
+  /// rebuild backward), single-item seek (`seekTo(position:)`),
+  /// error-recovery `pause()`, observer wiring (`installGaplessObservers`,
+  /// `installEventObservers`), audio session activation, NowPlaying /
+  /// RemoteCommands integration, and read paths (`currentTime`,
+  /// `timeControlStatus`, etc. — engine doesn't expose readable
+  /// scalars for these). Crossfade engine fill-in lifts the
+  /// queue/skip surface onto the engine.
+  internal var engine: PlaybackEngine?
+
+  /// Authoritative queue state — two parallel arrays (`tracks` +
+  /// `queueItemIds`) owned by `QueueState` so the type system
+  /// prevents either field from being mutated without the other.
+  /// AVQueuePlayer consumes items forward-only; skip-backward
+  /// rebuilds from `queueState.tracks`. `queueItemIds` is the
+  /// lib-generated identity per position, stamped onto each
+  /// AVPlayerItem so `matchTrackIndex` can resolve currentItem back
+  /// to an index. Queue-position identity is never derived from
+  /// `TrackItem` fields — only `track.url` is required + reliable
+  /// on consumer-supplied data.
+  internal var queueState = QueueState()
+
+  /// Read-only view of the queue's TrackItem array. Mutations go
+  /// through `queueState`'s API.
+  internal var tracks: [TrackItem] { queueState.tracks }
+
+  /// Read-only view of the parallel queue-item IDs. Mutations go
+  /// through `queueState`'s API.
+  internal var queueItemIds: [String] { queueState.queueItemIds }
+
+  /// Belt-and-braces: verify the parallel-array invariant before
+  /// any function that consumes both arrays. `QueueState` enforces
+  /// this at every mutation site, but a direct read of either array
+  /// outside `queueState`'s API can drift if a future contributor
+  /// bypasses the type. Catches the desync earlier than the
+  /// construction-time `precondition` in `AVQueueBuilder`.
+  /// Debug-only — the precondition vanishes in Release builds where
+  /// `AVQueueBuilder` already fails soft (returns `[]` + NSLog) on
+  /// the same desync.
+  private func assertQueueIdsInvariant(_ caller: StaticString) {
+    #if DEBUG
+    precondition(
+      self.tracks.count == self.queueItemIds.count,
+      "QueueState parallel-array invariant violated at \(caller): tracks=\(self.tracks.count), queueItemIds=\(self.queueItemIds.count)"
+    )
+    #endif
+  }
+
+  /// Index into `tracks` of the currently-playing item. -1 when empty
+  /// or before the first play. Surfaced to JS via getCurrentTrackIndex.
+  internal var currentTrackIndex: Int = -1
+
+  /// Most recent PlayerConfig passed in via configure(). Defaults are
+  /// empty — no custom headers, default UA. Used by AVQueueBuilder
+  /// when creating new AVURLAssets.
+  internal var config: PlayerConfig =
+    PlayerConfig(
+      httpHeaders: nil,
+      userAgent: nil,
+      autoRetries: nil,
+      retryBackoffMs: nil,
+      networkTimeoutMs: nil,
+      audioContentType: nil,
+      audioCategoryOptions: nil,
+      visualizationEnabled: nil,
+      clampSeekToBuffered: nil,
+      lookaheadCacheMaxSizeMb: nil, lookaheadCacheEvictionPolicy: nil,
+      progressUpdateIntervalMs: nil, backgroundProgressUpdateIntervalMs: nil
+    )
+
+  internal var repeatModeState: RepeatMode = .off
+
+  /// Canonical volume + playback speed, independent of the active
+  /// engine. Setters update these and forward to the engine; getters
+  /// read these (not `self.player`, which is nil under crossfade); the
+  /// engine swap re-applies them so a gapless↔crossfade swap preserves
+  /// the user's settings.
+  internal var volumeState: Float = 1.0
+  internal var playbackSpeedState: Float = 1.0
+
+  /// Lock-screen / control-center remote-control config. Applied to
+  /// `RemoteCommands` on set + re-applied on `configure`. Interval seek is
+  /// performed natively from the `onCommand` handler.
+  private var remoteSkipMode: RemoteSkipMode = .track
+  private var remoteForwardInterval: Double = 15
+  private var remoteBackwardInterval: Double = 15
+
+  /// Canonical pitch-correction mode, independent of the active engine.
+  /// Re-applied to the engine at configure + engine swap so it survives
+  /// a destroy→configure cycle and a gapless↔crossfade swap. Default
+  /// `voice` (pitch preserved, cheapest correct option).
+  internal var pitchCorrectionModeState: PitchCorrectionMode = .voice
+
+  /// AVAudioSession wrapper — handles activate/deactivate,
+  /// interruption (phone calls, Siri), and route change (headphones
+  /// unplugged) notifications. Wired in configure, torn down on
+  /// destroy. Interruption handlers pause + emit state change with
+  /// reason `.interruption`; resume on `.endedShouldResume`.
+  /// Route-change pauses on `.oldDeviceUnavailable` per Apple HIG.
+  private let audioSession = AudioSession()
+
+  /// Owns the `MPNowPlayingInfoCenter` dictionary that drives the
+  /// lock-screen / control-center / CarPlay surfaces. Wired in
+  /// `configure` (snapshot provider + 10s periodic timer), torn down
+  /// in `destroy`.
+  private let nowPlayingInfo = NowPlayingInfo()
+
+  /// Owns the `MPRemoteCommandCenter` handler registrations that
+  /// receive lock-screen / control-center / CarPlay / hardware
+  /// transport events. Wired in `configure`, uninstalled in `destroy`.
+  /// Each handler stamps `pendingStateChangeReason = .system` before
+  /// routing into the public transport methods so the resulting state-
+  /// change emit carries `.system`, distinguishing remote-command
+  /// origin from in-app `.user` taps.
+  private let remoteCommands = RemoteCommands()
+
+  /// Resolves `track.artworkUrl` to a UIImage for the lock-screen
+  /// surface. The placeholder is the synchronous floor (already
+  /// surfaced by `nowPlayingInfo.refreshAll`); `applyArtwork` swaps
+  /// in the resolved bitmap when the network fetch lands. Single
+  /// in-flight request — cancelled on track-change.
+  private let artworkResolver = ArtworkResolver()
+
+  /// Lookahead cache + prefetcher. Built in `configure`, torn down in
+  /// `destroy` (prefetcher first so its in-flight task can observe
+  /// cancellation cleanly before the cache's URLSession is
+  /// invalidated). Default 100 MB budget + 3-track lookahead window;
+  /// `setLookaheadCache` lets consumers override at runtime.
+  internal var lookaheadCache: LookaheadCache?
+  internal var lookaheadCachePrefetcher: LookaheadCachePrefetcher?
+
+  /// Live lookahead cache config — initialised from defaults on
+  /// first configure, mutated by `setLookaheadCache`.
+  /// Persists across destroy → configure so a consumer who set
+  /// custom values once doesn't lose them on a reconfigure cycle.
+  internal var lookaheadConfig: LookaheadCacheConfig = LookaheadCacheConfig(
+    enabled: true,
+    lookaheadCount: Double(LookaheadCachePrefetcher.DEFAULT_LOOKAHEAD_COUNT)
+  )
+
+  /// Cache-status callback registered via `onCacheStatusChange`.
+  /// Single-slot — the JS consumer owns the subscription via the
+  /// returned unsubscribe closure.
+  internal let cacheStatusListeners = ListenerRegistry<(CacheStatus) -> Void>()
+  internal let nowPlayingFormatListeners =
+    ListenerRegistry<(Variant_NullType_NowPlayingFormat?) -> Void>()
+
+  /// Cached snapshot of the active item's audio format. Returned
+  /// synchronously by `getNowPlayingFormat()`. `nil` between queue-end
+  /// (or pre-first-track) and the first successful resolve.
+  internal var lastEmittedFormat: NowPlayingFormat?
+
+  /// Identity key for `lastEmittedFormat`'s source AVPlayerItem. The
+  /// async resolver discards results whose source item is no longer
+  /// current and whose generation token has been superseded.
+  internal var lastEmittedFormatItemId: ObjectIdentifier?
+
+  /// Monotonic generation token bumped on every refresh request. Any
+  /// in-flight extractor Task whose captured token mismatches the
+  /// current value drops its result — guards against the cache-hit race
+  /// where `\.status == .readyToPlay` fires synchronously from the
+  /// status-observer bootstrap before `handleCurrentItemDidChange`
+  /// runs, producing two parallel resolves for the same item.
+  internal var nowPlayingFormatRequestGen: UInt64 = 0
+
+  /// True while a `reresolveNowPlayingFormatForBitrate` Task is mid-flight.
+  /// Access-log notifications fire multiple times per second during
+  /// streaming; without this gate every fire that lands while an extract
+  /// is still running would spawn another detached Task. Read+written on
+  /// the main actor only — set before the Task launches, cleared via
+  /// `defer` inside the MainActor.run completion (covers success, early-
+  /// return, and any future error path uniformly).
+  internal var bitrateReresolveInFlight: Bool = false
+
+  // MARK: - Events — callback storage + observer state
+  //
+  // Callbacks are stored on the main thread (registration funnels
+  // through `onMainSync`), read from the main thread (every observer
+  // body dispatches to main before reading), and invoked on the main
+  // thread. Nitro's callback plumbing handles cross-thread delivery
+  // into JS — our job is just to call them with the right values.
+  //
+  // State + track change flow out of KVO. Progress flows out of
+  // `addPeriodicTimeObserver` at 2 Hz (NOTES.md §5: "~1 Hz normal,
+  // faster when the consumer is actively scrubbing"). Error flows out
+  // of `AVPlayerItemFailedToPlayToEndTime`. Queue-end fires when
+  // AVQueuePlayer auto-advances past the last item (currentItem
+  // becomes nil while tracks is non-empty).
+  // Multi-listener registries — each `onXxx(callback)` registers an
+  // entry, returns a dispose closure that removes by id. Lets
+  // multiple consumers (Player UI, harness, test runner) subscribe
+  // simultaneously without clobbering each other.
+  private let stateChangeListeners = ListenerRegistry<(PlayerState, StateChangeReason) -> Void>()
+  private let trackChangeListeners = ListenerRegistry<(TrackItem?, Double, TrackChangeReason, Double?) -> Void>()
+  private let progressListeners = ListenerRegistry<(PlayerProgress) -> Void>()
+  private let milestoneListeners = ListenerRegistry<(Double, Double) -> Void>()
+  /// Per-playthrough 25/50/75/90% milestone state. Main-thread-confined
+  /// (mutated only from the progress tick, `seekTo`, and the track-change
+  /// delegates — all on main), so no extra synchronisation is needed.
+  private var milestoneTracker = MilestoneTracker()
+  /// Throttles `onProgress` JS emission to the configured foreground /
+  /// background cadence. Main-thread-confined (mutated only from the progress
+  /// tick + cast push + the app-lifecycle notifications, all on main).
+  private var progressEmissionGate = ProgressEmissionGate()
+  /// NotificationCenter tokens for the `didEnterBackground` /
+  /// `willEnterForeground` observers that drive `progressEmissionGate`'s
+  /// background state. Registered per instance in `configure()` and removed in
+  /// `internalDestroy()` — NOT tied to the AVQueuePlayer event observers, whose
+  /// install/teardown runs on every engine swap.
+  private var appLifecycleObservers: [NSObjectProtocol] = []
+  private let errorListeners = ListenerRegistry<(PlaybackError) -> Void>()
+  private let queueEndListeners = ListenerRegistry<() -> Void>()
+  // SkipCapability struct — wraps (canSkipPrevious, canSkipNext).
+  // Struct rather than separate bool args lets future capability
+  // flags be added without a breaking change AND dodges a Nitrogen
+  // 0.35.4 (bool, bool) callback codegen bug.
+  private let skipCapabilityListeners = ListenerRegistry<(SkipCapability) -> Void>()
+
+  /// Last-emitted skip capability tuple. Native owns the truth; the
+  /// JS layer is a passive observer. Recomputed via
+  /// `recomputeCapabilities()` at every `tracks` / `currentTrackIndex`
+  /// / `repeatModeState` write site, with dedup —
+  /// the listener fires only when the tuple actually changes. Single
+  /// reference write means JS callers reading both fields via
+  /// `getSkipCapability()` see a consistent pair without a torn-read
+  /// risk; the legacy `getCanSkipNext` / `getCanSkipPrevious` getters
+  /// delegate to this same struct.
+  private var cachedSkipCapability: SkipCapability =
+    SkipCapability(canSkipPrevious: false, canSkipNext: false)
+
+  // Buffer state — discrete empty/buffering/stalled/full for the active track, derived
+  // from the item's native playback-buffer flags. Recomputed on the gapless
+  // item's buffer KVO (sub-tick latency) and on the progress tick (covers the
+  // crossfade engine + safety net); emitted only on an actual change.
+  private let bufferStateListeners = ListenerRegistry<(BufferState) -> Void>()
+  private var currentBufferState: BufferState = .empty
+  private var lastEmittedBufferState: BufferState?
+  private var bufferEmptyObserver: NSKeyValueObservation?
+  private var bufferKeepUpObserver: NSKeyValueObservation?
+  private var bufferFullObserver: NSKeyValueObservation?
+  /// Fully-buffered — the whole track has downloaded. Distinct from
+  /// `BufferState.full` ("keeps up"). Recomputed on the buffer-full KVO + the
+  /// progress tick + track change; emitted on change. Reset per track.
+  private let fullyBufferedListeners = ListenerRegistry<(Bool) -> Void>()
+  private var currentFullyBuffered = false
+  private var lastEmittedFullyBuffered: Bool?
+  /// True once the current track has actually reached a playing state — the
+  /// discriminator between an initial `buffering` load and a mid-playback
+  /// `stalled` rebuffer. Reset on track change / stop / teardown.
+  private var hasStartedPlaying = false
+  /// Lib-level playback intent (play() → true, pause()/stop() → false). A
+  /// not-full buffer only reads as `stalled` while playback is both started and
+  /// intended; a paused load reads as `buffering`.
+  private var wantsToPlay = false
+
+  /// Sleep-timer state machine (wall-clock countdown, 10s fade, 60s tail rule).
+  /// Player/timer-free — this class drives it from `sleepTimerTimer` and applies
+  /// the returned fade/pause decision to the engine.
+  private var sleepTimerCore = SleepTimerCore()
+  private let sleepTimerListeners = ListenerRegistry<(SleepTimerState) -> Void>()
+  /// Repeating 0.5s wall-clock timer that ticks `sleepTimerCore`. Runs whether
+  /// playback is playing or paused (a wall-clock deadline must keep counting
+  /// while paused, so this can't piggyback on the progress observer).
+  private var sleepTimerTimer: Timer?
+  /// True while a fade is in progress — the engine volume is being driven below
+  /// `volumeState`. Cleared when the fade restores full volume or the timer
+  /// tears down, so `volumeState` (and `getVolume`) stay truthful.
+  private var sleepTimerFading = false
+
+  /// Token from `AVPlayer.addPeriodicTimeObserver`, paired with the
+  /// specific `AVQueuePlayer` instance that issued it. `removeTime
+  /// Observer` has to be called on the issuing player — keeping the
+  /// reference here guards against a tear-down call arriving after
+  /// `self.player` has been replaced by a later `configure`.
+  private var progressTimeObserver: (player: AVQueuePlayer, token: Any)?
+
+  /// Engine-agnostic progress fallback — used when `self.player`
+  /// is nil (CrossfadeEngine active). Polls
+  /// `engine.currentPositionSeconds` at the same 0.5s cadence the
+  /// `AVPlayer.addPeriodicTimeObserver` would. Started on engine
+  /// swap to a non-AVQueuePlayer backend; stopped on swap back to
+  /// gapless or on destroy.
+  private var progressFallbackTimer: Timer?
+  /// Last position published by the CrossfadeEngine fallback-timer progress
+  /// path. Lets a paused tick emit once when the playhead moves (seek / stop)
+  /// without re-publishing identical tuples during a steady pause.
+  private var lastEmittedCrossfadePosition: TimeInterval = -1
+
+  /// KVO on `player.timeControlStatus`. Fires whenever AVPlayer
+  /// transitions between `.paused`, `.waitingToPlayAtSpecifiedRate`,
+  /// and `.playing` — translated into our PlayerState enum.
+  private var timeControlStatusObserver: NSKeyValueObservation?
+
+  /// Dedup key for `errorListeners` fires. Keyed on
+  /// `(queueItemId, standardized code)` so AVPlayer-internal item
+  /// rebuilds during retries do not bypass dedup. A DIFFERENT error
+  /// on the same item still surfaces because the code is part of the
+  /// key. Cleared on track change, setQueue, clearQueue, destroy,
+  /// and on retry-initiation so the retry-then-fail can fire a
+  /// fresh error.
+  private var lastErrorQueueItemId: String?
+  private var lastErrorCode: PlaybackErrorCode?
+
+  /// Auto-retry counter per queue position, keyed on `queueItemId`
+  /// (the lib-generated UUID, never a consumer field). Decremented on each
+  /// transient-error fire; when 0, the error surfaces to JS.
+  /// Re-populated on setQueue / addToQueueBody from
+  /// `effectiveAutoRetries()` (clamped 0..5; default 3). Reset to 1
+  /// (single shot) by `play()` if state is `.error` and the counter
+  /// is 0 — stuck-recovery on user-initiated re-tap.
+  private var retryAttemptsRemaining: [String: Int] = [:]
+
+  /// Last PlayerState emitted — used to suppress duplicate emissions.
+  /// KVO fires for any status transition, but our PlayerState enum
+  /// collapses several AVPlayer states so re-emission is possible.
+  private var lastReportedState: PlayerState = .none
+
+  /// End-of-queue latch. iOS has no native "ended" player state, so this is set
+  /// when the queue drains with repeat off (`detectQueueEnd` / `enginePlaybackEnded`)
+  /// and drives the terminal `.ended` in `PlayerStateDerivation` for BOTH
+  /// engines. Cleared when playback resumes (`emitState(.playing)`), a new track
+  /// loads (`dispatchTrackChange`), on seek, and on destroy. Main-thread-confined.
+  private var reachedQueueEnd = false
+
+  /// User-facing reason carrier for the `onTrackChange(_, _, reason)`
+  /// emission. When a skip method (or `setQueue` /
+  /// `applyNewCurrentIndex`) stashes a value here, the subsequent
+  /// `\.currentItem` KVO fire reads it and emits with the right
+  /// hint (`.userSkipNext`, `.userSkipPrevious`, `.userSkipToIndex`,
+  /// `.queueReplaced`, etc). Consumed on a non-nil transition; the
+  /// `isMutatingPlayerQueue + currentItem == nil` early-return in
+  /// `handleCurrentItemDidChange` skips the intermediate `nil` fire
+  /// inside a rebuild so the reason isn't stolen by the wrong fire.
+  /// Defaults to `.autoAdvance` when nil at consumption time.
+  ///
+  /// Reason-carrier only — the `matchTrackIndex` resync gate lives
+  /// on `didPlayToEndPending` so chain-advance bounces never re-run
+  /// the resync.
+  private var pendingTrackChangeReason: TrackChangeReason?
+
+  /// Counterpart to `pendingTrackChangeReason` for state transitions.
+  /// `play` / `pause` / `stop` / `seekTo` stash `.user` before calling
+  /// the native method; the `timeControlStatus` KVO picks it up to
+  /// attribute the resulting state change. Default is `.system` when
+  /// nothing has stashed a reason (covers buffering, auto-advance
+  /// end-of-queue; AudioSession-driven interruptions and route
+  /// changes carry their own reasons).
+  private var pendingStateChangeReason: StateChangeReason?
+
+  /// Bridges receiver-driven cast session state into the lib's
+  /// existing event surface. Lazily constructed and held for the
+  /// `TrackPlayer`'s lifetime; `start()` on configure, `stop()` on
+  /// destroy.
+  private lazy var castEventBridge = CastEventBridge(owner: self)
+
+  /// Rises whenever a mutation is actively rearranging the player's
+  /// internal queue (setQueue, addToQueue, removeFromQueue,
+  /// moveInQueue, clearQueue, applyNewCurrentIndex,
+  /// fullRebuildPlayerQueue). Every `removeAllItems` + `insert` pair
+  /// produces an intermediate `currentItem == nil` KVO fire — the
+  /// event dispatch path checks this flag and skips the intermediate
+  /// fire so `onQueueEnd` isn't falsely emitted mid-rebuild and
+  /// `pendingTrackChangeReason` isn't consumed by the wrong fire.
+  /// Nested (mutations calling each other) safe because each nest
+  /// uses `performingMutation` which restores the prior value on exit.
+  private var isMutatingPlayerQueue: Bool = false
+
+  // MARK: - Gapless — observer state
+  //
+  // AVQueuePlayer does inter-track transitions for free when three
+  // conditions hold: (1) `actionAtItemEnd == .advance` (AVQueuePlayer's
+  // default; set explicitly in configure for resilience), (2) the
+  // next AVPlayerItem is preloaded in player.items() before the
+  // current ends (AVQueueBuilder + our surgical inserts keep that
+  // invariant), and (3) `automaticallyWaitsToMinimizeStalling == false`
+  // so the player doesn't pause at the boundary waiting for minimum
+  // buffer on the new item.
+  //
+  // The flip-pattern: start with stalling=true so the *first* track
+  // buffers properly
+  // before playback begins; once the first item reaches readyToPlay,
+  // flip stalling=false so every subsequent inter-track transition
+  // is tight. We re-arm on setQueue/clear because a fresh queue's
+  // first track needs the same initial-buffer leniency.
+  private var currentItemObserver: NSKeyValueObservation?
+  private var currentItemStatusObserver: NSKeyValueObservation?
+  private var gaplessFlipArmed: Bool = true
+
+  /// Set to true by the `AVPlayerItemDidPlayToEndTime` notification
+  /// handler when an item finishes playback naturally. Consumed by
+  /// `handleCurrentItemDidChange` as the SOLE signal for "this is a
+  /// real auto-advance" — gates the `matchTrackIndex` resync so
+  /// AVQueuePlayer chain-advance through unbuffered items (which
+  /// does NOT produce a DidPlayToEndTime notification) cannot
+  /// overwrite the user's authoritative `currentTrackIndex`.
+  private var didPlayToEndPending: Bool = false
+
+  /// Last `queueItemId` for which `trackChangeListeners` were fired.
+  /// Compared against the current item's `queueItemId` in
+  /// `handleCurrentItemDidChange` to dedup redundant emissions
+  /// across the chain-advance bounce + observer-reinstall classes.
+  /// Reset to nil on `destroy` (the next configure starts fresh).
+  ///
+  /// Why queueItemId not currentTrackIndex: setQueue replaces the
+  /// queue but may keep `currentTrackIndex == 0`; comparing index
+  /// alone would suppress the legitimate trackChange for the new
+  /// queue's first item. queueItemId differs across queue
+  /// replacements (UUID-per-item-at-construction), so the gate
+  /// fires emissions correctly for setQueue + skip + auto-advance
+  /// while still suppressing redundant fires.
+  private var lastEmittedQueueItemId: String? = nil
+
+  /// Cached classification of the active track's playback source.
+  /// Recomputed in `dispatchTrackChange` whenever the active track
+  /// changes (queue replace, skip, auto-advance, shuffle). Read by
+  /// `getCurrentTrackSource()` for sync JS access.
+  private var currentTrackSource: TrackSource? = nil
+
+  // Records mach-time at item-ended so the next auto-advance dispatch
+  // can compute a silence-gap delta, surfaced as `onTrackChange`'s
+  // `transitionGapMs`. Always-on (one UInt64 store on a low-frequency
+  // event). Verbose `[RNQP-GAPLESS]` diagnostic NSLogs against these
+  // timestamps are gated separately under `#if DEBUG`.
+  private var gaplessGapPrevEndedAtNs: UInt64 = 0
+
+  /// Latest `TrackItem` emitted by `dispatchTrackChange`. Snapshot
+  /// readable by SiriKit intent handlers that need a "current track"
+  /// seed without routing through JS. Updated on every natural track
+  /// change; nil when no queue is loaded. Read via
+  /// `TrackPlayer.cachedCurrentTrack`.
+  static var cachedCurrentTrack: TrackItem? = nil
+  // Captured at the top of `handleCurrentItemDidChange` so the
+  // `transitionGapMs` measurement reflects pure iOS scheduling latency
+  // between `AVPlayerItemDidPlayToEndTime` and the `\.currentItem` KVO fire,
+  // not the synchronous lib-side work `dispatchTrackChange` does
+  // before reaching the emit site (matchTrackIndex iteration,
+  // trackChangeListeners fan-out, refreshNowPlayingFormatForActiveItem,
+  // nowPlayingInfo.refreshAll, artworkResolver.resolve prelude). That
+  // intra-method work is sometimes 10s of ms on a cold first
+  // transition; measuring through it would conflate "scheduler
+  // latency" with "lib processing time" — the test contract is the
+  // former.
+  private var gaplessGapMeasuredAtNs: UInt64 = 0
+  #if DEBUG
+  // Debug-only timestamps backing the verbose `[RNQP-GAPLESS]` NSLog
+  // emits. Compiled out entirely in Release builds.
+  private var gaplessLogLastEndedAtNs: UInt64 = 0
+  private var gaplessLogLastChangedAtNs: UInt64 = 0
+  #endif
+
+  // MARK: - Lifecycle
+
+  func configure(config: PlayerConfig) throws -> Promise<Void> {
+    return Promise<Void>.async {
+      await self.onMain {
+        // Universal auto-destroy contract: every `configure()` call
+        // tears down any prior engine, audio session, observers, and
+        // pending pipeline state before reinitialising. On the first
+        // configure of a session this is a no-op (the gate inside
+        // `internalDestroy` short-circuits when `self.player == nil`).
+        // On subsequent calls it is a real teardown. Effect: configure
+        // is always a clean-slate operation; consumers don't need to
+        // remember to call `destroy()` before re-configuring.
+        // Capture the prior eviction policy before overwriting config — a change
+        // clears the rebuilt cache below so it starts fresh under the new policy
+        // (infrequent; a cache's eviction ordering is construction-fixed).
+        let previousEvictionPolicy = self.config.lookaheadCacheEvictionPolicy ?? .lru
+        self.internalDestroy()
+        self.config = config
+        let evictionPolicyChanged =
+          previousEvictionPolicy != (config.lookaheadCacheEvictionPolicy ?? .lru)
+        // Seed the progress-emission throttle from config and start observing
+        // app background/foreground. `internalDestroy()` above removed any
+        // prior observers, so this re-registers cleanly on every configure.
+        self.applyProgressEmissionIntervals()
+        self.installAppLifecycleObservers()
+        // Pin-at-configure visualization-disabled flag. Mirrored to
+        // the AudioTapProvider singleton so `Visualizer.subscribe`
+        // and the Visualizer Consumer's `wantsTap` predicate can
+        // read it live. Default `true` preserves existing behaviour.
+        AudioTapProvider.shared.setVisualizationEnabled(
+          config.visualizationEnabled ?? true
+        )
+        let engine = GaplessEngine()
+        self.engine = engine
+        // configure() always rebuilds the default GaplessEngine, so the mode
+        // state must reset to match. Otherwise getPlaybackMode() keeps
+        // reporting a stale crossfade selection after a clean-slate
+        // reconfigure while the engine is actually gapless — and a subsequent
+        // setPlaybackMode(.crossfade) would no-op against that stale state and
+        // never rebuild the CrossfadeEngine.
+        self.playbackModeState = PlaybackModeStateMachine.initial
+        let player = engine.player
+        self.player = player
+        self.gaplessFlipArmed = true
+        self.installGaplessObservers(on: player)
+        self.installEventObservers(on: player)
+        // Re-apply persisted config to the fresh engine. These survive a
+        // destroy→configure cycle and may be set before the first
+        // configure, so the first engine must pick them up — matching the
+        // engine-swap path. Speed is seeded (not set) so it doesn't start
+        // the paused player via AVPlayer.rate; play() applies it on the
+        // first resume.
+        engine.setRepeatMode(self.repeatModeState)
+        engine.setVolume(self.volumeState)
+        engine.seedPlaybackSpeed(self.playbackSpeedState)
+        engine.setPitchCorrectionMode(self.pitchCorrectionModeState)
+        self.wireAudioSession()
+        // Start observing receiver-driven cast session state; idempotent
+        // on re-configure (no-op if already started).
+        self.castEventBridge.start()
+        // Activate the lockscreen mirror for cast sessions. Subscribes
+        // through `PlaybackStateRouter.shared` — fires on every
+        // session-active transition.
+        CastNowPlayingController.shared.start()
+        // Wire the shared audio-tap provider onto the engine. The
+        // provider attaches an MTAudioProcessingTap-backed
+        // AVAudioMix to each queued AVPlayerItem when any
+        // registered consumer (EQ, visualizer) wants the tap.
+        AudioTapProvider.shared.wireToPlaybackEngine(engine)
+        // Notify subscribers when a tap-side RG extract lands so any
+        // `onNowPlayingFormatChange` listener picks up the new RG
+        // values immediately. `getNowPlayingFormat()` reads RG live
+        // from `AudioTapProvider`, so the synchronous read path
+        // doesn't depend on this callback — it's purely for change-
+        // notification subscribers.
+        AudioTapProvider.shared.onItemReplayGainDataPopulated = { [weak self] item in
+          guard let self else { return }
+          self.emitCurrentNowPlayingFormat(for: item)
+        }
+        self.audioSession.activate(
+          mode: AudioCategoryMapping.mode(for: config.audioContentType),
+          options: AudioCategoryMapping.options(
+            for: config.audioCategoryOptions,
+            contentType: config.audioContentType
+          )
+        )
+        self.audioSession.installObservers()
+        self.wireNowPlayingInfo()
+        self.nowPlayingInfo.startPeriodicTimer()
+        self.wireRemoteCommands()
+        self.remoteCommands.install()
+        self.remoteCommands.setSkipCapability(
+          canSkipNext: self.cachedSkipCapability.canSkipNext,
+          canSkipPrevious: self.cachedSkipCapability.canSkipPrevious
+        )
+        // Refresh on every configure() so a header / UA update lands
+        // on the next artwork resolve. Live config — read fresh on
+        // each track-change resolve.
+        self.artworkResolver.configHeaders = config.httpHeaders
+        self.artworkResolver.configUserAgent = config.userAgent
+        // Same live config for the cast lockscreen's own artwork
+        // resolver so authenticated covers resolve during cast.
+        CastNowPlayingController.shared.configureArtwork(
+          headers: config.httpHeaders, userAgent: config.userAgent
+        )
+        // Build the lookahead cache + prefetcher honouring the live
+        // `lookaheadConfig`. When disabled, neither is built.
+        // `internalDestroy` above already nilled out any prior cache
+        // + prefetcher, so this is always a fresh construction.
+        if self.lookaheadConfig.enabled {
+          let cache = LookaheadCache(
+            maxSizeBytes: LookaheadCache.maxBytes(
+              forMb: self.configuredCacheMaxSizeMb()
+            ),
+            evictionPolicy: self.configuredEvictionPolicy()
+          )
+          // A policy change wipes the retained files so the cache refills
+          // under the new eviction order.
+          if evictionPolicyChanged {
+            cache.clear()
+          }
+          self.lookaheadCache = cache
+          let prefetcher = LookaheadCachePrefetcher(
+            cache: cache,
+            configHeaders: config.httpHeaders,
+            configUserAgent: config.userAgent
+          )
+          prefetcher.defaultLookaheadCount =
+            max(0, Int(self.lookaheadConfig.lookaheadCount))
+          prefetcher.onTrackProcessed = { [weak self] in self?.emitCacheStatus() }
+          self.lookaheadCachePrefetcher = prefetcher
+        } else if evictionPolicyChanged {
+          // Cache disabled at configure — no instance to clear(); purge the
+          // on-disk files directly so a policy change still starts fresh
+          // (parity with Android's unconditional clear).
+          LookaheadCache.purgeDefaultDirectory()
+        }
+      }
+    }
+  }
+
+  /// Install AudioSession interruption + route-change callbacks on
+  /// top of the transport. Centralised here so both callback types
+  /// share the same emit-state-then-call-native-method pattern.
+  private func wireAudioSession() {
+    self.audioSession.onInterruption = { [weak self] kind in
+      guard let self else { return }
+      let player = self.player
+      switch kind {
+      case .began:
+        // System wants us paused (phone call, Siri, alarm). Pause
+        // + stash `.interruption` for the resulting `timeControl
+        // Status` KVO to pick up on the terminal `.paused` emit.
+        self.pendingStateChangeReason = .interruption
+        player?.pause()
+      case .endedShouldResume:
+        // System says it's safe to resume. Resume through the engine so
+        // the user's playback speed is restored (a raw AVPlayer.play()
+        // resets rate to 1.0) and crossfade — whose legs the OS paused on
+        // `.began` but which has no `self.player` to act on — resumes too.
+        // play() transitions via `.buffering` → `.playing`; buffering
+        // passes through as `.system` so the reason sticks until
+        // `.playing` lands.
+        self.pendingStateChangeReason = .interruption
+        self.engine?.play()
+      case .endedShouldNotResume:
+        // Interruption ended but user resolved it in a way that
+        // shouldn't restart music. The player is already paused
+        // (OS pre-paused on `.began`, we stayed paused), so no
+        // transport call and no state transition to report.
+        // Apple's docs confirm clients should not resume — no
+        // client action needed; a dedicated `onInterruptionEnd`
+        // event could land later if consumers need to clear UI
+        // annotations.
+        break
+      }
+
+      // Surface the interruption kind as a typed non-fatal
+      // `PlaybackError` so JS consumers can branch on the resume
+      // hint without inspecting a boolean. Wire literals + messages
+      // come from `InterruptionEventMapping` (single source of
+      // truth for the three nativeDomain strings).
+      let domain = InterruptionEventMapping.nativeDomain(for: kind)
+      let message = InterruptionEventMapping.message(for: kind)
+      let err = PlaybackError(
+        code: .unknown,
+        message: message,
+        fatal: false,
+        nativeCode: 0,
+        nativeDomain: domain,
+        nativeMessage: message,
+        queueItemId: "",
+        url: ""
+      )
+      self.errorListeners.forEach { $0(err) }
+    }
+
+    self.audioSession.onRouteChange = { [weak self] kind in
+      guard let self else { return }
+      switch kind {
+      case .oldDeviceUnavailable:
+        // Headphones unplugged, BT disconnected — never blast
+        // music over the speaker per Apple HIG.
+        guard let player = self.player else { return }
+        self.pendingStateChangeReason = .routeChange
+        player.pause()
+      case .newDeviceAvailable:
+        // New route arrived (BT connected, headphones plugged in).
+        // No automatic transport action; state is unchanged, so
+        // no emission either. Consumers wanting to observe new
+        // devices can subscribe to AVAudioSession notifications
+        // directly if needed.
+        break
+      }
+    }
+
+    // Audio-session lifecycle failures (`setCategory` /
+    // `setActive(true)` / `setActive(false)`) surface as non-fatal
+    // PlaybackErrors with stable codes (see `AudioSession.onError`
+    // doc). Deliberately do NOT call `emitState(.error, ...)` —
+    // these are session-level failures, not player-level; the
+    // player itself isn't in an error state and may still recover
+    // (e.g. another app released the session).
+    self.audioSession.onError = { [weak self] sessionError in
+      guard let self else { return }
+      // Audio-session errors don't have a meaningful AVPlayer-level
+      // standardized code (they're session-scope, not playback-
+      // scope). Surface as `.unknown` with the SCREAMING_SNAKE_CASE
+      // session code in `nativeDomain` so consumers can branch on
+      // `nativeDomain.startsWith("AUDIO_SESSION_")` if they need
+      // session-specific UX.
+      // Apply the same `stripQuery` PII safeguard as the rest of
+      // the error fire sites — audio-session messages today don't
+      // carry URLs, but defense in depth.
+      let safeMessage = PlaybackErrorMapping.stripQuery(sessionError.message)
+      // Audio-session errors are session-scope; no specific queue
+      // item to correlate, so queueItemId + url are empty.
+      let err = PlaybackError(
+        code: .unknown,
+        message: safeMessage,
+        fatal: false,
+        nativeCode: Double(sessionError.nativeCode),
+        nativeDomain: sessionError.nativeDomain,
+        nativeMessage: safeMessage,
+        queueItemId: "",
+        url: ""
+      )
+      self.errorListeners.forEach { $0(err) }
+    }
+  }
+
+  /// Map `MPRemoteCommandCenter` events to the public transport
+  /// methods. The closure stamps `pendingStateChangeReason = .system`
+  /// before invoking the transport call so the conditional
+  /// `pendingStateChangeReason ?? .user` write inside each transport
+  /// method short-circuits and the resulting state-change emit
+  /// carries `.system`.
+  ///
+  /// Race window: between the synchronous `.system` stamp and the
+  /// transport's Task-bodied `await self.onMain { ... }` hop, an
+  /// unrelated main-queue block (e.g. an `.interruption` stamp from
+  /// `wireAudioSession`) can overwrite the slot. The practical impact
+  /// is bounded — the default reason in `emitStateChangeIfChanged` is
+  /// `.system`, so a stolen `.system` re-falls-through to `.system` on
+  /// the next consumer. An `.interruption` interleave tags the
+  /// state-change as `.interruption` (semantically correct — the
+  /// interruption IS why the state changed); the subsequent play()
+  /// emit defaults to `.user`. Acceptable degradation.
+  ///
+  /// Togglers: `.togglePlayPause` flips off ANY actively-progressing
+  /// state, not just `.playing` — `.buffering` (waiting-to-play)
+  /// counts as "user is trying to play" and should pause on tap.
+  ///
+  /// `[weak self]` prevents the cycle TrackPlayer → remoteCommands →
+  /// onCommand → TrackPlayer (TrackPlayer owns RemoteCommands as a
+  /// `let` property).
+  private func wireRemoteCommands() {
+    self.remoteCommands.onCommand = { [weak self] command in
+      guard let self = self else { return }
+      self.pendingStateChangeReason = .system
+      switch command {
+      case .play:
+        _ = try? self.play()
+      case .pause:
+        _ = try? self.pause()
+      case .togglePlayPause:
+        let active =
+          self.lastReportedState == .playing ||
+          self.lastReportedState == .buffering
+        if active {
+          _ = try? self.pause()
+        } else {
+          _ = try? self.play()
+        }
+      case .stop:
+        _ = try? self.stop()
+      case .nextTrack:
+        _ = try? self.skipToNext()
+      case .previousTrack:
+        _ = try? self.skipToPrevious()
+      case .skipForward(let seconds):
+        // Chromecast: relative-seek the receiver from ITS position. AirPlay /
+        // local: `routeSeekBy` returns false (no GCK session), so seek the
+        // local engine — whose position is accurate (AVPlayer plays to the
+        // AirPlay route). `seekTo` clamps to [0, duration].
+        if !CastTransportRouter.routeSeekBy(deltaMs: Int64(seconds * 1000)) {
+          let base = self.engine?.currentPositionSeconds ?? 0
+          _ = try? self.seekTo(position: (base.isFinite ? base : 0) + seconds)
+        }
+      case .skipBackward(let seconds):
+        if !CastTransportRouter.routeSeekBy(deltaMs: -Int64(seconds * 1000)) {
+          let base = self.engine?.currentPositionSeconds ?? 0
+          _ = try? self.seekTo(position: (base.isFinite ? base : 0) - seconds)
+        }
+      case .changePlaybackPosition(let seconds):
+        _ = try? self.seekTo(position: seconds)
+      }
+    }
+  }
+
+  /// Set the `NowPlayingInfo` snapshot provider. Reads `currentTrackIndex`,
+  /// the AVPlayer's current item position + duration, and the player rate
+  /// in the same main-thread tick — all four values come from the same
+  /// observable state so the lock-screen scrubber doesn't see torn reads.
+  /// Returning `nil` track + zero values when the player is gone is
+  /// observed as "queue empty" by `NowPlayingInfo.refreshAll`, which then
+  /// clears the dictionary.
+  private func wireNowPlayingInfo() {
+    self.nowPlayingInfo.snapshotProvider = { [weak self] in
+      guard let self else {
+        return NowPlayingInfo.Snapshot(
+          track: nil, elapsedSeconds: 0, durationSeconds: 0, rate: 0)
+      }
+      let idx = self.currentTrackIndex
+      let track: TrackItem? = (idx >= 0 && idx < self.tracks.count)
+        ? self.tracks[idx] : nil
+      let item = self.player?.currentItem
+      let elapsed = item.map { CMTimeGetSeconds($0.currentTime()) } ?? 0
+      let duration = item.map { CMTimeGetSeconds($0.duration) } ?? 0
+      let rate = self.player?.rate ?? 0
+      return NowPlayingInfo.Snapshot(
+        track: track,
+        elapsedSeconds: elapsed,
+        durationSeconds: duration,
+        rate: rate
+      )
+    }
+  }
+
+  func destroy() throws -> Promise<Void> {
+    return Promise<Void>.async {
+      await self.onMain {
+        self.internalDestroy()
+      }
+    }
+  }
+
+  /// Synchronous teardown. Idempotent — no-op when nothing is
+  /// configured. Called from public `destroy()` and from `configure()`
+  /// (which auto-destroys before reinitialising; see `configure(_:)`
+  /// for the universal contract).
+  ///
+  /// Persists `config` / `repeatModeState` / `lookaheadConfig` across
+  /// the teardown so a consumer who called `setRepeatMode()` /
+  /// `setLookaheadCache()` doesn't lose those settings on a
+  /// reconfigure cycle. Matches Android's symmetric behaviour.
+  private func internalDestroy() {
+    // Idempotent gate: when nothing has been configured, every line
+    // below would either no-op (nil-coalesced calls) or perform
+    // unnecessary work against fresh state. The `player == nil`
+    // sentinel is the canonical "is configured?" check.
+    //
+    // Note on partial-init safety: `self.player = engine.player` is
+    // assigned in `configure(_:)` BEFORE `audioSession.activate`,
+    // `installObservers`, `wireNowPlayingInfo`, `remoteCommands.install`.
+    // If any of those subsequent steps ever fails (none can today —
+    // they're synchronous and non-throwing), `self.player` is already
+    // set, so this gate admits cleanup of every partially-installed
+    // resource. The audioSession + observers tear-down lines below
+    // are individually idempotent.
+    guard self.player != nil else { return }
+    // Tear the prefetcher down BEFORE the cache. Cancelling the
+    // prefetcher's Task chain arms cooperative cancellation so no
+    // new download dispatches against the about-to-die URLSession;
+    // the cache's `tearDown` then invalidates the session, which
+    // is what actually kills any already-suspended
+    // URLSessionDownloadTask mid-flight.
+    self.lookaheadCachePrefetcher?.tearDown()
+    self.lookaheadCachePrefetcher = nil
+    self.lookaheadCache?.tearDown()
+    self.lookaheadCache = nil
+
+    self.tearDownGaplessObservers()
+    self.tearDownEventObservers()
+    self.removeAppLifecycleObservers()
+    self.audioSession.tearDownObservers()
+    self.audioSession.onInterruption = nil
+    self.audioSession.onRouteChange = nil
+    self.audioSession.onError = nil
+    self.nowPlayingInfo.clear()
+    self.nowPlayingInfo.snapshotProvider = nil
+    self.remoteCommands.uninstall()
+    self.remoteCommands.onCommand = nil
+    self.artworkResolver.reset()
+    // CarPlay coordinator state lives for process lifetime. The
+    // bridge slots survive destroy — the subscription is owned by
+    // the JS consumer (re-registering replaces the slot), matching
+    // the documented Android behaviour. Browse data, in-flight
+    // resolver promises, and the artwork cache reset with the
+    // configure cycle.
+    let coordinator = CarPlayCoordinator.shared
+    coordinator.dataProvider.setSnapshot(nil)
+    coordinator.pending.clear()
+    coordinator.loader.clearCache()
+    // engine.release() drains the underlying AVQueuePlayer's items +
+    // nils its mix provider.
+    self.engine?.release()
+    self.engine = nil
+    self.player = nil
+    self.stopProgressFallbackTimer()
+    self.stopSleepTimerTick()
+    self.sleepTimerCore.clear()
+    self.sleepTimerFading = false
+    self.queueState.clear()
+    self.currentTrackIndex = -1
+    self.currentTrackSource = nil
+    self.currentBufferState = .empty
+    self.lastEmittedBufferState = nil
+    self.currentFullyBuffered = false
+    self.lastEmittedFullyBuffered = nil
+    self.hasStartedPlaying = false
+    self.wantsToPlay = false
+    self.lastEmittedQueueItemId = nil
+    self.didPlayToEndPending = false
+    // `player == nil` now; refresh emits null + cancels in-flight
+    // extractor Tasks via the generation token.
+    self.refreshNowPlayingFormatForActiveItem()
+    // `lastErrorQueueItemId` / `lastErrorCode` reset alongside the
+    // player so a subsequent error on a different item still fires
+    // (the dedup is per-item).
+    self.lastErrorQueueItemId = nil
+    self.lastErrorCode = nil
+    self.retryAttemptsRemaining.removeAll()
+    self.lastReportedState = .none
+    self.reachedQueueEnd = false
+    self.pendingTrackChangeReason = nil
+    self.pendingStateChangeReason = nil
+    self.audioSession.deactivate()
+    // Tear down the cast event bridge — disposers unsubscribe from
+    // both the global router and any active session's state listener.
+    self.castEventBridge.stop()
+    // Tear down the cast lockscreen mirror.
+    CastNowPlayingController.shared.stop()
+    // Final (false, false) emit so any still-registered subscriber
+    // sees the player is gone. JS hooks dispose their listener on
+    // unmount; this covers stragglers + native-side subscribers.
+    self.recomputeCapabilities()
+  }
+
+  /// Attach the KVO chain that powers the stalling-flip gapless
+  /// pattern: observe `player.currentItem` for item transitions,
+  /// and for each current item observe `status` so we can flip
+  /// `automaticallyWaitsToMinimizeStalling` to false the moment
+  /// the current item reaches `.readyToPlay` while
+  /// `gaplessFlipArmed == true`. Safe to call repeatedly — previous
+  /// observers are invalidated first.
+  ///
+  /// `.new`-only KVO: `.initial` is deliberately NOT used. `.initial`
+  /// fires synchronously during observer registration on whatever
+  /// thread the install runs from, which can land mid-mutation and
+  /// skip the lib's debounce step (`pendingStateChangeReason`
+  /// consumption, `lastEmittedQueueItemId` dedup). The explicit
+  /// async-to-main bootstrap below replicates `.initial` semantics
+  /// by funnelling through the same handler the `.new` callback
+  /// uses, but on a stable post-registration state. See NOTES.md §18.
+  private func installGaplessObservers(on player: AVQueuePlayer) {
+    tearDownGaplessObservers()
+
+    currentItemObserver = player.observe(
+      \.currentItem, options: [.new]
+    ) { [weak self] _, _ in
+      // KVO fires on AVFoundation's internal queue; funnel back to
+      // main to stay consistent with every other player mutation.
+      DispatchQueue.main.async {
+        guard let self else { return }
+        self.attachStatusObserverIfArmed()
+        self.handleCurrentItemDidChange()
+      }
+    }
+    // Bootstrap to replicate what `.initial` would have delivered.
+    // Async-to-main matches the `.new` callback body's dispatch
+    // shape so a fresh-install cur-item is observed identically
+    // to a subsequent transition.
+    DispatchQueue.main.async { [weak self] in
+      guard let self else { return }
+      self.attachStatusObserverIfArmed()
+      self.handleCurrentItemDidChange()
+    }
+  }
+
+  private func attachStatusObserverIfArmed() {
+    currentItemStatusObserver?.invalidate()
+    currentItemStatusObserver = nil
+    tearDownBufferObservers()
+    guard let item = self.player?.currentItem else {
+      // No current item (empty queue / torn down) — settle to empty.
+      recomputeBufferState()
+      return
+    }
+
+    // Two distinct concerns share this KVO:
+    //   1. `.readyToPlay` flips `automaticallyWaitsToMinimizeStalling`
+    //      back to false (initial-buffer leniency one-shot).
+    //   2. `.failed` surfaces an `onError` event — the only hook that
+    //      catches initial-load failures (closed port, 4xx/5xx HTTP,
+    //      malformed asset). Mid-playback failures arrive separately
+    //      via `AVPlayerItemFailedToPlayToEndTime`.
+    //
+    // `.new`-only KVO + synchronous bootstrap. The bootstrap is sync
+    // (not main-async like the sibling `\.currentItem` /
+    // `\.timeControlStatus` bootstraps) because this method is itself
+    // called from main (from `\.currentItem` KVO body's main-async
+    // block) — running the bootstrap inline catches a cache-hit path
+    // where the asset resolves to `.readyToPlay` before observer
+    // install would otherwise leave `gaplessFlipArmed` set forever.
+    //
+    // Re-entrancy: a `.failed` immediate resolution dispatches through
+    // `handleCurrentItemFailedToLoad` → `dispatchErrorOrRetry`, which
+    // may schedule a retry that calls `fullRebuildPlayerQueue`. The
+    // rebuild's `tearDownGaplessObservers` invalidates the just-
+    // installed observer reference; the synchronous bootstrap's local
+    // `let observer` reference still holds but its observation is
+    // disconnected. Safe — the inflight bootstrap path completes,
+    // returns to `attachStatusObserverIfArmed`, returns to the parent
+    // KVO body, and the rebuild's freshly-installed observer takes
+    // over.
+    currentItemStatusObserver = item.observe(
+      \.status, options: [.new]
+    ) { [weak self] item, _ in
+      guard let self else { return }
+      DispatchQueue.main.async {
+        self.dispatchItemStatus(item)
+      }
+    }
+    self.dispatchItemStatus(item)
+    installBufferObservers(on: item)
+  }
+
+  /// KVO on the gapless current item's three native playback-buffer flags.
+  /// Any change recomputes + emits the discrete `BufferState` on the next main
+  /// tick — sub-progress-tick latency for a stall / loading indicator.
+  private func installBufferObservers(on item: AVPlayerItem) {
+    let onChange: (AVPlayerItem, Any) -> Void = { [weak self] _, _ in
+      DispatchQueue.main.async {
+        self?.recomputeBufferState()
+        self?.recomputeFullyBuffered()
+      }
+    }
+    bufferEmptyObserver = item.observe(\.isPlaybackBufferEmpty, options: [.new], changeHandler: onChange)
+    bufferKeepUpObserver = item.observe(\.isPlaybackLikelyToKeepUp, options: [.new], changeHandler: onChange)
+    bufferFullObserver = item.observe(\.isPlaybackBufferFull, options: [.new], changeHandler: onChange)
+    recomputeBufferState()
+    recomputeFullyBuffered()
+  }
+
+  private func tearDownBufferObservers() {
+    bufferEmptyObserver?.invalidate(); bufferEmptyObserver = nil
+    bufferKeepUpObserver?.invalidate(); bufferKeepUpObserver = nil
+    bufferFullObserver?.invalidate(); bufferFullObserver = nil
+  }
+
+  /// Single source of truth for the per-item `\.status` KVO body.
+  /// Called both from the observer callback and from the synchronous
+  /// bootstrap in `attachStatusObserverIfArmed`.
+  private func dispatchItemStatus(_ item: AVPlayerItem) {
+    switch item.status {
+    case .readyToPlay:
+      if self.gaplessFlipArmed, let player = self.player {
+        player.automaticallyWaitsToMinimizeStalling = false
+        self.gaplessFlipArmed = false
+      }
+      // The asset's audio track + format descriptions are reliably
+      // loadable by the time we hit `.readyToPlay`. The post-track-
+      // change null-emit may race ahead of asset metadata load on
+      // first hit, so we re-resolve here to land the real format.
+      self.refreshNowPlayingFormatForActiveItem()
+      // Streaming-item audioMix catch-up for the gapless engine.
+      // engine.setItems / insertItems install the mix at insert
+      // time only for items whose `tracks` key is already loaded;
+      // streaming items insert with `audioMix == nil` and pick up
+      // their mix here once `.readyToPlay` confirms tracks have
+      // loaded. The crossfade engine has a parallel catch-up path
+      // through its `engineActiveItemFormatChanged` delegate hook —
+      // both call into `refreshActiveItemMixes`, which is
+      // idempotent on items that already carry a tap, so a double-
+      // fire is harmless.
+      AudioTapProvider.shared.refreshActiveItemMixes()
+    case .failed:
+      // Pause synchronously BEFORE surfacing the typed error. Without
+      // this, AVQueuePlayer treats `.failed` as end-of-item and chain-
+      // advances through subsequent items in the queue, walking
+      // `currentTrackIndex` past the failure point while the JS error
+      // event is still in flight. Pausing halts that walk so the
+      // consumer sees the error against the failing track and can
+      // decide whether to skip / retry / surface UI.
+      self.player?.pause()
+      self.handleCurrentItemFailedToLoad(item)
+    default:
+      break
+    }
+  }
+
+  /// Surface a `.failed` AVPlayerItem as an `onError` + state ERROR.
+  /// Idempotent per (queueItemId, standardized-code) so AVPlayer's
+  /// internal item-rebuild during retries doesn't bypass dedup. A
+  /// retry that flips the same item to a DIFFERENT error code still
+  /// surfaces because the code is part of the dedup key.
+  ///
+  /// `nativeDomain` on the emitted error is stamped to
+  /// `PLAYER_ITEM_LOAD_FAILED` so JS consumers can distinguish item-
+  /// load failures (the raw asset never reached `.readyToPlay`) from
+  /// mid-playback failures (which arrive via
+  /// `AVPlayerItemFailedToPlayToEndTime` and keep the underlying
+  /// `NSError.domain`). The underlying NSError code + message remain
+  /// available via `nativeCode` + `nativeMessage`.
+  private func handleCurrentItemFailedToLoad(_ item: AVPlayerItem) {
+    guard item.status == .failed else { return }
+    let underlying = item.error as NSError?
+    dispatchErrorOrRetry(
+      item: item,
+      underlying: underlying,
+      nativeDomainOverride: "PLAYER_ITEM_LOAD_FAILED"
+    )
+  }
+
+  /// Shared dispatch path for `handleCurrentItemFailedToLoad` +
+  /// `handlePlayerItemFailedToPlayToEndTime`. Encapsulates: (1)
+  /// classifier, (2) qid-fallback to fresh UUID for raw items, (3)
+  /// (queueItemId, code) dedup, (4) auto-retry path with dedup
+  /// clear-on-retry, (5) terminal `errorListeners.forEach` +
+  /// emitState(.error). Single chokepoint so the dedup + retry
+  /// contracts can't drift between callers.
+  ///
+  /// `nativeDomainOverride` lets a caller stamp a stable lib-defined
+  /// SCREAMING_SNAKE_CASE marker on the emitted `nativeDomain` (e.g.
+  /// `PLAYER_ITEM_LOAD_FAILED` from the `.failed`-status path) so JS
+  /// consumers can branch on the cause without parsing raw native
+  /// domain strings. Nil preserves the underlying `NSError.domain`.
+  private func dispatchErrorOrRetry(
+    item: AVPlayerItem?,
+    underlying: NSError?,
+    nativeDomainOverride: String? = nil
+  ) {
+    let mapped = PlaybackErrorMapping.classify(underlying)
+    // Fresh UUID fallback per fire (NOT a static sentinel) when
+    // queueItemId is missing — two unrelated items both lacking the
+    // associated-object would otherwise dedup against each other.
+    // Production AVQueueBuilder.makeItem always sets queueItemId; this
+    // path covers raw `makeItemRaw` items (test stubs).
+    let qid = item?.queueItemId ?? UUID().uuidString
+    if self.lastErrorQueueItemId == qid && self.lastErrorCode == mapped { return }
+    self.lastErrorQueueItemId = qid
+    self.lastErrorCode = mapped
+    // Auto-retry path: transient errors with retries left schedule
+    // a delayed rebuild. Skip JS emit + state.error transition until
+    // retries exhausted.
+    if PlaybackErrorMapping.isTransient(mapped),
+       let qidReal = item?.queueItemId,
+       (self.retryAttemptsRemaining[qidReal] ?? 0) > 0 {
+      self.retryAttemptsRemaining[qidReal] = self.retryAttemptsRemaining[qidReal]! - 1
+      // Clear dedup so the retry-then-fail (if any) fires fresh.
+      self.lastErrorQueueItemId = nil
+      self.lastErrorCode = nil
+      let backoff = self.effectiveRetryBackoffMs()
+      DispatchQueue.main.asyncAfter(deadline: .now() + .milliseconds(backoff)) {
+        [weak self] in self?.retryFailedItem(queueItemId: qidReal)
+      }
+      return
+    }
+    // Surface the failing item's queueItemId + URL so consumers can
+    // correlate the error to the specific track even when
+    // AVQueuePlayer chain-advances past it before the JS event fires.
+    // Reuse `qid` (which is the lib-generated UUID fallback for raw
+    // items) so the JS-visible field matches the dedup key.
+    let failedQid = item?.queueItemId ?? qid
+    let failedUrl = (item?.asset as? AVURLAsset)?.url.absoluteString ?? ""
+    let err = self.buildPlaybackError(
+      underlying,
+      mapped: mapped,
+      queueItemId: failedQid,
+      url: failedUrl,
+      nativeDomainOverride: nativeDomainOverride
+    )
+    self.errorListeners.forEach { $0(err) }
+    self.emitState(.error, reason: .error)
+  }
+
+  private func tearDownGaplessObservers() {
+    currentItemObserver?.invalidate()
+    currentItemObserver = nil
+    currentItemStatusObserver?.invalidate()
+    currentItemStatusObserver = nil
+    tearDownBufferObservers()
+  }
+
+  /// Re-arm the initial-buffer leniency: the next `.readyToPlay`
+  /// flips stalling back to false. Called from `fullRebuildPlayerQueue`
+  /// (central choke point for "the currentItem is being replaced by
+  /// a fresh AVPlayerItem") and from `removeFromQueue` when the
+  /// currentItem is dropped and AVQueuePlayer auto-advances to an
+  /// item that may not yet be buffered.
+  ///
+  /// The `\.currentItem` KVO chain already installed in `configure`
+  /// handles attaching the status observer once the new currentItem
+  /// is in place — we don't attach it synchronously here to avoid
+  /// racing against the caller's in-flight `player.insert(...)`
+  /// sequence.
+  internal func rearmGaplessFlip() {
+    guard let player = self.player else { return }
+    self.gaplessFlipArmed = true
+    player.automaticallyWaitsToMinimizeStalling = true
+  }
+
+  // MARK: - Queue mutation
+  //
+  // All mutations operate on two parallel structures:
+  //   1. `self.tracks` — the authoritative ordered TrackItem list.
+  //      AVQueuePlayer consumes items forward-only so skip-backward
+  //      rebuilds the player's queue from this list.
+  //   2. The AVQueuePlayer instance's internal queue — mirrors
+  //      `self.tracks` starting from `currentTrackIndex` onward.
+  //      Surgical insert/remove calls keep it in sync without
+  //      tearing down the currently-playing item when possible.
+  //
+  // Thread safety: every mutation body hops to the main thread via
+  // `onMain`. AVFoundation is not documented as thread-safe for
+  // AVQueuePlayer mutations, and Apple's samples always mutate from
+  // main. The hop also serialises concurrent JS calls — two back-
+  // to-back `addToQueue` + `removeFromQueue` invocations cannot
+  // interleave because DispatchQueue.main is serial by definition.
+
+  /// Serialise a mutation body on the main thread and return a
+  /// Promise-compatible awaitable. Centralising here keeps the
+  /// AVQueuePlayer-mutation rule (main-thread-only) enforceable.
+  /// `@MainActor` on the closure parameter lets the body access
+  /// MainActor-isolated AVFoundation APIs (AVPlayer.play / pause /
+  /// rate / etc.) without per-call-site warnings; the body really
+  /// does run on main because the dispatch destination is
+  /// `DispatchQueue.main`.
+  private func onMain(_ body: @escaping @MainActor () -> Void) async {
+    await withCheckedContinuation { (cont: CheckedContinuation<Void, Never>) in
+      DispatchQueue.main.async {
+        MainActor.assumeIsolated {
+          body()
+        }
+        cont.resume()
+      }
+    }
+  }
+
+  /// Throwing variant of `onMain` — propagates a Swift `throw` from
+  /// the body up through the await so callers wrapping the call in
+  /// a `Promise<Void>.async` see the JS Promise reject with the
+  /// thrown error's message via the Nitro bridge.
+  private func onMainThrowing(_ body: @escaping @MainActor () throws -> Void) async throws {
+    try await withCheckedThrowingContinuation { (cont: CheckedContinuation<Void, Error>) in
+      DispatchQueue.main.async {
+        MainActor.assumeIsolated {
+          do {
+            try body()
+            cont.resume()
+          } catch {
+            cont.resume(throwing: error)
+          }
+        }
+      }
+    }
+  }
+
+  /// Raise `isMutatingPlayerQueue` for the duration of `body`,
+  /// restoring the prior value on exit (so nested calls stay true
+  /// throughout the outer mutation). Used to suppress spurious
+  /// `onQueueEnd` / `onTrackChange` fires from the `\.currentItem`
+  /// KVO during the `removeAllItems` → `insert` intermediate nil
+  /// window. Must be called on main thread.
+  private func performingMutation(_ body: () -> Void) {
+    let wasAlready = self.isMutatingPlayerQueue
+    self.isMutatingPlayerQueue = true
+    defer { self.isMutatingPlayerQueue = wasAlready }
+    body()
+  }
+
+  func setQueue(tracks: [TrackItem], startAtIndex: Double?) throws -> Promise<Void> {
+    return Promise<Void>.async {
+      // Cast-route short-circuit: when a remote session is active,
+      // push the queue to the receiver via `CastTransportRouter`. Local
+      // `queueState` + `currentTrackIndex` are still updated so JS
+      // reads (`getQueue` / `getCurrentTrackIndex`) reflect the
+      // user-visible queue while the receiver is authoritative for
+      // playback. Mirrors Android 7B.2 (4/5)'s pattern. Remote-load
+      // failures fall through to the local path.
+      let resolvedStart: Int
+      if tracks.isEmpty {
+        resolvedStart = -1
+      } else {
+        let requested = startAtIndex.map { Int($0) } ?? 0
+        resolvedStart = max(0, min(requested, tracks.count - 1))
+      }
+      let castItems = tracks.compactMap { CastMediaItem.from(track: $0) }
+      // Skip the cast route if EVERY track had an unparseable url
+      // (`from(track:)` returned nil). Empty queues mean nothing to
+      // play; let the local path handle the clear-queue case.
+      let canRouteToCast = !tracks.isEmpty && castItems.count == tracks.count
+      var castItemIds: [Int]? = nil
+      if canRouteToCast {
+        do {
+          // Replacing the whole queue starts the new queue on the receiver
+          // (distinct from `handoffCurrentPlaybackToCast`, which preserves the
+          // in-flight play/pause state). The local engine is paused during cast,
+          // so its state can't stand in for the receiver's here.
+          castItemIds = try await CastTransportRouter.routeSetQueue(
+            tracks: castItems,
+            startIndex: max(0, resolvedStart),
+            startPositionMs: 0,
+            playWhenReady: true
+          )
+        } catch {
+          // Receiver-side load failed — fall through to local so the
+          // user isn't stuck.
+          castItemIds = nil
+        }
+      }
+      if castItemIds != nil {
+        // Mirror the new queue locally so JS reads stay accurate
+        // (`getQueue`/`getCurrentTrackIndex`) AND so the local engine
+        // is ready to take over with the right items when cast
+        // disconnects. `syncPlayerQueue(preserveCurrent: false)`
+        // rebuilds the AVQueuePlayer items + arms initial-buffer
+        // leniency for the resolved start track. The local engine
+        // is already paused (the handoff on the cast-active transition
+        // silenced it); the rebuild stays paused.
+        await self.onMain {
+          self.performingMutation {
+            guard self.engine != nil else { return }
+            _ = self.queueState.replaceAll(tracks)
+            self.currentTrackIndex = resolvedStart
+            self.pendingTrackChangeReason = .queueReplaced
+            self.lastErrorQueueItemId = nil
+            self.lastErrorCode = nil
+            self.syncPlayerQueue(preserveCurrent: false)
+          }
+          // Seed the start track's lockscreen metadata immediately so the
+          // surface doesn't wait for the first receiver status. The current
+          // track is resolved from the receiver's absolute queue index, not
+          // the itemIds, so no itemId map is needed here.
+          self.castEventBridge.seedStartMetadata(startIndex: resolvedStart)
+          self.rescheduleLookahead()
+          self.recomputeCapabilities()
+        }
+        return
+      }
+      await self.onMain {
+        self.performingMutation {
+          // `self.engine` is the canonical "lib initialised" sentinel.
+          // `self.player` is the gapless engine's AVQueuePlayer and is
+          // nil under CrossfadeEngine — gating on it here would silently
+          // no-op every queue mutation made while in crossfade mode.
+          guard self.engine != nil else { return }
+          let newIds = self.queueState.replaceAll(tracks)
+          // Clamp the consumer-supplied start index into the queue
+          // bounds. Empty queue ignores the parameter; nil / NaN /
+          // negative / out-of-range all coerce to 0.
+          let resolvedStart: Int
+          if tracks.isEmpty {
+            resolvedStart = -1
+          } else {
+            let requested = startAtIndex.map { Int($0) } ?? 0
+            resolvedStart = max(0, min(requested, tracks.count - 1))
+          }
+          self.currentTrackIndex = resolvedStart
+          self.pendingTrackChangeReason = .queueReplaced
+          // Fresh queue → fresh dedup state. Without this an error on
+          // the prior queue's last item could suppress an identical
+          // coded error on the new queue's first item.
+          self.lastErrorQueueItemId = nil
+          self.lastErrorCode = nil
+          // Reset auto-retry counters: new queueItemIds → new budget
+          // entries. The retry budget is per-queue-position; old
+          // entries from the prior queue are gone with the prior
+          // queueItemIds.
+          let attempts = self.effectiveAutoRetries()
+          self.retryAttemptsRemaining = Dictionary(
+            uniqueKeysWithValues: newIds.map { ($0, attempts) }
+          )
+          // Rearm happens inside `fullRebuildPlayerQueue` (called via
+          // `syncPlayerQueue(preserveCurrent: false)`) — the resolved
+          // start track gets initial-buffer leniency automatically.
+          self.syncPlayerQueue(preserveCurrent: false)
+        }
+        self.rescheduleLookahead()
+        self.recomputeCapabilities()
+      }
+    }
+  }
+
+  /// Adding to an empty queue (cur == -1) leaves cur at -1 and leaves
+  /// the player empty — consumer must call `skipToIndex(0)` to start
+  /// playback. This avoids implicit "start playing" surprises on
+  /// `addToQueue`. Non-empty queue with
+  /// insertion strictly after cur preserves the currently-playing
+  /// item surgically. Insertion before/at cur shifts cur forward;
+  /// since AVQueuePlayer holds only cur-onward items, the player
+  /// queue is unchanged by before-cur insertions (no playback gap).
+  func addToQueue(tracks newTracks: [TrackItem], insertBefore: Double?) throws -> Promise<Void> {
+    return Promise<Void>.async {
+      // Mutate local (the phone's source-of-truth queue) and capture the
+      // resolved insert index against the pre-mutation queue, then mirror
+      // the insert to the receiver. Index resolution to receiver itemIds
+      // happens inside the cast session via GCKMediaQueue.
+      let insertAt: Int = self.onMainSync {
+        let at = QueueMutationArithmetic.clampInsertBefore(
+          insertBefore: insertBefore.flatMap { $0.isFinite ? Int($0) : nil },
+          trackCount: self.tracks.count
+        )
+        self.performingMutation {
+          self.addToQueueBody(newTracks: newTracks, insertBefore: insertBefore)
+        }
+        self.rescheduleLookahead()
+        self.recomputeCapabilities()
+        return at
+      }
+      // Mirror only when every new track is castable. A dropped item would
+      // shift the receiver queue out of alignment with the local index space
+      // that later mutations (remove/move) resolve against, so a partial set
+      // is not routed at all — the same all-or-nothing rule `setQueue` applies.
+      let castItems = newTracks.compactMap { CastMediaItem.from(track: $0) }
+      if !castItems.isEmpty, castItems.count == newTracks.count {
+        _ = await CastTransportRouter.routeAddToQueue(items: castItems, beforeIndex: insertAt)
+      }
+    }
+  }
+
+  private func addToQueueBody(newTracks: [TrackItem], insertBefore: Double?) {
+    guard !newTracks.isEmpty, let engine = self.engine else { return }
+
+    // Non-finite `insertBefore` is dropped (treated as append) so
+    // `Int($0)` never traps on NaN / ±Infinity. Mirrors Android's
+    // `takeIf { it.isFinite() }?.toInt()` sanitisation at the
+    // mutation boundary.
+    let at = QueueMutationArithmetic.clampInsertBefore(
+      insertBefore: insertBefore.flatMap { $0.isFinite ? Int($0) : nil },
+      trackCount: self.tracks.count
+    )
+
+    let newIds = self.queueState.insert(newTracks, at: at)
+    // Initialise retry-budget entries for the new items so they have
+    // an auto-retry budget when (if) they hit a transient error.
+    let attempts = self.effectiveAutoRetries()
+    for id in newIds {
+      self.retryAttemptsRemaining[id] = attempts
+    }
+    // Queue mutation regenerates the shuffle order. Documented
+    // trade-off ("shuffle jumps" on mid-playback adds) over preserving
+    // partial ordering. No-op when shuffle is disabled.
+
+    let oldCur = self.currentTrackIndex
+    self.currentTrackIndex = QueueMutationArithmetic.currentIndexAfterAdd(
+      currentIndex: oldCur, insertAt: at, count: newTracks.count
+    )
+
+    if oldCur < 0 {
+      // Queue was empty — player stays empty until skipToIndex.
+      return
+    }
+
+    if at <= oldCur {
+      // Insertion at/before cur: player queue (cur-onward) is
+      // unchanged; only cur shifted forward (already applied via
+      // `currentIndexAfterAdd` above).
+      return
+    }
+
+    // Insertion strictly after cur: surgical insert preserves the
+    // currently-playing item and any preloaded look-ahead state.
+    // Anchor on the track immediately before the insertion point,
+    // matched by lib-generated identity so it resolves in either
+    // engine's live queue (cur-onward for GaplessEngine, full queue
+    // for CrossfadeEngine). `at > oldCur` here, so `at - 1` is at or
+    // after the current item and therefore present in both.
+    let existing = engine.allMediaItems
+    let anchorId: String? = (at - 1 >= 0 && at - 1 < self.queueItemIds.count)
+      ? self.queueItemIds[at - 1] : nil
+    let afterItem: AVPlayerItem? =
+      existing.first { $0.queueItemId != nil && $0.queueItemId == anchorId }
+        ?? existing.last
+
+    let newItems = AVQueueBuilder.buildPlayerItems(
+      tracks: newTracks, queueItemIds: newIds,
+      config: self.config, cache: self.lookaheadCache)
+    let ok = engine.insertItems(newItems, after: afterItem)
+    if !ok {
+      // Surgical insert failed — recover by rebuilding the tail
+      // so `self.tracks` and the engine queue cannot diverge.
+      self.syncPlayerQueue(preserveCurrent: true)
+    }
+  }
+
+  func removeFromQueue(indices: [Double]) throws -> Promise<Void> {
+    return Promise<Void>.async {
+      // Capture the sanitised indices against the pre-mutation queue, mutate
+      // local, then mirror the removal to the receiver (resolved to stable
+      // itemIds inside the cast session before removing).
+      let castIndices: [Int] = self.onMainSync {
+        // Exclude the current index — the currently-playing track is
+        // pinned on the receiver too, matching the local body below.
+        let cur = self.currentTrackIndex
+        let sanitised = QueueMutationArithmetic.sanitiseRemoveIndices(
+          rawIndices: indices.map { Int($0) }, trackCount: self.tracks.count
+        ).filter { $0 != cur }
+        self.performingMutation {
+          self.removeFromQueueBody(indices: indices)
+        }
+        self.rescheduleLookahead()
+        self.recomputeCapabilities()
+        return sanitised
+      }
+      if !castIndices.isEmpty {
+        _ = await CastTransportRouter.routeRemoveFromQueue(indices: castIndices)
+      }
+    }
+  }
+
+  private func removeFromQueueBody(indices: [Double]) {
+    guard !indices.isEmpty, let engine = self.engine else { return }
+    // `removeIds` below force-subscripts `queueItemIds`; this asserts the
+    // parallel-array invariant the sanitiser's in-range output relies on.
+    assertQueueIdsInvariant("removeFromQueueBody")
+
+    var sanitised = QueueMutationArithmetic.sanitiseRemoveIndices(
+      rawIndices: indices.map { Int($0) },
+      trackCount: self.tracks.count
+    )
+    // The currently-playing track is pinned: it cannot be removed via
+    // removeFromQueue (a consumer that wants it gone skips off it first,
+    // then removes it). Drop the current index from the set — a request
+    // to remove only the current track is a no-op; a mixed request drops
+    // the other tracks and keeps the current one.
+    sanitised.removeAll { $0 == self.currentTrackIndex }
+    guard !sanitised.isEmpty else { return }
+
+    let trackCountBefore = self.tracks.count
+    let oldCur = self.currentTrackIndex
+
+    // Match the AVPlayerItems to drop by their lib-generated identity
+    // rather than by index offset, so the removal is engine-agnostic:
+    // GaplessEngine exposes only the cur-onward slice (consumed items
+    // are gone), while CrossfadeEngine exposes the full queue. Captured
+    // before the `queueState.remove` loop below mutates the id array.
+    let removeIds = Set(sanitised.map { self.queueItemIds[$0] })
+    let itemsToRemove = engine.allMediaItems.filter { item in
+      guard let id = item.queueItemId else { return false }
+      return removeIds.contains(id)
+    }
+
+    // Iterate in descending order so earlier indices stay valid as
+    // each removal shifts the remainder. Drop the matching
+    // retry-budget entry so the map doesn't grow stale.
+    for i in sanitised.reversed() {
+      let removedId = self.queueState.remove(at: i)
+      self.retryAttemptsRemaining.removeValue(forKey: removedId)
+    }
+    // Queue mutation regenerates the shuffle order. No-op when
+    // shuffle is disabled.
+
+    // The current track is never in the removed set, so it keeps playing
+    // and its identity is unchanged; only its index shifts down by the
+    // number of removed earlier tracks.
+    self.currentTrackIndex = QueueMutationArithmetic.currentIndexAfterRemove(
+      currentIndex: oldCur,
+      sanitisedIndices: sanitised,
+      trackCountBefore: trackCountBefore
+    )
+
+    // The currentItem is untouched (never in `itemsToRemove`); removing
+    // only later/earlier items leaves it playing in place.
+    for item in itemsToRemove {
+      engine.remove(item)
+    }
+  }
+
+  func moveInQueue(fromIndex: Double, toIndex: Double) throws -> Promise<Void> {
+    return Promise<Void>.async {
+      // Capture the validated from/to against the pre-mutation queue, mutate
+      // local, then mirror the reorder to the receiver.
+      let move: (from: Int, to: Int)? = self.onMainSync {
+        let from = Int(fromIndex)
+        let to = Int(toIndex)
+        let valid = from >= 0 && from < self.tracks.count
+          && to >= 0 && to < self.tracks.count && from != to
+          && from != self.currentTrackIndex
+        self.performingMutation {
+          self.moveInQueueBody(fromIndex: fromIndex, toIndex: toIndex)
+        }
+        self.rescheduleLookahead()
+        self.recomputeCapabilities()
+        return valid ? (from, to) : nil
+      }
+      if let move = move {
+        _ = await CastTransportRouter.routeMoveInQueue(fromIndex: move.from, toIndex: move.to)
+      }
+    }
+  }
+
+  private func moveInQueueBody(fromIndex: Double, toIndex: Double) {
+    guard self.engine != nil else { return }
+    let from = Int(fromIndex)
+    let to = Int(toIndex)
+    // The currently-playing track cannot be reordered — only the tracks
+    // around it move. Reordering the current item would force a full
+    // rebuild that restarts the active track.
+    guard from >= 0, from < self.tracks.count,
+          to >= 0, to < self.tracks.count,
+          from != to,
+          from != self.currentTrackIndex else { return }
+
+    let oldCur = self.currentTrackIndex
+    self.queueState.move(from: from, to: to)
+    // Queue mutation regenerates the shuffle order. No-op when
+    // shuffle is disabled.
+
+    self.currentTrackIndex = QueueMutationArithmetic.currentIndexAfterMove(
+      currentIndex: oldCur, fromIndex: from, toIndex: to
+    )
+    let newCur = self.currentTrackIndex
+
+    // Decide engine-queue adjustment:
+    //   * cur unchanged (oldCur == newCur) AND cur track wasn't
+    //     moved: engine queue is stale only in the tail; rebuild
+    //     tail while preserving currentItem.
+    //   * cur moved (from == oldCur) OR cur's physical position
+    //     shifted: full rebuild. This restarts the currently-
+    //     playing track — unavoidable because AVQueuePlayer
+    //     cannot re-order arbitrary items around its play head.
+    let preserveCurrent = (from != oldCur) && (newCur == oldCur)
+    // performingMutation so the crossfade engine's setItems →
+    // engineDidTransitionTrack doesn't clobber the move-computed
+    // currentTrackIndex with the rebuilt slice's engine index 0 (mirrors the
+    // setQueue paths, which already mutate under this guard).
+    self.performingMutation {
+      self.syncPlayerQueue(preserveCurrent: preserveCurrent)
+    }
+  }
+
+  func clearQueue() throws -> Promise<Void> {
+    return Promise<Void>.async {
+      await self.onMain {
+        self.performingMutation {
+          self.engine?.removeAllItems()
+          self.queueState.clear()
+          self.currentTrackIndex = -1
+          self.currentTrackSource = nil
+          // No rearm here — the next `setQueue` goes through
+          // `fullRebuildPlayerQueue` which rearms before inserts,
+          // so the clean-slate initial-buffer phase is preserved.
+        }
+        // `performingMutation` suppresses the `\.currentItem` → nil
+        // KVO fire; emit a synthetic trackChange here so JS hooks
+        // (e.g. `useActiveTrack`) clear their (track, index) snapshot.
+        // Mirrors Android `clearQueueInternal` which fires
+        // `(null, -1, QUEUE_REPLACED)` via Media3's onMediaItemTransition
+        // → `handleMediaItemTransition`. Reset `lastEmittedQueueItemId`
+        // so a subsequent `setQueue` re-emits cleanly via the dedup
+        // gate at `handleCurrentItemDidChange`.
+        self.lastEmittedQueueItemId = nil
+        self.lastErrorQueueItemId = nil
+        self.lastErrorCode = nil
+        self.retryAttemptsRemaining.removeAll()
+        self.trackChangeListeners.forEach { $0(nil, Double(-1), .queueReplaced, nil) }
+        self.nowPlayingInfo.refreshAll()
+        self.artworkResolver.cancelInFlight()
+        // Drop any cached now-playing format + emit null so JS-side
+        // consumers of `onNowPlayingFormatChange` see the queue-cleared
+        // state without waiting for the engine's `currentMediaItem` to
+        // settle (it can briefly retain the last item post-removeAll).
+        self.refreshNowPlayingFormatForActiveItem()
+        self.rescheduleLookahead()
+        self.recomputeCapabilities()
+        // The queue is empty now → settle buffer state + fully-buffered to their
+        // empty defaults and emit the transition. The `\.currentItem → nil` KVO
+        // is suppressed under `performingMutation`, so recompute explicitly.
+        self.hasStartedPlaying = false
+        self.wantsToPlay = false
+        self.recomputeBufferState()
+        self.recomputeFullyBuffered()
+      }
+      // Mirror the clear to the receiver (removes every receiver queue item).
+      _ = await CastTransportRouter.routeClearQueue()
+    }
+  }
+
+  func getQueue() throws -> [TrackItem] {
+    return tracks
+  }
+
+  /// Sync the engine's queue with `self.tracks[currentTrackIndex...]`.
+  ///
+  /// When `preserveCurrent` is true AND the engine has a currentItem,
+  /// that item is kept in place and only the tail (items after
+  /// current) is rebuilt — avoids a playback restart of the current
+  /// track. Used for mutations that leave the currently-playing
+  /// track untouched (e.g. remove-after-cur, move-entirely-after-cur).
+  ///
+  /// When false (or when there is no currentItem), does a full
+  /// rebuild. The consumer track restarts from position 0.
+  internal func syncPlayerQueue(preserveCurrent: Bool) {
+    assertQueueIdsInvariant("syncPlayerQueue")
+    guard let engine = self.engine else { return }
+    guard self.currentTrackIndex >= 0,
+          self.currentTrackIndex < self.tracks.count else {
+      engine.removeAllItems()
+      return
+    }
+
+    // Build the full tail post-currentItem.
+    let tailStart = self.currentTrackIndex + 1
+    let tailEnd = self.tracks.count
+    let tailTracks = Array(self.tracks[tailStart ..< tailEnd])
+    let tailIds = Array(self.queueItemIds[tailStart ..< tailEnd])
+    let tailItems = AVQueueBuilder.buildPlayerItems(
+      tracks: tailTracks, queueItemIds: tailIds,
+      config: self.config, cache: self.lookaheadCache)
+
+    if preserveCurrent, let currentItem = engine.currentMediaItem {
+      for item in engine.allMediaItems where item !== currentItem {
+        engine.remove(item)
+      }
+      let ok = engine.insertItems(tailItems, after: currentItem)
+      if !ok {
+        // Couldn't insert into the live queue — fall through to
+        // full rebuild so authoritative state + player converge.
+        return self.fullRebuildPlayerQueue()
+      }
+      return
+    }
+
+    self.fullRebuildPlayerQueue()
+  }
+
+  /// Drain + re-install the full `tracks[currentTrackIndex...]`
+  /// slice on the active engine. The rate save/restore that used
+  /// to live here is now internal to `engine.setItems`. Rearms
+  /// gapless-flip stalling BEFORE the install so the fresh
+  /// currentItem gets initial-buffer leniency until its
+  /// `\.readyToPlay` flips stalling off via the KVO chain.
+  private func fullRebuildPlayerQueue() {
+    assertQueueIdsInvariant("fullRebuildPlayerQueue")
+    guard let engine = self.engine else { return }
+    guard self.currentTrackIndex >= 0,
+          self.currentTrackIndex < self.tracks.count else {
+      engine.removeAllItems()
+      return
+    }
+    rearmGaplessFlip()
+    // Rebuild the full `tracks[cur...]` slice. AVURLAsset construction
+    // cost is amortised by the lookahead-cache prefetcher for the
+    // upcoming window; items beyond that are constructed lazily
+    // (assets don't load until the engine queries them).
+    let cur = self.currentTrackIndex
+    let slice = Array(self.tracks[cur ..< self.tracks.count])
+    let sliceIds = Array(self.queueItemIds[cur ..< self.tracks.count])
+    let items = AVQueueBuilder.buildPlayerItems(
+      tracks: slice, queueItemIds: sliceIds,
+      config: self.config, cache: self.lookaheadCache)
+    engine.setItems(items, startIndex: 0, startPositionSeconds: 0)
+  }
+
+
+  // MARK: - Transport — pass-through to AVQueuePlayer.
+
+  func play() throws -> Promise<Void> {
+    return Promise<Void>.async {
+      if CastTransportRouter.routePlay() { return }
+      await self.onMain {
+        // Stuck-recovery: if the user re-taps play after an
+        // exhausted-retries error, give one more shot. Reset
+        // counter to 1 (single shot, not full autoRetries — each
+        // user tap = one attempt for predictable UX) and rebuild.
+        if self.lastReportedState == .error,
+           self.currentTrackIndex >= 0,
+           self.currentTrackIndex < self.queueItemIds.count {
+          let qid = self.queueItemIds[self.currentTrackIndex]
+          if (self.retryAttemptsRemaining[qid] ?? 0) == 0 {
+            self.retryAttemptsRemaining[qid] = 1
+            self.lastErrorQueueItemId = nil
+            self.lastErrorCode = nil
+            if self.player != nil {
+              self.performingMutation { self.fullRebuildPlayerQueue() }
+            }
+          }
+        }
+        self.pendingStateChangeReason = self.pendingStateChangeReason ?? .user
+        self.wantsToPlay = true
+        self.engine?.play()
+        self.recomputeBufferState()
+      }
+    }
+  }
+
+  func retry() throws -> Promise<Void> {
+    return Promise<Void>.async {
+      // During cast the receiver owns playback — forward a play so a failed
+      // receiver item re-attempts.
+      if CastTransportRouter.routePlay() { return }
+      await self.onMain {
+        // Local recovery: only meaningful for a track that errored after its
+        // automatic retries were exhausted. Give it one fresh attempt — reset
+        // the per-track retry budget, rebuild the failed item, and resume.
+        guard self.lastReportedState == .error,
+              self.currentTrackIndex >= 0,
+              self.currentTrackIndex < self.queueItemIds.count else { return }
+        let qid = self.queueItemIds[self.currentTrackIndex]
+        // Capture the pre-failure position so a mid-track failure resumes where
+        // it stopped (the rebuild below reloads the item from 0). Matches
+        // Android's retryFailedItem position-restore.
+        let resumePos = self.engine?.currentPositionSeconds ?? 0
+        self.retryAttemptsRemaining[qid] = 1
+        self.lastErrorQueueItemId = nil
+        self.lastErrorCode = nil
+        if self.player != nil {
+          self.performingMutation { self.fullRebuildPlayerQueue() }
+        }
+        self.pendingStateChangeReason = self.pendingStateChangeReason ?? .user
+        self.wantsToPlay = true
+        self.engine?.play()
+        if resumePos.isFinite, resumePos > 0 {
+          _ = try? self.seekTo(position: resumePos)
+        }
+        self.recomputeBufferState()
+      }
+    }
+  }
+
+  func pause() throws -> Promise<Void> {
+    return Promise<Void>.async {
+      if CastTransportRouter.routePause() { return }
+      await self.onMain {
+        self.pendingStateChangeReason = self.pendingStateChangeReason ?? .user
+        self.wantsToPlay = false
+        self.engine?.pause()
+        self.recomputeBufferState()
+      }
+    }
+  }
+
+  /// "Stop" = pause + seek to start of current item. Does NOT clear
+  /// the queue — consumers wanting a full reset call clearQueue().
+  func stop() throws -> Promise<Void> {
+    return Promise<Void>.async {
+      if CastTransportRouter.routeStop() { return }
+      await self.onMain {
+        guard let engine = self.engine else { return }
+        self.pendingStateChangeReason = self.pendingStateChangeReason ?? .user
+        self.wantsToPlay = false
+        self.hasStartedPlaying = false
+        engine.stop()
+        self.recomputeBufferState()
+      }
+    }
+  }
+
+  /// Seek within the current track. Position in seconds; negative
+  /// values clamp to 0, values past the duration clamp to duration.
+  func seekTo(position: Double) throws -> Promise<Void> {
+    return Promise<Void>.async {
+      // Match Android (`TrackPlayer.kt` seekToInternal): non-finite
+      // (NaN / ±Infinity) inputs are silent no-ops. See
+      // `InputGuards.sanitisedSeekPosition` for the rationale.
+      guard let position = InputGuards.sanitisedSeekPosition(position) else { return }
+      if CastTransportRouter.routeSeekTo(positionMs: Int64(position * 1000.0)) { return }
+
+      // Engine-aware seek: under CrossfadeEngine `self.player` is
+      // nil. Without this branch every seek call would silently
+      // no-op once crossfade mode is active, breaking transport
+      // controls + auto-advance test coverage.
+      if self.player == nil {
+        guard let engine = self.engine else { return }
+        await self.onMain {
+          // Seeking replays from a position — no longer at the end of the
+          // queue. (Gapless no-ops at end-of-queue with no current item below.)
+          self.reachedQueueEnd = false
+          let duration = engine.currentDurationSeconds
+          let clamped: Double
+          if position < 0 {
+            clamped = 0
+          } else {
+            clamped = (duration > 0 && position > duration) ? duration : position
+          }
+          let seekTarget = self.clampToBufferedIfEnabled(clamped)
+          self.pendingStateChangeReason = self.pendingStateChangeReason ?? .user
+          engine.seek(toIndex: self.currentTrackIndex, position: seekTarget)
+          self.milestoneTracker.seek(
+            durationSec: self.effectiveMilestoneDuration(playerDuration: duration),
+            positionSec: seekTarget)
+          self.nowPlayingInfo.refreshPositionAndRate()
+        }
+        return
+      }
+
+      // A drained gapless player (`currentItem == nil`, the end-of-queue state
+      // where `reachedQueueEnd` is set) returns here before seeking, so the
+      // latch persists; a live `currentItem` means the latch was never set, so
+      // no clear is needed on this path.
+      guard let player = self.player, let item = player.currentItem else {
+        return
+      }
+      let itemDuration = CMTimeGetSeconds(item.duration)
+      let clamped: Double
+      if position < 0 {
+        clamped = 0
+      } else {
+        clamped = (itemDuration.isFinite && position > itemDuration) ? itemDuration : position
+      }
+      // Apply the opt-in buffered clamp on top of the 0/duration clamp — caps
+      // the target at the buffered edge when the seek is past what's downloaded.
+      let seekTarget = self.clampToBufferedIfEnabled(clamped)
+      // Stash `.user` reason BEFORE the seek so any state transition
+      // the seek triggers (e.g. playable → buffering on a long jump)
+      // gets the correct origin. Matches the play / pause / stop
+      // pattern; the docstring contract at line 181-187 names all four
+      // transports as `.user` stashers.
+      // Consume jumped-over milestones BEFORE issuing the (async) seek, on
+      // main, so a time-jump progress tick that fires during the seek
+      // can't emit the thresholds the seek skips over.
+      await self.onMain {
+        self.milestoneTracker.seek(
+          durationSec: self.effectiveMilestoneDuration(
+            playerDuration: (itemDuration.isFinite && itemDuration > 0) ? itemDuration : 0),
+          positionSec: seekTarget)
+      }
+      self.pendingStateChangeReason = self.pendingStateChangeReason ?? .user
+      let target = CMTime(seconds: seekTarget, preferredTimescale: CMTimeScale(NSEC_PER_SEC))
+      await player.seek(
+        to: target,
+        toleranceBefore: .zero,
+        toleranceAfter: .zero)
+      // Surface the new scrubber position to the lock-screen / control-
+      // center immediately. The KVO state-change emit covers transitions
+      // (e.g. paused → buffering on a long jump) but a same-state seek
+      // won't trigger an emit; without this the lock-screen scrubber sits
+      // at the pre-seek position until the next 10s periodic tick.
+      await self.onMain {
+        self.nowPlayingInfo.refreshPositionAndRate()
+      }
+    }
+  }
+
+  // MARK: - Skip
+  //
+  // AVQueuePlayer is forward-only, so skipToPrevious and skipToIndex
+  // (when target < current) both require rebuilding the player's
+  // queue from the authoritative `self.tracks` list at the new
+  // index. skipToNext is a surgical `player.advanceToNextItem()`
+  // when the next track is already queued; wraps round (via full
+  // rebuild) when `repeatModeState == .queue` and we're past the
+  // end.
+  //
+  // Shuffle (task #19): destructive action `shuffleQueue()`. Mutates
+  // `self.tracks` to a Fisher-Yates permutation, resets
+  // `currentTrackIndex` to 0, resumes playback if was playing, and
+  // returns the new ordering to the consumer. Skip arithmetic walks
+  // linearly across whatever ordering the consumer last installed;
+  // there is no shadow shuffle queue + no shuffle-aware skip
+  // overloads.
+
+  /// `skipToIndex` is an explicit consumer intent — it always honours
+  /// the target index in every repeat mode, including `.queue` (it
+  /// never wraps — the target is absolute). Out-of-range indices
+  /// silently no-op.
+  func skipToIndex(index: Double) throws -> Promise<Void> {
+    return Promise<Void>.async {
+      await self.onMain {
+        // Engine-aware: under CrossfadeEngine `self.player` is nil
+        // by design. Gating the skip on the engine surface lets
+        // mid-play engine swaps + crossfade-mode user skips work.
+        guard self.engine != nil else { return }
+        // See `InputGuards.validQueueIndex` for the rationale —
+        // validates non-finite + out-of-range in Double space so
+        // the subsequent Int conversion is bounded.
+        guard let target = InputGuards.validQueueIndex(
+          index, count: self.tracks.count
+        ) else { return }
+        // During cast, jump the receiver to the target index; its status
+        // echo drives the metadata + active-track update through the
+        // bridge (same as skipToNext/Previous). The local engine stays
+        // paused, so a local index write would desync from the receiver.
+        if CastTransportRouter.routeSkipToIndex(index: target) { return }
+        self.applyNewCurrentIndex(
+          newIndex: target, reason: .userSkipToIndex)
+      }
+    }
+  }
+
+  func skipToNext() throws -> Promise<Void> {
+    return Promise<Void>.async {
+      if CastTransportRouter.routeSkipToNext() { return }
+      await self.onMain {
+        guard self.engine != nil else { return }
+        guard let next = self.computeNextIndex() else { return }
+        self.applyNewCurrentIndex(
+          newIndex: next, reason: .userSkipNext)
+      }
+    }
+  }
+
+  /// Standard skip-previous: go to the previous track if there is one
+  /// (per the arithmetic helper; `.off`/`.track` don't wrap, `.queue`
+  /// wraps). Under `.track` this navigates like `.off` and repeat-one
+  /// persists. Apps that want the Apple-Music-style "tap Previous
+  /// restarts when position > 3s" UX implement that in their button
+  /// handler — the lib provides the primitive (skip if there's a
+  /// track to skip to), not the policy.
+  func skipToPrevious() throws -> Promise<Void> {
+    return Promise<Void>.async {
+      if CastTransportRouter.routeSkipToPrevious() { return }
+      await self.onMain {
+        guard self.engine != nil else { return }
+        guard let prev = self.computePreviousIndex() else { return }
+        self.applyNewCurrentIndex(
+          newIndex: prev, reason: .userSkipPrevious)
+      }
+    }
+  }
+
+  /// Next-track index. Delegates to `QueueSkipArithmetic.computeNext`.
+  /// cur<0 sentinel: "nothing playing yet" → skipToNext is a no-op
+  /// (consumer starts via `setQueue` + `play` or `skipToIndex(0)`).
+  internal func computeNextIndex() -> Int? {
+    return QueueSkipArithmetic.computeNext(
+      trackCount: self.tracks.count,
+      currentIndex: self.currentTrackIndex,
+      repeatMode: repeatModeAsSkipMode())
+  }
+
+  /// Previous-track index. Delegates to `QueueSkipArithmetic.computePrevious`.
+  /// Same cur<0 early-bail as `computeNextIndex`.
+  internal func computePreviousIndex() -> Int? {
+    return QueueSkipArithmetic.computePrevious(
+      trackCount: self.tracks.count,
+      currentIndex: self.currentTrackIndex,
+      repeatMode: repeatModeAsSkipMode())
+  }
+
+  /// Map the Nitrogen-generated `RepeatMode` enum onto the pure-Swift
+  /// `QueueSkipRepeatMode` so `QueueSkipArithmetic` can stay off the
+  /// Swift ↔ C++ interop path (needed so XCTest targets reach the
+  /// arithmetic without C++-interop friction).
+  private func repeatModeAsSkipMode() -> QueueSkipRepeatMode {
+    switch self.repeatModeState {
+    case .off: return .off
+    case .track: return .track
+    case .queue: return .queue
+    }
+  }
+
+  /// Recompute `cachedSkipCapability` from
+  /// authoritative state (`tracks`, `currentTrackIndex`,
+  /// `repeatModeState`) and fire `onSkipCapabilityChange` if either
+  /// flipped.
+  ///
+  /// **Threading invariant:** must be called on main. Reads
+  /// `tracks` / `currentTrackIndex` / `repeatModeState`, all of
+  /// which mutate only on main, so the read is race-free; the
+  /// listener fire iterates a snapshot under `ListenerRegistry`'s
+  /// internal lock so subscriber add/remove during the fire round
+  /// is safe.
+  ///
+  /// **Dedup:** the listener fires only when the (prev, next) tuple
+  /// actually changes. Two back-to-back recompute calls that land on
+  /// the same tuple emit once, not twice. This is what makes it safe
+  /// to scatter `recomputeCapabilities()` calls across every
+  /// mutation site without producing chatty events.
+  ///
+  /// **Hook points** (every site that writes `tracks` /
+  /// `currentTrackIndex` / `repeatModeState`):
+  /// - `setQueue`, `addToQueueBody`, `removeFromQueueBody`,
+  ///   `moveInQueueBody`, `clearQueue`
+  /// - `applyNewCurrentIndex` (covers skipToNext / skipToPrevious /
+  ///   skipToIndex)
+  /// - `handleCurrentItemDidChange` (covers AVQueuePlayer auto-advance
+  ///   that updates `currentTrackIndex` via `matchTrackIndex`)
+  /// - `setRepeatMode`, `shuffleQueue`
+  /// - `destroy` (resets to (false, false) so a final emit lets
+  ///   subscribers know the player is gone)
+  internal func recomputeCapabilities() {
+    let mode = repeatModeAsSkipMode()
+    let count = tracks.count
+    let cur = currentTrackIndex
+    let newPrev = QueueSkipArithmetic.canSkipPrevious(
+      trackCount: count, currentIndex: cur, repeatMode: mode)
+    let newNext = QueueSkipArithmetic.canSkipNext(
+      trackCount: count, currentIndex: cur, repeatMode: mode)
+    let current = cachedSkipCapability
+    guard newPrev != current.canSkipPrevious || newNext != current.canSkipNext else {
+      return
+    }
+    let snapshot = SkipCapability(
+      canSkipPrevious: newPrev, canSkipNext: newNext)
+    cachedSkipCapability = snapshot
+    skipCapabilityListeners.forEach { $0(snapshot) }
+    self.remoteCommands.setSkipCapability(
+      canSkipNext: newNext, canSkipPrevious: newPrev
+    )
+  }
+
+  /// Apply a new `currentTrackIndex` and sync the AVQueuePlayer.
+  ///
+  /// **Forward skip** (newIndex > oldIndex) — surgical trim of items
+  /// between current and target + `player.advanceToNextItem()`. Safe
+  /// because `preferredForwardBufferDuration = 0.0` closes the
+  /// chain-advance-while-paused vector and the `didPlayToEndPending`
+  /// resync gate prevents any chain-advance from corrupting
+  /// `currentTrackIndex` even if it did fire.
+  ///
+  /// **Backward skip** (newIndex < oldIndex, including .queue-mode
+  /// wraparound) — full rebuild via `fullRebuildPlayerQueue`.
+  /// AVQueuePlayer is forward-only; backward navigation always
+  /// requires removing all items + re-inserting from the new index.
+  ///
+  /// - `newIndex == oldIndex` → explicit no-op (skipToIndex to the
+  ///   current index does not restart it; consumers seek explicitly).
+  /// - out-of-range `newIndex` → silent no-op.
+  ///
+  /// **Void return is intentional.** Silent-return cases here
+  /// (out-of-range, identity skip) are legitimate; track-change /
+  /// queue-end events flow through `handleCurrentItemDidChange`
+  /// driven by the AVQueuePlayer `\.currentItem` KVO, which is the
+  /// source of truth for whether a track actually became current.
+  /// A `Bool` return would be a *prediction* of whether KVO will
+  /// fire — predictions drift, KVO doesn't.
+  private func applyNewCurrentIndex(
+    newIndex: Int, reason: TrackChangeReason
+  ) {
+    guard newIndex >= 0, newIndex < self.tracks.count else { return }
+
+    let oldIndex = self.currentTrackIndex
+    if newIndex == oldIndex {
+      // A same-index skip is an explicit "restart this track" — no longer at
+      // the end of the queue. Clear the latch here because this branch returns
+      // before `dispatchTrackChange` (which is the other clear point), so a
+      // crossfade in-place replay after end-of-queue would otherwise stay
+      // stuck on `.ended`.
+      self.reachedQueueEnd = false
+      // Same-index user skip = "restart this track from 0". Don't
+      // rebuild the queue or fire onTrackChange (the active track
+      // hasn't changed), but do reset the engine's playhead so the
+      // call-site contract is "track N from position 0" regardless
+      // of where the engine currently is — including after a
+      // setPlaybackMode swap that carried position across.
+      //
+      // Engine-aware: GaplessEngine's `allMediaItems` is the
+      // REMAINING queue (consumed items are dropped post auto-
+      // advance), so `engine.seek(toIndex: lib's index, …)`
+      // indexes into the wrong space; reset via the AVQueuePlayer's
+      // currentItem directly. CrossfadeEngine maintains the full
+      // queue 1:1 with `self.tracks`, so the lib-side index is
+      // accepted directly.
+      //
+      // A drained gapless AVQueuePlayer (`currentItem == nil`, so `items()` is
+      // empty) can't be seeked — `actionAtItemEnd = .advance` consumes items as
+      // they finish, so at end-of-queue there's nothing to seek. Rebuild at the
+      // current index to reload the track so the restart intent isn't dropped.
+      // Crossfade (`self.player == nil`) keeps its item on the leading leg, so
+      // the engine seek resets it in place.
+      if let player = self.player, player.currentItem != nil {
+        player.currentItem?.seek(to: .zero, completionHandler: nil)
+      } else if self.player != nil {
+        self.performingMutation { self.fullRebuildPlayerQueue() }
+      } else {
+        self.engine?.seek(toIndex: newIndex, position: 0)
+      }
+      return
+    }
+
+    // Stash reason only now that we know a real transition is
+    // happening. Consumed by `handleCurrentItemDidChange` on the
+    // next non-nil `\.currentItem` KVO fire. Mid-rebuild nil fires
+    // are suppressed by `isMutatingPlayerQueue` so the reason
+    // survives until the terminal currentItem.
+    self.pendingTrackChangeReason = reason
+
+    self.performingMutation {
+      if oldIndex < 0 {
+        // Queue was empty / uninitialised — populate player fresh.
+        self.currentTrackIndex = newIndex
+        fullRebuildPlayerQueue()
+        return
+      }
+
+      self.currentTrackIndex = newIndex
+
+      if self.player == nil {
+        // CrossfadeEngine keeps the full queue 1:1 with `tracks`, so an
+        // absolute indexed seek lands on `newIndex` directly for both
+        // forward and backward navigation. The gapless forward-trim
+        // (`forwardSkipBy`) assumes `allMediaItems` is the remaining
+        // forward-only slice (consumed items dropped) — false for the
+        // crossfade engine, where it would remove the wrong items and
+        // desync the engine's current index from `currentTrackIndex`.
+        self.engine?.seek(toIndex: newIndex, position: 0)
+      } else if newIndex > oldIndex {
+        forwardSkipBy(delta: newIndex - oldIndex)
+      } else {
+        // Backward skip / `.queue`-mode wraparound — full rebuild.
+        // AVQueuePlayer is forward-only; backward navigation has no
+        // surgical alternative.
+        fullRebuildPlayerQueue()
+      }
+    }
+    // Every skip shifts the lookahead window. Reschedule covers all
+    // three skip methods (skipToIndex / Next / Previous all funnel
+    // through here).
+    self.rescheduleLookahead()
+    self.recomputeCapabilities()
+  }
+
+  /// Forward skip via surgical-trim + advanceToNextItem on the
+  /// player's existing items array. Caller holds the surrounding
+  /// `performingMutation` scope; this helper does NOT re-enter it.
+  /// Falls back to `fullRebuildPlayerQueue` when the player snapshot
+  /// is shorter than `delta` (defensive against partial chain-
+  /// advance / error-recovery state).
+  ///
+  /// Workaround: `advanceToNextItem` while paused can chain-advance
+  /// through unbuffered items because AVQueuePlayer interprets
+  /// unresolved durations as "played to end". Mitigated by
+  /// `preferredForwardBufferDuration = 0.0` at item construction +
+  /// the `didPlayToEndPending` resync gate.
+  /// TODO: monitor upstream for fixes — https://developer.apple.com/forums/thread/683744
+  private func forwardSkipBy(delta: Int) {
+    guard let engine = self.engine else { return }
+    let snapshot = engine.allMediaItems
+    guard snapshot.count > delta else {
+      fullRebuildPlayerQueue()
+      return
+    }
+    // Rearm the initial-buffer leniency window for the post-advance
+    // currentItem. `fullRebuildPlayerQueue` does this before
+    // inserting; surgical-trim doesn't touch items-array order, so
+    // the call is explicit here.
+    rearmGaplessFlip()
+    let trimRange = 1 ..< delta
+    let toRemove = Array(snapshot[trimRange])
+    for item in toRemove {
+      engine.remove(item)
+    }
+    engine.skipToNext()
+  }
+
+  /// Reschedule the proactive prefetcher after a queue or skip
+  /// mutation. Reads `tracks` + `currentTrackIndex` and dispatches
+  /// the next N remote tracks to [LookaheadCachePrefetcher]. No-op
+  /// when the prefetcher hasn't been built (configure not yet
+  /// called).
+  internal func rescheduleLookahead() {
+    guard let prefetcher = self.lookaheadCachePrefetcher else { return }
+    prefetcher.reschedule(
+      tracks: self.tracks,
+      currentIndex: self.currentTrackIndex
+    )
+  }
+
+  // MARK: - Playback configuration — some stubs, some lifecycle-adjacent
+
+  /// Mode-switch state machine — same matrix as the Android
+  /// counterpart in `PlaybackModeStateMachine.kt`. Driven by
+  /// `setPlaybackMode`; consumed by `getPlaybackMode` (returns
+  /// `state.active`) and the boundary fire path that promotes
+  /// pending modes on the next track-end.
+  internal let playbackModeStateMachine = PlaybackModeStateMachine()
+
+  internal var playbackModeState: PlaybackModeStateMachine.State =
+    PlaybackModeStateMachine.initial
+
+  func setPlaybackMode(mode: PlaybackMode) throws -> Promise<Void> {
+    return Promise<Void>.async {
+      try await self.onMainThrowing {
+        let (newState, effect) = try self.playbackModeStateMachine.setRequested(
+          state: self.playbackModeState,
+          requested: mode
+        )
+        self.playbackModeState = newState
+        switch effect {
+        case .noOp:
+          break
+        case .immediateSwap:
+          self.applyEngineSwapForMode(newState.active)
+        }
+      }
+    }
+  }
+
+  func getPlaybackMode() throws -> PlaybackMode {
+    return onMainSync { self.playbackModeState.active }
+  }
+
+  /// Build a fresh engine of the requested kind and swap it in
+  /// place of the active engine. The new engine starts empty; the
+  /// canonical queue model is re-installed via the engine surface
+  /// so playback continues from the current track / position.
+  ///
+  /// JS-facing event sources differ per engine. GaplessEngine ties
+  /// `self.player` to the underlying `AVQueuePlayer` and the KVO
+  /// chain installed by `installGaplessObservers` /
+  /// `installEventObservers` carries onTrackChange / onStateChange
+  /// / onError. CrossfadeEngine sets `self.player` to nil and
+  /// fires `PlaybackEngineDelegate` callbacks that this class
+  /// implements (extension at the end of the file); the delegate
+  /// is wired below. Both engines surface progress through
+  /// `emitProgressIfSubscribed`, polymorphic over self.player vs
+  /// engine state.
+  internal func applyEngineSwapForMode(_ active: PlaybackMode) {
+    let oldEngine = self.engine
+    // Capture pre-swap state — the engine swap releases the old
+    // engine; reading `newEngine.currentPositionSeconds` /
+    // `isPlaying` after would always return 0 / false. The
+    // wasPlaying capture is what carries playback continuity
+    // across the immediate engine swap.
+    let resumePosition = oldEngine?.currentPositionSeconds ?? 0
+    let resumeIndex = self.currentTrackIndex
+    let wasPlaying = oldEngine?.isPlaying ?? false
+
+    let newEngine: PlaybackEngine
+    switch active.kind {
+    case .gapless:
+      newEngine = GaplessEngine()
+    case .crossfade:
+      // PlaybackModeStateMachine.requireValid guarantees this is
+      // non-nil + within [1000, 12000] when `kind == .crossfade`.
+      // Fail loud rather than silently degrading to 0 (which would
+      // route through CrossfadeEngine's hard-cut path + skip
+      // engineCrossfadeDidBegin entirely).
+      guard let durationMs = active.crossfadeDurationMs else {
+        preconditionFailure("PlaybackMode(crossfade) missing crossfadeDurationMs at engine construction")
+      }
+      let durationSeconds = durationMs / 1000.0
+      newEngine = CrossfadeEngine(crossfadeDurationSeconds: durationSeconds)
+    }
+
+    self.engine = newEngine
+    // GaplessEngine path: keep the established self.player KVO
+    // chain (currentItem / timeControlStatus / item.status) as
+    // the canonical event source. CrossfadeEngine path:
+    // self.player stays nil; the engine fires PlaybackEngineDelegate
+    // callbacks for track-change / state-change / format-ready /
+    // failed / play-to-end / queue-end and progress is sourced
+    // from the engine via a Timer-driven fallback.
+    if let gapless = newEngine as? GaplessEngine {
+      self.player = gapless.player
+      self.gaplessFlipArmed = true
+      self.installGaplessObservers(on: gapless.player)
+      self.installEventObservers(on: gapless.player)
+      self.stopProgressFallbackTimer()
+      // Gapless does not need the engine delegate — the underlying
+      // self.player KVO chain is the canonical event source.
+      newEngine.delegate = nil
+    } else {
+      self.tearDownGaplessObservers()
+      self.tearDownEventObservers()
+      self.player = nil
+      newEngine.delegate = self
+      self.startProgressFallbackTimer()
+      // The crossfade engine re-attaches queue items at skip + fade-arm
+      // without re-running AVQueueBuilder.makeItem, so it can't see a
+      // track that cached after the queue was built. Hand it a cache
+      // resolver (read lazily so it always sees the current cache) so
+      // those late attaches swap a remote item for its local cache file.
+      if let crossfade = newEngine as? CrossfadeEngine {
+        crossfade.setCachedURLResolver { [weak self] url in
+          guard let cached = self?.lookaheadCache?.cachedURL(forUrl: url) else {
+            return nil
+          }
+          // Mirror AVQueueBuilder.makeItem's hit path: bump LRU so the
+          // track being attached for playback isn't the next evicted.
+          self?.lookaheadCache?.touch(url: url)
+          return cached
+        }
+      }
+    }
+
+    // Re-wire the shared audio-tap provider to the new engine's
+    // audio-mix provider slot.
+    AudioTapProvider.shared.wireToPlaybackEngine(newEngine)
+
+    // Re-apply canonical config to the freshly-built engine BEFORE the
+    // queue install / play — it starts at engine defaults (repeat off,
+    // volume 1, speed 1), so without this a gapless↔crossfade swap
+    // silently drops the user's settings.
+    newEngine.setRepeatMode(self.repeatModeState)
+    newEngine.setVolume(self.volumeState)
+    // Carry the user's speed into the new engine. When resuming playback,
+    // apply it live via `setPlaybackSpeed` (sets `AVPlayer.rate`) BEFORE
+    // `setItems` — GaplessEngine.setItems captures the player's rate to
+    // restore it across the queue rebuild, so a speed applied after
+    // setItems/play() would be clobbered by that async restore. When
+    // paused, seed it only (no rate write, so the engine stays paused);
+    // play() applies it on the next resume.
+    if wasPlaying {
+      newEngine.setPlaybackSpeed(self.playbackSpeedState)
+    } else {
+      newEngine.seedPlaybackSpeed(self.playbackSpeedState)
+    }
+    newEngine.setPitchCorrectionMode(self.pitchCorrectionModeState)
+
+    // Re-install canonical queue model.
+    if resumeIndex >= 0, resumeIndex < self.tracks.count {
+      let items = AVQueueBuilder.buildPlayerItems(
+        tracks: self.tracks,
+        queueItemIds: self.queueItemIds,
+        config: self.config,
+        cache: self.lookaheadCache
+      )
+      newEngine.setItems(
+        items,
+        startIndex: resumeIndex,
+        startPositionSeconds: resumePosition
+      )
+      // Honour pre-swap playing state so a mid-play
+      // setPlaybackMode keeps playing on the new engine. Without
+      // this, every immediate swap silently pauses the user —
+      // the new engine starts paused by construction and nothing
+      // else triggers play() in this path.
+      if wasPlaying {
+        newEngine.play()
+      }
+    }
+
+    oldEngine?.release()
+  }
+
+  func setPlaybackSpeed(rate: Double) throws -> Promise<Void> {
+    return Promise<Void>.async {
+      // Clamp to a 0.25 floor: rate=0 on AVPlayer is functionally
+      // equivalent to pause(), which would surprise consumers calling
+      // `setPlaybackSpeed(0)` for a slow-down effect. Cross-platform
+      // contract documented in TrackPlayer.nitro.ts. Mutate on main
+      // — AVPlayer property writes outside main are documented races.
+      let safeRate = Float(max(0.25, rate))
+      await self.onMain {
+        self.playbackSpeedState = safeRate
+        // Apply to the LIVE rate only when the user wants playback (already
+        // playing, OR buffering toward play). On a paused/idle engine writing
+        // `AVPlayer.rate` starts it (rate > 0 == "play"), so with no play intent
+        // seed the speed instead (no rate write); `play()` applies it on the next
+        // resume. This keeps a persisted speed applied at app start — before a
+        // restored `setQueue` — from auto-starting a paused queue. `wantsToPlay`
+        // (not just `isPlaying`) covers the buffering-toward-play window so a
+        // speed change there still applies live.
+        if self.wantsToPlay || self.engine?.isPlaying == true {
+          self.engine?.setPlaybackSpeed(safeRate)
+        } else {
+          self.engine?.seedPlaybackSpeed(safeRate)
+        }
+      }
+    }
+  }
+  func setPitchCorrectionMode(mode: PitchCorrectionMode) throws -> Promise<Void> {
+    return Promise<Void>.async {
+      // Mutate on main — the engine writes AVPlayerItem properties, and
+      // AVPlayer/AVPlayerItem writes outside main are documented races.
+      await self.onMain {
+        self.pitchCorrectionModeState = mode
+        self.engine?.setPitchCorrectionMode(mode)
+      }
+    }
+  }
+  func getPitchCorrectionMode() throws -> PitchCorrectionMode {
+    return onMainSync { self.pitchCorrectionModeState }
+  }
+  func setVolume(volume: Double) throws -> Promise<Void> {
+    return Promise<Void>.async {
+      if CastTransportRouter.routeSetVolume(value: volume) { return }
+      // Mutate on main — AVPlayer property writes outside main are
+      // documented races. Matches the main-hop discipline applied
+      // to setPlaybackSpeed.
+      let level = Float(volume)
+      await self.onMain {
+        self.volumeState = level
+        self.engine?.setVolume(level)
+      }
+    }
+  }
+  func setSleepTimer(seconds: Double) throws -> Promise<Void> {
+    return Promise<Void>.async {
+      await self.onMain { self.setSleepTimerInternal(seconds: seconds) }
+    }
+  }
+  func setSleepTimerToTrackEnd() throws -> Promise<Void> {
+    return Promise<Void>.async {
+      await self.onMain { self.armSleepTimerToTrackEndInternal() }
+    }
+  }
+  func clearSleepTimer() throws -> Promise<Void> {
+    return Promise<Void>.async {
+      await self.onMain { self.clearSleepTimerInternal() }
+    }
+  }
+  func getSleepTimer() throws -> SleepTimerState {
+    return onMainSync { self.sleepTimerSnapshot() }
+  }
+  func onSleepTimerChange(
+    callback: @escaping (_ state: SleepTimerState) -> Void
+  ) throws -> () -> Void {
+    let id = sleepTimerListeners.add(callback)
+    DispatchQueue.main.async { [weak self] in
+      guard let self else { return }
+      guard self.sleepTimerListeners.contains(id: id) else { return }
+      callback(self.sleepTimerSnapshot())
+    }
+    return { [weak self] in _ = self?.sleepTimerListeners.remove(id: id) }
+  }
+
+  // MARK: - Sleep timer — internal
+
+  /// Arm a wall-clock duration timer; a non-positive value clears any timer.
+  private func setSleepTimerInternal(seconds: Double) {
+    guard seconds.isFinite, seconds > 0 else {
+      clearSleepTimerInternal()
+      return
+    }
+    restoreSleepTimerVolume()
+    sleepTimerCore.armDuration(seconds: seconds, nowMs: Self.nowEpochMs())
+    startSleepTimerTick()
+    emitSleepTimerChanged()
+  }
+
+  private func armSleepTimerToTrackEndInternal() {
+    restoreSleepTimerVolume()
+    sleepTimerCore.armEndOfTrack()
+    startSleepTimerTick()
+    emitSleepTimerChanged()
+  }
+
+  private func clearSleepTimerInternal() {
+    let wasActive = sleepTimerCore.isActive
+    restoreSleepTimerVolume()
+    sleepTimerCore.clear()
+    stopSleepTimerTick()
+    if wasActive { emitSleepTimerChanged() }
+  }
+
+  private func sleepTimerSnapshot() -> SleepTimerState {
+    let now = Self.nowEpochMs()
+    return SleepTimerState(
+      active: sleepTimerCore.isActive,
+      endsAtEpochMs: sleepTimerCore.deadlineEpochMs.map { Double($0) },
+      remainingSeconds: sleepTimerCore.remainingSeconds(nowMs: now).map { Double($0) },
+      endOfTrack: sleepTimerCore.isEndOfTrack)
+  }
+
+  private func emitSleepTimerChanged() {
+    let snapshot = sleepTimerSnapshot()
+    sleepTimerListeners.forEach { $0(snapshot) }
+  }
+
+  private func startSleepTimerTick() {
+    guard sleepTimerTimer == nil else { return }
+    let timer = Timer.scheduledTimer(
+      withTimeInterval: Self.sleepTimerTickInterval,
+      repeats: true
+    ) { [weak self] _ in
+      self?.onSleepTimerTick()
+    }
+    sleepTimerTimer = timer
+  }
+
+  private func stopSleepTimerTick() {
+    sleepTimerTimer?.invalidate()
+    sleepTimerTimer = nil
+  }
+
+  private func onSleepTimerTick() {
+    // While casting, the local engine is intentionally frozen (its position
+    // never advances), so feed the state machine the receiver's position /
+    // duration instead — otherwise the end-of-track tail rule never trips and
+    // `.endOfTrack` stays idle forever.
+    let durationSec: Double
+    let positionSec: Double
+    if let remote = PlaybackStateRouter.shared.activeRemote() {
+      let d = Double(remote.lastDurationMs) / 1000.0
+      let p = Double(remote.lastPositionMs) / 1000.0
+      durationSec = (d.isFinite && d > 0) ? d : 0
+      positionSec = (p.isFinite && p > 0) ? p : 0
+    } else {
+      let duration = self.engine?.currentDurationSeconds ?? 0
+      let position = self.engine?.currentPositionSeconds ?? 0
+      durationSec = (duration.isFinite && duration > 0) ? duration : 0
+      positionSec = (position.isFinite && position > 0) ? position : 0
+    }
+    let result = sleepTimerCore.tick(
+      nowMs: Self.nowEpochMs(),
+      trackDurationSec: durationSec,
+      trackPositionSec: positionSec)
+    applySleepTimerFade(result.fadeFraction)
+    if result.stateChanged { emitSleepTimerChanged() }
+    if result.pauseNow {
+      // Route the boundary pause to the receiver when casting (the receiver
+      // emits its own paused state); only the local-engine pause needs the
+      // sleep-timer reason tag.
+      if !CastTransportRouter.routePause() {
+        self.pendingStateChangeReason = .sleepTimer
+        self.engine?.pause()
+      }
+    }
+    if !sleepTimerCore.isActive { stopSleepTimerTick() }
+  }
+
+  /// Fade multiplies off `volumeState` without mutating it, so `getVolume`
+  /// stays truthful and the pre-fade level is restored on clear/fire.
+  private func applySleepTimerFade(_ fraction: Double) {
+    // Fade is local-only: the receiver's volume is user/system-owned and
+    // `volumeState` tracks the local level, so ramping it on the receiver would
+    // clobber the cast volume. When casting the boundary pause still routes to
+    // the receiver; the pre-pause fade is skipped. Undo any in-progress local
+    // fade first so a cast session appearing mid-fade can't strand the local
+    // engine at a ramped-down volume for a later cast→local return.
+    if PlaybackStateRouter.shared.activeRemote() != nil {
+      restoreSleepTimerVolume()
+      return
+    }
+    if fraction < 1.0 {
+      self.engine?.setVolume(Float(Double(self.volumeState) * fraction))
+      sleepTimerFading = true
+    } else if sleepTimerFading {
+      self.engine?.setVolume(self.volumeState)
+      sleepTimerFading = false
+    }
+  }
+
+  private func restoreSleepTimerVolume() {
+    if sleepTimerFading {
+      self.engine?.setVolume(self.volumeState)
+      sleepTimerFading = false
+    }
+  }
+
+  private static func nowEpochMs() -> Int64 {
+    Int64(Date().timeIntervalSince1970 * 1000)
+  }
+  func setRepeatMode(mode: RepeatMode) throws -> Promise<Void> {
+    return Promise<Void>.async {
+      await self.onMain {
+        self.repeatModeState = mode
+        // Forward to the active engine. The CrossfadeEngine needs the
+        // mode to suppress its look-ahead fade + loop the current item
+        // under `.track` (AVPlayer has no native repeat); GaplessEngine
+        // treats it as a no-op (repeat-track replay lives in
+        // handlePlayerItemDidPlayToEndTime).
+        self.engine?.setRepeatMode(mode)
+        // Both canSkipNext and canSkipPrevious depend on repeat mode
+        // (e.g. at idx 0 / last index, OFF↔QUEUE flips the boolean
+        // because QUEUE wraps). Recompute is cheap; dedup keeps the
+        // listener silent when the (prev, next) tuple is unchanged.
+        self.recomputeCapabilities()
+      }
+    }
+  }
+
+  func setRemoteControls(options: RemoteControlOptions) throws -> Promise<Void> {
+    return Promise<Void>.async {
+      // Guard nonsensical negatives (a negative forward interval would seek
+      // backward). Non-positive is clamped to 0 rather than rejected.
+      let fwd = max(0, options.forwardJumpInterval)
+      let back = max(0, options.backwardJumpInterval)
+      await self.onMain {
+        self.remoteSkipMode = options.skipMode
+        self.remoteForwardInterval = fwd
+        self.remoteBackwardInterval = back
+        self.remoteCommands.setRemoteControls(
+          mode: options.skipMode,
+          forwardInterval: fwd,
+          backwardInterval: back)
+        // Re-apply the cached grey-out: switching to track mode re-enables
+        // next/prev, which must reflect the queue-boundary capability
+        // (setSkipCapability is otherwise only called on queue/repeat change,
+        // and no-ops in interval mode).
+        self.remoteCommands.setSkipCapability(
+          canSkipNext: self.cachedSkipCapability.canSkipNext,
+          canSkipPrevious: self.cachedSkipCapability.canSkipPrevious)
+      }
+    }
+  }
+
+  // ReplayGain mode — thin wrapper around `AudioTapProvider.shared`.
+  // The provider owns the per-item state set + recompute walk; this
+  // Hybrid surface is the JS-facing setter / getter only.
+  func setReplayGainMode(mode: ReplayGainMode) throws -> Promise<Void> {
+    return Promise<Void>.async {
+      AudioTapProvider.shared.setReplayGainMode(mode)
+      // Re-emit the active item's NowPlayingFormat so
+      // `onNowPlayingFormatChange` subscribers (e.g. the
+      // `useNowPlayingFormat` hook) observe the new `replayGainActive`
+      // flag without waiting for the next track change. Mirrors the
+      // Android path's `refreshNowPlayingFormatForActiveItem` call from
+      // its own `setReplayGainMode`.
+      DispatchQueue.main.async {
+        guard let item = self.activeMediaItem else { return }
+        self.emitCurrentNowPlayingFormat(for: item)
+      }
+    }
+  }
+  func getReplayGainMode() throws -> ReplayGainMode {
+    return AudioTapProvider.shared.getReplayGainMode()
+  }
+  /// Destructive shuffle. Mutates the current queue in-place via
+  /// Fisher-Yates, resets `currentTrackIndex` to 0, and resumes
+  /// playback on the new tracks[0] if the player was playing
+  /// pre-shuffle. Returns the post-shuffle snapshot so the consumer
+  /// app can immediately reflect the new ordering in its UI.
+  ///
+  /// The pre-shuffle ordering is not preserved; once shuffled the
+  /// queue stays in the new order until the consumer calls
+  /// `setQueue` to install a fresh ordering.
+  ///
+  /// Empty queue → returns `{ tracks: [], currentIndex: -1, currentTrack: nil }`
+  /// without mutating state.
+  func shuffleQueue() throws -> Promise<ShuffleResult> {
+    return Promise<ShuffleResult>.async {
+      // `self.onMain` is Void-returning; we capture the result in a
+      // local var inside the body and return it from the outer
+      // Promise closure after the main-thread work completes.
+      var result = ShuffleResult(
+        tracks: [], currentIndex: -1, currentTrack: nil)
+      await self.onMain {
+        // Capture playing state BEFORE the mutation so we know whether
+        // to resume after the rebuild. Read via the engine surface so
+        // crossfade mode (where `self.player` is nil) is reflected.
+        let wasPlaying = self.engine?.isPlaying ?? false
+
+        if self.tracks.isEmpty {
+          // Empty queue — leave state untouched, return empty
+          // snapshot. result already initialised to that.
+          return
+        }
+        guard self.engine != nil else {
+          // No engine attached (configure() not yet called). Bail with
+          // empty result rather than silently mutating tracks but not
+          // the player — the prior shape returned a "shuffled"
+          // snapshot while leaving self.tracks unchanged, which lied
+          // to the consumer. Gate on `self.engine` (canonical lib-
+          // initialised sentinel); `self.player` is gapless-only and
+          // nil under CrossfadeEngine.
+          return
+        }
+
+        // Fisher-Yates via Swift stdlib (Apple-documented contract).
+        var newTracks = self.tracks
+        newTracks.shuffle()
+
+        self.performingMutation {
+          // Mirrors setQueue — `replaceAll` regenerates queueItemIds
+          // so each new AVPlayerItem gets a unique lib-internal
+          // identity and the destructive shuffle re-keys every
+          // position.
+          let newIds = self.queueState.replaceAll(newTracks)
+          self.currentTrackIndex = 0
+          self.pendingTrackChangeReason = .queueReplaced
+          let attempts = self.effectiveAutoRetries()
+          self.retryAttemptsRemaining = Dictionary(
+            uniqueKeysWithValues: newIds.map { ($0, attempts) }
+          )
+          self.fullRebuildPlayerQueue()
+        }
+        self.rescheduleLookahead()
+        self.recomputeCapabilities()
+
+        // Resume playback if the user was playing before the shuffle.
+        // Stays paused otherwise — consumer can call play() if they
+        // want to start from the new track 0.
+        if wasPlaying {
+          self.pendingStateChangeReason = .user
+          self.engine?.play()
+        }
+
+        result = ShuffleResult(
+          tracks: self.tracks,
+          currentIndex: 0,
+          currentTrack: self.tracks[0])
+      }
+      return result
+    }
+  }
+
+  // MARK: - State snapshots
+  //
+  // Nitro dispatches JS calls on a worker thread, NOT main. Apple's
+  // AVFoundation guidance ("serialize your access to Player and
+  // PlayerItem on the main queue") means every read of AVPlayer
+  // state must hop. The cached `canSkip*` Bools are written from
+  // main inside `recomputeCapabilities()`, so they ride the same
+  // hop for consistency. `onMainSync` short-circuits when already
+  // on main, so callers that are on main don't deadlock.
+  func getState() throws -> PlayerState {
+    return onMainSync {
+      // Both engines derive PlayerState from the same inputs via
+      // `engine.timeControlStatus` (gapless returns its AVQueuePlayer's, which
+      // is what `self.player` also points at; crossfade returns the active
+      // leg's), so gapless + crossfade report identical states. `.none` when no
+      // engine is configured.
+      guard let engine = self.engine else { return .none }
+      return PlayerStateDerivation.translate(
+        status: engine.timeControlStatus,
+        currentIndex: self.currentTrackIndex,
+        hasCurrentItem: engine.currentMediaItem != nil,
+        reachedQueueEnd: self.reachedQueueEnd
+      )
+    }
+  }
+  func getCurrentTrackIndex() throws -> Double {
+    // Nitrogen spec types this return as Double; bridge the internal Int.
+    return onMainSync { Double(self.currentTrackIndex) }
+  }
+  func getCurrentTrackSource() throws -> TrackSource? {
+    return onMainSync { self.currentTrackSource }
+  }
+  func getCanSkipNext() throws -> Bool {
+    return onMainSync { self.cachedSkipCapability.canSkipNext }
+  }
+  func getSkipCapability() throws -> SkipCapability {
+    return onMainSync { self.cachedSkipCapability }
+  }
+  func getCanSkipPrevious() throws -> Bool {
+    return onMainSync { self.cachedSkipCapability.canSkipPrevious }
+  }
+  func getPlaybackSpeed() throws -> Double {
+    return onMainSync { Double(self.playbackSpeedState) }
+  }
+  func getVolume() throws -> Double {
+    return onMainSync { Double(self.volumeState) }
+  }
+  func getRemoteControls() throws -> RemoteControlOptions {
+    return onMainSync {
+      let options: RemoteControlOptions = .init(
+        skipMode: self.remoteSkipMode,
+        forwardJumpInterval: self.remoteForwardInterval,
+        backwardJumpInterval: self.remoteBackwardInterval)
+      return options
+    }
+  }
+
+  func getBufferState() throws -> BufferState {
+    return onMainSync { self.currentBufferState }
+  }
+
+  func getIsSeekable() throws -> Bool {
+    return onMainSync {
+      guard let item = self.engine?.currentMediaItem else { return true }
+      return !item.seekableTimeRanges.isEmpty
+    }
+  }
+
+  func isFullyBuffered() throws -> Bool {
+    return onMainSync { self.currentFullyBuffered }
+  }
+
+  func onBufferStateChange(
+    callback: @escaping (_ state: BufferState) -> Void
+  ) throws -> () -> Void {
+    let id = bufferStateListeners.add(callback)
+    // Fire once on subscribe with the current state so a UI renders immediately.
+    DispatchQueue.main.async { [weak self] in
+      guard let self else { return }
+      guard self.bufferStateListeners.contains(id: id) else { return }
+      callback(self.currentBufferState)
+    }
+    return { [weak self] in self?.bufferStateListeners.remove(id: id) }
+  }
+
+  func onFullyBufferedChange(
+    callback: @escaping (_ fullyBuffered: Bool) -> Void
+  ) throws -> () -> Void {
+    let id = fullyBufferedListeners.add(callback)
+    DispatchQueue.main.async { [weak self] in
+      guard let self else { return }
+      guard self.fullyBufferedListeners.contains(id: id) else { return }
+      callback(self.currentFullyBuffered)
+    }
+    return { [weak self] in self?.fullyBufferedListeners.remove(id: id) }
+  }
+
+  // MARK: - Events — public registration surface
+  //
+  // Each event has a multi-listener `ListenerRegistry`. Each `onXxx`
+  // call appends a new entry; the returned closure removes that entry
+  // by stable id. ListenerRegistry's internal queue.sync makes
+  // add/remove safe against concurrent fire rounds — fire iterates a
+  // snapshot taken under the lock.
+
+  func onStateChange(
+    callback: @escaping (_ state: PlayerState, _ reason: StateChangeReason) -> Void
+  ) throws -> () -> Void {
+    let id = stateChangeListeners.add(callback)
+    return { [weak self] in self?.stateChangeListeners.remove(id: id) }
+  }
+
+  func onTrackChange(
+    callback: @escaping (_ track: TrackItem?, _ index: Double, _ reason: TrackChangeReason, _ transitionGapMs: Double?) -> Void
+  ) throws -> () -> Void {
+    let id = trackChangeListeners.add(callback)
+    return { [weak self] in self?.trackChangeListeners.remove(id: id) }
+  }
+
+  func onProgress(
+    callback: @escaping (_ progress: PlayerProgress) -> Void
+  ) throws -> () -> Void {
+    let id = progressListeners.add(callback)
+    return { [weak self] in self?.progressListeners.remove(id: id) }
+  }
+
+  func onPlaybackMilestone(
+    callback: @escaping (_ milestone: Double, _ trackIndex: Double) -> Void
+  ) throws -> () -> Void {
+    let id = milestoneListeners.add(callback)
+    return { [weak self] in self?.milestoneListeners.remove(id: id) }
+  }
+
+  func onError(callback: @escaping (_ error: PlaybackError) -> Void) throws -> () -> Void {
+    let id = errorListeners.add(callback)
+    return { [weak self] in self?.errorListeners.remove(id: id) }
+  }
+
+  func onQueueEnd(callback: @escaping () -> Void) throws -> () -> Void {
+    let id = queueEndListeners.add(callback)
+    return { [weak self] in self?.queueEndListeners.remove(id: id) }
+  }
+
+  /// Subscribe to skip-capability changes. Auto-fires the callback
+  /// once on registration with the current cached values (mirrors
+  /// Media3 `Player.Listener.onAvailableCommandsChanged`) so new
+  /// subscribers don't have to seed via the getters first. Hop to
+  /// main for the auto-fire so the cache read is on the same
+  /// queue that mutates it. Subsequent fires happen synchronously
+  /// from `recomputeCapabilities()` (which is itself main-bound).
+  ///
+  /// **Dispose race guard:** the deferred main fire checks the
+  /// subscriber is still registered (`contains(id:)`) before
+  /// invoking the callback. Strict-mode subscribe → dispose →
+  /// subscribe sequences fire the cleanup before the deferred fire
+  /// runs; without the guard, the auto-fire would call into an
+  /// already-unmounted React component's `setSnapshot`.
+  func onSkipCapabilityChange(
+    callback: @escaping (_ capability: SkipCapability) -> Void
+  ) throws -> () -> Void {
+    let id = skipCapabilityListeners.add(callback)
+    DispatchQueue.main.async { [weak self] in
+      guard let self else { return }
+      guard self.skipCapabilityListeners.contains(id: id) else { return }
+      callback(SkipCapability(
+        canSkipPrevious: self.cachedSkipCapability.canSkipPrevious,
+        canSkipNext: self.cachedSkipCapability.canSkipNext))
+    }
+    return { [weak self] in self?.skipCapabilityListeners.remove(id: id) }
+  }
+
+  // MARK: - Events — observer wiring
+
+  /// Install the periodic progress observer, state-change KVO, and
+  /// the NotificationCenter observers for error + end-of-item.
+  /// Track-change is piggybacked on the existing `\.currentItem`
+  /// KVO installed by `installGaplessObservers` — see
+  /// `handleCurrentItemDidChange`.
+  private func installEventObservers(on player: AVQueuePlayer) {
+    tearDownEventObservers()
+
+    // 2 Hz progress tick — per NOTES.md §5, native periodic timer
+    // (not JS setInterval) is load-bearing for backgrounded playback.
+    let interval = CMTime(
+      seconds: Self.progressIntervalSeconds,
+      preferredTimescale: CMTimeScale(NSEC_PER_SEC))
+    let token = player.addPeriodicTimeObserver(
+      forInterval: interval, queue: .main
+    ) { [weak self] _ in
+      self?.emitProgressIfSubscribed()
+      self?.processMilestones()
+      self?.recomputeBufferState()
+      self?.recomputeFullyBuffered()
+    }
+    progressTimeObserver = (player: player, token: token)
+
+    // `.new`-only KVO + async-to-main bootstrap. See
+    // `installGaplessObservers` for the rationale on why `.initial`
+    // is avoided lib-wide.
+    timeControlStatusObserver = player.observe(
+      \.timeControlStatus, options: [.new]
+    ) { [weak self] player, _ in
+      #if DEBUG
+      let observedStatus = player.timeControlStatus
+      #endif
+      DispatchQueue.main.async {
+        guard let self else { return }
+        #if DEBUG
+        if observedStatus == .playing && self.gaplessLogLastChangedAtNs > 0 {
+          let now = DispatchTime.now().uptimeNanoseconds
+          let deltaMs = Double(now &- self.gaplessLogLastChangedAtNs) / 1_000_000.0
+          NSLog("[RNQP-GAPLESS] tcs-playing trackIdx=%d ts_ns=%llu delta_since_changed_ms=%.3f",
+                self.currentTrackIndex, now, deltaMs)
+          // One-shot: clear the marker so a subsequent buffering/play
+          // cycle within the same track doesn't re-log against the
+          // stale baseline.
+          self.gaplessLogLastChangedAtNs = 0
+        }
+        #endif
+        self.emitStateChangeIfChanged()
+      }
+    }
+    // Bootstrap to replicate what `.initial` would have delivered.
+    // Contract: this consumes any staked-but-not-yet-emitted
+    // `pendingStateChangeReason` (path: emitStateChangeIfChanged
+    // consumes for non-buffering states). Today only `configure()`
+    // (gated on `self.player == nil`) reaches here, and at first
+    // configure `pendingStateChangeReason` is nil — so the
+    // consumption is a no-op. A future caller that invokes
+    // installEventObservers from a path where a reason is staked
+    // would silently swallow that reason; if such a path is ever
+    // added, restore the contract by stashing/reinstating the
+    // reason around this bootstrap.
+    DispatchQueue.main.async { [weak self] in
+      self?.emitStateChangeIfChanged()
+    }
+
+    NotificationCenter.default.addObserver(
+      self, selector: #selector(handlePlayerItemFailedToPlayToEndTime(_:)),
+      name: .AVPlayerItemFailedToPlayToEndTime, object: nil)
+    // Explicit AVPlayerItemDidPlayToEndTime observer. The SOLE
+    // authoritative signal for natural end-of-track,
+    // distinguishing real auto-advance from chain-advance bounces
+    // (AVQueuePlayer walking past unbuffered items during a rebuild
+    // does not fire DidPlayToEndTime). The handler sets
+    // `didPlayToEndPending` for `handleCurrentItemDidChange` to gate
+    // the matchTrackIndex resync, AND handles the repeat-track mode
+    // auto-rewind (seek to zero + replay). Item-status observation
+    // (initial-buffer leniency + load-failure → onError) is
+    // installed by `attachStatusObserverIfArmed`, which runs on
+    // every currentItem swap from the gapless KVO.
+    NotificationCenter.default.addObserver(
+      self, selector: #selector(handlePlayerItemDidPlayToEndTime(_:)),
+      name: .AVPlayerItemDidPlayToEndTime, object: nil)
+    // Access-log entries arrive multiple times per second during
+    // streaming (per network transfer chunk). Two consumers share the
+    // notification: (1) the streaming-MP3 bitrate fallback chain
+    // `handleNewAccessLogEntry → reresolveNowPlayingFormatForBitrate →
+    // NowPlayingFormatExtractor.extract → readStreamingMP3Bitrate`
+    // re-resolves the now-playing format for items whose cached
+    // bitrate is still null (CBR stream where `estimatedDataRate` came
+    // back zero); (2) the DEBUG gapless logger records stalls /
+    // observed bitrate / transfer duration against the transition
+    // timeline. The error-log subscription is DEBUG-only — it has no
+    // production consumer.
+    NotificationCenter.default.addObserver(
+      self, selector: #selector(handleNewAccessLogEntry(_:)),
+      name: AVPlayerItem.newAccessLogEntryNotification, object: nil)
+    #if DEBUG
+    NotificationCenter.default.addObserver(
+      self, selector: #selector(handleNewErrorLogEntry(_:)),
+      name: AVPlayerItem.newErrorLogEntryNotification, object: nil)
+    #endif
+  }
+
+  private func tearDownEventObservers() {
+    if let pair = progressTimeObserver {
+      pair.player.removeTimeObserver(pair.token)
+      progressTimeObserver = nil
+    }
+    timeControlStatusObserver?.invalidate()
+    timeControlStatusObserver = nil
+    NotificationCenter.default.removeObserver(
+      self, name: .AVPlayerItemFailedToPlayToEndTime, object: nil)
+    NotificationCenter.default.removeObserver(
+      self, name: .AVPlayerItemDidPlayToEndTime, object: nil)
+    NotificationCenter.default.removeObserver(
+      self, name: AVPlayerItem.newAccessLogEntryNotification, object: nil)
+    #if DEBUG
+    NotificationCenter.default.removeObserver(
+      self, name: AVPlayerItem.newErrorLogEntryNotification, object: nil)
+    #endif
+  }
+
+  /// Start polling the engine for progress at the same 0.5s
+  /// cadence the AVPlayer periodic time observer would. Used when
+  /// `self.player` is nil (CrossfadeEngine active). Idempotent —
+  /// repeat calls drop the prior timer first.
+  private func startProgressFallbackTimer() {
+    stopProgressFallbackTimer()
+    self.lastEmittedCrossfadePosition = -1
+    let timer = Timer.scheduledTimer(
+      withTimeInterval: Self.progressIntervalSeconds,
+      repeats: true
+    ) { [weak self] _ in
+      // Timer fires on the run loop the timer was scheduled on
+      // (main, since this is invoked from `applyEngineSwapForMode`
+      // which is on main). Run the same `emitProgressIfSubscribed`
+      // body the periodic observer would.
+      self?.emitProgressIfSubscribed()
+      self?.processMilestones()
+      self?.recomputeBufferState()
+      self?.recomputeFullyBuffered()
+    }
+    progressFallbackTimer = timer
+  }
+
+  private func stopProgressFallbackTimer() {
+    progressFallbackTimer?.invalidate()
+    progressFallbackTimer = nil
+  }
+
+  // MARK: - Events — dispatch
+
+  /// Called from the `\.currentItem` KVO dispatch in
+  /// `installGaplessObservers`. Fires `onTrackChange` whenever the
+  /// player's current item changes, and — when the change is
+  /// "currentItem went nil while the queue still had tracks" outside
+  /// of an in-flight mutation — also fires `onQueueEnd` and emits an
+  /// `.ended` state change.
+  ///
+  /// Mid-mutation nil fires are suppressed entirely. Every
+  /// `removeAllItems` + `insert` pair produces a transient
+  /// `currentItem == nil` observation before the real new item
+  /// lands; without the `isMutatingPlayerQueue` guard we'd both
+  /// consume `pendingTrackChangeReason` against the intermediate
+  /// fire AND spuriously emit `onQueueEnd` on every backward skip,
+  /// setQueue, full rebuild, etc.
+  private func handleCurrentItemDidChange() {
+    if self.isMutatingPlayerQueue && self.player?.currentItem == nil {
+      return
+    }
+    // Snapshot timestamp first thing so `transitionGapMs` measures the
+    // iOS-side notification→KVO scheduling delta, not the synchronous
+    // lib work that follows. Always overwritten — cheap UInt64 store.
+    self.gaplessGapMeasuredAtNs = DispatchTime.now().uptimeNanoseconds
+    let reason = consumePendingReasonAndResyncIndex()
+    dispatchTrackChange(reason: reason)
+    // Native auto-advance can change `currentTrackIndex` (via the
+    // matchTrackIndex resync) without going through any explicit
+    // mutation method. Recompute capabilities here so the boundary-
+    // flip canSkipNext under `.off` (last-track auto-advance leaving
+    // cur on the last track with no next) lands.
+    self.recomputeCapabilities()
+    detectQueueEnd()
+    // The matchTrackIndex resync makes `currentTrackIndex` canonical
+    // post-auto-advance, so rescheduling the prefetcher window from
+    // here shifts it to cur+1..cur+lookaheadCount against the
+    // freshly-synced index. The prefetcher dedupes by url, so
+    // re-issuing the same window mid-prefetch is cheap.
+    self.rescheduleLookahead()
+  }
+
+  /// Consume `pendingTrackChangeReason` + `didPlayToEndPending` and,
+  /// when the player has auto-advanced naturally, resync
+  /// `currentTrackIndex` from the player's current AVPlayerItem via
+  /// `matchTrackIndex`. Returns the consumed reason for the caller
+  /// to thread into `dispatchTrackChange`. Defaults to `.autoAdvance`
+  /// when no user mutation stashed a reason.
+  ///
+  /// Resync requires BOTH `didPlayToEndPending` set AND no pending
+  /// user-mutation reason. User mutations pre-write
+  /// `currentTrackIndex` before the rebuild — that intent is
+  /// authoritative. The reason gate covers the FB9221518 case where
+  /// a paused-state `removeAllItems` fires DidPlayToEndTime for a
+  /// queue item that was never played; without it the post-rebuild
+  /// KVO main hop would resync to AVQueuePlayer's stale
+  /// `currentItem` value (the pre-rebuild item).
+  private func consumePendingReasonAndResyncIndex() -> TrackChangeReason {
+    // Resync gate: only when the player auto-advanced naturally
+    // (no pending user-mutation reason AND DidPlayToEndTime fired).
+    //
+    // Two gates AND-ed together because each catches a distinct
+    // wrong-resync vector:
+    //
+    // 1. `didPlayToEndPending`: chain-advance bounces during a
+    //    `removeAllItems` + insert rebuild do NOT fire the notification,
+    //    so this gate excludes those.
+    // 2. `pendingUserMutation`: a paused-state queue mutation
+    //    (skipToIndex, skipPrev, skipNext via fullRebuild) under FB9221518
+    //    can fire `AVPlayerItemDidPlayToEndTime` for an item being
+    //    pulled from the queue. Without this gate the fired
+    //    notification lands at the post-mutation `\.currentItem` KVO
+    //    main hop, sees `didPlayToEndPending == true`, and resyncs
+    //    `currentTrackIndex` to whatever AVQueuePlayer's
+    //    not-yet-published `currentItem` resolves to — which can be
+    //    the pre-mutation item's queueItemId. The user-mutation pre-
+    //    write of `currentTrackIndex` is authoritative; the resync
+    //    must defer to it.
+    let pendingUserMutation = self.pendingTrackChangeReason != nil
+    let reason = self.pendingTrackChangeReason ?? .autoAdvance
+    self.pendingTrackChangeReason = nil
+    let endFired = self.didPlayToEndPending
+    self.didPlayToEndPending = false
+    if endFired && !pendingUserMutation {
+      if let derived = matchTrackIndex(forCurrentItem: self.player?.currentItem) {
+        self.currentTrackIndex = derived
+      }
+    }
+    return reason
+  }
+
+  /// Fire `trackChangeListeners` for the current `(track, idx,
+  /// reason)`, deduped on `lastEmittedQueueItemId` (NOT idx — index
+  /// alone would suppress setQueue replacements that keep cur=0 with
+  /// a different first track). On a real fire, also resets the
+  /// error-dedup state so a new item's identical-coded error fires.
+  private func dispatchTrackChange(reason: TrackChangeReason) {
+    let idx = self.currentTrackIndex
+    let track: TrackItem? = (idx >= 0 && idx < self.tracks.count)
+      ? self.tracks[idx] : nil
+    let currentItemId: String? = self.queueItemIds[safe: idx]
+    let cache = self.lookaheadCache
+    self.currentTrackSource = TrackPlayer.classifyTrackSource(url: track?.url) { url in
+      cache?.isFullyCached(url: url) ?? false
+    }
+    if self.lastEmittedQueueItemId != currentItemId {
+      self.lastEmittedQueueItemId = currentItemId
+      self.lastErrorQueueItemId = nil
+      self.lastErrorCode = nil
+      // A real track (re)loaded => no longer at the end of the queue. At true
+      // end-of-queue this block is skipped entirely — the last-track id still
+      // matches `lastEmittedQueueItemId` — so the latch survives; the `idx >= 0`
+      // guard only keeps an explicit clear to index -1 from touching it.
+      if idx >= 0 { self.reachedQueueEnd = false }
+      // New active track => new milestone playthrough. This is the single
+      // deduped track-change point (the crossfade fade-start echo collapses
+      // here), so it resets exactly once per real track change.
+      self.milestoneTracker.reset()
+      // New track => its initial load counts as `buffering` (not `stalled`)
+      // until it reaches a playing state, and it starts not-fully-buffered.
+      self.hasStartedPlaying = false
+      self.recomputeFullyBuffered()
+      // Measure the gapless auto-advance silence gap (nil for every
+      // other transition) before the emit so it rides on onTrackChange
+      // as `transitionGapMs`. The timestamp was captured at the top of
+      // handleCurrentItemDidChange, above this method's synchronous lib
+      // work; falls back to now() if the snapshot wasn't taken.
+      var transitionGapMs: Double? = nil
+      if reason == .autoAdvance && self.gaplessGapPrevEndedAtNs > 0 {
+        let now = self.gaplessGapMeasuredAtNs > 0
+          ? self.gaplessGapMeasuredAtNs
+          : DispatchTime.now().uptimeNanoseconds
+        let gapNs = now &- self.gaplessGapPrevEndedAtNs
+        transitionGapMs = Double(gapNs) / 1_000_000.0
+        self.gaplessGapPrevEndedAtNs = 0
+        self.gaplessGapMeasuredAtNs = 0
+        #if DEBUG
+        self.gaplessLogLastChangedAtNs = now
+        NSLog("[RNQP-GAPLESS] item-changed trackIdx=%d ts_ns=%llu delta_since_ended_ms=%.3f",
+              idx, now, transitionGapMs ?? 0)
+        #endif
+      }
+      // Cross-platform listener-fire order: track-change first so the
+      // consumer's track-keyed handlers run before the format-refresh
+      // emits null. Matches Android's onMediaItemTransition →
+      // refreshNowPlayingFormatForActiveItem ordering.
+      trackChangeListeners.forEach { $0(track, Double(idx), reason, transitionGapMs) }
+      // Mirror the active track into a static cache so SiriKit intent
+      // handlers can read a "current track" seed without crossing back
+      // into JS. Nil-out happens on queue-end via the same dispatch
+      // path (track == nil).
+      TrackPlayer.cachedCurrentTrack = track
+      self.refreshNowPlayingFormatForActiveItem()
+      self.nowPlayingInfo.refreshAll()
+      // Kick the network resolve. The placeholder is already on the
+      // lock-screen via refreshAll; the resolver swaps in the real
+      // bitmap when the fetch lands. ArtworkResolver's single in-
+      // flight + last-URL guard drops a stale fetch if another track
+      // change fires before completion.
+      self.artworkResolver.resolve(url: track?.artworkUrl) { [weak self] image in
+        self?.nowPlayingInfo.applyArtwork(image)
+      }
+    }
+  }
+
+  /// Classify the active-track playback source. `nil` when the URL
+  /// is nil or its scheme is neither `file://` nor `http(s)://`
+  /// (e.g. `data:`, `blob:`, custom schemes — the lib has no contract
+  /// to honour for those today). `http(s)://` URLs split on whether
+  /// `isUrlCached` returns true (`.cached`) or false (`.streaming`).
+  /// `isUrlCached` is invoked at most once, only for `http(s)://` URLs.
+  internal static func classifyTrackSource(
+    url: String?, isUrlCached: (String) -> Bool
+  ) -> TrackSource? {
+    guard let url = url else { return nil }
+    if url.hasPrefix("file://") { return .local }
+    let isHttp = url.hasPrefix("http://") || url.hasPrefix("https://")
+    guard isHttp else { return nil }
+    return isUrlCached(url) ? .cached : .streaming
+  }
+
+  /// Queue-end detection — fires only when AVQueuePlayer has
+  /// auto-advanced past the last item: `currentItem == nil`,
+  /// `!tracks.isEmpty`, no mutation in flight. Under `.queue`
+  /// repeat mode synthesises a wrap-to-0 (mirroring Android
+  /// REPEAT_MODE_ALL); otherwise fires `queueEndListeners` + emits
+  /// `.ended` with reason `.queueEnd`.
+  ///
+  /// The wrap path resets `lastEmittedQueueItemId` so the
+  /// single-track .queue case re-fires `onTrackChange` (the
+  /// queueItemId at idx 0 is unchanged across the wrap; without
+  /// this clear the next dispatch would dedup-swallow the
+  /// re-emission).
+  private func detectQueueEnd() {
+    // Engine-aware "is the active item nil" check. With
+    // CrossfadeEngine `self.player` is nil by design — reading it
+    // alone would mis-detect every mid-play engine swap as
+    // queue-end and fire a spurious onQueueEnd + emitState(.ended).
+    let activeItemNil: Bool
+    if self.player != nil {
+      activeItemNil = self.player?.currentItem == nil
+    } else if let engine = self.engine {
+      activeItemNil = engine.currentMediaItem == nil
+    } else {
+      activeItemNil = true
+    }
+    guard activeItemNil && !self.tracks.isEmpty else { return }
+    if self.repeatModeState == .queue, self.player != nil {
+      self.currentTrackIndex = 0
+      self.pendingTrackChangeReason = .autoAdvance
+      self.lastEmittedQueueItemId = nil
+      self.performingMutation { self.fullRebuildPlayerQueue() }
+    } else {
+      self.reachedQueueEnd = true
+      queueEndListeners.forEach { $0() }
+      emitState(.ended, reason: .queueEnd)
+    }
+  }
+
+  /// Fires from the `addPeriodicTimeObserver` tick (gapless mode)
+  /// or the engine-agnostic `progressFallbackTimer` (crossfade
+  /// mode, where `self.player` is nil). Reports current position +
+  /// duration + seconds-buffered-ahead-of-position.
+  ///
+  /// The two paths source position differently: gapless reads off
+  /// `self.player.currentItem` directly; crossfade reads off
+  /// `engine.currentPositionSeconds` / `currentDurationSeconds` /
+  /// `bufferedPositionSeconds` (computed properties on the
+  /// engine surface that delegate to whichever leg is leading).
+  private func emitProgressIfSubscribed() {
+    guard !progressListeners.isEmpty else { return }
+    let position: TimeInterval
+    let duration: TimeInterval
+    let buffered: TimeInterval
+    // Whether the playhead is actively advancing. The throttle applies only
+    // while playing (the streaming firehose); a paused player's ticks are
+    // discrete (seek / stop / repeat-rewind) and must always deliver so the UI
+    // reflects the move — otherwise a paused seek under a >500ms interval is
+    // lost until playback resumes.
+    let isPlaying: Bool
+    if let item = self.player?.currentItem {
+      position = CMTimeGetSeconds(item.currentTime())
+      let rawDuration = CMTimeGetSeconds(item.duration)
+      duration = (rawDuration.isFinite && rawDuration > 0) ? rawDuration : 0.0
+      buffered = loadedAheadSeconds(for: item, currentPosition: position)
+      isPlaying = (self.player?.rate ?? 0) != 0
+    } else if let engine = self.engine {
+      // Engine-driven path (CrossfadeEngine): the fallback Timer fires
+      // unconditionally. While paused, emit ONLY when the playhead moved since
+      // the last emit (a seek / stop / repeat-rewind), mirroring the gapless
+      // periodic observer which fires once on seek completion even while
+      // paused — otherwise the post-stop "position reset to 0" tick never
+      // reaches consumers. A steady pause (position unchanged) still skips, so
+      // identical tuples aren't re-published every 0.5s.
+      position = engine.currentPositionSeconds
+      // Qualify Swift.abs: a bare `abs(...)` is ambiguous against Darwin's
+      // C `abs` when that's in scope (the library build context), so name
+      // the Swift overload explicitly — matches BiquadCoefficients.
+      let playheadDelta = Swift.abs(position - self.lastEmittedCrossfadePosition)
+      let moved = playheadDelta > 0.001
+      guard engine.isPlaying || moved else { return }
+      self.lastEmittedCrossfadePosition = position
+      duration = engine.currentDurationSeconds
+      let bufferedAbs = engine.bufferedPositionSeconds
+      buffered = max(0, bufferedAbs - position)
+      isPlaying = engine.isPlaying
+    } else {
+      return
+    }
+    let safePosition = position.isFinite ? position : 0.0
+    let safeDuration = duration.isFinite ? duration : 0.0
+    let progress = PlayerProgress(
+      position: safePosition, duration: safeDuration, buffered: buffered)
+    // Throttle only the playing firehose; paused ticks (discrete seek/stop
+    // results) always deliver. The crossfade movement bookkeeping above already
+    // ran this tick, and milestones + buffer state are separate calls, so both
+    // stay full-rate regardless of the throttle.
+    guard !isPlaying || self.progressEmissionGate.shouldEmit(nowMs: self.monotonicNowMs()) else {
+      return
+    }
+    progressListeners.forEach { $0(progress) }
+  }
+
+  /// Advance the milestone tracker off the same periodic tick and emit any
+  /// 25/50/75/90% thresholds forward playback just crossed. Runs the
+  /// tracker even with no subscribers (so a mid-stream subscribe doesn't
+  /// retroactively fire already-passed thresholds); emission is gated on
+  /// having listeners.
+  private func processMilestones() {
+    // No active track => nothing to attribute a milestone to (mirrors the
+    // Android guard; avoids emitting with trackIndex -1 on a stale read
+    // during a clear / queue-end transition).
+    guard !self.tracks.isEmpty, self.currentTrackIndex >= 0 else { return }
+    let position: TimeInterval
+    let playerDuration: TimeInterval
+    if let item = self.player?.currentItem {
+      position = CMTimeGetSeconds(item.currentTime())
+      let raw = CMTimeGetSeconds(item.duration)
+      playerDuration = (raw.isFinite && raw > 0) ? raw : 0
+    } else if let engine = self.engine {
+      position = engine.currentPositionSeconds
+      playerDuration = engine.currentDurationSeconds
+    } else {
+      return
+    }
+    guard position.isFinite else { return }
+    let duration = effectiveMilestoneDuration(playerDuration: playerDuration)
+    let crossed = milestoneTracker.tick(durationSec: duration, positionSec: position)
+    guard !crossed.isEmpty, !milestoneListeners.isEmpty else { return }
+    let idx = Double(self.currentTrackIndex)
+    for m in crossed {
+      milestoneListeners.forEach { $0(Double(m), idx) }
+    }
+  }
+
+  /// Player-reported duration when known (> 0), else the consumer-supplied
+  /// `TrackItem.duration` (seconds) for the active track, else 0 (no
+  /// computable duration → no milestones).
+  private func effectiveMilestoneDuration(playerDuration: TimeInterval) -> TimeInterval {
+    if playerDuration > 0 { return playerDuration }
+    let idx = self.currentTrackIndex
+    if idx >= 0, idx < self.tracks.count, let d = self.tracks[idx].duration, d > 0 {
+      return d
+    }
+    return 0
+  }
+
+  /// Map an `AVPlayerItem` back to an index in `self.tracks`.
+  ///
+  /// Lookup is keyed on the lib-generated `queueItemId`
+  /// associated-object set by `AVQueueBuilder.makeItem` at
+  /// construction. `self.queueItemIds` is a parallel `[String]`
+  /// array maintained 1:1 with `self.tracks` at every queue
+  /// mutation site; `firstIndex(of:)` resolves the AVPlayerItem's
+  /// `queueItemId` to its position in O(N) — N is queue size,
+  /// typical < 100 tracks, no memoization warranted.
+  ///
+  /// queueItemId is unique per construction, so each AVPlayerItem
+  /// maps to exactly one queue position even when the consumer
+  /// supplies the same `track.url` at multiple positions.
+  ///
+  /// Returns nil when `item` is nil, when the item lacks a
+  /// queueItemId (e.g. constructed outside `AVQueueBuilder` —
+  /// shouldn't happen in production), or when the queueItemId
+  /// isn't in `self.queueItemIds` (post-mutation desync — also
+  /// shouldn't happen, but defensive). The caller leaves
+  /// `currentTrackIndex` unchanged on a nil result.
+  private func matchTrackIndex(forCurrentItem item: AVPlayerItem?) -> Int? {
+    guard let id = item?.queueItemId else { return nil }
+    return self.queueItemIds.firstIndex(of: id)
+  }
+
+  /// Compute "seconds buffered ahead of position" — consumers use
+  /// this for the "buffered track" overlay on a progress bar. Takes
+  /// the end of the last loaded `CMTimeRange`, subtracts the current
+  /// position, and clamps to zero. Returns 0 when no ranges are
+  /// loaded or when the subtraction is non-finite.
+  private func loadedAheadSeconds(
+    for item: AVPlayerItem, currentPosition: Double
+  ) -> Double {
+    guard let last = item.loadedTimeRanges.last?.timeRangeValue else { return 0 }
+    let end = CMTimeGetSeconds(CMTimeAdd(last.start, last.duration))
+    guard end.isFinite, currentPosition.isFinite else { return 0 }
+    return max(0, end - currentPosition)
+  }
+
+  /// Recompute the current buffer state from the active engine item, advance
+  /// the per-track buffered high-water mark, and fire `onBufferStateChange`
+  /// when the discrete state actually changes. Runs on the buffer KVO, each
+  /// progress tick, the transport methods, and at track change.
+  ///
+  /// `.full` = keeps up (`playbackLikelyToKeepUp` / `playbackBufferFull`).
+  /// A not-full loaded item is `.stalled` when playback had started and is
+  /// intended (a mid-play rebuffer) or `.buffering` otherwise (initial load /
+  /// loading while paused). `.empty` means nothing is loaded to play.
+  private func recomputeBufferState() {
+    let computed: BufferState
+    if let item = self.engine?.currentMediaItem {
+      if item.isPlaybackLikelyToKeepUp || item.isPlaybackBufferFull {
+        computed = .full
+      } else {
+        computed = (self.hasStartedPlaying && self.wantsToPlay) ? .stalled : .buffering
+      }
+    } else {
+      computed = .empty
+    }
+    self.currentBufferState = computed
+    guard computed != self.lastEmittedBufferState else { return }
+    self.lastEmittedBufferState = computed
+    bufferStateListeners.forEach { $0(computed) }
+  }
+
+  /// The whole track has downloaded — the loaded range has reached the track's
+  /// duration. When the player can't report a duration (e.g. a transcoded
+  /// stream) it falls back to the consumer-supplied `track.duration`, the same
+  /// fallback milestones use. A live / indefinite source never completes.
+  /// (`isPlaybackBufferFull` is deliberately NOT used — it means the fixed
+  /// buffer is full, not that the whole track has downloaded.)
+  private func computeFullyBuffered() -> Bool {
+    guard let item = self.engine?.currentMediaItem else { return false }
+    if item.duration.isIndefinite { return false }
+    // A local file or a fully-cached source is entirely on disk — fully
+    // available regardless of the playback buffer.
+    if self.currentTrackSource == .local || self.currentTrackSource == .cached { return true }
+    var dur = CMTimeGetSeconds(item.duration)
+    if !dur.isFinite || dur <= 0 {
+      let idx = self.currentTrackIndex
+      guard idx >= 0, idx < self.tracks.count, let d = self.tracks[idx].duration, d > 0 else {
+        return false
+      }
+      dur = d
+    }
+    guard let last = item.loadedTimeRanges.last?.timeRangeValue else { return false }
+    let end = CMTimeGetSeconds(CMTimeAdd(last.start, last.duration))
+    return end.isFinite && end >= dur - Self.fullyBufferedEpsilonSeconds
+  }
+
+  /// Recompute fully-buffered and fire `onFullyBufferedChange` on a change.
+  /// Runs on the buffer-full KVO, the progress tick (the loaded range grows),
+  /// and at track change.
+  private func recomputeFullyBuffered() {
+    let computed = computeFullyBuffered()
+    self.currentFullyBuffered = computed
+    guard computed != self.lastEmittedFullyBuffered else { return }
+    self.lastEmittedFullyBuffered = computed
+    fullyBufferedListeners.forEach { $0(computed) }
+  }
+
+  /// Cap `target` at the current buffered extent when `clampSeekToBuffered`
+  /// is enabled and the target is past what has buffered. A local or fully-
+  /// buffered track reports `buffered >= duration >= target`, so nothing is
+  /// clamped and a seek reaches the end freely; a partly-buffered stream caps
+  /// at the downloaded edge. Reads the live buffered position (not a tracked
+  /// mark) so a seek-back that evicted the ahead-buffer clamps to what's there.
+  private func clampToBufferedIfEnabled(_ target: Double) -> Double {
+    guard self.config.clampSeekToBuffered == true else { return target }
+    guard let buffered = self.engine?.bufferedPositionSeconds, buffered.isFinite, buffered > 0 else {
+      return target
+    }
+    return target > buffered ? buffered : target
+  }
+
+  /// Translate `AVPlayer.timeControlStatus` into our `PlayerState`
+  /// enum and fire `onStateChange` when the value actually changed.
+  /// Consumes `pendingStateChangeReason` (set by transport methods
+  /// before they call `play`/`pause`/`stop`, or by the AudioSession
+  /// handlers for interruption/route-change events) so user-
+  /// initiated transitions are labelled correctly while purely
+  /// system-internal ones default to `.system`.
+  ///
+  /// `.buffering` is a system-internal intermediate state — it
+  /// shows up between `.paused` → `.playing` while AVPlayer fills
+  /// its buffer. We deliberately do NOT consume the pending reason
+  /// for `.buffering` so the reason survives to the terminal
+  /// `.playing` emit. Otherwise a play() after interruption would
+  /// label buffering `.interruption` and the actual `.playing` as
+  /// `.system`, which consumers won't expect.
+  private func emitStateChangeIfChanged() {
+    guard let engine = self.engine else { return }
+    let computed = PlayerStateDerivation.translate(
+      status: engine.timeControlStatus,
+      currentIndex: self.currentTrackIndex,
+      hasCurrentItem: engine.currentMediaItem != nil,
+      reachedQueueEnd: self.reachedQueueEnd
+    )
+    emitState(computed, reason: reasonForComputedState(computed))
+  }
+
+  /// Reason for a derived `PlayerState`, shared by the gapless KVO
+  /// (`emitStateChangeIfChanged`) and the crossfade delegate
+  /// (`engineStateMaybeChanged`) so both label states identically.
+  /// `.buffering` is intermediate — pass through as `.system` and leave the
+  /// pending reason for the terminal emit. `.ended` is always end-of-queue —
+  /// stamp `.queueEnd` to match `detectQueueEnd` / `enginePlaybackEnded`.
+  private func reasonForComputedState(_ computed: PlayerState) -> StateChangeReason {
+    if computed == .buffering {
+      return .system
+    }
+    if computed == .ended {
+      self.pendingStateChangeReason = nil
+      return .queueEnd
+    }
+    let reason = self.pendingStateChangeReason ?? .system
+    self.pendingStateChangeReason = nil
+    return reason
+  }
+
+  /// Bypass the timeControlStatus translation and emit a specific
+  /// state directly (used for `.ended` / `.error` which AVPlayer
+  /// doesn't model as timeControlStatus).
+  private func emitState(_ state: PlayerState, reason: StateChangeReason) {
+    // Playback (re)starting clears the end-of-queue latch — do this BEFORE the
+    // dedup guard so a redundant `.playing` re-emit still clears it.
+    if state == .playing { self.reachedQueueEnd = false }
+    guard state != self.lastReportedState else { return }
+    self.lastReportedState = state
+    // Once the track actually plays, a later not-full buffer is a mid-playback
+    // `stalled`, not the initial `buffering` load.
+    if state == .playing { self.hasStartedPlaying = true }
+    self.stateChangeListeners.forEach { $0(state, reason) }
+    self.nowPlayingInfo.refreshPositionAndRate()
+  }
+
+  /// Internal entry point for `CastEventBridge` to fan receiver-driven
+  /// state into the JS-facing event surface. Goes through the same
+  /// `emitState` dedup chokepoint as local-engine transitions, so JS
+  /// sees one event per real receiver transition regardless of source.
+  func emitRemoteState(_ state: PlayerState, reason: StateChangeReason) {
+    self.emitState(state, reason: reason)
+  }
+
+  /// Fan a cast receiver's position update to JS `onProgress` so the
+  /// consumer's player screen (progress bar / position / duration) tracks
+  /// the receiver while a remote session is active. The receiver reports
+  /// milliseconds; `PlayerProgress` is in seconds. Buffered arrives as an
+  /// absolute receiver position, so it's reduced to "ahead of position"
+  /// to match the local path's semantics. The local now-playing / format
+  /// path is untouched — the local engine is silent during cast.
+  func emitRemoteProgress(positionMs: Int64, durationMs: Int64, bufferedMs: Int64) {
+    guard !progressListeners.isEmpty else { return }
+    // Same throttle as the local tick, shared instance — a consumer's
+    // configured cadence caps cast progress too (the receiver pushes at its own
+    // rate, so the effective cadence is min(receiver rate, configured interval)).
+    guard self.progressEmissionGate.shouldEmit(nowMs: self.monotonicNowMs()) else { return }
+    let position = TimeInterval(max(0, positionMs)) / 1000.0
+    let duration = TimeInterval(max(0, durationMs)) / 1000.0
+    let buffered = TimeInterval(max(0, bufferedMs - positionMs)) / 1000.0
+    let progress = PlayerProgress(position: position, duration: duration, buffered: buffered)
+    progressListeners.forEach { $0(progress) }
+  }
+
+  /// Fan a cast receiver's track advance to JS `onTrackChange` and update
+  /// the authoritative `currentTrackIndex` so the consumer's player screen
+  /// follows the receiver's current track. Mirrors the local dispatch's
+  /// listener fire without the local-engine now-playing refresh (the cast
+  /// lockscreen is driven separately via `CastNowPlayingController`).
+  /// Called on the main thread from `CastEventBridge`, like `emitRemoteState`.
+  func emitRemoteTrackChange(index: Int) {
+    guard index >= 0, index < self.tracks.count else { return }
+    self.currentTrackIndex = index
+    let track = self.tracks[index]
+    self.trackChangeListeners.forEach { $0(track, Double(index), .autoAdvance, nil) }
+    // `currentTrackIndex` just moved — recompute skip capability so the
+    // receiver's advance updates canSkipPrevious/Next (skip-back enables
+    // once off the first track), same as every local index write.
+    self.recomputeCapabilities()
+  }
+
+  /// Hand off current local playback to a newly-connected cast receiver:
+  /// load the current queue at the current playhead with the current
+  /// play/pause, so playback continues where it was. The local engine is
+  /// silenced immediately (after the state read) so the device speaker
+  /// never overlaps the receiver. Async — the receiver load is a
+  /// round-trip; a failed load leaves local paused (never blasts audio).
+  func handoffCurrentPlaybackToCast() {
+    // Capture + pause synchronously (the cast-active transition fires on
+    // the main thread) so the resume seed lands before the async load
+    // below — a disconnect during the load round-trip then restores the
+    // captured local state instead of being left paused.
+    let snapshot = onMainSync { () -> HandoffSnapshot? in
+      let tracks = self.tracks
+      let idx = self.currentTrackIndex
+      let positionMs = Int64(max(0, (self.engine?.currentPositionSeconds ?? 0)) * 1000.0)
+      let playing = self.engine?.isPlaying ?? false
+      self.engine?.pause()
+      guard idx >= 0, idx < tracks.count else { return nil }
+      let items = tracks.compactMap { CastMediaItem.from(track: $0) }
+      guard items.count == tracks.count else { return nil }
+      return HandoffSnapshot(
+        items: items, startIndex: idx, positionMs: positionMs, playing: playing
+      )
+    }
+    guard let snapshot else { return }
+    castEventBridge.seedDeactivationSnapshot(
+      trackIndex: snapshot.startIndex,
+      positionMs: snapshot.positionMs
+    )
+    Task { [weak self] in
+      guard let self = self else { return }
+      let ids = try? await CastTransportRouter.routeSetQueue(
+        tracks: snapshot.items,
+        startIndex: snapshot.startIndex,
+        startPositionMs: snapshot.positionMs,
+        playWhenReady: snapshot.playing
+      )
+      // A non-nil result means the receiver load succeeded; seed the start
+      // track's lockscreen metadata. The current track is then tracked via
+      // the receiver's absolute queue index, not these itemIds.
+      if ids != nil {
+        await self.onMain {
+          self.castEventBridge.seedStartMetadata(startIndex: snapshot.startIndex)
+        }
+      }
+    }
+  }
+
+  private struct HandoffSnapshot {
+    let items: [CastMediaItem]
+    let startIndex: Int
+    let positionMs: Int64
+    let playing: Bool
+  }
+
+  /// Return local playback to the receiver's last track + position after
+  /// a cast session ends. The local engine kept the mirrored queue
+  /// (paused) during cast, so this seeks it to the handback point and
+  /// stays PAUSED — the user resumes locally. Never auto-blasts audio out
+  /// of the phone on disconnect. A `-1` trackIndex (receiver index never
+  /// resolved) is a no-op; local stays where it was.
+  func resumeLocalAfterCast(trackIndex: Int, positionMs: Int64) {
+    onMainSync {
+      guard trackIndex >= 0, trackIndex < self.tracks.count else { return }
+      let positionSec = max(0, Double(positionMs) / 1000.0)
+      self.currentTrackIndex = trackIndex
+      // Rebuild the local engine from the resumed absolute index. The
+      // engine was frozen at the cast-start index for the whole cast
+      // session, so its queue no longer matches `tracks[trackIndex...]`;
+      // a raw `engine.seek(toIndex: trackIndex)` would index the
+      // GaplessEngine's remaining-queue space (not the lib's absolute
+      // index) and seat the wrong item, leaving a later skipToIndex /
+      // play desynced from `currentTrackIndex`. The rebuild re-seats the
+      // current item at engine-index 0 so transport stays consistent.
+      self.performingMutation { self.fullRebuildPlayerQueue() }
+      // Seek within the freshly-seated current item to the receiver's
+      // last position (engine-index 0 is the current item post-rebuild).
+      if positionSec > 0 {
+        self.engine?.seek(toIndex: 0, position: positionSec)
+      }
+      // Stay paused — the user resumes locally; never auto-blast the
+      // phone speaker on revert.
+      self.engine?.pause()
+      self.pendingStateChangeReason = self.pendingStateChangeReason ?? .user
+      self.rescheduleLookahead()
+      self.recomputeCapabilities()
+    }
+  }
+
+  /// Real end-of-track signal. AVPlayerItemDidPlayToEndTime fires
+  /// when an item finishes playback naturally — NOT when
+  /// AVQueuePlayer chain-advances through unbuffered items during a
+  /// rebuild. The lib uses this distinction to:
+  ///
+  /// - Natural auto-advance: notification fires → set
+  ///   `didPlayToEndPending` → `handleCurrentItemDidChange` runs
+  ///   `matchTrackIndex` resync → `currentTrackIndex` updates to
+  ///   the auto-advanced position.
+  /// - Chain-advance bounce: notification does NOT fire (items
+  ///   weren't actually playing). `\.currentItem` KVO still fires
+  ///   from the rebuild's insert sequence, but
+  ///   `handleCurrentItemDidChange`'s gate sees
+  ///   `didPlayToEndPending == false` and skips the resync —
+  ///   `currentTrackIndex` stays at whatever the user mutation
+  ///   pre-wrote.
+  ///
+  /// Repeat-track handling: when `repeatModeState == .track`, seek
+  /// the just-finished item back to zero + replay. The notification
+  /// fires BEFORE AVQueuePlayer auto-advances (per Apple docs), so
+  /// we get the chance to rewind without flashing through the next
+  /// item. We do NOT set `didPlayToEndPending` in this branch —
+  /// the seek-to-zero produces no `\.currentItem` change, so there
+  /// is no auto-advance to gate.
+  @objc private func handlePlayerItemDidPlayToEndTime(_ notification: Notification) {
+    DispatchQueue.main.async { [weak self] in
+      guard let self else { return }
+      // Branch on repeat-track FIRST, separately from the
+      // currentItem === item check. The notification dispatches
+      // async to main but AVQueuePlayer
+      // runs `actionAtItemEnd = .advance` synchronously on its own
+      // queue — under load, the player can have already advanced
+      // by the time our async block runs. Falling through to the
+      // auto-advance branch in repeat-track mode would incorrectly
+      // arm `didPlayToEndPending`; the resync would then run on
+      // the unintended-advance currentItem and clobber the user's
+      // expected repeat-track stay-on-current.
+      if self.repeatModeState == .track {
+        // Repeat-track: rewind the just-finished item + replay.
+        // Apple's docs note the notification fires BEFORE
+        // actionAtItemEnd is honoured, so the seek-to-zero +
+        // play normally beats the auto-advance.
+        if let player = self.player {
+          // Repeat-one loop = a new milestone playthrough of the same track.
+          // The gapless engine fires no track-change / delegate here, so
+          // dispatchTrackChange's reset is skipped — reset directly, and
+          // UNCONDITIONALLY for the gapless engine (self.player non-nil), not
+          // only when the rewind race below is won: under load this async block
+          // can run AFTER AVQueuePlayer already chain-advanced, in which case
+          // the seek is skipped but the track still loops, so milestones must
+          // re-arm regardless. (CrossfadeEngine has self.player == nil here and
+          // resets via engineDidPlayItemToEnd instead — no double reset.)
+          self.milestoneTracker.reset()
+          if let item = notification.object as? AVPlayerItem,
+             player.currentItem === item {
+            item.seek(to: .zero, completionHandler: nil)
+            // Replay through the engine so the user's playback speed is
+            // restored (a raw AVPlayer.play() resets rate to 1.0).
+            self.engine?.play()
+          }
+        }
+        // If the rewind window was lost (player chain-advanced
+        // before our async block ran), accept that the
+        // KVO fire will re-sync currentTrackIndex via the next
+        // currentItem change — but DO NOT arm `didPlayToEndPending`
+        // here, because in repeat-track mode the auto-advance
+        // shouldn't have happened. The resync via KVO without
+        // didPlayToEndPending stays correct because user
+        // mutations pre-write the index; nothing overwrites the
+        // shadow index incorrectly.
+        return
+      }
+      // Repeat-off / repeat-queue: arm the resync gate so
+      // `handleCurrentItemDidChange` will run `matchTrackIndex`
+      // when the `\.currentItem` KVO fires for the next item.
+      self.didPlayToEndPending = true
+      let now = DispatchTime.now().uptimeNanoseconds
+      self.gaplessGapPrevEndedAtNs = now
+      #if DEBUG
+      self.gaplessLogLastEndedAtNs = now
+      NSLog("[RNQP-GAPLESS] item-ended trackIdx=%d ts_ns=%llu",
+            self.currentTrackIndex, now)
+      #endif
+    }
+  }
+
+  /// New `AVPlayerItem` access-log entries arrive multiple times per
+  /// second during streaming (per network transfer chunk). Two
+  /// concerns share the handler: the streaming-MP3 bitrate fallback
+  /// (re-resolves the now-playing format when the cache currently has
+  /// no bitrate) and DEBUG-only timeline logging.
+  ///
+  /// The fallback dedup key is the cached format's `bitrate` field —
+  /// once a non-null value lands, subsequent access-log fires for the
+  /// same item don't trigger a re-resolve. The active-item gate
+  /// (`item === self.player?.currentItem`) drops fires from items the
+  /// AVQueuePlayer has already advanced past; the
+  /// `nowPlayingFormatRequestGen` token inside
+  /// `refreshNowPlayingFormatForActiveItem` provides a second line of
+  /// defence against a stale resolve overwriting a newer item's format.
+  @objc private func handleNewAccessLogEntry(_ notification: Notification) {
+    DispatchQueue.main.async { [weak self] in
+      guard let self,
+            let item = notification.object as? AVPlayerItem else { return }
+      if item === self.activeMediaItem,
+         self.lastEmittedFormatItemId == ObjectIdentifier(item),
+         let format = self.lastEmittedFormat,
+         format.codec == .mp3 {
+        let hasBitrate: Bool = {
+          guard let variant = format.bitrate,
+                case .second = variant else { return false }
+          return true
+        }()
+        if !hasBitrate {
+          self.reresolveNowPlayingFormatForBitrate()
+        }
+      }
+      #if DEBUG
+      guard let event = item.accessLog()?.events.last else { return }
+      let now = DispatchTime.now().uptimeNanoseconds
+      let deltaSinceChangedMs = self.gaplessLogLastChangedAtNs > 0
+        ? (now &- self.gaplessLogLastChangedAtNs) / 1_000_000 : 0
+      NSLog("[RNQP-GAPLESS] access-log trackIdx=%d stalls=%ld observedBitrate=%lld transferDurationMs=%d numberOfMediaRequests=%ld delta_since_changed_ms=%llu",
+            self.currentTrackIndex,
+            event.numberOfStalls,
+            Int64(event.observedBitrate),
+            Int(event.transferDuration * 1000),
+            event.numberOfMediaRequests,
+            deltaSinceChangedMs)
+      #endif
+    }
+  }
+
+  #if DEBUG
+  /// Error-log entries surface alongside the existing
+  /// `AVPlayerItemFailedToPlayToEndTime` notification for a richer
+  /// diagnostic record. Compiled out in Release builds.
+  @objc private func handleNewErrorLogEntry(_ notification: Notification) {
+    DispatchQueue.main.async { [weak self] in
+      guard let self,
+            let item = notification.object as? AVPlayerItem,
+            let log = item.errorLog(),
+            let event = log.events.last else { return }
+      NSLog("[RNQP-GAPLESS] error-log trackIdx=%d errorDomain=%@ errorCode=%ld errorComment=%@",
+            self.currentTrackIndex,
+            event.errorDomain,
+            event.errorStatusCode,
+            event.errorComment ?? "nil")
+    }
+  }
+  #endif
+
+  @objc private func handlePlayerItemFailedToPlayToEndTime(_ notification: Notification) {
+    DispatchQueue.main.async { [weak self] in
+      guard let self else { return }
+      let underlying = notification.userInfo?[
+        AVPlayerItemFailedToPlayToEndTimeErrorKey] as? NSError
+      // Mid-play failures share the same dedup + retry path as
+      // load failures — both routed through `dispatchErrorOrRetry`.
+      // Real-world repro showed 4× identical AVFoundation "Cannot
+      // Open" fires from this notification firing repeatedly when
+      // the player is in a wedged state; the dedup gate suppresses
+      // them, the retry path attempts recovery before surfacing.
+      let item = notification.object as? AVPlayerItem ?? self.player?.currentItem
+      self.dispatchErrorOrRetry(item: item, underlying: underlying)
+    }
+  }
+
+  /// Construct a richly-populated `PlaybackError` from an underlying
+  /// `NSError` + the already-mapped standardized code. Centralised so
+  /// every iOS error fire site produces the same shape (sanitised
+  /// `nativeMessage`, consistent `fatal` classifier, etc.). Mirrors
+  /// `PlaybackErrorMapping.kt#buildPlaybackError` on Android.
+  ///
+  /// `nativeDomainOverride` replaces the underlying `NSError.domain`
+  /// on the emitted error — used by lib-defined error categories
+  /// (`PLAYER_ITEM_LOAD_FAILED`, `AUDIO_SESSION_*`,
+  /// `AUDIO_SESSION_INTERRUPTION_*`) that need a stable
+  /// SCREAMING_SNAKE_CASE marker for JS branching. Nil keeps the raw
+  /// underlying domain for callers that prefer the native string.
+  internal func buildPlaybackError(
+    _ underlying: NSError?,
+    mapped: PlaybackErrorCode,
+    queueItemId: String = "",
+    url: String = "",
+    nativeDomainOverride: String? = nil
+  ) -> PlaybackError {
+    let nativeCode = underlying?.code ?? 0
+    let nativeDomain = nativeDomainOverride ?? (underlying?.domain ?? "")
+    let nativeMessage = PlaybackErrorMapping.stripQuery(
+      underlying?.localizedDescription ?? ""
+    )
+    return PlaybackError(
+      code: mapped,
+      message: PlaybackErrorMapping.messageFor(mapped),
+      fatal: !PlaybackErrorMapping.isTransient(mapped),
+      nativeCode: Double(nativeCode),
+      nativeDomain: nativeDomain,
+      nativeMessage: nativeMessage,
+      queueItemId: queueItemId,
+      url: url
+    )
+  }
+
+  // MARK: - Auto-retry + stuck-recovery
+
+  /// Lib-clamped auto-retry budget. Reads from `config.autoRetries`,
+  /// defaults to 3, clamps to [0, 5]. Called from `setQueue` /
+  /// `addToQueueBody` to populate `retryAttemptsRemaining`.
+  ///
+  /// Non-finite (NaN / ±Infinity) inputs from JS would trap at
+  /// `Int(Double.nan)` — Swift's Int initialiser preconditionFails
+  /// rather than rounding to 0 like Kotlin. Mirror Android's
+  /// `coerceIn` behaviour by gating on `isFinite` first.
+  internal func effectiveAutoRetries() -> Int {
+    guard let raw = self.config.autoRetries, raw.isFinite else { return 3 }
+    return max(0, min(5, Int(raw)))
+  }
+
+  /// Lib-clamped retry backoff in milliseconds. Reads from
+  /// `config.retryBackoffMs`, defaults to 500, clamps to [200, 5000].
+  /// Floor at 200ms prevents retry storms against misbehaving servers
+  /// (e.g. 503 with `Retry-After: 0`). Same `isFinite` gate as
+  /// `effectiveAutoRetries`.
+  internal func effectiveRetryBackoffMs() -> Int {
+    guard let raw = self.config.retryBackoffMs, raw.isFinite else { return 500 }
+    return max(200, min(5000, Int(raw)))
+  }
+
+  // MARK: - Progress-emission throttle
+
+  /// Monotonic clock in milliseconds for the progress-emission throttle.
+  /// `systemUptime` is monotonic and needs no extra framework import.
+  private func monotonicNowMs() -> Double {
+    ProcessInfo.processInfo.systemUptime * 1000
+  }
+
+  /// Foreground `onProgress` cadence in ms. Reads
+  /// `config.progressUpdateIntervalMs`, defaults to 500, floors at the 500 ms
+  /// native tick rate, and ignores non-finite / non-positive inputs.
+  private func effectiveForegroundProgressIntervalMs() -> Double {
+    guard let raw = self.config.progressUpdateIntervalMs, raw.isFinite, raw > 0 else { return 500 }
+    return max(500, raw)
+  }
+
+  /// Background `onProgress` cadence in ms. Reads
+  /// `config.backgroundProgressUpdateIntervalMs`, defaults to the effective
+  /// foreground value (⇒ no background reduction), floors at 500, ignores
+  /// non-finite / non-positive inputs.
+  private func effectiveBackgroundProgressIntervalMs() -> Double {
+    let foreground = effectiveForegroundProgressIntervalMs()
+    guard let raw = self.config.backgroundProgressUpdateIntervalMs, raw.isFinite, raw > 0 else {
+      return foreground
+    }
+    return max(500, raw)
+  }
+
+  /// Push the configured foreground + background cadences into the throttle.
+  /// Called on every `configure()`; the gate preserves its runtime state.
+  private func applyProgressEmissionIntervals() {
+    self.progressEmissionGate.setIntervals(
+      foregroundMs: effectiveForegroundProgressIntervalMs(),
+      backgroundMs: effectiveBackgroundProgressIntervalMs(),
+      samplerPeriodMs: Self.progressIntervalSeconds * 1000)
+  }
+
+  /// Observe app background/foreground so the throttle can switch cadence.
+  /// Idempotent — a no-op when already installed. Seeds the current state so a
+  /// `configure()` issued while already backgrounded starts throttled.
+  private func installAppLifecycleObservers() {
+    guard appLifecycleObservers.isEmpty else { return }
+    self.progressEmissionGate.setBackgrounded(
+      UIApplication.shared.applicationState == .background)
+    let center = NotificationCenter.default
+    appLifecycleObservers.append(
+      center.addObserver(
+        forName: UIApplication.didEnterBackgroundNotification,
+        object: nil, queue: .main
+      ) { [weak self] _ in
+        self?.progressEmissionGate.setBackgrounded(true)
+      })
+    appLifecycleObservers.append(
+      center.addObserver(
+        forName: UIApplication.willEnterForegroundNotification,
+        object: nil, queue: .main
+      ) { [weak self] _ in
+        self?.progressEmissionGate.setBackgrounded(false)
+      })
+  }
+
+  /// Remove the app-lifecycle observers registered by
+  /// `installAppLifecycleObservers`. Idempotent.
+  private func removeAppLifecycleObservers() {
+    let center = NotificationCenter.default
+    appLifecycleObservers.forEach { center.removeObserver($0) }
+    appLifecycleObservers.removeAll()
+  }
+
+  /// Try to recover from a transient failure by rebuilding the
+  /// AVQueuePlayer items at the current position. Called from
+  /// `handleCurrentItemFailedToLoad` / `handlePlayerItemFailedToPlayToEndTime`
+  /// (auto-retry) AND from `play()` (one-shot stuck-recovery).
+  ///
+  /// Implementation: `fullRebuildPlayerQueue` with the current index
+  /// unchanged — it does `removeAllItems()` + reinserts fresh
+  /// AVPlayerItems via `AVQueueBuilder.makeItem(...)` using the
+  /// existing `queueItemIds` (so dedup keys remain stable). Position
+  /// is reset to 0 (mid-play failures lose position; matches RNTP
+  /// fork's `recreateAVPlayer` behaviour).
+  internal func retryFailedItem(queueItemId qid: String) {
+    guard let player = self.player else { return }
+    // Verify the failed item is still the current one. A subsequent
+    // user skip / queue mutation could have moved past it; in that
+    // case the retry is moot.
+    guard let idx = self.queueItemIds.firstIndex(of: qid),
+          idx == self.currentTrackIndex else { return }
+    self.performingMutation { self.fullRebuildPlayerQueue() }
+    // Resume playback if not already playing. Through the engine so the
+    // user's playback speed is restored (a raw AVPlayer.play() resets
+    // rate to 1.0).
+    if player.timeControlStatus != .playing {
+      self.engine?.play()
+    }
+  }
+
+  /// Run `body` on the main thread synchronously and return its
+  /// value. Short-circuits when already on main so consumers calling
+  /// from main don't deadlock. Used by Nitro getters + listener
+  /// register/dispose paths that aren't Promise-wrapped and run on
+  /// whatever thread the JS bridge uses.
+  private func onMainSync<T>(_ body: () -> T) -> T {
+    if Thread.isMainThread { return body() }
+    return DispatchQueue.main.sync(execute: body)
+  }
+
+  // MARK: - Automotive / voice handler registration
+
+  /// Atomically replace the cached `BrowseSnapshot` on the
+  /// process-wide [CarPlayCoordinator]. The data provider posts a
+  /// `didUpdateNotification` on the main queue; an active CarPlay
+  /// scene observes the notification + rebuilds the root template
+  /// against the new snapshot. Push semantics — most-recent call
+  /// wins. Safe to call before a CarPlay scene attaches: the
+  /// snapshot is cached on the coordinator + the next scene reads
+  /// it directly at didConnect.
+  func setBrowseSnapshot(snapshot: BrowseSnapshot) throws {
+    CarPlayCoordinator.shared.dataProvider.setSnapshot(snapshot)
+  }
+
+  func onBrowseRequest(
+    callback: @escaping (_ parentId: String) -> Promise<Promise<[BrowseItem]>>
+  ) throws -> () -> Void {
+    return CarPlayCoordinator.shared.bridge.registerOnBrowseRequest(callback)
+  }
+
+  // `onSearchRequest` is Android-only — CarPlay audio-entitled apps
+  // cannot legally present `CPSearchTemplate` (per the CarPlay App
+  // Programming Guide template-by-category rules); pushing or
+  // presenting it raises NSInvalidArgumentException at runtime. Apple
+  // Music + Spotify both dropped CarPlay search in iOS 26; the
+  // canonical CarPlay search affordance for audio apps is Siri via
+  // SiriKit's `INPlayMediaIntent`, not an in-app search template.
+  //
+  // `onPlayFromSearchRequest` IS wired on iOS — it serves the
+  // SiriKit `INPlayMediaIntent` path: Siri parses "Hey Siri play X
+  // on MyApp" into a structured `INMediaSearch`, the lib's
+  // `PlayMediaIntentHandler` maps it to `MediaSearchRequest`, and
+  // dispatches into this callback via `CarPlayBridge`.
+  //
+  // For `onSearchRequest` we accept the consumer's registration on
+  // iOS to keep the TS API shape cross-platform; the callback is
+  // discarded (`_ = callback` consumes the value), and the returned
+  // disposer is a no-op so the consumer's bookkeeping stays sane.
+  func onSearchRequest(
+    callback: @escaping (_ query: String) -> Promise<Promise<[BrowseItem]>>
+  ) throws -> () -> Void {
+    _ = callback
+    return {}
+  }
+
+  func onPlayFromSearchRequest(
+    callback: @escaping (_ request: MediaSearchRequest) -> Promise<Promise<[TrackItem]>>
+  ) throws -> () -> Void {
+    return CarPlayCoordinator.shared.bridge.registerOnPlayFromSearchRequest(callback)
+  }
+
+  func onPlayFromIdRequest(
+    callback: @escaping (_ mediaId: String) -> Promise<Promise<[TrackItem]>>
+  ) throws -> () -> Void {
+    return CarPlayCoordinator.shared.bridge.registerOnPlayFromIdRequest(callback)
+  }
+
+  // Donation Hybrid method — fire-and-forget into Siri's vocabulary
+  // donation pipeline. Real impl lives in `ios/Siri/VoiceDonation.swift`.
+  // Uses `INVocabulary.setVocabularyStrings(_:of:)` to seed Siri's NLU
+  // with the consumer's artist + playlist names.
+  func donateVoiceVocabulary(vocabulary: VoiceVocabulary) throws {
+    VoiceDonation.donateVoiceVocabulary(vocabulary)
+  }
+
+  func onCarConnect(callback: @escaping () -> Void) throws -> () -> Void {
+    return CarPlayCoordinator.shared.bridge.registerOnCarConnect(callback)
+  }
+
+  // `onServiceReady` is an Android-only signal. iOS apps die fully
+  // under memory pressure (no separate service lifecycle), so there's
+  // no `service-reborn` scenario to surface here. The lib accepts the
+  // registration to keep the cross-platform API shape consistent and
+  // returns a no-op disposer; the callback is consumed (so it isn't
+  // retained) and never invoked. Consumers writing for both platforms
+  // register one handler; on iOS only `onCarConnect` carries the
+  // equivalent "automotive surface available" signal.
+  func onServiceReady(
+    callback: @escaping (_ reason: ServiceReadyReason) -> Void
+  ) throws -> () -> Void {
+    _ = callback
+    return {}
+  }
+
+  func onCarDisconnect(callback: @escaping () -> Void) throws -> () -> Void {
+    return CarPlayCoordinator.shared.bridge.registerOnCarDisconnect(callback)
+  }
+
+  // MARK: - Lookahead cache — runtime config + status surface
+  func setLookaheadCache(config: LookaheadCacheConfig) throws -> Promise<Void> {
+    return Promise<Void>.async {
+      // Lift-throw across the non-throwing `onMain` closure: capture
+      // any error inside, re-throw after the main-hop completes so JS
+      // sees `[QP_EVICTION_UNSUPPORTED]` (or other validation
+      // failures) as a Promise rejection rather than silent no-op.
+      var caught: Error?
+      await self.onMain {
+        do {
+          try self.applyLookaheadConfig(config)
+        } catch {
+          caught = error
+        }
+      }
+      if let error = caught { throw error }
+    }
+  }
+
+  func getLookaheadCacheStatus() throws -> CacheStatus {
+    // Synchronous read — must hop to main since the cache + prefetcher
+    // were built there. `DispatchQueue.main.sync` deadlocks if called
+    // from main; the Thread guard short-circuits that path.
+    if Thread.isMainThread {
+      return buildCacheStatusSnapshot()
+    }
+    return DispatchQueue.main.sync { self.buildCacheStatusSnapshot() }
+  }
+
+  func clearLookaheadCache() throws -> Promise<Void> {
+    return Promise<Void>.async {
+      await self.onMain {
+        // Cancel any in-flight prefetch + drop everything on disk.
+        // We deliberately do NOT call rescheduleLookahead() here —
+        // an immediate refill makes `clearLookaheadCache` impossible
+        // to observe at zero from JS, and "clear" semantically means
+        // "wipe and stop" (the consumer can re-trigger prefetch by
+        // calling setLookaheadCache, skipToIndex, or setQueue again).
+        self.lookaheadCachePrefetcher?.cancel()
+        self.lookaheadCache?.clear()
+        self.emitCacheStatus()
+      }
+    }
+  }
+
+  func onCacheStatusChange(callback: @escaping (_ status: CacheStatus) -> Void) throws -> () -> Void {
+    // ListenerRegistry.add is internally serialized, so a JS consumer
+    // that does
+    //   const unsub = onCacheStatusChange(cb)
+    //   await setLookaheadCache(cfg)
+    // is guaranteed to see the post-config-change emit (the
+    // setLookaheadCache call synchronously crosses the bridge after
+    // the listener is in the registry).
+    let id = cacheStatusListeners.add(callback)
+    return { [weak self] in self?.cacheStatusListeners.remove(id: id) }
+  }
+
+  /// Returns the active item's runtime audio format, or the null variant
+  /// when nothing is currently playable / the format hasn't loaded yet.
+  /// `Variant_NullType_NowPlayingFormat` is Nitrogen's bridge for
+  /// `NowPlayingFormat | null` (`.first(.null)` = absent, `.second(format)` =
+  /// present). Cached by the async resolver; never blocks.
+  ///
+  /// An empty / out-of-range queue short-circuits to `.null` regardless
+  /// of the cache — the canonical-state branch below.
+  func getNowPlayingFormat() throws -> Variant_NullType_NowPlayingFormat {
+    return onMainSync {
+      // Lib canonical state takes precedence over the cached format.
+      // After `clearQueue` / queue-end the engine's `currentMediaItem`
+      // can briefly retain the last item; without this guard the read
+      // returns the prior track's stale codec / bitrate / duration
+      // even though `currentTrackIndex == -1` and the JS-facing state
+      // shows track == null.
+      if self.tracks.isEmpty
+        || self.currentTrackIndex < 0
+        || self.currentTrackIndex >= self.tracks.count {
+        return .first(.null)
+      }
+      // RG fields are read live from `AudioTapProvider`'s per-item
+      // cache so they surface as soon as the one-shot
+      // `MetadataReader` extract completes (sub-100 ms post queue
+      // load) — independently of the slow-path AVFoundation
+      // metadata/format-description loads that populate
+      // `lastEmittedFormat`'s codec/bitrate/duration fields.
+      let activeItem = self.activeMediaItem
+      let rgData = activeItem.flatMap { AudioTapProvider.shared.replayGainDataForItem($0) }
+      let rgActive = activeItem.map { AudioTapProvider.shared.replayGainActiveForItem($0) } ?? false
+      if let cached = self.lastEmittedFormat {
+        return .second(mergeRG(cached, rgData: rgData, rgActive: rgActive))
+      }
+      // No slow-path snapshot yet. Surface RG fields alone so
+      // consumers waiting on RG (e.g. visualisation, normalisation
+      // UI) don't have to wait for the AVAsset chain to complete.
+      // Non-RG fields fall through to their `.null` sentinels.
+      if rgData != nil {
+        return .second(NowPlayingFormat(
+          codec: .unknown,
+          container: .unknown,
+          mimeType: .first(.null),
+          sampleRate: .first(.null),
+          channelCount: .first(.null),
+          bitrate: .first(.null),
+          durationSec: .first(.null),
+          replayGainTrackDb: rgData?.trackGainDb.map { .second($0) } ?? .first(.null),
+          replayGainTrackPeak: rgData?.trackPeak.map { .second($0) } ?? .first(.null),
+          replayGainAlbumDb: rgData?.albumGainDb.map { .second($0) } ?? .first(.null),
+          replayGainAlbumPeak: rgData?.albumPeak.map { .second($0) } ?? .first(.null),
+          replayGainActive: rgActive,
+          ios: NowPlayingFormatIosExtras(bitsPerChannel: .first(.null)),
+          android: nil
+        ))
+      }
+      return .first(.null)
+    }
+  }
+
+  /// Replace the four RG fields of `cached` with live values from
+  /// the AudioTap. Non-RG fields are preserved as-is.
+  private func mergeRG(
+    _ cached: NowPlayingFormat,
+    rgData: ReplayGainData?,
+    rgActive: Bool
+  ) -> NowPlayingFormat {
+    return NowPlayingFormat(
+      codec: cached.codec,
+      container: cached.container,
+      mimeType: cached.mimeType,
+      sampleRate: cached.sampleRate,
+      channelCount: cached.channelCount,
+      bitrate: cached.bitrate,
+      durationSec: cached.durationSec,
+      replayGainTrackDb: rgData?.trackGainDb.map { .second($0) } ?? .first(.null),
+      replayGainTrackPeak: rgData?.trackPeak.map { .second($0) } ?? .first(.null),
+      replayGainAlbumDb: rgData?.albumGainDb.map { .second($0) } ?? .first(.null),
+      replayGainAlbumPeak: rgData?.albumPeak.map { .second($0) } ?? .first(.null),
+      replayGainActive: rgActive,
+      ios: cached.ios,
+      android: cached.android
+    )
+  }
+
+  /// Emit the current now-playing format to subscribers. Used by
+  /// the AudioTap RG-data-populated callback to push the updated
+  /// format without re-running `NowPlayingFormatExtractor`.
+  internal func emitCurrentNowPlayingFormat(for item: AVPlayerItem) {
+    guard let active = self.activeMediaItem,
+          ObjectIdentifier(active) == ObjectIdentifier(item) else { return }
+    let rgData = AudioTapProvider.shared.replayGainDataForItem(item)
+    let rgActive = AudioTapProvider.shared.replayGainActiveForItem(item)
+    if let cached = self.lastEmittedFormat {
+      let merged = mergeRG(cached, rgData: rgData, rgActive: rgActive)
+      self.lastEmittedFormat = merged
+      self.nowPlayingFormatListeners.forEach { $0(.second(merged)) }
+    }
+  }
+
+  func onNowPlayingFormatChange(
+    callback: @escaping (_ format: Variant_NullType_NowPlayingFormat?) -> Void
+  ) throws -> () -> Void {
+    let id = nowPlayingFormatListeners.add(callback)
+    return { [weak self] in self?.nowPlayingFormatListeners.remove(id: id) }
+  }
+
+  /// Bump the request generation, drop a stale cache (emitting null so
+  /// the JS consumer sees a loading state), and kick off the async
+  /// extractor for the current AVPlayerItem. Call sites: every
+  /// `\.currentItem` KVO transition + every `.readyToPlay` status flip
+  /// for the active item. When there is no current item, clears + emits
+  /// null and returns without launching a Task.
+  /// Engine-agnostic active-item accessor. Reads via the active
+  /// engine's `currentMediaItem` getter (works for GaplessEngine
+  /// AND CrossfadeEngine — `self.player` is nil during crossfade-
+  /// mode playback because that engine routes through dual private
+  /// AVPlayers). Falls back to `self.player?.currentItem` for paths
+  /// that pre-date the engine surface.
+  internal var activeMediaItem: AVPlayerItem? {
+    return self.engine?.currentMediaItem ?? self.player?.currentItem
+  }
+
+  internal func refreshNowPlayingFormatForActiveItem(force: Bool = false) {
+    self.nowPlayingFormatRequestGen &+= 1
+    let gen = self.nowPlayingFormatRequestGen
+
+    guard let item = self.activeMediaItem else {
+      if self.lastEmittedFormat != nil || self.lastEmittedFormatItemId != nil {
+        self.lastEmittedFormat = nil
+        self.lastEmittedFormatItemId = nil
+        nowPlayingFormatListeners.forEach { $0(.first(.null)) }
+      }
+      return
+    }
+    let itemId = ObjectIdentifier(item)
+
+    // Same item already resolved — no work, no emit. `force: true`
+    // bypasses this dedup; used by the AudioTapProvider RG-data-
+    // populated callback to refresh the snapshot once the async RG
+    // extract lands data that was unavailable on the initial
+    // resolve.
+    if !force, self.lastEmittedFormatItemId == itemId, self.lastEmittedFormat != nil {
+      return
+    }
+
+    // New (or different) item — drop stale cache + emit null so the
+    // JS consumer can show a loading state before the new format
+    // lands. Skip the null-emit when `force: true` and we're
+    // re-resolving the same item; a transient null in the middle of a
+    // stable item would needlessly flash a loading state.
+    if !force, self.lastEmittedFormat != nil {
+      self.lastEmittedFormat = nil
+      self.lastEmittedFormatItemId = nil
+      nowPlayingFormatListeners.forEach { $0(.first(.null)) }
+    }
+
+    Task { [weak self] in
+      let resolved = await NowPlayingFormatExtractor.extract(item: item)
+      await MainActor.run { [weak self] in
+        guard let self else { return }
+        guard self.nowPlayingFormatRequestGen == gen else { return }
+        // Drops fires from items the active engine has already
+        // advanced past during the await.
+        guard let current = self.activeMediaItem,
+              ObjectIdentifier(current) == itemId else { return }
+        guard let format = resolved else { return }
+        self.lastEmittedFormat = format
+        self.lastEmittedFormatItemId = itemId
+        self.nowPlayingFormatListeners.forEach { $0(.second(format)) }
+      }
+    }
+  }
+
+  /// Compare two `Variant_NullType_Double?` values for "is the bitrate
+  /// effectively the same". Treats `nil` and `.first(.null)` as
+  /// equivalent (both mean "no bitrate"); `.second(Double)` matches
+  /// only on IEEE-754 equality (Swift's `Double ==`). Value equality is
+  /// intentional — the extractor produces values from a small set of
+  /// integer-source feeds (Core Audio bitrate is `UInt32`, access-log
+  /// bitrate is a server-declared kbps figure) so equality holds across
+  /// repeated reads of the same underlying signal.
+  private func sameBitrateVariant(
+    _ a: Variant_NullType_Double?, _ b: Variant_NullType_Double?
+  ) -> Bool {
+    let aValue: Double? = {
+      guard let a = a, case .second(let v) = a else { return nil }
+      return v
+    }()
+    let bValue: Double? = {
+      guard let b = b, case .second(let v) = b else { return nil }
+      return v
+    }()
+    return aValue == bValue
+  }
+
+  /// Re-resolve the active item's now-playing format for the streaming-MP3
+  /// bitrate-fill path. The base `refreshNowPlayingFormatForActiveItem`
+  /// dedups on `(itemId, lastEmittedFormat != nil)` so re-running it for
+  /// the same item is a no-op; this entry point bypasses that dedup,
+  /// runs the extractor, and emits only when the resolved bitrate
+  /// actually differs from the cached value. Called from the access-log
+  /// notification handler when the active item is streaming MP3 with no
+  /// bitrate yet.
+  ///
+  /// `bitrateReresolveInFlight` early-returns when a previous call is
+  /// still resolving — access-log notifications fire many times per
+  /// second so without this gate every fire while the first extract is
+  /// running would spawn another detached Task. The active-item gate +
+  /// generation token + `lastEmittedFormatItemId` check still apply on
+  /// the completion side; the flag just suppresses redundant launches.
+  internal func reresolveNowPlayingFormatForBitrate() {
+    if self.bitrateReresolveInFlight { return }
+    guard let item = self.activeMediaItem else { return }
+    self.nowPlayingFormatRequestGen &+= 1
+    let gen = self.nowPlayingFormatRequestGen
+    let itemId = ObjectIdentifier(item)
+    self.bitrateReresolveInFlight = true
+
+    Task { [weak self] in
+      let resolved = await NowPlayingFormatExtractor.extract(item: item)
+      await MainActor.run { [weak self] in
+        guard let self else { return }
+        defer { self.bitrateReresolveInFlight = false }
+        guard self.nowPlayingFormatRequestGen == gen else { return }
+        guard let current = self.activeMediaItem,
+              ObjectIdentifier(current) == itemId else { return }
+        guard self.lastEmittedFormatItemId == itemId else { return }
+        guard let format = resolved else { return }
+        // Emit only on a meaningful change. Bitrate is the field this
+        // path exists to fill; comparing the variant tag handles both
+        // null→value transitions and value→value updates without
+        // pulling the wrapped Double into Equatable territory.
+        let prev = self.lastEmittedFormat
+        let bitrateChanged = !sameBitrateVariant(prev?.bitrate, format.bitrate)
+        if !bitrateChanged { return }
+        self.lastEmittedFormat = format
+        self.lastEmittedFormatItemId = itemId
+        self.nowPlayingFormatListeners.forEach { $0(.second(format)) }
+      }
+    }
+  }
+
+  /// Apply a runtime config update on main. Both runtime dimensions are
+  /// live (no configure() needed):
+  /// - `enabled` toggle: build/teardown the prefetcher against the cache
+  /// - `lookaheadCount` change: live update on the prefetcher
+  ///
+  /// Cache SIZE + eviction policy are NOT runtime dimensions — they are fixed
+  /// at `configure()` from `PlayerConfig` (kept consistent with Android, whose
+  /// SimpleCache is immutable after construction).
+  internal func applyLookaheadConfig(_ config: LookaheadCacheConfig) throws {
+    let previous = self.lookaheadConfig
+    self.lookaheadConfig = config
+
+    let enableChanged = config.enabled != previous.enabled
+    let countChanged = config.lookaheadCount != previous.lookaheadCount
+
+    if enableChanged {
+      rebuildCacheStack(config: config)
+    } else if config.enabled {
+      applyLiveConfigUpdates(config: config, countChanged: countChanged)
+    }
+
+    emitCacheStatus()
+  }
+
+  /// Configure-time cache disk budget in MB — `PlayerConfig.lookaheadCacheMaxSizeMb`
+  /// or the 100 MB default. Fixed at cache construction; reported read-only via
+  /// `getLookaheadCacheStatus().maxSizeMb`.
+  private func configuredCacheMaxSizeMb() -> Double {
+    self.config.lookaheadCacheMaxSizeMb
+      ?? Double(LookaheadCache.DEFAULT_MAX_SIZE_BYTES) / Double(LookaheadCache.BYTES_PER_MB)
+  }
+
+  /// Configure-time cache eviction policy — `PlayerConfig.lookaheadCacheEvictionPolicy`
+  /// or `.lru`. Fixed at cache construction; a change at `configure()` clears the
+  /// cache and rebuilds under the new policy (see `configure`).
+  private func configuredEvictionPolicy() -> EvictionPolicy {
+    self.config.lookaheadCacheEvictionPolicy ?? .lru
+  }
+
+  /// Quiesce or re-arm the cache + prefetcher pair when the
+  /// `enabled` flag flipped. Disable cancels in-flight prefetch +
+  /// quiesces the cache (URLSession STAYS alive — it is only
+  /// invalidated by full `destroy`). Enable rebuilds the prefetcher
+  /// (or constructs the pair from scratch on first enable) and
+  /// reschedules.
+  ///
+  /// Keeping the cache instance + URLSession alive across disable
+  /// avoids `Task created in a session that has been invalidated`
+  /// (Obj-C exception, uncatchable in Swift's `do-catch`) when a
+  /// prefetcher Task survived disable + tried to download against
+  /// a freshly-invalidated session before the dispatch barrier saw
+  /// the cancellation.
+  private func rebuildCacheStack(config: LookaheadCacheConfig) {
+    if !config.enabled {
+      lookaheadCachePrefetcher?.tearDown()
+      lookaheadCachePrefetcher = nil
+      lookaheadCache?.disable()
+      return
+    }
+    if lookaheadCache == nil {
+      // Size is fixed at construction from the configure-time budget.
+      lookaheadCache = LookaheadCache(
+        maxSizeBytes: LookaheadCache.maxBytes(forMb: configuredCacheMaxSizeMb()),
+        evictionPolicy: configuredEvictionPolicy()
+      )
+    } else {
+      lookaheadCache?.enable()
+    }
+    guard let cache = lookaheadCache else { return }
+    let prefetcher = LookaheadCachePrefetcher(
+      cache: cache,
+      configHeaders: self.config.httpHeaders,
+      configUserAgent: self.config.userAgent
+    )
+    prefetcher.defaultLookaheadCount = max(0, Int(config.lookaheadCount))
+    prefetcher.onTrackProcessed = { [weak self] in self?.emitCacheStatus() }
+    lookaheadCachePrefetcher = prefetcher
+    rescheduleLookahead()
+  }
+
+  /// Apply in-place config updates when the cache stack already exists
+  /// (no enable-flag change). Only `lookaheadCount` is a runtime dimension
+  /// now — it updates the prefetcher's default + reschedules. Cache size is
+  /// configure-time and never changes here.
+  private func applyLiveConfigUpdates(
+    config: LookaheadCacheConfig, countChanged: Bool
+  ) {
+    if countChanged {
+      lookaheadCachePrefetcher?.defaultLookaheadCount =
+        max(0, Int(config.lookaheadCount))
+      rescheduleLookahead()
+    }
+  }
+
+  /// Build a [CacheStatus] snapshot from current cache + prefetcher
+  /// state. Synchronous — caller must already be on main.
+  internal func buildCacheStatusSnapshot() -> CacheStatus {
+    let cache = self.lookaheadCache
+    let currentBytes = cache?.currentSizeBytes() ?? 0
+    // Queue-agnostic: count fully-cached entries in the cache itself,
+    // not the intersection with `self.tracks`. Mirrors the semantics
+    // of `currentSizeBytes` (total cache disk usage) and the
+    // prefetcher's `currentlyDownloadingUrl` (active downloads) — all
+    // three reflect cache state independent of any current queue.
+    // Per-track local/stream/cache attribution for the active queue
+    // is exposed via `getCurrentTrackSource()`.
+    let fullyCached = cache?.fullyCachedCount() ?? 0
+    let inFlight = lookaheadCachePrefetcher?.currentlyDownloadingUrl
+    return CacheStatus(
+      enabled: lookaheadConfig.enabled,
+      currentSizeMb: Double(currentBytes) / Double(LookaheadCache.BYTES_PER_MB),
+      maxSizeMb: configuredCacheMaxSizeMb(),
+      tracksFullyCached: Double(fullyCached),
+      currentlyCaching: inFlight.map { [$0] } ?? []
+    )
+  }
+
+  /// Fire the cache-status callback with a fresh snapshot. Caller
+  /// must already be on main.
+  internal func emitCacheStatus() {
+    guard !cacheStatusListeners.isEmpty else { return }
+    let snapshot = buildCacheStatusSnapshot()
+    cacheStatusListeners.forEach { $0(snapshot) }
+  }
+}
+
+// MARK: - PlaybackEngineDelegate
+
+/// `CrossfadeEngine` fires these callbacks; `GaplessEngine`'s
+/// equivalent surface continues to flow through `self.player`'s
+/// KVO chain installed by `installGaplessObservers` /
+/// `installEventObservers`. Each delegate method therefore runs
+/// only when the active engine is `CrossfadeEngine` (per the
+/// `delegate = self` wiring in `applyEngineSwapForMode`).
+extension TrackPlayer: PlaybackEngineDelegate {
+  func engineStateMaybeChanged(
+    _ engine: PlaybackEngine, reason: StateChangeReason?
+  ) {
+    if let reason {
+      // Engine-supplied classified reason takes precedence over
+      // any prior staked reason — match the gapless KVO path
+      // where pendingStateChangeReason is overwritten by the
+      // newer staked reason.
+      self.pendingStateChangeReason = reason
+    }
+    // The leading leg's `timeControlStatus` drives `.buffering` (load /
+    // rebuffer) and the end-of-queue latch drives `.ended`.
+    let computed = PlayerStateDerivation.translate(
+      status: engine.timeControlStatus,
+      currentIndex: self.currentTrackIndex,
+      hasCurrentItem: engine.currentMediaItem != nil,
+      reachedQueueEnd: self.reachedQueueEnd
+    )
+    emitState(computed, reason: reasonForComputedState(computed))
+  }
+
+  func engineIsPlayingChanged(_ engine: PlaybackEngine, isPlaying: Bool) {
+    // No-op — engineStateMaybeChanged already drives the
+    // PlayerState emit on every leg-state change; this method is
+    // here for delegate parity with the protocol so future
+    // diagnostics / progress wake-up hooks have a slot.
+    _ = engine
+    _ = isPlaying
+  }
+
+  func engineDidTransitionTrack(_ engine: PlaybackEngine) {
+    // Bring TrackPlayer's currentTrackIndex into sync with the
+    // engine's index — CrossfadeEngine.completeCrossfade
+    // increments engine.currentMediaItemIndex; on setItems / seek
+    // the engine's index is already aligned with the caller's
+    // resumeIndex.
+    //
+    // Crossfade post-swap echo: fade-start already fired
+    // `engineCrossfadeDidBegin` which dispatched the JS-facing
+    // track-change for the same incoming index. The
+    // `lastEmittedQueueItemId` dedup inside `dispatchTrackChange`
+    // turns the second call into a no-op. Capability + lookahead
+    // refresh still run unconditionally — both are idempotent and
+    // the second pass picks up any state that landed during the
+    // fade window.
+    // Skip the engine→canonical index sync during a queue mutation: the
+    // mutation already computed the authoritative currentTrackIndex via
+    // QueueMutationArithmetic, and the rebuild's setItems(startIndex: 0) on the
+    // `tracks[cur...]` slice would otherwise clobber it with the slice's
+    // engine-relative index 0. (CrossfadeEngine.setItems fires this delegate
+    // synchronously; GaplessEngine does not, so this only bit crossfade.)
+    let engineIdx = engine.currentMediaItemIndex
+    if !self.isMutatingPlayerQueue, engineIdx >= 0, engineIdx < self.tracks.count {
+      self.currentTrackIndex = engineIdx
+    }
+    let reason = self.pendingTrackChangeReason ?? .autoAdvance
+    self.pendingTrackChangeReason = nil
+    dispatchTrackChange(reason: reason)
+    self.recomputeCapabilities()
+    self.rescheduleLookahead()
+    // Refresh the now-playing format for the new active item. The crossfade
+    // engine's `\.tracks` KVO is `.new`-only and a forward skip rebuilds the
+    // incoming leg as a fresh AVPlayerItem whose tracks key isn't auto-loaded
+    // (only playable/duration are), so engineActiveItemFormatChanged may never
+    // fire for it — without this, getNowPlayingFormat() stays nil after a
+    // skip to a cached track. The extractor loads the format asynchronously
+    // and the lastEmittedFormatItemId dedup makes a redundant call a no-op.
+    self.refreshNowPlayingFormatForActiveItem()
+  }
+
+  func engineCrossfadeDidBegin(_ engine: PlaybackEngine, incomingIndex: Int) {
+    // Fade-start: the standby leg is now audibly playing (volume 0
+    // ramping up). Flip JS-facing active track + lock-screen / Now
+    // Playing surface to the incoming track immediately so the
+    // user sees the new track's title/artwork the moment they
+    // start hearing it. The leading leg continues fading out for
+    // the configured `crossfadeDurationMs`; engine accessors
+    // already prefer the standby leg while `fadeInFlight` is true.
+    //
+    // Reason is hardcoded `.autoAdvance` — fade-start is always an
+    // auto-advance event; any user-driven transition (skipToNext /
+    // skipToIndex / setMediaItems) would have called
+    // `cancelFadeInternal` first, so a stashed
+    // `pendingTrackChangeReason` here is stale and should not
+    // re-attribute the fade.
+    _ = engine
+    guard incomingIndex >= 0, incomingIndex < self.tracks.count else { return }
+    self.currentTrackIndex = incomingIndex
+    self.pendingTrackChangeReason = nil
+    dispatchTrackChange(reason: .autoAdvance)
+    self.recomputeCapabilities()
+    self.rescheduleLookahead()
+  }
+
+  func engineCrossfadeDidCancel(_ engine: PlaybackEngine, revertedIndex: Int) {
+    // Fade-cancelled mid-flight (pause / stop / focus loss /
+    // queue mutation). JS already received `onTrackChange(incoming,
+    // reason: .autoAdvance)` from the prior fade-start fire; the
+    // incoming track is no longer the active one. Revert
+    // `currentTrackIndex` to the leading-leg index and emit
+    // `onTrackChange(leading, reason: .crossfadeCancelled)` so
+    // consumer UI can rewind to the leading track.
+    _ = engine
+    guard revertedIndex >= 0, revertedIndex < self.tracks.count else { return }
+    self.currentTrackIndex = revertedIndex
+    self.pendingTrackChangeReason = nil
+    dispatchTrackChange(reason: .crossfadeCancelled)
+    self.recomputeCapabilities()
+    self.rescheduleLookahead()
+  }
+
+  func engineActiveItemFormatChanged(_ engine: PlaybackEngine) {
+    _ = engine
+    self.refreshNowPlayingFormatForActiveItem()
+    // Streaming-item audioMix catch-up for the crossfade engine
+    // (which fires this delegate hook on its own KVO chain). The
+    // gapless engine has a parallel catch-up path through
+    // `dispatchItemStatus(.readyToPlay)`; both call into
+    // `refreshActiveItemMixes`, which is idempotent on items that
+    // already carry a tap, so a double-fire is harmless.
+    AudioTapProvider.shared.refreshActiveItemMixes()
+  }
+
+  func engineDidFailWithError(_ engine: PlaybackEngine, error: Error) {
+    _ = engine
+    let underlying = error as NSError
+    dispatchErrorOrRetry(
+      item: nil,
+      underlying: underlying,
+      nativeDomainOverride: nil
+    )
+  }
+
+  func engineDidPlayItemToEnd(_ engine: PlaybackEngine) {
+    // CrossfadeEngine fires this on natural end-of-leading; the
+    // boundary signal that drives JS-facing track-change is
+    // engineDidTransitionTrack which fires immediately after.
+    //
+    // Under repeat-one the same track replays with no track-change (the
+    // queueItemId is unchanged, so dispatchTrackChange's dedup skips its
+    // reset). Each loop is a fresh playthrough, so re-arm the milestone
+    // tracker here for that case only.
+    if self.repeatModeState == .track {
+      self.milestoneTracker.reset()
+    }
+    _ = engine
+  }
+
+  func enginePlaybackEnded(_ engine: PlaybackEngine) {
+    _ = engine
+    if self.repeatModeState == .queue {
+      self.currentTrackIndex = 0
+      self.pendingTrackChangeReason = .autoAdvance
+      self.lastEmittedQueueItemId = nil
+      self.performingMutation { self.fullRebuildPlayerQueue() }
+      // The natural end stopped the player; the repeat-queue wrap must resume
+      // playback from the rebuilt track 0. Gapless's AVQueuePlayer kept its
+      // rate across the rebuild, but the crossfade rebuild's
+      // replaceCurrentItem resets the leading leg's rate to 0 — without this
+      // the queue wraps but sits paused.
+      self.engine?.play()
+    } else {
+      self.reachedQueueEnd = true
+      queueEndListeners.forEach { $0() }
+      emitState(.ended, reason: .queueEnd)
+    }
+  }
+}