react-native-queue-player 1.1.2 → 2.0.0

package/ios/Tests/RetryRecoveryTests.swift

@@ -0,0 +1,303 @@
+import AVFoundation
+import XCTest
+@testable import QueuePlayer
+
+/// The automatic retry rebuilds the failed item and resumes where playback had
+/// reached, on whichever engine is active.
+final class RetryRecoveryTests: XCTestCase {
+
+  /// One automatic attempt by default. A transient failure that survives a
+  /// rebuild is rarely cured by a second, and further attempts only delay the
+  /// error the consumer needs to act on; `retry()` is the escape hatch after it.
+  func testTheAutomaticRetryBudgetIsOneAttemptByDefault() {
+    let player = TrackPlayer()
+    XCTAssertEqual(player.effectiveAutoRetries(), 1)
+  }
+
+  func testTheConsumerCanAskForNoneOrMore() {
+    let player = TrackPlayer()
+    player.config = PlayerFixtures.config(autoRetries: 0)
+    XCTAssertEqual(player.effectiveAutoRetries(), 0, "zero means zero")
+    player.config = PlayerFixtures.config(autoRetries: 4)
+    XCTAssertEqual(player.effectiveAutoRetries(), 4)
+    player.config = PlayerFixtures.config(autoRetries: 99)
+    XCTAssertEqual(player.effectiveAutoRetries(), 5, "clamped to the documented ceiling")
+    player.config = PlayerFixtures.config(autoRetries: .nan)
+    XCTAssertEqual(player.effectiveAutoRetries(), 1, "a value that is not a number falls back")
+  }
+
+  /// A crossfade failure reaches the automatic retry.
+  ///
+  /// The retry is keyed by `queueItemId`, so an engine reporting a failure
+  /// without the item leaves `dispatchErrorOrRetry` synthesising a key that
+  /// cannot appear in the queue — the retry branch is skipped and a transient
+  /// blip goes straight to the consumer instead of being recovered.
+  func testAnEngineFailureCarryingItsItemIsRetried() {
+    let player = TrackPlayer()
+    let engine = RetryEngineStub()
+    seed(player, engine: engine)
+    let qid = player.queueItemIds[0]
+    player.retryAttemptsRemaining[qid] = 1
+    // The engine names the item that failed, carrying the queue identity the
+    // retry is keyed by.
+    let item = AVPlayerItem(url: URL(string: "https://example.com/0.m4a")!)
+    item.queueItemId = qid
+
+    player.engineDidFailWithError(
+      engine, error: URLError(.timedOut), item: item)
+
+    XCTAssertEqual(
+      player.retryAttemptsRemaining[qid], 0,
+      "a transient failure spends the track's automatic attempt")
+  }
+
+  /// The other half of the same contract: with no item there is nothing to key
+  /// a retry against, so the failure is surfaced rather than silently retried.
+  func testAFailureWithoutAnItemIsNotRetried() {
+    let player = TrackPlayer()
+    let engine = RetryEngineStub()
+    seed(player, engine: engine)
+    let qid = player.queueItemIds[0]
+    player.retryAttemptsRemaining[qid] = 1
+
+    player.engineDidFailWithError(
+      engine, error: URLError(.timedOut), item: nil)
+
+    XCTAssertEqual(
+      player.retryAttemptsRemaining[qid], 1,
+      "no item means no automatic attempt is spent")
+  }
+
+  /// A repeat of the same failure while the attempt is pending stays inside
+  /// the library.
+  func testAnEchoOfThePendingFailureIsNotReported() {
+    let player = TrackPlayer()
+    let engine = RetryEngineStub()
+    seed(player, engine: engine)
+    let qid = player.queueItemIds[0]
+    player.retryAttemptsRemaining[qid] = 1
+    let item = AVPlayerItem(url: URL(string: "https://example.com/0.m4a")!)
+    item.queueItemId = qid
+    var reported: [PlaybackError] = []
+    _ = player.errorListeners.add { reported.append($0) }
+
+    player.engineDidFailWithError(engine, error: URLError(.timedOut), item: item)
+    player.engineDidFailWithError(engine, error: URLError(.timedOut), item: item)
+
+    XCTAssertEqual(reported.count, 0, "the pending attempt owns both fires")
+    XCTAssertEqual(
+      player.retryAttemptsRemaining[qid], 0,
+      "one failure spends one attempt, however many times it is reported")
+  }
+
+  /// A failure after the attempt has run is the consumer's to see.
+  func testAFailureAfterTheAttemptIsReported() {
+    let player = TrackPlayer()
+    let engine = RetryEngineStub()
+    seed(player, engine: engine)
+    let qid = player.queueItemIds[0]
+    player.retryAttemptsRemaining[qid] = 1
+    let item = AVPlayerItem(url: URL(string: "https://example.com/0.m4a")!)
+    item.queueItemId = qid
+    var reported: [PlaybackError] = []
+    _ = player.errorListeners.add { reported.append($0) }
+
+    player.engineDidFailWithError(engine, error: URLError(.timedOut), item: item)
+    player.retryFailedItem(queueItemId: qid)
+    player.engineDidFailWithError(engine, error: URLError(.timedOut), item: item)
+
+    XCTAssertEqual(reported.count, 1, "the attempt was spent and the track is still broken")
+  }
+
+  /// A user retry hands back the allowance the consumer configured, so one for
+  /// a default player and none for a consumer who turned the automatic attempt
+  /// off.
+  func testAUserRetryRestoresTheConfiguredBudget() async throws {
+    let player = TrackPlayer()
+    let engine = RetryEngineStub()
+    seed(player, engine: engine)
+    player.config = PlayerFixtures.config(autoRetries: 0)
+    let qid = player.queueItemIds[0]
+
+    _ = try await player.retry().await()
+
+    XCTAssertEqual(
+      player.retryAttemptsRemaining[qid], 0,
+      "a consumer who asked for no automatic attempt must not be given one")
+  }
+
+  /// The user-facing retry clears `reachedQueueEnd` too — a queue whose
+  /// only track failed to load has already drained, and that is the case the
+  /// button exists for.
+  func testAUserRetryClearsTheEndOfQueueState() async throws {
+    let player = TrackPlayer()
+    let engine = RetryEngineStub()
+    seed(player, engine: engine)
+    player.reachedQueueEnd = true
+
+    _ = try await player.retry().await()
+
+    XCTAssertFalse(player.reachedQueueEnd)
+  }
+
+  /// The rebuild a user asked for replaces a scheduled one, so the rebuilt
+  /// item's own failure is reported rather than taken for an echo.
+  func testAUserRetrySupersedesAScheduledAttempt() async throws {
+    let player = TrackPlayer()
+    let engine = RetryEngineStub()
+    seed(player, engine: engine)
+    player.pendingRetryQueueItemId = player.queueItemIds[0]
+
+    _ = try await player.retry().await()
+
+    XCTAssertNil(player.pendingRetryQueueItemId)
+  }
+
+  /// A retry clears `reachedQueueEnd`.
+  ///
+  /// A queue whose only track fails to load drains the engine, so the queue-end
+  /// verdict calls it finished and parks the player. Without clearing it
+  /// the retry seats an item into a queue that believes it is over, and
+  /// playback never resumes — the automatic attempt rebuilds and nothing plays.
+  func testRetryingClearsTheEndOfQueueState() {
+    let player = TrackPlayer()
+    let engine = RetryEngineStub()
+    seed(player, engine: engine)
+    player.reachedQueueEnd = true
+
+    player.retryFailedItem(queueItemId: player.queueItemIds[0])
+
+    XCTAssertFalse(
+      player.reachedQueueEnd,
+      "a retry is an intent to play this track, so the queue is not over")
+  }
+
+  /// A drain whose current item failed with an automatic attempt already
+  /// scheduled is not the end of the queue. `AVQueuePlayer` consumes a failed
+  /// item and drains to `currentItem == nil`, which reaches `applyEndVerdict`;
+  /// deciding a queue-end there clears the play intent the scheduled retry
+  /// reads, so the recovered track never resumes. The verdict holds the queue
+  /// open while a retry is pending for the current track.
+  func testADrainWithAPendingRetryDoesNotEndTheQueue() {
+    let player = TrackPlayer()
+    let engine = RetryEngineStub()
+    seed(player, engine: engine)
+    player.currentTrackIndex = 1
+    player.wantsToPlay = true
+    player.pendingRetryQueueItemId = player.queueItemIds[1]
+
+    player.applyEndVerdict()
+
+    XCTAssertTrue(
+      player.wantsToPlay,
+      "a pending retry keeps the play intent so the automatic attempt can resume")
+    XCTAssertFalse(
+      player.reachedQueueEnd,
+      "a drain with a retry pending is a recovery in flight, not the end of the queue")
+  }
+
+  func testRetryResumesFromWherePlaybackHadReached() {
+    let player = TrackPlayer()
+    let engine = RetryEngineStub()
+    engine.position = 42.5
+    seed(player, engine: engine)
+    // The crossfade shape: an engine is live, the gapless queue player is not.
+    XCTAssertNil(player.player)
+
+    player.retryFailedItem(queueItemId: player.queueItemIds[0])
+
+    XCTAssertEqual(
+      engine.seeks.first?.position, 42.5,
+      "a blip well into a long track must not restart it from zero")
+  }
+
+  func testRetryDoesNotSeekWhenPlaybackHadNotStarted() {
+    let player = TrackPlayer()
+    let engine = RetryEngineStub()
+    engine.position = 0
+    seed(player, engine: engine)
+
+    player.retryFailedItem(queueItemId: player.queueItemIds[0])
+
+    XCTAssertTrue(engine.seeks.isEmpty, "position 0 is the rebuild's own starting point")
+  }
+
+  func testRetryIsMootOnceTheUserHasMovedOn() {
+    let player = TrackPlayer()
+    let engine = RetryEngineStub()
+    engine.position = 30
+    seed(player, engine: engine)
+    let staleId = player.queueItemIds[1]
+    // The failure belongs to a track the player is no longer on.
+    player.retryFailedItem(queueItemId: staleId)
+
+    XCTAssertTrue(engine.seeks.isEmpty)
+  }
+
+  private func seed(_ player: TrackPlayer, engine: RetryEngineStub) {
+    _ = player.queueState.replaceAll((0 ..< 2).map {
+      TrackItem(
+        id: "t\($0)", url: "https://example.com/\($0).m4a", title: nil, artist: nil,
+        album: nil, duration: nil, artworkUrl: nil, extras: nil,
+        replayGainTrackGain: nil, replayGainTrackPeak: nil,
+        replayGainAlbumGain: nil, replayGainAlbumPeak: nil)
+    })
+    player.currentTrackIndex = 0
+    player.engine = engine
+  }
+}
+
+/// Records the seeks the retry issues; everything else is inert.
+private final class RetryEngineStub: PlaybackEngine {
+  var position: TimeInterval = 0
+  private(set) var seeks: [(index: Int, position: TimeInterval)] = []
+
+  var currentPositionSeconds: TimeInterval { position }
+  func seek(toIndex index: Int, position: TimeInterval) {
+    seeks.append((index, position))
+  }
+
+  func setAudioMixProvider(_ provider: AudioMixProvider?) {}
+  func refreshAllItemMixes() {}
+  func release() {}
+  /// Holds what it is given, so a caller resolving a queue position to an
+  /// engine index by `queueItemId` gets the same answer a real engine would.
+  func setItems(_ items: [AVPlayerItem], startIndex: Int, startPositionSeconds: TimeInterval) {
+    installed = items
+  }
+  @discardableResult
+  func insertItems(_ items: [AVPlayerItem], after: AVPlayerItem?) -> Bool {
+    installed.append(contentsOf: items)
+    return true
+  }
+  func remove(_ item: AVPlayerItem) {
+    installed.removeAll { $0 === item }
+  }
+  func removeAllItems() {}
+  func canInsert(_ item: AVPlayerItem, after: AVPlayerItem?) -> Bool { true }
+  func play() {}
+  func pause() {}
+  func stop() {}
+  func skipToNext() {}
+  func skipToPrevious() {}
+  func setVolume(_ volume: Float) {}
+  func setPlaybackSpeed(_ speed: Float) {}
+  func seedPlaybackSpeed(_ speed: Float) {}
+  func setRepeatMode(_ mode: RepeatMode) {}
+  func setPitchCorrectionMode(_ mode: PitchCorrectionMode) {}
+
+  var currentDurationSeconds: TimeInterval { 0 }
+  var isPlaying: Bool { false }
+  var currentMediaItemIndex: Int { -1 }
+  var bufferedPositionSeconds: TimeInterval { 0 }
+  var timeControlStatus: AVPlayer.TimeControlStatus { .paused }
+  var currentMediaItem: AVPlayerItem? { nil }
+  private var installed: [AVPlayerItem] = []
+  var allMediaItems: [AVPlayerItem] { installed }
+  /// No fade to schedule — this stub exercises the rest of the surface.
+  var isFadePendingOrActive: Bool { false }
+  /// Nothing attached — this stub exercises the rest of the surface.
+  var attachedQueueItemIds: [String] { [] }
+
+  var delegate: PlaybackEngineDelegate?
+}

