react-native-queue-player 1.2.0 → 2.0.1

package/ios/Tests/RetryRecoveryTests.swift

@@ -0,0 +1,418 @@
+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)
+  }
+
+  // MARK: - The queue stops on a track whose failure was reported
+
+  /// A failure dispatched as its item is seated survives the first
+  /// announcement of that position, which happens in the same block.
+  func testAFailureAtSeatTimeStillHoldsTheQueueAfterTheTrackIsAnnounced() {
+    let player = TrackPlayer()
+    let engine = RetryEngineStub()
+    seed(player, engine: engine)
+    let qid = player.queueItemIds[0]
+    let item = AVPlayerItem(url: URL(string: "https://example.com/0.m4a")!)
+    item.queueItemId = qid
+
+    player.dispatchErrorOrRetry(
+      item: item,
+      underlying: NSError(domain: AVFoundationErrorDomain, code: -11828, userInfo: nil))
+    player.handleCurrentItemDidChange()
+
+    XCTAssertEqual(
+      player.reportedFailureOnCurrentTrack, qid,
+      "the track change announcing the failed track must not clear its report")
+  }
+
+  /// Announcing a different track clears a report the queue has moved past.
+  func testAnnouncingADifferentTrackClearsTheReport() {
+    let player = TrackPlayer()
+    let engine = RetryEngineStub()
+    seed(player, engine: engine)
+    player.reportedFailureQueueItemIds = [player.queueItemIds[0]]
+    player.currentTrackIndex = 1
+
+    player.dispatchTrackChange(reason: .userSkipNext)
+
+    XCTAssertTrue(player.reportedFailureQueueItemIds.isEmpty)
+  }
+
+  /// A forced reinstall builds the current position from scratch, so what was
+  /// reported against it no longer describes what is installed.
+  func testAForcedReinstallClearsTheReport() {
+    let player = TrackPlayer()
+    let engine = RetryEngineStub()
+    seed(player, engine: engine)
+    player.reportedFailureQueueItemIds = [player.queueItemIds[0]]
+
+    player.performingMutation { player.fullRebuildPlayerQueue(forcingReinstall: true) }
+
+    XCTAssertTrue(player.reportedFailureQueueItemIds.isEmpty)
+  }
+
+  /// A reconcile that is not rebuilding the position leaves the report alone —
+  /// the track it names is still the one that failed.
+  func testAPlainRebuildLeavesTheReportAlone() {
+    let player = TrackPlayer()
+    let engine = RetryEngineStub()
+    seed(player, engine: engine)
+    let qid = player.queueItemIds[0]
+    player.reportedFailureQueueItemIds = [qid]
+
+    player.performingMutation { player.fullRebuildPlayerQueue() }
+
+    XCTAssertEqual(player.reportedFailureQueueItemIds, [qid])
+  }
+
+  /// One `play()`, one error. Several tracks of an installed run fail at once —
+  /// a window of unplayable sources does exactly that — and only the track the
+  /// listener is on is theirs to act on; it reports once however many times it
+  /// or its neighbours fire. The record is a set so a repeat cannot be reopened
+  /// by a different track replacing it in a one-slot key.
+  func testOnlyTheCurrentTrackReportsAndOnlyOnce() {
+    let player = TrackPlayer()
+    let engine = RetryEngineStub()
+    seed(player, engine: engine)
+    var reported: [PlaybackError] = []
+    _ = player.errorListeners.add { reported.append($0) }
+    let fatal = NSError(domain: AVFoundationErrorDomain, code: -11828, userInfo: nil)
+    func item(at index: Int) -> AVPlayerItem {
+      let made = AVPlayerItem(url: URL(string: "https://example.com/\(index).m4a")!)
+      made.queueItemId = player.queueItemIds[index]
+      return made
+    }
+
+    // Two tracks failing, each reported twice, in the order that defeats a
+    // one-slot key: every fire names a different track than the one before it.
+    player.dispatchErrorOrRetry(item: item(at: 0), underlying: fatal)
+    player.dispatchErrorOrRetry(item: item(at: 1), underlying: fatal)
+    player.dispatchErrorOrRetry(item: item(at: 0), underlying: fatal)
+    player.dispatchErrorOrRetry(item: item(at: 1), underlying: fatal)
+
+    XCTAssertEqual(
+      reported.count, 1,
+      "one play(), one error: the track being played, once, whatever else fails")
+    XCTAssertEqual(
+      reported.first?.queueItemId, player.queueItemIds[0],
+      "the error names the track the listener is on")
+    XCTAssertEqual(
+      player.reportedFailureQueueItemIds, Set([player.queueItemIds[0]]),
+      "and only that track holds the queue")
+  }
+
+  /// Seating a position is an attempt at it, so a skip onto a track that
+  /// reported earlier clears its report. Without this the track is wedged:
+  /// it never reports again, its run is never extended, and it never reaches
+  /// an end verdict — silently, until play().
+  func testSkippingOntoAReportedTrackClearsItsReport() {
+    let player = TrackPlayer()
+    let engine = RetryEngineStub()
+    seed(player, engine: engine)
+    player.reportedFailureQueueItemIds = [player.queueItemIds[1]]
+
+    player.applyNewCurrentIndex(newIndex: 1, reason: .userSkipToIndex)
+
+    XCTAssertTrue(
+      player.reportedFailureQueueItemIds.isEmpty,
+      "the track being skipped onto is being tried again")
+  }
+
+  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)
+  }
 }