react-native-queue-player 1.0.0

package/ios/CrossfadeEngine.swift

@@ -0,0 +1,1343 @@
+import AVFoundation
+import Foundation
+
+/// Dual-`AVPlayer` engine implementing equal-power crossfade at
+/// track boundaries.
+///
+/// Two `AVPlayer` instances rotate roles per fade: the leading
+/// leg is currently audible; the standby leg prerolls the next
+/// queue item ahead of the fade window and ramps up from silence
+/// as the leading ramps down.
+///
+/// Architecture (per platform research):
+/// - Single-item per `AVPlayer` (NOT `AVQueuePlayer`) so each
+///   leg's `AVMutableAudioMixInputParameters.setVolumeRamp` is
+///   independently scheduled. The lib-side queue model on
+///   `TrackPlayer` is the canonical position; the engine
+///   advances the standby leg's currentItem to the next queue
+///   position ahead of fade-start.
+/// - Equal-power curve approximated via N short linear
+///   `setVolumeRamp` sub-ramps. `setVolumeRamp` is linear-only
+///   per the AVFoundation API; ~50 sub-ramps over a fade window
+///   is auditorily indistinguishable from true `cos(t·π/2)` /
+///   `sin(t·π/2)`.
+/// - Standby preroll via `AVPlayer.preroll(atRate: 1.0)` ~500ms
+///   before fade-start so the audio output graph is hot when
+///   its volume ramp begins.
+/// - Backward seek through a scheduled ramp window corrupts the
+///   mix per Wade Tregaskis's `setVolumeRamp` findings —
+///   recovery is `audioMix = nil` + `volume = userVolume`.
+/// - Per-boundary route check via `OutputRouteMonitor`: if the
+///   active route is `.airPlay` / `.carAudio`, the boundary
+///   hard-cuts (no fade) for that transition. Mid-fade route
+///   change cancels the fade synchronously.
+///
+/// Runtime fade execution (multi-second `setVolumeRamp` schedule
+/// + standby promotion to leading at fade-end) is exercised at
+/// the demo-app integration layer; the engine's deterministic
+/// primitives (curve math, sub-ramp count, route classification,
+/// boundary fade-vs-cut decision) are unit-tested.
+final class CrossfadeEngine: PlaybackEngine {
+
+  // MARK: - Construction
+
+  /// User-set fade duration captured at construction time. Both
+  /// `AVAudioMix` ramp scheduling and the role-swap timer
+  /// coordinate against this value; runtime duration changes
+  /// require a fresh engine instance via `handoff`.
+  private let crossfadeDurationSeconds: TimeInterval
+
+  /// Pre-fade preroll lead so the standby leg's audio output
+  /// graph is hot when its first ramp starts. 500ms matches the
+  /// platform research recommendation.
+  static let prerollLeadSeconds: TimeInterval = 0.5
+
+  /// Equal-power approximation step count. ~50 sub-ramps over a
+  /// 6-second fade is below the audibility threshold for the
+  /// difference between staircased and continuous cos/sin.
+  static let subRampCount: Int = 50
+
+  /// Volume multiplier applied to both legs during the fade.
+  /// Tracked so manual `setVolume(v)` survives a subsequent
+  /// fade cancel / handoff.
+  private var userVolume: Float = 1.0
+
+  /// Tracked so the user's playback speed survives a crossfade
+  /// transition: the standby leg prerolls/plays at the configured
+  /// rate and is re-set to this when promoted to leading. Without it
+  /// every fade resets the rate to 1.0.
+  private var userPlaybackSpeed: Float = 1.0
+
+  /// Persisted pitch-correction mode, stamped as `audioTimePitchAlgorithm`
+  /// on both legs' items. The resolved algorithm depends on
+  /// `userPlaybackSpeed` (the intended rate), not the live leg rate
+  /// (0 while paused / on the silent standby).
+  private var pitchCorrectionMode: PitchCorrectionMode = .voice
+
+  weak var delegate: PlaybackEngineDelegate?
+
+  /// Owns the route monitor instead of relying on a shared one
+  /// — the engine starts/stops monitoring with its own
+  /// lifecycle.
+  private let routeMonitor: OutputRouteMonitor
+
+  // MARK: - Players
+
+  private let playerA: AVPlayer
+  private let playerB: AVPlayer
+
+  /// `true` when [leadingPlayer] is `playerA` (the engine's
+  /// first-built player). Flips on every fade-complete role
+  /// swap. Read by the test surface to verify role-swap
+  /// arithmetic without driving a real fade.
+  private(set) var currentRoleIsA: Bool = true
+
+  /// Leading leg — currently audible.
+  var leadingPlayer: AVPlayer { currentRoleIsA ? playerA : playerB }
+
+  /// Standby leg — prerolls the next queue item ahead of fade-start.
+  var standbyPlayer: AVPlayer { currentRoleIsA ? playerB : playerA }
+
+  // MARK: - Queue model
+
+  /// Engine-internal queue snapshot — caller sets via
+  /// `setItems`; engine advances `currentIndex` on user skip /
+  /// auto-advance. Each `AVPlayer` instance holds at most one
+  /// item from this list at a time.
+  private var queue: [AVPlayerItem] = []
+  private var currentIndex: Int = -1
+
+  /// Active repeat mode. AVPlayer has no native repeat, so the engine
+  /// implements repeat-one itself: it suppresses the look-ahead fade
+  /// and loops the current item on natural end (see `maybeArmCrossfade`
+  /// + `handleItemDidPlayToEnd`). `.queue` wrap is driven by TrackPlayer
+  /// rebuilding the queue, same as the gapless engine.
+  private var repeatMode: RepeatMode = .off
+
+  /// `true` while a fade ramp is scheduled / in flight.
+  private var fadeInFlight: Bool = false
+
+  /// Periodic-time-observer + the AVPlayer it was registered
+  /// against. `AVPlayer.removeTimeObserver` raises
+  /// `NSInvalidArgumentException` when called on a different
+  /// instance than the one that issued the token, so the player
+  /// is captured alongside the token. Removed on pause / stop /
+  /// seek / skip / role-swap / release; re-installed on play.
+  private var armingObserver: (player: AVPlayer, token: Any)?
+
+  /// `true` after [armCrossfade] has prerolled standby for the
+  /// upcoming fade.
+  private var standbyArmed: Bool = false
+
+  /// Wall-clock task that fires `completeCrossfade` after the
+  /// fade duration. Stored so `cancelFadeInternal` /
+  /// `release` can cancel it before a stale completion runs
+  /// against a fresh fade.
+  private var fadeCompletionTask: Task<Void, Never>?
+
+  /// Audio-mix provider supplied by `Equalizer` (and future
+  /// `Visualizer`). Per-AVPlayerItem `AVAudioMix` is built
+  /// per-item via the provider's `audioMix(for:)`.
+  private var mixProvider: AudioMixProvider?
+
+  /// Resolves a track's source URL to its lookahead-cache local file
+  /// URL when fully cached, else nil. Supplied by `TrackPlayer` (reads
+  /// `LookaheadCache.cachedURL(forUrl:)` lazily so it always sees the
+  /// current cache). The engine re-resolves at every late item attach
+  /// (skip cross-attach, fade-arm preroll) so a track that finished
+  /// caching AFTER its queue item was first built from the remote URL
+  /// is played from the local file — instead of re-loading the remote
+  /// asset, whose `.tracks` round-trip can fail the now-playing format
+  /// extractor.
+  private var cachedURLResolver: ((String) -> URL?)?
+
+  /// Released-once flag so `release()` is idempotent.
+  private var released: Bool = false
+
+  /// One-shot KVO on the standby `AVPlayer.status`. Set during
+  /// [armCrossfade] when `replaceCurrentItem` was just called and
+  /// the asset hasn't reached `.readyToPlay` yet — `preroll(atRate:)`
+  /// raises `NSInternalInconsistencyException` if invoked before
+  /// the status flip per `AVPlayer.h`. Invalidated on
+  /// [cancelFadeInternal] / [release] / when the readiness fires.
+  private var standbyReadyObserver: NSKeyValueObservation?
+
+  /// Wall-clock fallback used when standby never reaches
+  /// `.readyToPlay` (asset load failure / network error). Lets the
+  /// arm path bail cleanly instead of stranding `standbyArmed = true`
+  /// against a broken standby. 5s covers local + warm cache; for
+  /// streaming the consumer would have already failed by then via
+  /// the leading-leg error path.
+  private var standbyReadyTimeout: DispatchWorkItem?
+
+  /// Generation counter incremented at every [awaitStandbyReady]
+  /// entry. Closures captured by the KVO observer + the timeout
+  /// `DispatchWorkItem` carry their generation value — if a new
+  /// arm cycle increments the counter while a stale main-async
+  /// hop is pending, the gate inside the closure short-circuits.
+  /// Defends against a narrow race where the original arm's
+  /// `.readyToPlay` callback fires AFTER `cancelFadeInternal` +
+  /// a fresh `armCrossfade` re-flipped `standbyArmed` to true.
+  private var standbyReadyGen: Int = 0
+
+  // MARK: - Engine event observers
+
+  /// `\.timeControlStatus` KVO on the leading leg + the player it
+  /// was registered against. Re-installed on every role swap.
+  /// Fires `engineStateMaybeChanged` + `engineIsPlayingChanged`.
+  private var leadingTimeControlObserver: NSKeyValueObservation?
+
+  /// `\.currentItem.tracks` KVO on the leading leg's currentItem.
+  /// Fires `engineActiveItemFormatChanged` once tracks populate.
+  /// Re-installed on role swap and on `setItems`.
+  private var leadingItemTracksObserver: NSKeyValueObservation?
+
+  /// `\.currentItem.status` KVO on the leading leg's currentItem.
+  /// Routes `.failed` through `engineDidFailWithError`.
+  private var leadingItemStatusObserver: NSKeyValueObservation?
+
+  /// Block-based `NotificationCenter` observer tokens for the
+  /// AVPlayerItem lifecycle notifications. Filtered inside the
+  /// block to leading-leg only. Removed in `release`.
+  private var itemDidPlayToEndToken: NSObjectProtocol?
+  private var itemFailedToPlayToEndToken: NSObjectProtocol?
+
+  // MARK: - Init
+
+  init(crossfadeDurationSeconds: TimeInterval) {
+    precondition(
+      crossfadeDurationSeconds >= 0,
+      "crossfadeDurationSeconds must be non-negative"
+    )
+    self.crossfadeDurationSeconds = crossfadeDurationSeconds
+
+    let p1 = AVPlayer()
+    p1.automaticallyWaitsToMinimizeStalling = true
+    p1.volume = userVolume
+    let p2 = AVPlayer()
+    p2.automaticallyWaitsToMinimizeStalling = true
+    p2.volume = 0  // standby starts silent
+
+    self.playerA = p1
+    self.playerB = p2
+
+    let monitor = OutputRouteMonitor()
+    self.routeMonitor = monitor
+    monitor.start()
+    monitor.onRouteBecameNonMixable = { [weak self] in
+      // Mid-fade route change: cancel the in-flight fade so iOS
+      // doesn't arbitrarily silence one of the two players. The
+      // outgoing leg snaps to userVolume; the standby drops its
+      // item.
+      DispatchQueue.main.async { [weak self] in
+        self?.cancelFade()
+      }
+    }
+
+    // Lib-wide notifications fire for any AVPlayerItem; the
+    // closure filters by `object === leadingPlayer.currentItem`
+    // so events on the standby leg's preroll item don't surface.
+    itemDidPlayToEndToken = NotificationCenter.default.addObserver(
+      forName: .AVPlayerItemDidPlayToEndTime,
+      object: nil,
+      queue: .main
+    ) { [weak self] note in
+      self?.handleItemDidPlayToEnd(note)
+    }
+    itemFailedToPlayToEndToken = NotificationCenter.default.addObserver(
+      forName: .AVPlayerItemFailedToPlayToEndTime,
+      object: nil,
+      queue: .main
+    ) { [weak self] note in
+      self?.handleItemFailedToPlayToEnd(note)
+    }
+
+    // iOS 26+ AVRoutingPlaybackArbiter would let the engine name
+    // the preferred participant for non-mixable routes (AirPlay
+    // 2 / wireless CarPlay) so iOS doesn't arbitrarily silence
+    // one of two playing AVPlayer instances during the
+    // engagement transient. The current iOS SDK in this build
+    // ships AVRoutingPlaybackArbiter but the
+    // `preferredParticipantForNonMixableAudioRoutes` property
+    // marker is unavailable on iOS at the SDK header level —
+    // tracked as a follow-up once the SDK exposes it on iOS or
+    // an alternative API surface lands.
+  }
+
+  /// No-op placeholder — see init comment for the iOS 26+
+  /// AVRoutingPlaybackArbiter follow-up.
+  private func updateRoutingArbiter() {
+    // Intentional no-op pending SDK availability.
+  }
+
+  // MARK: - Lifecycle
+
+  func prepare(
+    items: [AVPlayerItem],
+    startIndex: Int,
+    startPositionSeconds: TimeInterval
+  ) async {
+    setItems(items, startIndex: startIndex, startPositionSeconds: startPositionSeconds)
+  }
+
+  func release() {
+    guard !released else { return }
+    released = true
+    // Release runs as part of an engine swap or destroy; the new
+    // engine has already taken over the canonical active-track
+    // state, so a mid-fade revert emit here would surface a
+    // spurious onTrackChange to the OUTGOING leg of a fade that
+    // the consumer no longer cares about.
+    cancelFadeInternal(emitRevert: false)
+    stopArmingObserver()
+    teardownLeadingObservers()
+    if let token = itemDidPlayToEndToken {
+      NotificationCenter.default.removeObserver(token)
+      itemDidPlayToEndToken = nil
+    }
+    if let token = itemFailedToPlayToEndToken {
+      NotificationCenter.default.removeObserver(token)
+      itemFailedToPlayToEndToken = nil
+    }
+    routeMonitor.stop()
+    leadingPlayer.replaceCurrentItem(with: nil)
+    standbyPlayer.replaceCurrentItem(with: nil)
+    queue.removeAll()
+    currentIndex = -1
+    mixProvider = nil
+    delegate = nil
+  }
+
+  // MARK: - Queue mutation
+
+  func setItems(
+    _ items: [AVPlayerItem],
+    startIndex: Int,
+    startPositionSeconds: TimeInterval
+  ) {
+    cancelFadeInternal()
+    queue = items
+    teardownLeadingObservers()
+    if items.isEmpty || startIndex < 0 || startIndex >= items.count {
+      currentIndex = -1
+      leadingPlayer.replaceCurrentItem(with: nil)
+      standbyPlayer.replaceCurrentItem(with: nil)
+      return
+    }
+    currentIndex = startIndex
+    let activeItem = items[startIndex]
+    applyMixIfNeeded(to: activeItem)
+    applyPitchAlgorithm(to: activeItem)
+    leadingPlayer.replaceCurrentItem(with: activeItem)
+    standbyPlayer.replaceCurrentItem(with: nil)
+    if startPositionSeconds > 0 {
+      activeItem.seek(
+        to: CMTime(seconds: startPositionSeconds, preferredTimescale: 600),
+        completionHandler: nil
+      )
+    }
+    installLeadingObservers()
+    updateRoutingArbiter()
+    delegate?.engineDidTransitionTrack(self)
+  }
+
+  @discardableResult
+  func insertItems(
+    _ items: [AVPlayerItem],
+    after: AVPlayerItem?
+  ) -> Bool {
+    if items.isEmpty { return true }
+    // Queue mutation invalidates the standby leg's pre-loaded
+    // future. Cancel any in-flight fade before mutating so the
+    // standby's stale state doesn't race a swap against the
+    // post-mutation index space.
+    cancelFadeInternal()
+    let insertOffset: Int
+    if let after, let idx = queue.firstIndex(where: { $0 === after }) {
+      insertOffset = idx + 1
+    } else if after == nil {
+      insertOffset = queue.count
+    } else {
+      // Reference item not in the engine's queue — fall back to
+      // a full rebuild signal so the caller can call setItems.
+      return false
+    }
+    queue.insert(contentsOf: items, at: insertOffset)
+    return true
+  }
+
+  func remove(_ item: AVPlayerItem) {
+    guard let idx = queue.firstIndex(where: { $0 === item }) else { return }
+    cancelFadeInternal()
+    queue.remove(at: idx)
+    if idx == currentIndex {
+      // Removing the leading leg's current item — auto-advance
+      // to whatever follows or drain.
+      if currentIndex >= queue.count {
+        currentIndex = queue.count - 1
+      }
+      if currentIndex < 0 {
+        leadingPlayer.replaceCurrentItem(with: nil)
+      } else {
+        let next = queue[currentIndex]
+        applyMixIfNeeded(to: next)
+        applyPitchAlgorithm(to: next)
+        leadingPlayer.replaceCurrentItem(with: next)
+      }
+    } else if idx < currentIndex {
+      currentIndex -= 1
+    }
+  }
+
+  func removeAllItems() {
+    cancelFadeInternal()
+    queue.removeAll()
+    currentIndex = -1
+    leadingPlayer.replaceCurrentItem(with: nil)
+    standbyPlayer.replaceCurrentItem(with: nil)
+  }
+
+  func canInsert(_ item: AVPlayerItem, after: AVPlayerItem?) -> Bool {
+    if let after {
+      return queue.contains(where: { $0 === after })
+    }
+    return true  // append-at-end always permitted
+  }
+
+  // MARK: - Transport
+
+  func play() {
+    // Resume at the user's speed (AVPlayer.play() resets rate to 1.0).
+    leadingPlayer.rate = userPlaybackSpeed
+    startArmingObserver()
+  }
+
+  func pause() {
+    cancelFadeInternal()
+    stopArmingObserver()
+    leadingPlayer.pause()
+    standbyPlayer.pause()
+  }
+
+  func stop() {
+    cancelFadeInternal()
+    stopArmingObserver()
+    leadingPlayer.pause()
+    standbyPlayer.pause()
+    // Match GaplessEngine.stop(): pause + seek the CURRENT (leading) item to 0
+    // and KEEP it. Replacing it with nil leaves no currentItem — so position
+    // never resets to observe, the periodic time observer never fires the
+    // post-stop progress tick consumers wait for, and getState() drops to NONE
+    // instead of PAUSED. Drain only the standby (prerolled next-track) leg;
+    // it's stale once stopped and re-arms on the next play.
+    leadingPlayer.currentItem?.seek(to: .zero, completionHandler: nil)
+    standbyPlayer.replaceCurrentItem(with: nil)
+  }
+
+  func seek(toIndex index: Int, position: TimeInterval) {
+    guard index >= 0, index < queue.count else { return }
+    // Capture playing intent before the fade-cancel: a cross-attach
+    // (replaceCurrentItem) drops the leading player to rate 0, so the
+    // new leg must be resumed at the user's speed below to match the
+    // gapless skip (which restores rate across its queue rebuild).
+    let wasPlaying = isPlaying
+    // Seek is itself a track-change: the engineDidTransitionTrack
+    // fire at the end of this method is the authoritative active-
+    // track flip for the new index. Suppress the cancel-revert
+    // emit so a mid-fade seek doesn't dispatch an intermediate
+    // engineCrossfadeDidCancel(revertedIndex: outgoing) event
+    // before the seek's own track-change lands.
+    cancelFadeInternal(emitRevert: false)
+    teardownLeadingObservers()
+    currentIndex = index
+    let existing = queue[index]
+    // Same-instance no-op: target is already leadingPlayer's
+    // currentItem (seek-within-current-track, or seekTo right
+    // after setItems). Calling replaceCurrentItem with the same
+    // instance triggers a redundant KVO cascade and delays
+    // duration re-propagation by seconds; skip the re-attach.
+    if leadingPlayer.currentItem === existing {
+      if position > 0 {
+        existing.seek(
+          to: CMTime(seconds: position, preferredTimescale: 600),
+          completionHandler: nil
+        )
+      } else {
+        // Same-instance keeps any prior playhead; force-reset to
+        // zero to honour the seek contract.
+        existing.seek(to: .zero, completionHandler: nil)
+      }
+      standbyArmed = false
+      installLeadingObservers()
+      updateRoutingArbiter()
+      delegate?.engineDidTransitionTrack(self)
+      return
+    }
+    // Cross-attach case: target is associated with another
+    // AVPlayer (typically standbyPlayer post fade-arm). Rebuild
+    // as a fresh AVPlayerItem on the existing asset.
+    // AVPlayer.replaceCurrentItem(with:) raises NSException
+    // (uncatchable in Swift → process abort) if the item is still
+    // associated with another AVPlayer; AVPlayerItem.player
+    // releases asynchronously after the previous player calls
+    // replaceCurrentItem(with: nil) and there's no synchronous
+    // way to wait for the release, no public API to inspect the
+    // association. Mirror AVQueueBuilder.makeItem's construction
+    // (`automaticallyLoadedAssetKeys` + buffer pin) and carry
+    // queueItemId across so TrackPlayer.matchTrackIndex can still
+    // resolve the new item back to its queue position.
+    let target = AVPlayerItem(
+      // Prefer the lookahead cache's local file when the track has
+      // cached since the queue item was built from its remote URL —
+      // otherwise this fresh item re-loads the remote asset and the
+      // `.tracks` round-trip can fail the now-playing format extractor.
+      asset: cacheResolvedAsset(for: existing),
+      // Mirror AVQueueBuilder.makeItem fully — including "tracks". A forward
+      // skip to a cached track rebuilds the incoming leg here; without the
+      // tracks key auto-loading, the `.new`-only tracks KVO never fires for
+      // the fresh item and the now-playing format never resolves.
+      automaticallyLoadedAssetKeys: ["playable", "duration", "tracks"]
+    )
+    target.preferredForwardBufferDuration = 0.0
+    target.queueItemId = existing.queueItemId
+    target.sourceURL = existing.sourceURL
+    // Replace the queue slot with the rebuilt item — any cached
+    // AVPlayerItem reference held by a future callsite (e.g. an
+    // armCrossfade re-arming on this index) must read queue[index]
+    // afresh; the prior `existing` instance is now orphaned and
+    // its prior-player association will release asynchronously.
+    queue[index] = target
+    applyMixIfNeeded(to: target)
+    applyPitchAlgorithm(to: target)
+    leadingPlayer.replaceCurrentItem(with: target)
+    if position > 0 {
+      target.seek(
+        to: CMTime(seconds: position, preferredTimescale: 600),
+        completionHandler: nil
+      )
+    }
+    if wasPlaying {
+      // replaceCurrentItem leaves the player at rate 0 — resume at the
+      // user's speed (mirrors play() / completeCrossfade) so a skip while
+      // playing at a non-default speed doesn't fall back to 1.0x.
+      leadingPlayer.rate = userPlaybackSpeed
+    }
+    standbyArmed = false
+    installLeadingObservers()
+    updateRoutingArbiter()
+    delegate?.engineDidTransitionTrack(self)
+  }
+
+  func skipToNext() {
+    let next = currentIndex + 1
+    if next < queue.count {
+      seek(toIndex: next, position: 0)
+    }
+  }
+
+  func skipToPrevious() {
+    let prev = currentIndex - 1
+    if prev >= 0 {
+      seek(toIndex: prev, position: 0)
+    } else {
+      leadingPlayer.currentItem?.seek(to: .zero, completionHandler: nil)
+    }
+  }
+
+  // MARK: - Config
+
+  func setVolume(_ volume: Float) {
+    userVolume = volume
+    leadingPlayer.volume = volume
+    // Standby stays silent outside fade window.
+  }
+
+  func setPlaybackSpeed(_ speed: Float) {
+    userPlaybackSpeed = speed
+    leadingPlayer.rate = speed
+    // Crossing the 1.0 boundary changes the resolved algorithm; restamp
+    // both legs (standby prerolls at this rate).
+    reapplyPitchToCurrentLegs()
+  }
+
+  func seedPlaybackSpeed(_ speed: Float) {
+    // Persist only; `play()` applies it. Does not touch the leg rate,
+    // so it won't start a paused engine.
+    userPlaybackSpeed = speed
+    reapplyPitchToCurrentLegs()
+  }
+
+  func setRepeatMode(_ mode: RepeatMode) {
+    // `.queue` wrap is still driven by TrackPlayer rebuilding the queue
+    // (as on gapless). `.track` (repeat-one) is handled here because
+    // AVPlayer has no native repeat: the engine suppresses the fade and
+    // loops the current item on natural end.
+    repeatMode = mode
+  }
+
+  // MARK: - State
+
+  /// During a crossfade the conceptual "active" track flips to the
+  /// standby leg the moment the fade begins (matches the JS-facing
+  /// `onTrackChange` + lock-screen / Now Playing flip the delegate
+  /// performs in response to `engineCrossfadeDidBegin`). All four
+  /// accessors below honour this: when `fadeInFlight`, they read
+  /// from `standbyPlayer` (the incoming leg) so `useProgress`,
+  /// seek clamps, preserve-current, and index lookups all see the
+  /// incoming track. Engine-internal code reaches `leadingPlayer`
+  /// / `currentIndex` directly.
+  var currentMediaItemIndex: Int {
+    if queue.isEmpty { return -1 }
+    return fadeInFlight ? currentIndex + 1 : currentIndex
+  }
+
+  var currentPositionSeconds: TimeInterval {
+    let player = fadeInFlight ? standbyPlayer : leadingPlayer
+    let t = player.currentTime()
+    return t.isNumeric ? CMTimeGetSeconds(t) : 0
+  }
+
+  var currentDurationSeconds: TimeInterval {
+    let player = fadeInFlight ? standbyPlayer : leadingPlayer
+    guard let d = player.currentItem?.duration, d.isNumeric else { return 0 }
+    return CMTimeGetSeconds(d)
+  }
+
+  var bufferedPositionSeconds: TimeInterval {
+    let player = fadeInFlight ? standbyPlayer : leadingPlayer
+    guard let ranges = player.currentItem?.loadedTimeRanges,
+          let last = ranges.last?.timeRangeValue else { return 0 }
+    return CMTimeGetSeconds(last.start + last.duration)
+  }
+
+  var isPlaying: Bool {
+    // Reads the leading leg unconditionally (both legs play mid-fade); the
+    // `timeControlStatus` accessor below deliberately reads the active leg
+    // (standby while fading) to match `currentMediaItem` for state derivation.
+    leadingPlayer.timeControlStatus == .playing
+  }
+
+  var timeControlStatus: AVPlayer.TimeControlStatus {
+    // Mirror `currentMediaItem`'s leg selection: during a fade the standby
+    // (incoming) leg is the conceptually-active track, so its status is the
+    // one a consumer's spinner/state should reflect.
+    let player = fadeInFlight ? standbyPlayer : leadingPlayer
+    return player.timeControlStatus
+  }
+
+  var currentMediaItem: AVPlayerItem? {
+    let player = fadeInFlight ? standbyPlayer : leadingPlayer
+    return player.currentItem
+  }
+
+  var allMediaItems: [AVPlayerItem] {
+    queue
+  }
+
+  // MARK: - Effect chain
+
+  func setAudioMixProvider(_ provider: AudioMixProvider?) {
+    mixProvider = provider
+    refreshAllItemMixes()
+  }
+
+  func setCachedURLResolver(_ resolver: ((String) -> URL?)?) {
+    cachedURLResolver = resolver
+  }
+
+  /// The lookahead cache's local file URL for [item]'s source track,
+  /// when it has fully cached since the item was built; nil when no
+  /// resolver is wired, the item carries no source URL, or the cache
+  /// misses. Keyed by the verbatim `sourceURL` the cache was keyed
+  /// with — never the asset URL (already `file://` once local).
+  private func cachedLocalURL(for item: AVPlayerItem) -> URL? {
+    guard let resolver = cachedURLResolver, let url = item.sourceURL else {
+      return nil
+    }
+    return resolver(url)
+  }
+
+  /// The asset a queue item should be (re)built from at a late attach:
+  /// the lookahead cache's local file when [existing]'s track has
+  /// since cached, else [existing]'s own asset. Re-resolving here lets
+  /// a forward/back skip to a now-cached track play from local disk
+  /// rather than re-loading the remote asset.
+  private func cacheResolvedAsset(for existing: AVPlayerItem) -> AVAsset {
+    // Reuse the existing asset when it's already this cache file (built
+    // cached at queue-build time) — the cross-attach rebuilds the item
+    // regardless, so there's nothing to upgrade and a fresh AVURLAsset
+    // on the same file would just be a wasted allocation.
+    guard let cachedURL = cachedLocalURL(for: existing),
+          (existing.asset as? AVURLAsset)?.url != cachedURL else {
+      return existing.asset
+    }
+    return AVURLAsset(url: cachedURL)
+  }
+
+  /// If [index]'s queue item was built from a remote URL whose track
+  /// has since fully cached, swap the slot for a fresh item backed by
+  /// the local cache file (carrying `queueItemId` + `sourceURL` across)
+  /// and return it; otherwise return the existing item unchanged. Lets
+  /// the fade-arm preroll pick up a track that cached after the queue
+  /// was first built so an auto-advance crossfade plays from local disk.
+  private func cacheUpgradedItem(at index: Int) -> AVPlayerItem {
+    let existing = queue[index]
+    // Only rebuild on the genuine remote→cached transition. When the slot
+    // was already built from this cache file (cached at queue-build time),
+    // reuse the prepared item rather than discarding its buffers for an
+    // identical rebuild + re-preroll.
+    guard let cachedURL = cachedLocalURL(for: existing),
+          (existing.asset as? AVURLAsset)?.url != cachedURL else {
+      return existing
+    }
+    let upgraded = AVPlayerItem(
+      asset: AVURLAsset(url: cachedURL),
+      automaticallyLoadedAssetKeys: ["playable", "duration", "tracks"]
+    )
+    upgraded.preferredForwardBufferDuration = 0.0
+    upgraded.queueItemId = existing.queueItemId
+    upgraded.sourceURL = existing.sourceURL
+    queue[index] = upgraded
+    return upgraded
+  }
+
+  func refreshAllItemMixes() {
+    // Catch-up walk: only fill items that lack an `audioMix`. Items
+    // that already carry a tap are left alone (re-assigning on an
+    // already-rendering item allocates fresh `MTAudioProcessingTap`
+    // + `EQProcessor` cascade resources that AVPlayer silently
+    // drops, leaking them to ARC). See `GaplessEngine.refreshAllItemMixes`
+    // for the full rationale.
+    if let leading = leadingPlayer.currentItem, leading.audioMix == nil {
+      leading.audioMix = mixProvider?.audioMix(for: leading)
+    }
+    if let standby = standbyPlayer.currentItem, standby.audioMix == nil {
+      standby.audioMix = mixProvider?.audioMix(for: standby)
+    }
+  }
+
+  private func applyMixIfNeeded(to item: AVPlayerItem) {
+    guard let provider = mixProvider,
+          let mix = provider.audioMix(for: item) else { return }
+    item.audioMix = mix
+  }
+
+  func setPitchCorrectionMode(_ mode: PitchCorrectionMode) {
+    pitchCorrectionMode = mode
+    reapplyPitchToCurrentLegs()
+  }
+
+  /// Stamp the resolved algorithm on `item`. Idempotent: a no-op when
+  /// the item already carries it, so re-applying on a rendering item
+  /// doesn't churn the audio graph.
+  private func applyPitchAlgorithm(to item: AVPlayerItem) {
+    let algo = PitchAlgorithm.resolve(
+      mode: pitchCorrectionMode,
+      speed: userPlaybackSpeed
+    )
+    if item.audioTimePitchAlgorithm != algo {
+      item.audioTimePitchAlgorithm = algo
+    }
+  }
+
+  private func reapplyPitchToCurrentLegs() {
+    if let leading = leadingPlayer.currentItem { applyPitchAlgorithm(to: leading) }
+    if let standby = standbyPlayer.currentItem { applyPitchAlgorithm(to: standby) }
+  }
+
+  // MARK: - Handoff
+
+  func handoff(to nextEngine: PlaybackEngine, atTrackBoundary: Bool) async {
+    // Engine handoff (gapless ↔ crossfade) is driven by
+    // TrackPlayer.swift's mode-switch path which holds the
+    // canonical queue model. The engine's own `release()` is
+    // the caller's responsibility AFTER the swap.
+    return
+  }
+
+  // MARK: - Equal-power gain math
+
+  /// Equal-power gain pair for fade progress `t ∈ [0, 1]`.
+  /// `(outgoing, incoming)` — sum-of-squares stays at 1.0
+  /// across the ramp so perceived loudness is constant.
+  static func equalPowerGains(t: Float) -> (Float, Float) {
+    let clamped = max(0, min(1, t))
+    let angle = clamped * Float.pi / 2
+    return (cos(angle), sin(angle))
+  }
+
+  /// Approximate the equal-power curve via [subRampCount]
+  /// short linear segments. Returns the gain pair at each
+  /// step's start. Caller schedules each segment via
+  /// `setVolumeRamp(fromStartVolume:toEndVolume:timeRange:)`.
+  ///
+  /// `setVolumeRamp` is linear-only per the AVFoundation API;
+  /// staircasing the cos/sin curve into N segments is the
+  /// supported approximation.
+  static func equalPowerSubRamps(
+    durationSeconds: TimeInterval,
+    steps: Int = subRampCount
+  ) -> [(timeRange: CMTimeRange, outgoing: (start: Float, end: Float), incoming: (start: Float, end: Float))] {
+    guard steps > 0, durationSeconds > 0 else { return [] }
+    let stepSeconds = durationSeconds / Double(steps)
+    var ramps: [(CMTimeRange, (Float, Float), (Float, Float))] = []
+    for i in 0 ..< steps {
+      let tStart = Float(i) / Float(steps)
+      let tEnd = Float(i + 1) / Float(steps)
+      let (outStart, inStart) = equalPowerGains(t: tStart)
+      let (outEnd, inEnd) = equalPowerGains(t: tEnd)
+      let cmStart = CMTime(seconds: Double(i) * stepSeconds, preferredTimescale: 600)
+      let cmEnd = CMTime(seconds: Double(i + 1) * stepSeconds, preferredTimescale: 600)
+      let range = CMTimeRange(start: cmStart, end: cmEnd)
+      ramps.append((range, (outStart, outEnd), (inStart, inEnd)))
+    }
+    return ramps
+  }
+
+  /// Auto-clamp the configured fade duration so the ramp never
+  /// overflows either leg's track length. Mirrors the Android
+  /// `effectiveCrossfadeMs`.
+  func effectiveCrossfadeSeconds(
+    leadingDurationSeconds: TimeInterval,
+    standbyDurationSeconds: TimeInterval
+  ) -> TimeInterval {
+    let configured = crossfadeDurationSeconds
+    let leadingHalf = leadingDurationSeconds > 0
+      ? leadingDurationSeconds / 2 : configured
+    let standbyHalf = standbyDurationSeconds > 0
+      ? standbyDurationSeconds / 2 : configured
+    return max(0, min(min(configured, leadingHalf), standbyHalf))
+  }
+
+  // MARK: - Fade cancel
+
+  /// Cancel any in-flight fade — strip the volume ramp from
+  /// both legs' current `audioMix`, snap leading to userVolume,
+  /// drop the standby's currentItem so its preroll bytes are
+  /// released. Internal entry point used by `pause` / `seek` /
+  /// `setItems` and by the route-monitor non-mixable callback.
+  func cancelFade() {
+    cancelFadeInternal()
+  }
+
+  // MARK: - Boundary arming
+
+  /// Boundary-arming periodic time observer. Watches the leading
+  /// leg's time at 200ms cadence; when within
+  /// `effectiveCrossfadeSeconds + prerollLeadSeconds` of track end,
+  /// prerolls standby + schedules the equal-power ramp on both
+  /// legs' `AVMutableAudioMixInputParameters`.
+  ///
+  /// Cancellation: `pause` / `stop` / `seek` / `skipToNext` /
+  /// `skipToPrevious` / `release` all remove the observer. `play`
+  /// re-installs it.
+  private func startArmingObserver() {
+    if armingObserver != nil { return }
+    let player = leadingPlayer
+    let interval = CMTime(seconds: 0.2, preferredTimescale: CMTimeScale(NSEC_PER_SEC))
+    let token = player.addPeriodicTimeObserver(
+      forInterval: interval,
+      queue: .main
+    ) { [weak self] _ in
+      self?.maybeArmCrossfade()
+    }
+    armingObserver = (player, token)
+  }
+
+  private func stopArmingObserver() {
+    if let observer = armingObserver {
+      observer.player.removeTimeObserver(observer.token)
+    }
+    armingObserver = nil
+  }
+
+  private func maybeArmCrossfade() {
+    if standbyArmed { return }
+    if fadeInFlight { return }
+    if !routeMonitor.isCurrentRouteMixable { return }  // hard-cut on AirPlay/CarPlay
+    if crossfadeDurationSeconds <= 0 { return }
+    // Repeat-one loops the current item in place (see
+    // `handleItemDidPlayToEnd`); never arm a look-ahead fade, which
+    // would advance past the track the user asked to repeat.
+    if repeatMode == .track { return }
+    if currentIndex < 0 || currentIndex >= queue.count - 1 { return }  // last track or empty
+    guard let leading = leadingPlayer.currentItem else { return }
+    let duration = leading.duration
+    if !duration.isNumeric { return }
+    let durationSeconds = CMTimeGetSeconds(duration)
+    if durationSeconds <= 0 { return }
+    let position = CMTimeGetSeconds(leading.currentTime())
+    // Standby duration unknown until prepared — pass 0 so
+    // effectiveCrossfadeSeconds falls through to the configured
+    // value with leading-half clamp only.
+    let effective = effectiveCrossfadeSeconds(
+      leadingDurationSeconds: durationSeconds,
+      standbyDurationSeconds: 0
+    )
+    let armThreshold = durationSeconds - effective - Self.prerollLeadSeconds
+    if position < armThreshold { return }
+    standbyArmed = true
+    armCrossfade(durationSeconds: effective)
+  }
+
+  /// Preload the next queue item onto standby + schedule the
+  /// equal-power N-sub-ramp `setVolumeRamp` schedule on both legs'
+  /// `AVMutableAudioMixInputParameters`. Caller (the periodic
+  /// observer) has already validated route + index + arming state.
+  ///
+  /// `AVPlayer.preroll(atRate:)` has TWO documented preconditions
+  /// per Apple's `AVPlayer.h`:
+  ///   1. `AVPlayer.status == .readyToPlay`
+  ///   2. `automaticallyWaitsToMinimizeStalling == false`
+  ///
+  /// Violating either raises `NSInternalInconsistencyException`
+  /// synchronously. After `replaceCurrentItem` the status flip is
+  /// asynchronous — the asset has to load tracks/duration. KVO-
+  /// wait until the status reaches `.readyToPlay` before invoking
+  /// `preroll`; `runFade` chains through the readiness callback so
+  /// the timing semantics (preroll → ramp schedule → wall-clock
+  /// completion) are preserved. The pre-attach `seek(to: .zero)`
+  /// on the prior implementation was redundant — `replaceCurrentItem`
+  /// resets the item's playhead — and was masking the readiness
+  /// race because seek-on-detached-item is a documented no-op on
+  /// modern iOS.
+  private func armCrossfade(durationSeconds: TimeInterval) {
+    let nextIdx = currentIndex + 1
+    guard nextIdx < queue.count else {
+      standbyArmed = false
+      return
+    }
+    // Re-resolve against the cache: a track that finished caching after
+    // the queue was built is swapped for its local file here so the
+    // auto-advance fade plays from local disk, not the remote URL.
+    let nextItem = cacheUpgradedItem(at: nextIdx)
+    applyMixIfNeeded(to: nextItem)
+    applyPitchAlgorithm(to: nextItem)
+    let standby = standbyPlayer
+    standby.replaceCurrentItem(with: nextItem)
+    let priorAutoStall = standby.automaticallyWaitsToMinimizeStalling
+    awaitStandbyReady(standby) { [weak self] in
+      guard let self else { return }
+      if self.released || !self.standbyArmed { return }
+      // Explicit `tracks` key load on the freshly-replaced standby
+      // asset BEFORE preroll. `AVPlayerItem.status == .readyToPlay`
+      // does NOT guarantee the asset's tracks key is loaded —
+      // that's a separate async load. `runFade` requires the
+      // tracks to be present so it can attach the volume-ramp
+      // audioMix to the standby item.
+      let nextAsset = nextItem.asset
+      Task { @MainActor [weak self] in
+        do {
+          _ = try await nextAsset.load(.tracks)
+        } catch {
+          self?.cancelFadeInternal()
+          return
+        }
+        guard let self else { return }
+        if self.released || !self.standbyArmed { return }
+        standby.automaticallyWaitsToMinimizeStalling = false
+        // Await preroll via a checked continuation so the rest of
+        // the chain stays on @MainActor. Spawning a fresh Task
+        // inside `preroll`'s @escaping completion would create a
+        // @Sendable-closure-captures-non-Sendable-self warning
+        // because preroll's callback queue is unspecified.
+        _ = await withCheckedContinuation { (cont: CheckedContinuation<Bool, Never>) in
+          standby.preroll(atRate: 1.0) { ready in
+            cont.resume(returning: ready)
+          }
+        }
+        if self.released || !self.standbyArmed { return }
+        // Best-effort restore: cancel/release paths drop the
+        // standby item entirely, so a missed restore here is
+        // bounded by the next replaceCurrentItem.
+        standby.automaticallyWaitsToMinimizeStalling = priorAutoStall
+        self.runFade(durationSeconds: durationSeconds)
+      }
+    }
+  }
+
+  /// One-shot KVO on `standby.status`. Fires [ready] once status
+  /// reaches `.readyToPlay`; fires immediately on the calling
+  /// runloop turn if already `.readyToPlay`. On `.failed` the
+  /// callback fires too — caller must check `released` /
+  /// `standbyArmed` before acting. Backed by a 5s wall-clock
+  /// timeout that calls `cancelFadeInternal` if the status never
+  /// flips (stuck-load defence).
+  private func awaitStandbyReady(_ player: AVPlayer, ready: @escaping () -> Void) {
+    standbyReadyObserver?.invalidate()
+    standbyReadyObserver = nil
+    standbyReadyTimeout?.cancel()
+    standbyReadyTimeout = nil
+    standbyReadyGen &+= 1
+    let myGen = standbyReadyGen
+
+    if player.status == .readyToPlay {
+      ready()
+      return
+    }
+
+    standbyReadyObserver = player.observe(\.status, options: [.new]) { [weak self] obs, _ in
+      let s = obs.status
+      // `.unknown` is the start state — wait for the first real flip.
+      guard s == .readyToPlay || s == .failed else { return }
+      DispatchQueue.main.async { [weak self] in
+        guard let self else { return }
+        // Cross-cycle race guard: if a new armCrossfade cycle
+        // started after this observer queued its main-async hop,
+        // the generation counter has advanced — this fire belongs
+        // to a stale standby and must not run `ready()` against
+        // the new arm's state.
+        if self.standbyReadyGen != myGen { return }
+        self.standbyReadyObserver?.invalidate()
+        self.standbyReadyObserver = nil
+        self.standbyReadyTimeout?.cancel()
+        self.standbyReadyTimeout = nil
+        if s == .readyToPlay {
+          ready()
+        } else {
+          // Standby load failed — drop the arm cleanly so the
+          // leading leg keeps playing through to its natural end.
+          self.cancelFadeInternal()
+        }
+      }
+    }
+
+    let timeout = DispatchWorkItem { [weak self] in
+      guard let self else { return }
+      // Same cross-cycle guard for the timeout path.
+      if self.standbyReadyGen != myGen { return }
+      self.standbyReadyObserver?.invalidate()
+      self.standbyReadyObserver = nil
+      self.standbyReadyTimeout = nil
+      self.cancelFadeInternal()
+    }
+    standbyReadyTimeout = timeout
+    DispatchQueue.main.asyncAfter(deadline: .now() + 5.0, execute: timeout)
+  }
+
+  /// Input parameters to drive the fade ramp on [item]. Reuses the item's
+  /// existing tap-bearing parameters when present so the EQ / visualizer /
+  /// ReplayGain tap survives the fade; otherwise a bare ramp-only object
+  /// keyed to [track]. Never re-runs the mix provider — that allocates a
+  /// fresh MTAudioProcessingTap on an already-rendering item and leaks it
+  /// (see refreshAllItemMixes).
+  private func fadeParams(
+    for item: AVPlayerItem,
+    track: AVAssetTrack
+  ) -> AVMutableAudioMixInputParameters {
+    if let existing = item.audioMix?.inputParameters.first
+      as? AVMutableAudioMixInputParameters {
+      return existing
+    }
+    return AVMutableAudioMixInputParameters(track: track)
+  }
+
+  /// Schedule the equal-power N-sub-ramp `setVolumeRamp` schedule
+  /// on both legs' currentItem `audioMix.inputParameters`. Caller
+  /// has already prerolled standby. The fade runs against
+  /// asset-time on each item; the post-fade swap is scheduled via
+  /// a Task that sleeps for `durationSeconds` then promotes
+  /// standby to leading.
+  private func runFade(durationSeconds: TimeInterval) {
+    if released { return }
+    guard let leading = leadingPlayer.currentItem,
+          let standby = standbyPlayer.currentItem else { return }
+
+    // BOTH sides must produce a valid AVAssetTrack; if either is
+    // empty the fade can't ramp evenly and the user hears a hard
+    // transition. armCrossfade has already awaited the standby
+    // asset's tracks key load, so empty here is a real error —
+    // fail loud, cancel cleanly, log via NSLog so the issue isn't
+    // silent (the prior implementation's `if let` guard silently
+    // skipped, which is exactly the failure mode this guard
+    // exists to surface).
+    // Read tracks via the AVPlayerItem.tracks chain — populated
+    // at .readyToPlay and sync-accessible. Avoids the deprecated
+    // sync `asset.tracks(withMediaType:)` (replaced by async
+    // `loadTracks(withMediaType:)` in macOS 13 / iOS 16). The
+    // standby asset's tracks key was already async-loaded in
+    // armCrossfade so the chain is guaranteed populated by here.
+    let leadingTrack = leading.tracks
+      .first(where: { $0.assetTrack?.mediaType == .audio })?.assetTrack
+    let standbyTrack = standby.tracks
+      .first(where: { $0.assetTrack?.mediaType == .audio })?.assetTrack
+    guard let leadingTrack, let standbyTrack else {
+      NSLog("[RNQP-CROSSFADE] runFade aborting — missing audio track (leading=%@ standby=%@); cancelling fade",
+            leadingTrack == nil ? "MISSING" : "ok",
+            standbyTrack == nil ? "MISSING" : "ok")
+      cancelFadeInternal()
+      return
+    }
+
+    fadeInFlight = true
+
+    let leadingFadeStart = leading.currentTime()
+    let ramps = Self.equalPowerSubRamps(durationSeconds: durationSeconds)
+
+    // Reuse each leg's EXISTING tap-bearing input parameters so the EQ /
+    // visualizer / ReplayGain MTAudioProcessingTap keeps processing through
+    // the fade window — the volume ramp and the tap coexist on one
+    // AVMutableAudioMixInputParameters (the tap is pre-effects, so it sees
+    // the track audio and the ramp scales the tapped output). A fresh tap is
+    // never allocated here — re-running the provider on an already-rendering
+    // item leaks tap resources (see refreshAllItemMixes). Falls back to a
+    // bare ramp-only params object only when the leg carries no tap (no
+    // EQ/viz/RG consumer, HLS, or tracks not yet loaded).
+    let leadingParams = fadeParams(for: leading, track: leadingTrack)
+    for ramp in ramps {
+      let absStart = leadingFadeStart + ramp.timeRange.start
+      let timeRange = CMTimeRange(start: absStart, duration: ramp.timeRange.duration)
+      leadingParams.setVolumeRamp(
+        fromStartVolume: ramp.outgoing.start,
+        toEndVolume: ramp.outgoing.end,
+        timeRange: timeRange
+      )
+    }
+    let leadingMix = AVMutableAudioMix()
+    leadingMix.inputParameters = [leadingParams]
+    leading.audioMix = leadingMix
+
+    // Standby ramp anchored at asset-time zero, NOT
+    // `standby.currentTime()`. After `replaceCurrentItem` +
+    // `preroll(atRate:)` the standby's currentTime is unstable
+    // across iOS versions until first decode pull lands; using
+    // kCMTimeZero is the only reliable anchor for the head of a
+    // freshly-attached AVPlayerItem.
+    let standbyParams = fadeParams(for: standby, track: standbyTrack)
+    for ramp in ramps {
+      let timeRange = CMTimeRange(
+        start: ramp.timeRange.start, duration: ramp.timeRange.duration
+      )
+      standbyParams.setVolumeRamp(
+        fromStartVolume: ramp.incoming.start,
+        toEndVolume: ramp.incoming.end,
+        timeRange: timeRange
+      )
+    }
+    let standbyMix = AVMutableAudioMix()
+    standbyMix.inputParameters = [standbyParams]
+    standby.audioMix = standbyMix
+
+    standbyPlayer.volume = userVolume  // ramp inside the mix handles the actual envelope
+    standbyPlayer.play()
+
+    // Active-track flip: the standby leg is now audibly playing
+    // (volume 0 → ramping up). Notify the delegate so JS-facing
+    // `onTrackChange` + `MPNowPlayingInfoCenter` retarget to the
+    // incoming track immediately, not at fade-end. The accessor
+    // group above (`currentMediaItem*`, `currentPositionSeconds`,
+    // etc.) also flips at this point because `fadeInFlight = true`
+    // is already set above; the delegate sees consistent state
+    // across the callback.
+    let incomingIdx = currentIndex + 1
+    delegate?.engineCrossfadeDidBegin(self, incomingIndex: incomingIdx)
+
+    // Post-fade swap scheduled in wall-clock — the asset-time-keyed
+    // ramps complete in this many seconds regardless of pause
+    // because pausing also halts the asset clock. The Task handle
+    // is stored so a subsequent `cancelFadeInternal` /
+    // `release` can cancel it; without cancellation a stale
+    // completion can run against a fresh fade after the user
+    // pauses+resumes within one boundary window.
+    fadeCompletionTask?.cancel()
+    let durationNs = UInt64(durationSeconds * 1_000_000_000)
+    fadeCompletionTask = Task { @MainActor [weak self] in
+      do {
+        try await Task.sleep(nanoseconds: durationNs)
+      } catch {
+        return  // cancelled
+      }
+      self?.completeCrossfade()
+    }
+  }
+
+  /// Promote standby to leading at fade-end. Drops the old
+  /// leading's currentItem; advances `currentIndex`; resets
+  /// arming markers so the new leading can re-arm for its own
+  /// next-track boundary; fires `engineDidTransitionTrack` so
+  /// `TrackPlayer` can refresh JS-facing state.
+  ///
+  /// Observer cleanup runs BEFORE the role flip so
+  /// `removeTimeObserver` is called against the player that
+  /// issued the token; reinstall runs AFTER the flip so the new
+  /// observer attaches to the new leading. The fade ramp's
+  /// audioMix wiped any provider-supplied EQ params on the new
+  /// leading's currentItem — re-apply via `applyMixIfNeeded`
+  /// after stripping the ramp mix.
+  private func completeCrossfade() {
+    if released { return }
+    if !fadeInFlight { return }
+    fadeInFlight = false
+    fadeCompletionTask = nil
+    stopArmingObserver()
+    teardownLeadingObservers()
+    let oldLeading = leadingPlayer
+    oldLeading.pause()
+    oldLeading.replaceCurrentItem(with: nil)
+    oldLeading.volume = userVolume
+    // The fade ramp's final tick already settled the standby (about
+    // to be promoted to leading) at userVolume; no explicit write
+    // needed across the toggle.
+    currentRoleIsA.toggle()
+    if let newLeading = leadingPlayer.currentItem {
+      newLeading.audioMix = nil
+      applyMixIfNeeded(to: newLeading)
+    }
+    // The promoted standby was prerolled + played at rate 1.0; restore
+    // the user's playback speed so it survives the transition.
+    leadingPlayer.rate = userPlaybackSpeed
+    standbyArmed = false
+    currentIndex += 1
+    startArmingObserver()
+    installLeadingObservers()
+    updateRoutingArbiter()
+    delegate?.engineDidTransitionTrack(self)
+  }
+
+  private func cancelFadeInternal(emitRevert: Bool = true) {
+    fadeCompletionTask?.cancel()
+    fadeCompletionTask = nil
+    standbyReadyObserver?.invalidate()
+    standbyReadyObserver = nil
+    standbyReadyTimeout?.cancel()
+    standbyReadyTimeout = nil
+    // Capture pre-state: if a fade was in flight we already fired
+    // `engineCrossfadeDidBegin` for `currentIndex + 1` — the
+    // delegate believes the incoming is active. We must fire
+    // `engineCrossfadeDidCancel(revertedIndex: currentIndex)` so
+    // the delegate reverts active-track state back to the leading
+    // leg. `emitRevert: false` is for callers that will immediately
+    // set a new active track themselves (e.g. seek to a different
+    // index) — emitting the intermediate revert would surface a
+    // spurious track-change to the outgoing leg before the caller's
+    // own track-change.
+    let wasMidFade = fadeInFlight
+    let leadingIdx = currentIndex
+    fadeInFlight = false
+    standbyArmed = false
+    // Backward seek through a scheduled ramp window leaves the
+    // mix in a wonky state per Wade Tregaskis — strip the mix
+    // and re-apply the EQ-only mix to recover.
+    if let leading = leadingPlayer.currentItem {
+      leading.audioMix = nil
+      applyMixIfNeeded(to: leading)
+    }
+    if let standby = standbyPlayer.currentItem {
+      standby.audioMix = nil
+    }
+    leadingPlayer.volume = userVolume
+    standbyPlayer.volume = 0
+    standbyPlayer.replaceCurrentItem(with: nil)
+    if wasMidFade && emitRevert {
+      delegate?.engineCrossfadeDidCancel(self, revertedIndex: leadingIdx)
+    }
+  }
+
+  // MARK: - Engine event observer install/teardown
+
+  /// Install KVO on the leading leg's `timeControlStatus` (drives
+  /// `engineStateMaybeChanged` + `engineIsPlayingChanged`) and on
+  /// the leading leg's currentItem `tracks` / `status` (drives
+  /// format-ready + failed-to-load delegate fires). Called whenever
+  /// the leading leg or its currentItem changes — i.e. from
+  /// [setItems], [seek], and [completeCrossfade] after the role
+  /// flip. Idempotent — teardown runs first inside.
+  private func installLeadingObservers() {
+    teardownLeadingObservers()
+    let player = leadingPlayer
+    leadingTimeControlObserver = player.observe(
+      \.timeControlStatus, options: [.new]
+    ) { [weak self] obs, _ in
+      let isPlayingNow = obs.timeControlStatus == .playing
+      DispatchQueue.main.async {
+        guard let self else { return }
+        self.delegate?.engineStateMaybeChanged(self, reason: nil)
+        self.delegate?.engineIsPlayingChanged(self, isPlaying: isPlayingNow)
+      }
+    }
+    if let item = player.currentItem {
+      leadingItemTracksObserver = item.observe(
+        \.tracks, options: [.new]
+      ) { [weak self] obs, _ in
+        // tracks fires on every mutation including transient empty
+        // states during seek; only fire format-changed when the
+        // tracks array is populated so the gapless KVO path's
+        // dedup contract is matched.
+        guard !obs.tracks.isEmpty else { return }
+        DispatchQueue.main.async {
+          guard let self else { return }
+          self.delegate?.engineActiveItemFormatChanged(self)
+        }
+      }
+      // Bootstrap: `.new`-only KVO won't fire when the item's tracks are
+      // ALREADY populated at install time — a cached / preloaded asset, e.g. a
+      // skip to a lookahead-cached track. Without this the format-change never
+      // propagates and the now-playing format stays nil. Mirrors what
+      // `.initial` would have delivered.
+      if !item.tracks.isEmpty {
+        DispatchQueue.main.async { [weak self] in
+          guard let self else { return }
+          self.delegate?.engineActiveItemFormatChanged(self)
+        }
+      }
+      leadingItemStatusObserver = item.observe(
+        \.status, options: [.new]
+      ) { [weak self] obs, _ in
+        guard obs.status == .failed else { return }
+        let underlying = obs.error ?? NSError(
+          domain: "CrossfadeEngine", code: -1, userInfo: nil
+        )
+        DispatchQueue.main.async {
+          guard let self else { return }
+          self.delegate?.engineDidFailWithError(self, error: underlying)
+        }
+      }
+    }
+  }
+
+  private func teardownLeadingObservers() {
+    leadingTimeControlObserver?.invalidate()
+    leadingTimeControlObserver = nil
+    leadingItemTracksObserver?.invalidate()
+    leadingItemTracksObserver = nil
+    leadingItemStatusObserver?.invalidate()
+    leadingItemStatusObserver = nil
+  }
+
+  private func handleItemDidPlayToEnd(_ note: Notification) {
+    guard let item = note.object as? AVPlayerItem,
+          item === leadingPlayer.currentItem else { return }
+    delegate?.engineDidPlayItemToEnd(self)
+    // Repeat-one: loop the current item in place instead of advancing
+    // or ending the queue. The fade is suppressed under `.track`, so
+    // the item reaches its true end here; seek to zero + play replays
+    // it, matching the gapless engine's repeat-track replay. Applies on
+    // every track (incl. the last), so it must precede the queue-end check.
+    if repeatMode == .track, !fadeInFlight, currentIndex >= 0 {
+      leadingPlayer.seek(to: .zero)
+      leadingPlayer.play()
+      return
+    }
+    // Queue-end detection: leading played its last item to end
+    // AND no fade is in flight (mid-fade end is normal — the
+    // standby is about to be promoted, not the queue ending).
+    // [currentIndex] is still pre-swap during a fade; gating on
+    // [fadeInFlight] avoids firing enginePlaybackEnded one item
+    // too early when the penultimate track ends naturally during
+    // its outgoing fade.
+    if !fadeInFlight,
+       currentIndex >= 0,
+       currentIndex >= queue.count - 1 {
+      delegate?.enginePlaybackEnded(self)
+    }
+  }
+
+  private func handleItemFailedToPlayToEnd(_ note: Notification) {
+    guard let item = note.object as? AVPlayerItem,
+          item === leadingPlayer.currentItem else { return }
+    let underlying = (note.userInfo?[AVPlayerItemFailedToPlayToEndTimeErrorKey] as? Error)
+      ?? item.error
+      ?? NSError(domain: "CrossfadeEngine", code: -2, userInfo: nil)
+    delegate?.engineDidFailWithError(self, error: underlying)
+  }
+}