react-native-queue-player 1.2.0 → 2.0.0

package/ios/TrackPlayer+SleepTimer.swift

@@ -0,0 +1,175 @@
+import Foundation
+import NitroModules
+
+extension TrackPlayer {
+  func setSleepTimer(seconds: Double) throws -> Promise<Void> {
+    return enqueue { self.setSleepTimerInternal(seconds: seconds) }
+  }
+  func setSleepTimerToTrackEnd() throws -> Promise<Void> {
+    return enqueue { self.armSleepTimerToTrackEndInternal() }
+  }
+  func clearSleepTimer() throws -> Promise<Void> {
+    return enqueue { self.clearSleepTimerInternal() }
+  }
+  func getSleepTimer() throws -> SleepTimerState {
+    return onPlayerQueueSync { self.sleepTimerSnapshot() }
+  }
+  func onSleepTimerChange(
+    callback: @escaping (_ state: SleepTimerState) -> Void
+  ) throws -> () -> Void {
+    let id = sleepTimerListeners.add(callback)
+    playerQueue.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 = DispatchSource.makeTimerSource(queue: playerQueue)
+    timer.schedule(
+      deadline: .now() + Self.sleepTimerTickInterval,
+      repeating: Self.sleepTimerTickInterval)
+    timer.setEventHandler { [weak self] in
+      self?.onSleepTimerTick()
+    }
+    sleepTimerTimer = timer
+    // The source is resumed exactly once and never suspended — a suspended
+    // source traps libdispatch on release.
+    timer.resume()
+  }
+
+  /// Caller must be on `playerQueue` — cancelling from the source's own
+  /// queue is what guarantees no further tick.
+  internal func stopSleepTimerTick() {
+    sleepTimerTimer?.cancel()
+    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)
+    applySleepTimerResult(result)
+  }
+
+  /// Apply a `SleepTimerCore.Tick` decision to the engine — fade, state emit,
+  /// and the boundary pause. Shared by the polling tick and the real track-end
+  /// signal (`handlePlayerItemDidPlayToEndTime`).
+  internal func applySleepTimerResult(_ result: SleepTimerCore.Tick) {
+    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
+        // The timer's pause is a transport intent like the user's: without
+        // clearing these, a drain that follows (the timer firing at a track
+        // end on the last installed item) or a buffer refill would restart
+        // playback the timer just stopped.
+        self.wantsToPlay = false
+        self.isRecoveringFromStall = false
+        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)
+  }
+}

package/ios/TrackPlayer+State.swift

@@ -0,0 +1,108 @@
+import Foundation
+
+extension TrackPlayer {
+  // MARK: - State snapshots
+  //
+  // Nitro calls these getters on a JS worker thread. Player state lives
+  // on `playerQueue`, so every read hops there with `onPlayerQueueSync`,
+  // which runs the body inline when the caller is already on that queue
+  // (a `sync` from the queue onto itself would deadlock). The cached
+  // `canSkip*` Bools are written on `playerQueue` by
+  // `recomputeCapabilities()`, so the same hop reads them consistently.
+  func getState() throws -> PlayerState {
+    // The receiver owns playback during a cast session — the local engine is
+    // parked and paused for its duration, so its derived state describes
+    // nothing the user can hear. Until the receiver has reported (session
+    // still activating, holding its initial `.idle`) the local read is the
+    // better answer; after that the receiver is authoritative, including a
+    // later `.idle`, which means it genuinely has nothing loaded.
+    if let remote = PlaybackStateRouter.shared.activeRemote(), remote.hasReportedState {
+      return remote.lastState.asPlayerState
+    }
+    return onPlayerQueueSync {
+      // 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 onPlayerQueueSync { Double(self.currentTrackIndex) }
+  }
+  func getCurrentTrackSource() throws -> TrackSource? {
+    return onPlayerQueueSync { self.currentTrackSource }
+  }
+  func getCanSkipNext() throws -> Bool {
+    return onPlayerQueueSync { self.cachedSkipCapability.canSkipNext }
+  }
+  func getSkipCapability() throws -> SkipCapability {
+    return onPlayerQueueSync { self.cachedSkipCapability }
+  }
+  func getCanSkipPrevious() throws -> Bool {
+    return onPlayerQueueSync { self.cachedSkipCapability.canSkipPrevious }
+  }
+  func getPlaybackSpeed() throws -> Double {
+    return onPlayerQueueSync { Double(self.playbackSpeedState) }
+  }
+  func getVolume() throws -> Double {
+    return onPlayerQueueSync { Double(self.volumeState) }
+  }
+  func getRemoteControls() throws -> RemoteControlOptions {
+    return onPlayerQueueSync {
+      let options: RemoteControlOptions = .init(
+        skipMode: self.remoteSkipMode,
+        forwardJumpInterval: self.remoteForwardInterval,
+        backwardJumpInterval: self.remoteBackwardInterval)
+      return options
+    }
+  }
+
+  func getBufferState() throws -> BufferState {
+    return onPlayerQueueSync { self.currentBufferState }
+  }
+
+  func getIsSeekable() throws -> Bool {
+    return onPlayerQueueSync {
+      guard let item = self.engine?.currentMediaItem else { return true }
+      return !item.seekableTimeRanges.isEmpty
+    }
+  }
+
+  func isFullyBuffered() throws -> Bool {
+    return onPlayerQueueSync { 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.
+    playerQueue.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)
+    playerQueue.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) }
+  }
+}