package/ios/Tests/SkipCapabilityTests.swift

@@ -34,20 +34,50 @@ final class SkipCapabilityTests: XCTestCase {
     dispose()
   }
 
-  func testDisposeBeforeAutoFireSuppressesCallback() throws {
-    // Subscribing then immediately disposing produces no callback,
-    // even though the auto-fire is dispatched asynchronously to main.
+  /// A disposed subscription receives nothing once the auto-fire has settled.
+  ///
+  /// An immediate dispose racing the auto-fire is a race, not a contract: the
+  /// fire is enqueued on the owner queue when `subscribe` returns, so the queue
+  /// block usually waits while the caller's synchronous dispose lands first,
+  /// and under load it does not. What the library guarantees is that the
+  /// registry is consulted before the callback runs, so a settled dispose is
+  /// final.
+  func testDisposeStopsCallbacksOnceSettled() throws {
     let player = TrackPlayer()
     var fireCount = 0
     let dispose = try player.onSkipCapabilityChange { _ in
       fireCount += 1
     }
     dispose()
-    // Pump the run loop so the deferred main.async block executes.
-    let exp = expectation(description: "drain main")
-    DispatchQueue.main.async { exp.fulfill() }
-    wait(for: [exp], timeout: 1.0)
-    XCTAssertEqual(fireCount, 0, "Auto-fire must not fire after dispose.")
+    drain(player)
+    let afterDispose = fireCount
+
+    // A queue with a track on either side, so the recompute below is a real
+    // change from the empty-queue capability rather than a deduplicated repeat
+    // — the disposed subscription has to be what keeps it from arriving.
+    player.playerQueue.async {
+      _ = player.queueState.replaceAll((0 ..< 3).map {
+        PlayerFixtures.track(id: "t\($0)", url: "https://example.com/\($0).m4a")
+      })
+      player.currentTrackIndex = 1
+      player.recomputeCapabilities()
+    }
+    drain(player)
+
+    XCTAssertEqual(
+      fireCount, afterDispose,
+      "a disposed subscription receives no further capability changes")
+  }
+
+  /// Two hops: the auto-fire runs on the owner queue and consumers are called
+  /// from there, so draining main alone can return before either has run.
+  private func drain(_ player: TrackPlayer) {
+    let queueDrained = expectation(description: "owner queue drained")
+    player.playerQueue.async { queueDrained.fulfill() }
+    wait(for: [queueDrained], timeout: 2.0)
+    let mainDrained = expectation(description: "main drained")
+    DispatchQueue.main.async { mainDrained.fulfill() }
+    wait(for: [mainDrained], timeout: 2.0)
   }
 
   func testOnSkipCapabilityChangeMultiSubscriberEachGetsAutoFire() throws {
@@ -81,6 +111,129 @@ final class SkipCapabilityTests: XCTestCase {
     dispose()
   }
 
+  // MARK: - computeCapabilities
+
+  func testComputeCapabilitiesEnablesBothDirectionsMidQueue() {
+    let player = TrackPlayer()
+    seedQueue(player, count: 3, currentIndex: 1)
+    let capability = player.computeCapabilities()
+    XCTAssertTrue(capability.canSkipPrevious)
+    XCTAssertTrue(capability.canSkipNext)
+  }
+
+  func testComputeCapabilitiesDisablesTheAbsentDirectionAtEachQueueEnd() {
+    let player = TrackPlayer()
+    seedQueue(player, count: 3, currentIndex: 0)
+    let first = player.computeCapabilities()
+    XCTAssertFalse(first.canSkipPrevious)
+    XCTAssertTrue(first.canSkipNext)
+
+    player.currentTrackIndex = 2
+    let last = player.computeCapabilities()
+    XCTAssertTrue(last.canSkipPrevious)
+    XCTAssertFalse(last.canSkipNext)
+  }
+
+  func testComputeCapabilitiesEnablesBothDirectionsUnderRepeatQueue() {
+    let player = TrackPlayer()
+    seedQueue(player, count: 3, currentIndex: 0)
+    player.repeatModeState = .queue
+    let capability = player.computeCapabilities()
+    XCTAssertTrue(capability.canSkipPrevious)
+    XCTAssertTrue(capability.canSkipNext)
+  }
+
+  func testComputeCapabilitiesLeavesTheCachedCapabilityUntouched() {
+    let player = TrackPlayer()
+    seedQueue(player, count: 3, currentIndex: 1)
+    player.cachedSkipCapability = SkipCapability(canSkipPrevious: true, canSkipNext: false)
+
+    _ = player.computeCapabilities()
+
+    XCTAssertTrue(player.cachedSkipCapability.canSkipPrevious)
+    XCTAssertFalse(player.cachedSkipCapability.canSkipNext)
+  }
+
+  // MARK: - buildCarPlayQueueSnapshot
+
+  func testBuildCarPlayQueueSnapshotMirrorsTheQueueAndCurrentIndex() {
+    let player = TrackPlayer()
+    seedQueue(player, count: 3, currentIndex: 2)
+    let snapshot = player.buildCarPlayQueueSnapshot()
+    XCTAssertEqual(snapshot?.entries.count, 3)
+    XCTAssertEqual(snapshot?.currentIndex, 2)
+    XCTAssertEqual(snapshot?.entries.map { $0.title }, ["Track 0", "Track 1", "Track 2"])
+  }
+
+  func testBuildCarPlayQueueSnapshotIsNilForAnEmptyQueue() {
+    let player = TrackPlayer()
+    XCTAssertNil(player.buildCarPlayQueueSnapshot())
+  }
+
+  func testBuildCarPlayQueueSnapshotFallsBackToAlbumWhenArtistIsAbsent() {
+    let player = TrackPlayer()
+    _ = player.queueState.replaceAll([
+      makeTrack(index: 0, title: nil, artist: nil, album: "Album"),
+      makeTrack(index: 1, title: "Titled", artist: "Artist", album: "Album"),
+    ])
+    player.currentTrackIndex = 0
+    let entries = player.buildCarPlayQueueSnapshot()?.entries
+    XCTAssertEqual(entries?[0].title, "", "an absent title renders as an empty string")
+    XCTAssertEqual(entries?[0].subtitle, "Album")
+    XCTAssertEqual(entries?[1].subtitle, "Artist")
+  }
+
+  // MARK: - publishCapabilities
+
+  func testPublishCapabilitiesRefreshesTheCarPlayMirrorWhenTheCapabilityIsUnchanged() {
+    let player = TrackPlayer()
+    seedQueue(player, count: 3, currentIndex: 1)
+    let capability = player.computeCapabilities()
+    player.cachedSkipCapability = capability
+    defer { CarPlayCoordinator.shared.queueProvider.setSnapshot(nil) }
+
+    player.publishCapabilities(
+      capability, queueSnapshot: player.buildCarPlayQueueSnapshot(), carAttached: true)
+
+    XCTAssertEqual(
+      CarPlayCoordinator.shared.queueProvider.getSnapshot()?.entries.count, 3,
+      "a reorder or metadata change refreshes the mirror even though it leaves "
+        + "skip capability untouched")
+  }
+
+  func testPublishCapabilitiesClearsTheCarPlayMirrorForAnEmptyQueue() {
+    let player = TrackPlayer()
+    defer { CarPlayCoordinator.shared.queueProvider.setSnapshot(nil) }
+    CarPlayCoordinator.shared.queueProvider.setSnapshot(
+      CarPlayQueueSnapshot(
+        entries: [CarPlayQueueEntry(title: "stale", subtitle: nil, artworkUrl: nil)],
+        currentIndex: 0))
+
+    player.publishCapabilities(
+      player.computeCapabilities(),
+      queueSnapshot: player.buildCarPlayQueueSnapshot(), carAttached: true)
+
+    XCTAssertNil(CarPlayCoordinator.shared.queueProvider.getSnapshot())
+  }
+
+  func testPublishCapabilitiesLeavesTheMirrorAloneWithNoCarAttached() {
+    let player = TrackPlayer()
+    seedQueue(player, count: 2, currentIndex: 0)
+    defer { CarPlayCoordinator.shared.queueProvider.setSnapshot(nil) }
+    CarPlayCoordinator.shared.queueProvider.setSnapshot(
+      CarPlayQueueSnapshot(
+        entries: [CarPlayQueueEntry(title: "held", subtitle: nil, artworkUrl: nil)],
+        currentIndex: 0))
+
+    player.publishCapabilities(
+      player.computeCapabilities(), queueSnapshot: nil, carAttached: false)
+
+    XCTAssertEqual(
+      CarPlayCoordinator.shared.queueProvider.getSnapshot()?.entries.first?.title, "held",
+      "a snapshot that was never built because no car is attached must not be "
+        + "mistaken for a request to clear")
+  }
+
   func testListenerRegistryContainsAfterAddAndAbsentAfterRemove() {
     // After `add()` returns an id, `contains(id:)` returns true.
     // After `remove(id:)`, `contains(id:)` returns false.
@@ -92,4 +245,76 @@ final class SkipCapabilityTests: XCTestCase {
     XCTAssertFalse(registry.contains(id: id))
     XCTAssertFalse(registry.remove(id: id))
   }
+  private func seedQueue(_ player: TrackPlayer, count: Int, currentIndex: Int) {
+    _ = player.queueState.replaceAll(
+      (0 ..< count).map { makeTrack(index: $0, title: "Track \($0)") })
+    player.currentTrackIndex = currentIndex
+  }
+
+  private func makeTrack(
+    index: Int, title: String?, artist: String? = nil, album: String? = nil
+  ) -> TrackItem {
+    return TrackItem(
+      id: "t\(index)", url: "https://example.com/\(index).m4a",
+      title: title, artist: artist, album: album, duration: nil, artworkUrl: nil,
+      extras: nil, replayGainTrackGain: nil, replayGainTrackPeak: nil,
+      replayGainAlbumGain: nil, replayGainAlbumPeak: nil
+    )
+  }
+
+
+  /// Restart-or-previous with no loaded track keeps Previous disabled.
+  func testRestartModeWithNoLoadedTrackKeepsPreviousDisabled() {
+    let player = TrackPlayer()
+    player.config = PlayerConfig(httpHeaders: nil, userAgent: nil, placeholderArtworkUri: nil, autoRetries: nil, retryBackoffMs: nil, networkTimeoutMs: nil, audioContentType: nil, audioCategoryOptions: nil, voiceVocabularyDonationEnabled: nil, visualizationEnabled: nil, clampSeekToBuffered: nil, skipToPreviousBehavior: .restartOrPrevious, lookaheadCacheMaxSizeMb: nil, lookaheadCacheEvictionPolicy: nil, progressUpdateIntervalMs: nil, backgroundProgressUpdateIntervalMs: nil)
+    seedQueue(player, count: 3, currentIndex: -1)
+    XCTAssertFalse(player.computeCapabilities().canSkipPrevious)
+  }
+
+  /// Restart-or-previous with a loaded track at index 0 enables Previous.
+  func testRestartModeAtIndexZeroEnablesPrevious() {
+    let player = TrackPlayer()
+    player.config = PlayerConfig(httpHeaders: nil, userAgent: nil, placeholderArtworkUri: nil, autoRetries: nil, retryBackoffMs: nil, networkTimeoutMs: nil, audioContentType: nil, audioCategoryOptions: nil, voiceVocabularyDonationEnabled: nil, visualizationEnabled: nil, clampSeekToBuffered: nil, skipToPreviousBehavior: .restartOrPrevious, lookaheadCacheMaxSizeMb: nil, lookaheadCacheEvictionPolicy: nil, progressUpdateIntervalMs: nil, backgroundProgressUpdateIntervalMs: nil)
+    seedQueue(player, count: 3, currentIndex: 0)
+    XCTAssertTrue(player.computeCapabilities().canSkipPrevious)
+  }
+
+  // MARK: - cast index writes keep capability and source current
+
+  /// A receiver advance to the last track disables Next, as a local advance does.
+  func testRemoteTrackChangeToLastIndexDisablesNext() {
+    let player = TrackPlayer()
+    seedQueue(player, count: 3, currentIndex: 0)
+    player.playerQueue.async { player.recomputeCapabilities() }
+    drain(player)
+    XCTAssertTrue(player.cachedSkipCapability.canSkipNext)
+
+    player.emitRemoteTrackChange(index: 2)
+    drain(player)
+    XCTAssertEqual(player.currentTrackIndex, 2)
+    XCTAssertFalse(player.cachedSkipCapability.canSkipNext)
+    XCTAssertTrue(player.cachedSkipCapability.canSkipPrevious)
+  }
+
+  /// A receiver advance classifies the source of the track it moved to.
+  func testRemoteTrackChangeClassifiesTheNewTracksSource() {
+    let player = TrackPlayer()
+    _ = player.queueState.replaceAll([
+      makeTrack(index: 0, title: "a"),
+      makeTrack(index: 1, title: "b"),
+      TrackItem(
+        id: "local", url: "file:///tmp/local.m4a",
+        title: nil, artist: nil, album: nil, duration: nil, artworkUrl: nil,
+        extras: nil, replayGainTrackGain: nil, replayGainTrackPeak: nil,
+        replayGainAlbumGain: nil, replayGainAlbumPeak: nil),
+    ])
+    player.currentTrackIndex = 0
+    player.playerQueue.async { player.reclassifyCurrentTrackSource() }
+    drain(player)
+    XCTAssertEqual(player.currentTrackSource, .streaming)
+
+    player.emitRemoteTrackChange(index: 2)
+    drain(player)
+    XCTAssertEqual(player.currentTrackSource, .local)
+  }
 }

package/ios/Tests/SkipIndexTests.swift

@@ -91,8 +91,8 @@ final class SkipIndexTests: XCTestCase {
 
   func testComputePreviousRepeatOffAtStartReturnsNil() {
     // No rewind-on-boundary under .off. The consumer-facing "tap Previous
-    // at index 0 restarts the track" behaviour lives in the skipToPrevious
-    // glue, not here.
+    // at index 0 restarts the track" behaviour lives in `skipToPrevious`,
+    // not here.
     XCTAssertNil(QueueSkipArithmetic.computePrevious(
       trackCount: 3, currentIndex: 0, repeatMode: .off))
   }
@@ -353,4 +353,34 @@ final class SkipIndexTests: XCTestCase {
     XCTAssertTrue(QueueSkipArithmetic.canSkipPrevious(
       trackCount: 3, currentIndex: 1, repeatMode: .off, restartEnabled: false))
   }
+
+  func testCanSkipPreviousRestartNothingPlayingReturnsFalseInAnyMode() {
+    // Nothing is loaded, so there is no track to restart and no previous
+    // track to reach: resolveSkipToPrevious returns no-op for this state.
+    for mode in [QueueSkipRepeatMode.off, .queue, .track] {
+      XCTAssertFalse(QueueSkipArithmetic.canSkipPrevious(
+        trackCount: 5, currentIndex: -1, repeatMode: mode, restartEnabled: true))
+    }
+  }
+
+  func testCanSkipPreviousAgreesWithResolveSkipToPrevious() {
+    // canSkipPrevious is the enabled-state of the same decision
+    // resolveSkipToPrevious makes; the two must never disagree.
+    for count in [0, 1, 3] {
+      for index in [-1, 0, 1, 2] {
+        for mode in [QueueSkipRepeatMode.off, .queue, .track] {
+          for restart in [false, true] {
+            let can = QueueSkipArithmetic.canSkipPrevious(
+              trackCount: count, currentIndex: index, repeatMode: mode,
+              restartEnabled: restart)
+            let resolved = QueueSkipArithmetic.resolveSkipToPrevious(
+              trackCount: count, currentIndex: index, repeatMode: mode,
+              restartEnabled: restart, positionMs: 0)
+            XCTAssertEqual(can, resolved != .noOp,
+              "count=\(count) index=\(index) mode=\(mode) restart=\(restart)")
+          }
+        }
+      }
+    }
+  }
 }

package/ios/Tests/SleepTimerPauseIntentTests.swift

@@ -0,0 +1,43 @@
+import XCTest
+@testable import QueuePlayer
+
+/// The sleep timer's pause is a transport intent: the paths that restart
+/// playback on their own (a drain refill, a buffer coming back) read
+/// `wantsToPlay`, so the timer clears it the way a user pause does.
+final class SleepTimerPauseIntentTests: XCTestCase {
+
+  private var player: TrackPlayer!
+
+  override func setUp() async throws {
+    try await super.setUp()
+    player = TrackPlayer()
+    _ = try await player.configure(config: PlayerFixtures.config()).await()
+    _ = try await player.setQueue(
+      tracks: PlayerFixtures.localTracks(count: 2, for: self), startAtIndex: 0
+    ).await()
+  }
+
+  override func tearDown() async throws {
+    if let player {
+      _ = try await player.destroy().await()
+    }
+    player = nil
+    try await super.tearDown()
+  }
+
+  func testTheTimersPauseClearsTheIntentToPlay() async throws {
+    let player = try XCTUnwrap(self.player)
+    await player.onPlayerQueue {
+      player.wantsToPlay = true
+      player.isRecoveringFromStall = true
+      player.applySleepTimerResult(
+        SleepTimerCore.Tick(fadeFraction: 1.0, pauseNow: true, stateChanged: true))
+    }
+
+    let state = await player.onPlayerQueueValue {
+      (wants: player.wantsToPlay, recovering: player.isRecoveringFromStall)
+    }
+    XCTAssertFalse(state.wants, "a drain or a buffer refill must not restart what the timer stopped")
+    XCTAssertFalse(state.recovering)
+  }
+}