react-native-queue-player 1.1.2 → 2.0.0

package/ios/PlaybackEngine.swift

@@ -15,41 +15,40 @@ import Foundation
 /// track-boundary scheduling. The lib's `TrackPlayer` holds the canonical
 /// queue model + listener registries + system-side surfaces (NowPlaying,
 /// RemoteCommands, AudioSession, ArtworkResolver) and routes transport /
-/// queue calls through whichever engine is active. Engine swap (gapless ↔
-/// crossfade) is a `handoff` at the next track boundary.
+/// queue calls through whichever engine is active. An engine swap (gapless ↔
+/// crossfade) is `TrackPlayer.applyEngineSwapForMode`: it builds the new
+/// engine, seeds it through `setItems`, then releases the old one.
 ///
-/// Threading: methods are called on the main actor by convention. State
-/// queries (positions, indices, isPlaying) are read off the underlying
-/// player and so reflect the same single-threaded view AVFoundation
-/// provides on the main thread. `async` methods are launched on the same
-/// actor; impl is responsible for any internal off-actor work (e.g. the
-/// crossfade engine's standby preroll).
+/// Threading: `TrackPlayer` calls every method on its `playerQueue`, a
+/// private serial queue, and every delegate fire lands on that queue.
+/// The crossfade engine is constructed confined to it and hops each
+/// AVFoundation observer, notification and timer callback onto it before
+/// firing (a few fires are also synchronous inside a `setItems` / `seek`
+/// / `remove` call). The gapless engine does not use the delegate at all:
+/// `TrackPlayer` observes its player directly and does its own hop. State
+/// queries (positions, indices, isPlaying) read the underlying player from
+/// that queue. An engine is responsible for any internal off-queue work
+/// (the crossfade engine's standby preroll) and for returning to the queue
+/// before touching shared state.
 protocol PlaybackEngine: AnyObject {
 
-  /// Build the underlying player(s), apply [items] starting at
-  /// [startIndex] / [startPositionSeconds], and wait for the
-  /// underlying player(s) to reach a playable state.
-  ///
-  /// Empty [items] is allowed; the engine prepares an empty queue
-  /// and `currentMediaItemIndex` returns `-1` until items arrive
-  /// via `setItems` / `insertItems`.
-  func prepare(
-    items: [AVPlayerItem],
-    startIndex: Int,
-    startPositionSeconds: TimeInterval
-  ) async
-
   /// Release the underlying player(s) and stop all background work.
   /// After `release`, no further methods are valid.
   func release()
 
   // MARK: - Queue mutation
 
-  /// Drain the queue and re-install the slice of [items] from
-  /// [startIndex] onward. Items before [startIndex] are not held —
-  /// `AVQueuePlayer` is forward-only and the canonical queue model
-  /// lives on `TrackPlayer`. After the call,
-  /// `allMediaItems.count == max(0, items.count - startIndex)`.
+  /// Drain the queue and install [items], beginning playback at
+  /// [startIndex]. Callers pass a run that may start behind the playhead, so
+  /// [startIndex] names where in that run to begin rather than where to cut
+  /// it: an engine holds every item it is given unless it cannot.
+  ///
+  /// `GaplessEngine` cannot: `AVQueuePlayer` is forward-only and consumes
+  /// finished items, so it drops everything before [startIndex] and
+  /// `allMediaItems.count == max(0, items.count - startIndex)` there.
+  /// `CrossfadeEngine` holds the whole run, which is what lets it keep a
+  /// trail behind the playhead for an immediate backward skip.
+  ///
   /// Active index resolves to `items[startIndex]` at
   /// [startPositionSeconds].
   ///
@@ -67,8 +66,8 @@ protocol PlaybackEngine: AnyObject {
   ///
   /// Caller (`TrackPlayer`) constructs `[AVPlayerItem]` via
   /// `AVQueueBuilder` so consumer config (HTTP headers, user-agent,
-  /// lookahead-cache file:// rewrites) is applied before items
-  /// reach the engine.
+  /// read-through server routing) is applied before items reach
+  /// the engine.
   func setItems(
     _ items: [AVPlayerItem],
     startIndex: Int,
@@ -96,13 +95,16 @@ protocol PlaybackEngine: AnyObject {
   /// Remove [item] from the engine's queue. Removing the current
   /// item on `GaplessEngine` triggers `AVQueuePlayer` auto-advance
   /// to the next queued item; on `CrossfadeEngine` removing the
-  /// leading leg's item triggers boundary handoff + standby
-  /// promotion. No-op when [item] is not present.
+  /// current item cancels any pending fade and replaces the leading
+  /// leg's item with the one now at that index (the previous item when
+  /// the removed one was last), or drains when the queue is empty.
+  /// No-op when [item] is not present.
   func remove(_ item: AVPlayerItem)
 
   /// Remove every item from the queue. After this call,
   /// `currentMediaItem == nil` and `allMediaItems` is empty. Used
-  /// by `TrackPlayer.fullRebuildPlayerQueue` before re-inserting
+  /// by `TrackPlayer.fullRebuildPlayerQueue` when it installs a whole slice,
+  /// before re-inserting
   /// the post-mutation queue snapshot.
   func removeAllItems()
 
@@ -118,6 +120,12 @@ protocol PlaybackEngine: AnyObject {
   func play()
   func pause()
   func stop()
+  /// Seek to [index] within the engine's own queue, at [position].
+  ///
+  /// [index] is an index into the slice this engine was handed, **not** a
+  /// queue position — the two differ whenever the caller installed anything
+  /// other than the whole track list. Callers translate by `queueItemId`
+  /// identity before calling.
   func seek(toIndex index: Int, position: TimeInterval)
   func skipToNext()
   func skipToPrevious()
@@ -141,10 +149,14 @@ protocol PlaybackEngine: AnyObject {
 
   // MARK: - State
 
-  /// Current item index within the engine's queue. Returns `-1`
+  /// Current item index within the engine's own queue. Returns `-1`
   /// when the queue is empty (matches the canonical sentinel in
-  /// `TrackPlayer`). When non-empty, mirrors the AVQueuePlayer's
-  /// resolved index.
+  /// `TrackPlayer`).
+  ///
+  /// This is **not** a queue position — it counts within the slice the
+  /// engine was handed. Resolve the active track by item identity
+  /// (`currentMediaItem.queueItemId`) rather than reading this as an index
+  /// into the consumer's track list.
   var currentMediaItemIndex: Int { get }
   var currentPositionSeconds: TimeInterval { get }
   var currentDurationSeconds: TimeInterval { get }
@@ -163,6 +175,40 @@ protocol PlaybackEngine: AnyObject {
   /// duplicate it for hot-path reads.
   var allMediaItems: [AVPlayerItem] { get }
 
+  /// Identity of the item actually being heard.
+  ///
+  /// `currentMediaItem` reports the incoming leg the moment a crossfade is in
+  /// flight, which is right for "what is the queue moving to" and wrong for
+  /// "where is the run anchored". Callers that reason about the installed run
+  /// — where it starts, what may be trimmed behind it — read this instead, and
+  /// it stays on the outgoing leg until the fade completes.
+  var leadingQueueItemId: String? { get }
+
+  /// Identities of the items attached to the engine's players right now.
+  ///
+  /// Not the whole installed run — only what is loaded and about to be, or
+  /// already, heard. A queue mutation that touches one of these has to be
+  /// applied to the engine at once; one that does not can wait for a fade to
+  /// finish rather than cancelling it.
+  ///
+  /// Mid-fade a crossfading engine reports both legs, which is the only
+  /// truthful answer while two items are audible.
+  ///
+  /// Required rather than defaulted, for the same reason as
+  /// `isFadePendingOrActive` and more so: an engine that under-reports has a
+  /// mutation to an audible item deferred, and the fade then runs into a track
+  /// the queue no longer has.
+  var attachedQueueItemIds: [String] { get }
+
+  /// Whether a crossfade is scheduled or running.
+  ///
+  /// Every branch that changes the installed items cancels an in-flight fade,
+  /// so work that can wait — extending the run, trimming behind it — asks
+  /// first rather than cutting the fade short. Required rather than defaulted:
+  /// an engine that answers wrongly has its fades cut short silently, so each
+  /// one states its own answer.
+  var isFadePendingOrActive: Bool { get }
+
   // MARK: - Effect chain
 
   /// Set the single active `AudioMixProvider`. The engine consults
@@ -182,33 +228,15 @@ protocol PlaybackEngine: AnyObject {
   /// No-op when no provider is set.
   func refreshAllItemMixes()
 
-  // MARK: - Handoff
-
-  /// Hand playback off to [nextEngine] when the user changes
-  /// `PlaybackMode`.
-  ///
-  /// Contract:
-  ///  - The receiver inherits the donor's queue, current index, and
-  ///    current position; the caller does NOT pre-call `prepare` on
-  ///    [nextEngine].
-  ///  - When [atTrackBoundary] is `true`, the donor plays the
-  ///    active track to its natural end and the receiver starts
-  ///    playing the NEXT queue position fresh.
-  ///  - When [atTrackBoundary] is `false` (idle player or empty
-  ///    queue), the swap is immediate; receiver picks up at the
-  ///    inherited position.
-  ///  - The donor's `release` is the caller's responsibility AFTER
-  ///    the boundary fires; the engine itself does not self-release.
-  func handoff(to nextEngine: PlaybackEngine, atTrackBoundary: Bool) async
-
   // MARK: - Delegate
 
-  /// Single delegate receiving state / track / progress / error /
-  /// queue-end events. `TrackPlayer` is the canonical delegate;
-  /// engines fire on the main actor.
+  /// Single delegate receiving state / track / error /
+  /// queue-end events. `TrackPlayer` is the canonical delegate; the
+  /// crossfade engine fires it on `playerQueue`, the gapless engine
+  /// never fires it (`TrackPlayer` leaves its delegate nil).
   ///
-  /// Threading: setter MUST be invoked on the main actor to avoid
-  /// a write-vs-fire race during `handoff`.
+  /// Threading: set on `playerQueue`, the queue the fires run on, so a
+  /// write cannot race a fire during an engine swap.
   var delegate: PlaybackEngineDelegate? { get set }
 }
 
@@ -240,11 +268,6 @@ protocol PlaybackEngineDelegate: AnyObject {
     reason: StateChangeReason?
   )
 
-  /// Fires when the underlying player's `timeControlStatus`
-  /// transitions to / from `.playing`. Drives diagnostics +
-  /// progress-tick wake-up.
-  func engineIsPlayingChanged(_ engine: PlaybackEngine, isPlaying: Bool)
-
   /// Fires on `AVPlayer.currentItem` KVO when the active item
   /// changes (auto-advance, user skip, queue replace). The
   /// delegate translates against its own state machine (e.g.
@@ -257,10 +280,16 @@ protocol PlaybackEngineDelegate: AnyObject {
   /// counterpart fires on `Player.Listener.onTracksChanged`.
   func engineActiveItemFormatChanged(_ engine: PlaybackEngine)
 
-  /// Fires on a player item failure (`AVPlayerItem.failedToPlayToEndTime`
-  /// or `AVPlayerItem.status == .failed`). The delegate maps the
-  /// underlying `Error` via the lib's `PlaybackErrorMapping`.
-  func engineDidFailWithError(_ engine: PlaybackEngine, error: Error)
+  /// A playback failure, with the item it happened on when the engine can name
+  /// it.
+  ///
+  /// The item is what makes the automatic retry reachable: the retry is keyed
+  /// by `queueItemId`, so a failure reported without one is surfaced to the
+  /// consumer and never retried. Engines that know which item failed must say
+  /// so — both of `CrossfadeEngine`'s failure paths do, since each is already
+  /// filtered to the leading leg's current item.
+  func engineDidFailWithError(
+    _ engine: PlaybackEngine, error: Error, item: AVPlayerItem?)
 
   /// Fires on every `AVPlayerItemDidPlayToEndTime` — i.e. each
   /// item's natural end, including non-terminal items in a queue.
@@ -286,10 +315,12 @@ protocol PlaybackEngineDelegate: AnyObject {
   /// subsequent `engineDidTransitionTrack` for the same incoming
   /// index is a structural KVO echo and must be deduplicated.
   ///
-  /// Crossfade-only — `GaplessEngine` never invokes this.
-  /// `incomingIndex` is the global queue index of the fading-in
-  /// track.
-  func engineCrossfadeDidBegin(_ engine: PlaybackEngine, incomingIndex: Int)
+  /// Crossfade-only — `GaplessEngine` never invokes this. The
+  /// incoming track is read from `engine.currentMediaItem`, which
+  /// already resolves to the standby leg once the fade is in flight;
+  /// the delegate maps that item to a queue position by identity
+  /// rather than trusting an engine-relative index.
+  func engineCrossfadeDidBegin(_ engine: PlaybackEngine)
 
   /// Fires when an in-flight crossfade is cancelled before
   /// `swapRoles` runs (pause / stop / audio-focus loss / queue
@@ -300,20 +331,78 @@ protocol PlaybackEngineDelegate: AnyObject {
   /// `engineCrossfadeDidBegin`: only fires when a `DidBegin` was
   /// fired earlier and the fade did not complete.
   ///
-  /// Crossfade-only. `revertedIndex` is the leading-leg index that
-  /// is now the active track.
-  func engineCrossfadeDidCancel(_ engine: PlaybackEngine, revertedIndex: Int)
+  /// Crossfade-only. The reverted track is read from
+  /// `engine.currentMediaItem`, which resolves back to the leading leg
+  /// once `fadeInFlight` clears.
+  func engineCrossfadeDidCancel(_ engine: PlaybackEngine)
+
+  /// A fade is no longer scheduled or running, however it ended.
+  ///
+  /// Distinct from `engineCrossfadeDidCancel`, which reports that an
+  /// *in-flight* fade was reverted and carries a track change with it. This
+  /// fires for every end of every fade — completed, cancelled, abandoned
+  /// during the arm window, timed out — because work that waits on a fade has
+  /// to be released by all of them, not only the ones a listener cares about.
+  func engineFadeDidSettle(_ engine: PlaybackEngine)
+
+  /// The active leg's buffer flags changed (`isPlaybackBufferEmpty` /
+  /// `isPlaybackLikelyToKeepUp` / `isPlaybackBufferFull`). Prompts a
+  /// buffer-state recompute so the discrete `onBufferStateChange` surface
+  /// tracks the crossfade engine's leg the same way it tracks the gapless
+  /// `AVQueuePlayer`'s item KVO. Buffer state only — no direct player-state
+  /// emission.
+  func engineBufferStateMaybeChanged(_ engine: PlaybackEngine)
+}
+
+extension PlaybackEngineDelegate {
+  /// Nothing to release by default.
+  func engineFadeDidSettle(_ engine: PlaybackEngine) {}
+  /// The gapless engine drives buffer recompute through its own item KVO, not
+  /// this delegate; conformers that do not surface buffer state ignore it.
+  func engineBufferStateMaybeChanged(_ engine: PlaybackEngine) {}
+}
+
+extension PlaybackEngine {
+  /// An engine with one leg is always leading with the item it reports as
+  /// current; only a crossfading engine has two ends that can disagree.
+  var leadingQueueItemId: String? { currentMediaItem?.queueItemId }
+
 }
 
 /// Single-slot audio-mix provider. The equalizer + visualizer share
 /// a single provider that builds an `MTAudioProcessingTap`-backed
 /// `AVAudioMix` per `AVPlayerItem` the engine constructs.
 ///
-/// `audioMix(for:)` is called on the main thread; implementations
-/// may allocate freshly or cache + reuse. Returning `nil` skips
+/// `audioMix(for:)` is called on the mix dispatch target — `TrackPlayer`
+/// points it at `playerQueue`; implementations may allocate freshly or
+/// cache + reuse. Returning `nil` skips
 /// attachment for that item — used to bypass mix on items that
 /// don't support a tap (HLS sources).
 protocol AudioMixProvider: AnyObject {
   /// Build the audio mix for [item], or return `nil` to skip.
   func audioMix(for item: AVPlayerItem) -> AVAudioMix?
+
+  /// Declare which asset is active, without building a mix. `audioMix(for:)`
+  /// announces whatever item it is handed, so a caller that refreshes several
+  /// items uses this to name the one actually playing.
+  func noteActiveAsset(_ asset: AVAsset?)
+
+  /// Whether any registered consumer wants the tap installed right now (the
+  /// equaliser is enabled, or a visualizer has subscribers). The crossfade
+  /// engine holds a freshly-seated leading leg at rate 0 until its
+  /// `.readyToPlay` mix install lands only when this is true — a mix set once
+  /// the leg is already rendering is dropped, silencing the tap — so the
+  /// common no-tap path is left to start immediately.
+  func anyConsumerWantsTap() -> Bool
+}
+
+extension AudioMixProvider {
+  /// A provider with no consumer model (a test double) never holds a leg for a
+  /// tap; only `AudioTapProvider` overrides this.
+  func anyConsumerWantsTap() -> Bool { false }
+}
+
+extension AudioMixProvider {
+  /// Providers that track no active asset need no behaviour here.
+  func noteActiveAsset(_ asset: AVAsset?) {}
 }

package/ios/PlaybackErrorMapping.swift

@@ -53,9 +53,9 @@ public enum PlaybackErrorMapping {
   }
 
   /// Strip query strings from a native error message so logged
-  /// `nativeMessage` doesn't carry auth tokens (Subsonic-style
-  /// `s=…&t=…` salt+token pairs in stream URLs end up inside
-  /// `localizedDescription` strings).
+  /// `nativeMessage` doesn't carry auth tokens: stream URLs with
+  /// `?token=…`-style query strings end up inside
+  /// `localizedDescription` strings, and every `?…` run is removed.
   ///
   /// Walks the entire message, removing every `?…(whitespace|end)`
   /// run so a multi-URL error message ("redirect from

package/ios/PlaybackModeStateMachine.swift

@@ -66,8 +66,8 @@ final class PlaybackModeStateMachine {
   /// the Nitro Promise<Void> bridge as a JS-thrown error.
   ///
   /// The caller is responsible for managing the brief audio
-  /// interruption (resume position carryover, queue re-attach,
-  /// etc.) — that's the engine-handoff contract.
+  /// interruption — `applyEngineSwapForMode` carries the position
+  /// and re-installs the queue.
   func setRequested(
     state: State,
     requested: PlaybackMode

package/ios/PlaybackNetworkMonitor.swift

@@ -0,0 +1,73 @@
+import Foundation
+import Network
+
+/// Reports the moment the network comes back after an outage.
+///
+/// A player that failed its retries while the device was offline has nothing
+/// to react to when connectivity returns: the item stays failed and playback
+/// stays stopped until the user notices and presses play. This is the signal
+/// that lets recovery run at the point it can actually succeed.
+///
+/// Only the **down → up** edge is reported. A satisfied → satisfied update —
+/// a Wi-Fi to cellular handoff, an interface change — is not an outage
+/// recovery, and treating it as one would retry against a connection that
+/// never dropped.
+///
+/// One-shot: `start()` arms the monitor once, and `stop()` after it is
+/// terminal — a later `start()` does nothing. `NWPathMonitor` does not define
+/// `start` after `cancel`, and the player never needs it: `configure()`
+/// creates a fresh monitor and destroy stops it.
+///
+/// `NWPathMonitor` delivers the current path once on `start` and then on
+/// every change, so a monitor started while online reports that first
+/// delivery as a restore (the seed below is unsatisfied). Downstream that is
+/// harmless — recovery only runs for an item that has already failed.
+final class PlaybackNetworkMonitor {
+
+  /// Fired on the down → up transition, on `queue`.
+  var onNetworkRestored: (() -> Void)?
+
+  private let monitor = NWPathMonitor()
+  private let queue: DispatchQueue
+  /// Seeded unsatisfied so a monitor that starts while offline reports the
+  /// first success as a recovery rather than swallowing it as "no change".
+  private var lastStatus: NWPath.Status = .unsatisfied
+  private var started = false
+  /// Set by `stop()` after a `start()`; nothing clears it.
+  private var stopped = false
+
+  /// - Parameter queue: the queue callbacks are delivered on. Callers pass the
+  ///   queue that serialises player state, so the handler needs no hop.
+  init(queue: DispatchQueue) {
+    self.queue = queue
+  }
+
+  func start() {
+    guard !started, !stopped else { return }
+    started = true
+    monitor.pathUpdateHandler = { [weak self] path in
+      guard let self else { return }
+      let previous = self.lastStatus
+      self.lastStatus = path.status
+      guard previous != .satisfied, path.status == .satisfied else { return }
+      self.onNetworkRestored?()
+    }
+    monitor.start(queue: queue)
+  }
+
+  /// Terminal once the monitor has started; a `stop()` before any `start()`
+  /// changes nothing.
+  func stop() {
+    guard started else { return }
+    started = false
+    stopped = true
+    monitor.pathUpdateHandler = nil
+    monitor.cancel()
+  }
+
+  /// A monitor dropped without `stop()` — `configure()` replaced it, or the
+  /// player was released — must not keep its handler queue alive.
+  deinit {
+    monitor.cancel()
+  }
+}

package/ios/PlayerStateDerivation.swift

@@ -7,14 +7,14 @@ import AVFoundation
 /// Android's `TransportStateTranslator`; pure + deterministic.
 ///
 /// iOS has no native "ended" player state (unlike Android's `STATE_ENDED`), so
-/// `reachedQueueEnd` is a latch that `TrackPlayer` sets when the queue drains
-/// with repeat off and clears when playback resumes / a new track loads.
+/// `TrackPlayer` sets `reachedQueueEnd` when the queue drains with repeat off
+/// and clears it when playback resumes / a new track loads.
 enum PlayerStateDerivation {
   /// - Parameters:
   ///   - status: the active player's `timeControlStatus`.
   ///   - currentIndex: the lib's canonical current track index (`-1` = empty).
   ///   - hasCurrentItem: whether the active player has a current item.
-  ///   - reachedQueueEnd: the end-of-queue latch (see type doc).
+  ///   - reachedQueueEnd: whether the queue has drained with repeat off (see type doc).
   static func translate(
     status: AVPlayer.TimeControlStatus,
     currentIndex: Int,
@@ -22,8 +22,8 @@ enum PlayerStateDerivation {
     reachedQueueEnd: Bool
   ) -> PlayerState {
     // A drained queue (repeat off) that isn't actively playing is terminal.
-    // `.playing` takes precedence so a resume reads correctly even before the
-    // latch clears.
+    // `.playing` takes precedence so a resume reads correctly even before
+    // `reachedQueueEnd` is cleared.
     if reachedQueueEnd, currentIndex >= 0, status != .playing {
       return .ended
     }
@@ -33,7 +33,7 @@ enum PlayerStateDerivation {
     case .waitingToPlayAtSpecifiedRate:
       // Waiting WITH a current item = initial load / rebuffer → `.buffering`.
       // Waiting with NO item = the AVQueuePlayer advanced past the last item
-      // (end of queue) before the latch flipped → terminal `.ended`.
+      // (end of queue) before `reachedQueueEnd` was set → terminal `.ended`.
       return hasCurrentItem ? .buffering : (currentIndex < 0 ? .none : .ended)
     case .playing:
       return .playing

package/ios/QueueMutationArithmetic.swift

@@ -19,6 +19,31 @@ import Foundation
 /// test bundle.
 public enum QueueMutationArithmetic {
 
+  /// How many leading positions the engine already holds correctly.
+  ///
+  /// A rebuild that installs the whole slice throws away the item the engine
+  /// has already buffered, which is an audible cut when it happens at a
+  /// boundary. Comparing what the engine holds against what it should hold
+  /// says how much of the front can stay, so only the divergent tail is
+  /// replaced.
+  ///
+  /// Both sides are `queueItemId` — the library's own per-position identity.
+  /// Consumer fields cannot be used here: two tracks may be the same URL, and
+  /// `track.id` is optional consumer data, so neither distinguishes positions.
+  /// A `nil` id belongs to an item the library did not stamp and never
+  /// matches, so the prefix stops there.
+  @_spi(QueuePlayerTests)
+  public static func commonPrefixLength(
+    current: [String?], desired: [String]
+  ) -> Int {
+    var length = 0
+    while length < current.count, length < desired.count {
+      guard let id = current[length], id == desired[length] else { break }
+      length += 1
+    }
+    return length
+  }
+
   /// Clamp an `insertBefore` argument to a valid insertion point in
   /// a track list of size `trackCount`. `nil` → append (return
   /// `trackCount`). Out-of-range values clamp into `0...trackCount`.

package/ios/QueueSkipArithmetic.swift

@@ -91,14 +91,16 @@ public enum QueueSkipArithmetic {
   /// When `restartEnabled` is true (`PlayerConfig.skipToPreviousBehavior
   /// == .restartOrPrevious`), Previous is enabled whenever a track is
   /// loaded — even at index 0, where past the threshold it restarts the
-  /// current track — so the control never greys out.
+  /// current track — so the control never greys out while something is
+  /// playing. With no loaded track (`currentIndex < 0`) there is nothing
+  /// to restart, matching what resolveSkipToPrevious does for that state.
   public static func canSkipPrevious(
     trackCount: Int,
     currentIndex: Int,
     repeatMode: QueueSkipRepeatMode,
     restartEnabled: Bool = false
   ) -> Bool {
-    if restartEnabled { return trackCount > 0 }
+    if restartEnabled { return trackCount > 0 && currentIndex >= 0 }
     return computePrevious(
       trackCount: trackCount,
       currentIndex: currentIndex,
@@ -117,7 +119,7 @@ public enum QueueSkipArithmetic {
     case previous(Int)
     /// Restart the current track (seek to 0) — not a track change.
     case restartCurrent
-    /// Nothing to do (empty queue).
+    /// Nothing to do (empty queue, or no loaded track).
     case noOp
   }