package/ios/TrackPlayer+Threading.swift

@@ -0,0 +1,135 @@
+import Foundation
+import NitroModules
+
+extension TrackPlayer {
+  /// True when the caller is already executing on `playerQueue`.
+  ///
+  /// `DispatchQueue.sync` runs its body on the calling thread, so a thread
+  /// identity test answers the wrong question — it reports "main" for work
+  /// serialised on the queue and would let a nested `sync` deadlock. The
+  /// queue's own specific travels with the execution context instead.
+  internal var isOnPlayerQueue: Bool {
+    DispatchQueue.getSpecific(key: playerQueueKey) == ObjectIdentifier(self)
+  }
+
+  /// Claim the audio session, then start the engine.
+  ///
+  /// Every path that starts playback goes through here so activation cannot be
+  /// forgotten at a new one. `activateIfNeeded` is idempotent, so the cost
+  /// after the first play is a bool check.
+  ///
+  /// Activation is deliberately not done at `configure()`: that would stop
+  /// whatever else the user is listening to the moment a consumer app
+  /// launches, before they have pressed anything.
+  internal func beginPlayback() {
+    audioSession.activateIfNeeded()
+    engine?.play()
+  }
+
+  /// Enqueue `body` on `playerQueue` **at call time**, on the calling thread,
+  /// and resolve the returned promise when it completes.
+  ///
+  /// This is what makes the queue's FIFO order equal the JS call order.
+  /// `Promise.async` starts an unstructured `Task`, and two Tasks created back
+  /// to back have no ordering relationship with each other — so a body that
+  /// hops onto the queue *inside* the Task reaches the player at an arbitrary
+  /// later point. Two calls issued in order from JS could then arrive
+  /// reversed: `play()` then `pause()` landing as pause-then-play, leaving
+  /// audio running after the user paused it.
+  ///
+  /// A serial queue gives mutual exclusion, not ordering. Ordering comes from
+  /// when the work is enqueued, which is why this runs before returning.
+  internal func enqueue(_ body: @escaping () -> Void) -> Promise<Void> {
+    let promise = Promise<Void>()
+    playerQueue.async {
+      body()
+      promise.resolve()
+    }
+    return promise
+  }
+
+  /// Enqueue a mutation at call time and hand its result to a receiver mirror
+  /// that runs off the queue.
+  ///
+  /// The enqueue is what fixes ordering against other player work — a later
+  /// call cannot overtake this one. Doing it with `async` rather than `sync`
+  /// matters just as much: the mutation can rebuild the whole player queue,
+  /// and `sync` would run that on the JS thread.
+  ///
+  /// `mirror` awaits the receiver afterwards, holding neither the queue nor
+  /// the calling thread, and is chained behind the previous mutation's mirror
+  /// so the receiver sees mutations in the order they were made. The promise
+  /// resolves once the mirror returns, so a consumer awaiting the call knows
+  /// local and remote are both settled.
+  internal func enqueueThenMirror<T>(
+    _ body: @escaping () -> T,
+    mirror: @escaping (T, _ generation: UInt64) async -> Void
+  ) -> Promise<Void> {
+    let promise = Promise<Void>()
+    playerQueue.async {
+      self.queueMutationGeneration &+= 1
+      let generation = self.queueMutationGeneration
+      let value = body()
+      let previous = self.castMirrorChain
+      self.castMirrorChain = Task {
+        // Deltas are only correct against a receiver that has applied
+        // everything before them, so this waits rather than racing. A failed
+        // mirror still completes its Task, so one bad round-trip cannot wedge
+        // the chain.
+        await previous?.value
+        await mirror(value, generation)
+        promise.resolve()
+      }
+    }
+    return promise
+  }
+
+  /// Value-returning variant of `enqueue`.
+  internal func enqueueValue<T>(_ body: @escaping () -> T) -> Promise<T> {
+    let promise = Promise<T>()
+    playerQueue.async {
+      promise.resolve(withResult: body())
+    }
+    return promise
+  }
+
+  /// Throwing variant of `enqueue` — a thrown error rejects the JS promise
+  /// with its message, as `Promise.async` does for a throwing body.
+  internal func enqueueThrowing(_ body: @escaping () throws -> Void) -> Promise<Void> {
+    let promise = Promise<Void>()
+    playerQueue.async {
+      do {
+        try body()
+        promise.resolve()
+      } catch {
+        promise.reject(withError: error)
+      }
+    }
+    return promise
+  }
+
+  /// Serialise a mutation body on `playerQueue` and return a
+  /// Promise-compatible awaitable. Centralising here keeps every access to
+  /// player state on one queue, which is what makes the state safe to read
+  /// without locks inside these bodies.
+  internal func onPlayerQueue(_ body: @escaping () -> Void) async {
+    await withCheckedContinuation { (cont: CheckedContinuation<Void, Never>) in
+      playerQueue.async {
+        body()
+        cont.resume()
+      }
+    }
+  }
+
+  /// Run `body` on `playerQueue` synchronously and return its value. Used by
+  /// the Nitro getters and the listener register / dispose paths, which are
+  /// not Promise-wrapped and run on whatever thread the JS bridge uses.
+  ///
+  /// Running inline when already on the queue is what makes re-entrant calls
+  /// safe: `playerQueue.sync` from a block already on `playerQueue` is an
+  /// immediate deadlock.
+  internal func onPlayerQueueSync<T>(_ body: () -> T) -> T {
+    if isOnPlayerQueue { return body() }
+    return playerQueue.sync(execute: body)
+  }
+}

package/ios/TrackPlayer+Transport.swift

@@ -0,0 +1,267 @@
+import AVFoundation
+import NitroModules
+
+extension TrackPlayer {
+  // MARK: - Transport — pass-through to AVQueuePlayer.
+
+  func play() throws -> Promise<Void> {
+    return enqueue {
+      if CastTransportRouter.routePlay() { return }
+      // Stuck-recovery: a user re-tapping play after an exhausted-retries error
+      // is asking for this track again, so it gets the allowance the consumer
+      // configured back and a rebuild. Not a hard-coded 1: `autoRetries: 0`
+      // asked for none.
+      if self.lastReportedState == .error,
+         self.currentTrackIndex >= 0,
+         self.currentTrackIndex < self.queueItemIds.count {
+        let qid = self.queueItemIds[self.currentTrackIndex]
+        if (self.retryAttemptsRemaining[qid] ?? 0) == 0 {
+          // Asking for this track to play is incompatible with the queue being
+          // over, so `reachedQueueEnd` cannot survive it.
+          self.reachedQueueEnd = false
+          self.retryAttemptsRemaining[qid] = self.effectiveAutoRetries()
+          // A scheduled attempt for this item is superseded by the rebuild below.
+          if self.pendingRetryQueueItemId == qid { self.pendingRetryQueueItemId = nil }
+          self.lastErrorQueueItemId = nil
+          self.lastErrorCode = nil
+          // Rebuild whenever an engine is live — the rebuild is
+          // engine-agnostic, and the failed item has to be
+          // reconstructed on either engine for the retry to reach it.
+          // Forced: the failed item keeps its `queueItemId`, so a rebuild
+          // that compares identity would find nothing to do.
+          if self.engine != nil {
+            self.performingMutation {
+              self.fullRebuildPlayerQueue(forcingReinstall: true)
+            }
+          }
+        }
+      }
+      // At the end of the queue there is nothing to play: the engine is
+      // parked on the finished track (or drained), and writing a rate onto
+      // it would report `.playing` for a moment or, on some OS versions,
+      // re-post the item's end. A skip, a seek or a fresh queue leaves this
+      // state; play() alone restarts nothing.
+      if self.reachedQueueEnd, self.currentTrackIndex >= 0 { return }
+      self.pendingStateChangeReason = self.pendingStateChangeReason ?? .user
+      self.wantsToPlay = true
+      // An explicit play ends an interruption from the user's side: the
+      // system does not always deliver `.ended` (an app suspended mid-call
+      // never sees it), and the flag would otherwise keep retries, window
+      // refills and network recovery disabled for the rest of the session.
+      self.isInterrupted = false
+      self.beginPlayback()
+      self.recomputeBufferState()
+    }
+  }
+
+  func retry() throws -> Promise<Void> {
+    return enqueue {
+      // During cast the receiver owns playback — forward a play so a failed
+      // receiver item re-attempts.
+      if CastTransportRouter.routePlay() { return }
+      // A user asking for a retry has a reason, and the library is not the one
+      // to judge it. This is the manual attempt once the automatic one is
+      // spent, so gating it on the player's state would gate recovery on the
+      // state of a player that has already failed to recover — and a wedged
+      // decoder still reporting `playing` is exactly when someone reaches for
+      // the button.
+      //
+      // Only the bounds remain: no current track is genuinely nothing to
+      // retry, which is not second-guessing the request.
+      guard 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
+      // Asking for this track to play is incompatible with the queue being over,
+      // and a queue whose only track failed to load has already drained: without
+      // this the rebuild seats an item into a queue that believes it is finished.
+      self.reachedQueueEnd = false
+      // The configured budget, not a hard-coded 1: this restores the track's
+      // automatic allowance for whatever fails *next*, and a consumer who set
+      // `autoRetries: 0` asked for none.
+      self.retryAttemptsRemaining[qid] = self.effectiveAutoRetries()
+      // A scheduled attempt for this item is superseded by the rebuild below;
+      // leaving it set would suppress the rebuilt item's own failure until the
+      // earlier attempt fired.
+      if self.pendingRetryQueueItemId == qid { self.pendingRetryQueueItemId = nil }
+      self.lastErrorQueueItemId = nil
+      self.lastErrorCode = nil
+      // Rebuild whenever an engine is live — the rebuild is
+      // engine-agnostic, and the failed item has to be reconstructed
+      // on either engine for the retry to reach it. Forced: the failed
+      // item keeps its `queueItemId`, so a rebuild that compares
+      // identity would find nothing to do.
+      if self.engine != nil {
+        self.performingMutation {
+          self.fullRebuildPlayerQueue(forcingReinstall: true)
+        }
+      }
+      self.pendingStateChangeReason = self.pendingStateChangeReason ?? .user
+      self.wantsToPlay = true
+      self.beginPlayback()
+      if resumePos.isFinite, resumePos > 0 {
+        _ = try? self.seekTo(position: resumePos)
+      }
+      self.recomputeBufferState()
+    }
+  }
+
+  func pause() throws -> Promise<Void> {
+    return enqueue {
+      if CastTransportRouter.routePause() { return }
+      self.pendingStateChangeReason = self.pendingStateChangeReason ?? .user
+      self.wantsToPlay = false
+      // An explicit pause outranks a pending stall recovery: without this the
+      // buffer refilling afterwards would restart audio the user just stopped.
+      self.isRecoveringFromStall = 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 enqueue {
+      if CastTransportRouter.routeStop() { return }
+      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> {
+    // Enqueued at call time, like every other transport method, so a seek
+    // reaches the player in the order JS issued it. The promise resolves once
+    // the seek's own completion has landed, which is why this builds the
+    // promise by hand rather than using `enqueue`.
+    let promise = Promise<Void>()
+    playerQueue.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 {
+        promise.resolve()
+        return
+      }
+      if CastTransportRouter.routeSeekTo(positionMs: Int64(position * 1000.0)) {
+        promise.resolve()
+        return
+      }
+
+      // Every player + queue read and the seek itself run on this one hop, so
+      // the player never crosses a concurrency boundary. The return value
+      // carries whether a seek was issued: the crossfade branch and the
+      // drained-gapless branch complete in place and yield false.
+      //
+      // Named rather than inlined so the two early-return branches and the
+      // seek branch share one exit.
+      let issueSeek: () -> Bool = {
+        // 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 false }
+          // 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
+          let engineIdx: Int
+          if let installed = self.engineIndex(forQueuePosition: self.currentTrackIndex) {
+            engineIdx = installed
+          } else {
+            // Active track absent from the engine — reinstall it, then seek
+            // within the reinstalled run so the position is applied rather
+            // than dropped with a resolved promise.
+            self.performingMutation { self.fullRebuildPlayerQueue() }
+            guard let reinstalled = self.engineIndex(forQueuePosition: self.currentTrackIndex)
+            else { return false }
+            engineIdx = reinstalled
+          }
+          engine.seek(toIndex: engineIdx, position: seekTarget)
+          self.milestoneTracker.seek(
+            durationSec: self.effectiveMilestoneDuration(playerDuration: duration),
+            positionSec: seekTarget)
+          self.nowPlayingInfo.refreshPositionAndRate(self.nowPlayingSnapshot())
+          return false
+        }
+
+        guard let player = self.player else { return false }
+        // A gapless player drained at the end of the queue has no item to
+        // seek in: reinstall the finished track first, as a same-index skip
+        // does, so a seek after the end replays it on every engine. Seeking
+        // is what leaves the ended state, so the flag clears here.
+        if player.currentItem == nil, self.reachedQueueEnd,
+           self.currentTrackIndex >= 0, self.currentTrackIndex < self.tracks.count {
+          self.reachedQueueEnd = false
+          self.performingMutation { self.fullRebuildPlayerQueue() }
+        }
+        guard let item = player.currentItem else { return false }
+        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)
+        // Consume jumped-over milestones BEFORE issuing the (async) seek so a
+        // time-jump progress tick that fires during the seek can't emit the
+        // thresholds the seek skips over.
+        self.milestoneTracker.seek(
+          durationSec: self.effectiveMilestoneDuration(
+            playerDuration: (itemDuration.isFinite && itemDuration > 0) ? itemDuration : 0),
+          positionSec: seekTarget)
+        // 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.
+        self.pendingStateChangeReason = self.pendingStateChangeReason ?? .user
+        player.seek(
+          to: CMTime(seconds: seekTarget, preferredTimescale: CMTimeScale(NSEC_PER_SEC)),
+          toleranceBefore: .zero,
+          toleranceAfter: .zero
+        ) { _ in
+          // This closure captures `player`, so a teardown that drops every
+          // other reference cannot deallocate it with the seek still pending.
+          // AVFoundation invokes the handler when the seek completes or is
+          // interrupted, and the capture is released with it.
+          _ = player
+          self.playerQueue.async {
+            // 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.
+            self.nowPlayingInfo.refreshPositionAndRate(self.nowPlayingSnapshot())
+            promise.resolve()
+          }
+        }
+        return true
+      }
+      // A branch that completed in place has nothing pending, so the promise
+      // resolves here; the seek branch resolves from its completion instead.
+      if !issueSeek() { promise.resolve() }
+    }
+    return promise
+  }
+}