react-native-audio-browser 0.1.1 → 0.2.0-next.10

package/ios/Tests/PlaybackTimerTests.swift

@@ -0,0 +1,55 @@
+import XCTest
+
+@testable import AudioBrowserTestable
+
+@MainActor
+final class PlaybackTimerTests: XCTestCase {
+  func testNoTicksUntilIntervalSetAndActive() async throws {
+    var ticks = 0
+    let timer = PlaybackTimer(isActive: { $0 == .playing }) { ticks += 1 }
+    timer.onPlaybackStateChanged(.playing) // no interval yet
+    try await Task.sleep(nanoseconds: 1_200_000_000)
+    XCTAssertEqual(ticks, 0)
+  }
+
+  func testTicksWhenIntervalSetAndActive() async throws {
+    var ticks = 0
+    let timer = PlaybackTimer(isActive: { $0 == .playing }) { ticks += 1 }
+    timer.setInterval(1)
+    timer.onPlaybackStateChanged(.playing)
+    try await Task.sleep(nanoseconds: 2_200_000_000)
+    XCTAssertGreaterThanOrEqual(ticks, 1)
+  }
+
+  func testStopsWhenStateLeavesActive() async throws {
+    var ticks = 0
+    let timer = PlaybackTimer(isActive: { $0 == .playing }) { ticks += 1 }
+    timer.setInterval(1)
+    timer.onPlaybackStateChanged(.playing)
+    timer.onPlaybackStateChanged(.paused)
+    let after = ticks
+    try await Task.sleep(nanoseconds: 1_200_000_000)
+    XCTAssertEqual(ticks, after)
+  }
+
+  func testNilIntervalStops() async throws {
+    var ticks = 0
+    let timer = PlaybackTimer(isActive: { $0 == .playing }) { ticks += 1 }
+    timer.setInterval(1)
+    timer.onPlaybackStateChanged(.playing)
+    timer.setInterval(nil) // off-switch
+    let after = ticks
+    try await Task.sleep(nanoseconds: 1_200_000_000)
+    XCTAssertEqual(ticks, after)
+  }
+
+  func testIsActivePredicateGatesState() async throws {
+    // A "playing-only" predicate must not tick while buffering.
+    var ticks = 0
+    let timer = PlaybackTimer(isActive: { $0 == .playing }) { ticks += 1 }
+    timer.setInterval(1)
+    timer.onPlaybackStateChanged(.buffering)
+    try await Task.sleep(nanoseconds: 1_200_000_000)
+    XCTAssertEqual(ticks, 0)
+  }
+}

package/ios/Tests/PlayerTimeObserverTests.swift

@@ -0,0 +1,37 @@
+import AVFoundation
+import Testing
+
+@testable import AudioBrowserTestable
+
+@MainActor
+@Suite("PlayerTimeObserver")
+struct PlayerTimeObserverTests {
+  /// An AVPlayer retains its time observers, so one left registered outlives both this object and
+  /// the caller's interest in it (#96).
+  @Test func unregisteringDropsTheToken() {
+    // Held: `avPlayer` is weak, so a temporary is gone before the next line.
+    let player = AVPlayer()
+    let observer = PlayerTimeObserver(onAudioDidStart: {})
+    observer.avPlayer = player
+
+    observer.registerForBoundaryTimeEvents()
+    #expect(observer.boundaryTimeStartObserverToken != nil)
+
+    observer.unregisterForBoundaryTimeEvents()
+    #expect(observer.boundaryTimeStartObserverToken == nil)
+  }
+
+  /// Swapping players has to unregister from the outgoing one — it is a different AVPlayer, and
+  /// the token cannot be removed from it afterwards.
+  @Test func swappingPlayersUnregistersFromThePrevious() {
+    let first = AVPlayer()
+    let second = AVPlayer()
+    let observer = PlayerTimeObserver(onAudioDidStart: {})
+    observer.avPlayer = first
+    observer.registerForBoundaryTimeEvents()
+
+    observer.avPlayer = second
+
+    #expect(observer.boundaryTimeStartObserverToken == nil)
+  }
+}

package/ios/Tests/PlayingStateManagerTests.swift

@@ -0,0 +1,57 @@
+import Foundation
+import Testing
+
+@testable import AudioBrowserTestable
+
+@Suite("PlayingStateManager")
+struct PlayingStateManagerTests {
+  @MainActor
+  private func makeManager() -> (manager: PlayingStateManager, changes: () -> [PlayingState]) {
+    var recorded: [PlayingState] = []
+    let manager = PlayingStateManager { recorded.append($0) }
+    return (manager, { recorded })
+  }
+
+  @Test @MainActor
+  func playing_whenIntentAndActiveState() {
+    let (m, _) = makeManager()
+    m.update(playWhenReady: true, state: .playing)
+    #expect(m.playing == true)
+    #expect(m.buffering == false)
+  }
+
+  @Test @MainActor
+  func buffering_whenIntentAndLoading() {
+    let (m, _) = makeManager()
+    m.update(playWhenReady: true, state: .loading)
+    #expect(m.playing == true)
+    #expect(m.buffering == true)
+  }
+
+  @Test @MainActor
+  func notPlaying_withoutIntent() {
+    let (m, _) = makeManager()
+    m.update(playWhenReady: false, state: .playing)
+    #expect(m.playing == false)
+  }
+
+  /// Terminal states are not playable regardless of intent. .stopped was
+  /// missing from the exclusion list — masked only by stop() clearing
+  /// playWhenReady right after transitioning, which made the gap latent.
+  @Test @MainActor
+  func notPlaying_inTerminalStates_evenWithIntent() {
+    for state in [PlaybackState.none, .stopped, .ended, .error] {
+      let (m, _) = makeManager()
+      m.update(playWhenReady: true, state: state)
+      #expect(m.playing == false, "Expected not playing in \(state) despite intent")
+    }
+  }
+
+  @Test @MainActor
+  func onChange_firesOnlyOnActualChange() {
+    let (m, changes) = makeManager()
+    m.update(playWhenReady: true, state: .playing)
+    m.update(playWhenReady: true, state: .playing)
+    #expect(changes().count == 1)
+  }
+}

package/ios/Tests/QueueManagerTests.swift

@@ -74,6 +74,52 @@ struct NextTests {
     #expect(q.currentIndex == 0)
   }
 
+  /// The start track must be first in the shuffle order, not wherever the permutation put it —
+  /// otherwise auto-advance ends the queue as soon as it is reached (#96).
+  @Test func shuffle_startTrackLeadsTheOrder() {
+    for start in 0 ..< 6 {
+      let q = QueueManager()
+      q.setQueue(tracks("a", "b", "c", "d", "e", "f"), initialIndex: start)
+      q.shuffleEnabled = true
+
+      #expect(q.shuffleOrder.isFirst(start))
+      #expect(!q.isLastInPlaybackOrder)
+      #expect(q.nextTracks.count == 5)
+      #expect(q.previousTracks.isEmpty)
+    }
+  }
+
+  /// Same hazard on enabling shuffle mid-queue: the existing order has the current track wherever
+  /// it landed, so without re-pinning, turning shuffle on can immediately report end-of-queue.
+  @Test func shuffle_enablingMidQueueLeadsFromCurrent() {
+    for start in 0 ..< 6 {
+      let q = QueueManager()
+      q.setQueue(tracks("a", "b", "c", "d", "e", "f"))
+      _ = try? q.skipTo(start)
+
+      q.shuffleEnabled = true
+
+      #expect(q.shuffleOrder.isFirst(start))
+      #expect(!q.isLastInPlaybackOrder)
+      #expect(q.nextTracks.count == 5)
+    }
+  }
+
+  /// Re-pinning happens on enable only — flipping it off and on again must not renege on the
+  /// order mid-listen, and a redundant `= true` must not reshuffle under the listener.
+  @Test func shuffle_redundantEnableKeepsTheOrder() {
+    let q = QueueManager()
+    q.setQueue(tracks("a", "b", "c", "d", "e", "f"))
+    q.shuffleEnabled = true
+    let order = q.shuffleOrder.shuffled
+
+    q.shuffleEnabled = true
+    #expect(q.shuffleOrder.shuffled == order)
+
+    q.shuffleEnabled = false
+    #expect(q.shuffleOrder.shuffled == order)
+  }
+
   @Test func shuffle_visitsAllTracks() {
     let q = QueueManager()
     q.setQueue(tracks("a", "b", "c", "d"))
@@ -390,16 +436,16 @@ struct AddAtTests {
     #expect(try q.addAt([], at: 0) == false)
   }
 
-  @Test func singleExistingTrack_insertBeforeCurrent_doesNotShift() throws {
+  @Test func singleExistingTrack_insertBeforeCurrent_shifts() throws {
     let q = QueueManager()
     q.setQueue(tracks("a"))
-    // guard `tracks.count > 1` is false (count is 1), so currentIndex is NOT shifted.
-    // The original track moves to index 1 but currentIndex stays 0.
     let changed = try q.addAt(tracks("x"), at: 0)
     #expect(changed == false)
-    #expect(q.currentIndex == 0)
-    // currentTrack is now "x" (the inserted track), not "a"
-    #expect(q.currentTrack?.id == "x")
+    // The pointer follows the playing track — the old `tracks.count > 1`
+    // guard silently swapped currentTrack to the inserted track while the
+    // player kept playing the old one.
+    #expect(q.currentIndex == 1)
+    #expect(q.currentTrack?.id == "a")
   }
 
   @Test func atExactCurrentIndex_shiftsCurrentIndex() throws {
@@ -524,13 +570,17 @@ struct RemoveTests {
 @Suite("move()")
 @MainActor
 struct MoveTests {
-  @Test func currentTrack_returnsTrue_updatesIndex() throws {
+  // A move never changes which track is current — the pointer follows the
+  // track, and no move returns true (true triggers a reload at the caller,
+  // which would restart playback on a reorder).
+
+  @Test func currentTrack_pointerFollows() throws {
     let q = QueueManager()
     q.setQueue(tracks("a", "b", "c"), initialIndex: 0)
     let changed = try q.move(fromIndex: 0, toIndex: 2)
-    #expect(changed == true)
+    #expect(changed == false)
     #expect(q.currentIndex == 2)
-    #expect(q.tracks[2].id == "a")
+    #expect(q.currentTrack?.id == "a")
   }
 
   @Test func nonCurrent_returnsFalse() throws {
@@ -548,26 +598,37 @@ struct MoveTests {
     }
   }
 
-  @Test func nonCurrent_acrossCurrent_doesNotAdjustIndex() throws {
+  @Test func nonCurrent_acrossCurrent_keepsPointerOnSameTrack() throws {
     let q = QueueManager()
     q.setQueue(tracks("a", "b", "c"), initialIndex: 1)
-    // Move track from before current to after current.
-    // currentIndex is NOT adjusted (only adjusted when fromIndex == currentIndex).
     let changed = try q.move(fromIndex: 0, toIndex: 2)
     #expect(changed == false)
-    #expect(q.currentIndex == 1)
-    // After remove(0): [b, c], insert at min(2,2)=2: [b, c, a]
-    // currentIndex 1 now points to "c", not "b"
-    #expect(q.currentTrack?.id == "c")
+    // [a,b,c] → [b,c,a]; "b" is now index 0.
+    #expect(q.currentTrack?.id == "b")
+    #expect(q.currentIndex == 0)
   }
 
-  @Test func toIndexBeyondCount_clampsToEnd() throws {
+  @Test func nonCurrent_acrossCurrentBackwards_keepsPointerOnSameTrack() throws {
+    let q = QueueManager()
+    q.setQueue(tracks("a", "b", "c"), initialIndex: 1)
+    let changed = try q.move(fromIndex: 2, toIndex: 0)
+    #expect(changed == false)
+    // [a,b,c] → [c,a,b]; "b" is now index 2.
+    #expect(q.currentTrack?.id == "b")
+    #expect(q.currentIndex == 2)
+  }
+
+  @Test func toIndexBeyondCount_clampsPointerToo() throws {
     let q = QueueManager()
     q.setQueue(tracks("a", "b", "c"), initialIndex: 0)
     let changed = try q.move(fromIndex: 0, toIndex: 99)
-    #expect(changed == true)
+    #expect(changed == false)
     // remove(0): [b, c], insert at min(2, 99)=2: [b, c, a]
     #expect(q.tracks[2].id == "a")
+    // The unclamped assignment left currentIndex at 99 → currentTrack nil →
+    // a reorder unloaded playback.
+    #expect(q.currentIndex == 2)
+    #expect(q.currentTrack?.id == "a")
   }
 
   @Test func invalidFromIndex_throws() {
@@ -606,6 +667,23 @@ struct ClearTests {
     let q = QueueManager()
     #expect(q.clear() == false)
   }
+
+  /// clear() and removeUpcomingTracks() were the only mutations not
+  /// maintaining the shuffle order — a stale order over a rebuilt queue
+  /// navigates to phantom indices, nil-ing currentTrack and unloading
+  /// playback mid-session.
+  @Test func clear_alsoClearsShuffleOrder() {
+    let q = QueueManager()
+    q.shuffleEnabled = true
+    q.setQueue(tracks("a", "b", "c", "d", "e"))
+
+    q.clear()
+
+    #expect(q.shuffleOrder.shuffled.isEmpty)
+
+    _ = try? q.addAt(tracks("x", "y"), at: 0)
+    #expect(q.shuffleOrder.shuffled.count == q.tracks.count)
+  }
 }
 
 // MARK: - Other: replace, removeUpcomingTracks
@@ -620,6 +698,16 @@ struct OtherMutationTests {
     #expect(q.tracks[1].id == "B")
   }
 
+  @Test func removeUpcomingTracks_alsoTrimsShuffleOrder() {
+    let q = QueueManager()
+    q.shuffleEnabled = true
+    q.setQueue(tracks("a", "b", "c", "d", "e"), initialIndex: 1)
+
+    q.removeUpcomingTracks()
+
+    #expect(q.shuffleOrder.shuffled.count == q.tracks.count)
+  }
+
   @Test func removeUpcomingTracks_keepsCurrentAndBefore() {
     let q = QueueManager()
     q.setQueue(tracks("a", "b", "c", "d"), initialIndex: 1)
@@ -878,3 +966,92 @@ struct DelegateTests {
     #expect(spy.calls.isEmpty)
   }
 }
+
+// MARK: - canNext / canPrevious
+
+@Suite("canNext / canPrevious")
+@MainActor
+struct SkipAvailabilityTests {
+  @Test func emptyQueue_bothFalse() {
+    let q = QueueManager()
+    #expect(q.canNext == false)
+    #expect(q.canPrevious == false)
+  }
+
+  @Test func singleTrack_repeatOff_bothFalse() {
+    let q = QueueManager()
+    q.setQueue(tracks("a"))
+    #expect(q.canNext == false)
+    #expect(q.canPrevious == false)
+  }
+
+  @Test func singleTrack_repeatQueue_bothFalse() {
+    let q = QueueManager()
+    q.setQueue(tracks("a"))
+    q.repeatMode = .queue
+    #expect(q.canNext == false)
+    #expect(q.canPrevious == false)
+  }
+
+  @Test func firstOfMany_nextOnly() {
+    let q = QueueManager()
+    q.setQueue(tracks("a", "b", "c"), initialIndex: 0)
+    #expect(q.canNext == true)
+    #expect(q.canPrevious == false)
+  }
+
+  @Test func middleOfMany_both() {
+    let q = QueueManager()
+    q.setQueue(tracks("a", "b", "c"), initialIndex: 1)
+    #expect(q.canNext == true)
+    #expect(q.canPrevious == true)
+  }
+
+  @Test func lastOfMany_repeatOff_previousOnly() {
+    let q = QueueManager()
+    q.setQueue(tracks("a", "b", "c"), initialIndex: 2)
+    #expect(q.canNext == false)
+    #expect(q.canPrevious == true)
+  }
+
+  @Test func lastOfMany_repeatQueue_bothTrue() {
+    let q = QueueManager()
+    q.setQueue(tracks("a", "b", "c"), initialIndex: 2)
+    q.repeatMode = .queue
+    #expect(q.canNext == true) // wraps to first
+    #expect(q.canPrevious == true)
+  }
+
+  @Test func firstOfMany_repeatQueue_bothTrue() {
+    let q = QueueManager()
+    q.setQueue(tracks("a", "b", "c"), initialIndex: 0)
+    q.repeatMode = .queue
+    #expect(q.canNext == true)
+    #expect(q.canPrevious == true) // wraps to last
+  }
+
+  // Shuffle wraps the playback order unconditionally (even with repeat off), so
+  // next()/previous() always move when count > 1 — canNext/canPrevious must
+  // agree at the shuffle-order boundaries, not grey out.
+  @Test func shuffleEnd_repeatOff_canNextTrue() {
+    let q = QueueManager()
+    q.setQueue(tracks("a", "b", "c", "d"))
+    q.shuffleEnabled = true
+    q.repeatMode = .off
+    while !q.isLastInPlaybackOrder {
+      _ = q.next()
+    } // advance to last in shuffle order
+    #expect(q.canNext == true) // next() wraps to the first shuffle position
+  }
+
+  @Test func shuffleStart_repeatOff_canPreviousTrue() {
+    let q = QueueManager()
+    q.setQueue(tracks("a", "b", "c", "d"))
+    q.shuffleEnabled = true
+    q.repeatMode = .off
+    while !q.previousTracks.isEmpty {
+      _ = q.previous()
+    } // back to first in shuffle order
+    #expect(q.canPrevious == true) // previous() wraps to the last shuffle position
+  }
+}

package/ios/Tests/RemoteCommandControllerTests.swift

@@ -0,0 +1,156 @@
+import Foundation
+import MediaPlayer
+import Testing
+
+@testable import AudioBrowserTestable
+
+/// Exercises the controller against the real `MPRemoteCommandCenter`.
+///
+/// `MPRemoteCommandCenter`'s `init()` is unavailable, so `shared()` — a
+/// process-wide singleton — is the only center available. The suite is
+/// `.serialized` because of that shared state, and every test resets the
+/// commands it touches through `reset()`.
+@Suite("RemoteCommandController", .serialized)
+@MainActor
+struct RemoteCommandControllerTests {
+  final class SpyCallbacks: RemoteCommandCallbacks {
+    var events: [String] = []
+    func remotePlay() { events.append("play") }
+    func remotePause() { events.append("pause") }
+    func remoteStop() { events.append("stop") }
+    func remotePlayPause() { events.append("playPause") }
+    func remoteNext() { events.append("next") }
+    func remotePrevious() { events.append("previous") }
+    func remoteJumpForward(interval: Double) { events.append("jumpForward:\(interval)") }
+    func remoteJumpBackward(interval: Double) { events.append("jumpBackward:\(interval)") }
+    func remoteSeek(position: Double) { events.append("seek:\(position)") }
+    func remoteChangeRepeatMode(mode: RepeatMode) { events.append("repeat:\(mode)") }
+    func remoteChangeShuffleMode(enabled: Bool) { events.append("shuffle:\(enabled)") }
+    func remoteChangePlaybackRate(rate: Float) { events.append("rate:\(rate)") }
+  }
+
+  /// Clears every command on the shared center so a test starts from a known
+  /// state regardless of what ran before it.
+  private func makeController() -> (RemoteCommandController, SpyCallbacks) {
+    let center = MPRemoteCommandCenter.shared()
+    let reset = RemoteCommandController(remoteCommandCenter: center)
+    reset.enable(commands: RemoteCommand.all())
+    reset.disableAll()
+
+    let spy = SpyCallbacks()
+    return (RemoteCommandController(remoteCommandCenter: center, callbacks: spy), spy)
+  }
+
+  /// The reported bug: a changed jump interval used to disable the very command
+  /// it had just re-enabled, removing the skip button from the lock screen,
+  /// Control Center and CarPlay while `enabledCommands` still reported it on.
+  @Test func changedJumpIntervalKeepsCommandEnabled() {
+    let (controller, _) = makeController()
+    let center = MPRemoteCommandCenter.shared()
+
+    controller.enable(commands: [
+      .play, .skipForward(preferredIntervals: [15]), .skipBackward(preferredIntervals: [15]),
+    ])
+    #expect(center.skipForwardCommand.isEnabled)
+
+    controller.enable(commands: [
+      .play, .skipForward(preferredIntervals: [30]), .skipBackward(preferredIntervals: [30]),
+    ])
+
+    #expect(center.skipForwardCommand.isEnabled)
+    #expect(center.skipBackwardCommand.isEnabled)
+    #expect(controller.commandTargetPointers["skipForward"] != nil)
+    #expect(controller.commandTargetPointers["skipBackward"] != nil)
+    #expect(center.skipForwardCommand.preferredIntervals == [30])
+    #expect(center.skipBackwardCommand.preferredIntervals == [30])
+  }
+
+  @Test func changedPlaybackRatesKeepCommandEnabled() {
+    let (controller, _) = makeController()
+    let center = MPRemoteCommandCenter.shared()
+
+    controller.enable(commands: [.changePlaybackRate(supportedPlaybackRates: [1.0])])
+    controller.enable(commands: [.changePlaybackRate(supportedPlaybackRates: [1.0, 1.5, 2.0])])
+
+    #expect(center.changePlaybackRateCommand.isEnabled)
+    #expect(controller.commandTargetPointers["changePlaybackRate"] != nil)
+    #expect(center.changePlaybackRateCommand.supportedPlaybackRates == [1.0, 1.5, 2.0])
+  }
+
+  @Test func removedCommandIsDisabledAndUntargeted() {
+    let (controller, _) = makeController()
+    let center = MPRemoteCommandCenter.shared()
+
+    controller.enable(commands: [.play, .pause, .next])
+    #expect(center.nextTrackCommand.isEnabled)
+
+    controller.enable(commands: [.play, .pause])
+
+    #expect(!center.nextTrackCommand.isEnabled)
+    #expect(controller.commandTargetPointers["nextTrack"] == nil)
+    #expect(center.playCommand.isEnabled)
+    #expect(controller.commandTargetPointers["play"] != nil)
+  }
+
+  @Test func disableAllClearsEveryTarget() {
+    let (controller, _) = makeController()
+    let center = MPRemoteCommandCenter.shared()
+
+    controller.enable(commands: [.play, .pause, .skipForward(preferredIntervals: [15])])
+    controller.disableAll()
+
+    #expect(controller.commandTargetPointers.isEmpty)
+    #expect(!center.playCommand.isEnabled)
+    #expect(!center.pauseCommand.isEnabled)
+    #expect(!center.skipForwardCommand.isEnabled)
+  }
+
+  /// Re-enabling the same set must not accumulate handlers: `enableRemoteCommand`
+  /// removes the previous target before adding the new one.
+  @Test func reEnablingKeepsOneTargetPerCommand() {
+    let (controller, _) = makeController()
+
+    controller.enable(commands: [.play, .pause])
+    let first = controller.commandTargetPointers["play"]
+    controller.enable(commands: [.play, .pause])
+    let second = controller.commandTargetPointers["play"]
+
+    #expect(controller.commandTargetPointers.count == 2)
+    #expect(first as AnyObject? !== second as AnyObject?)
+  }
+
+  /// `setSkipAvailability` greys out next/previous when the queue has nowhere to
+  /// go, and the state must survive a later `enable(commands:)`.
+  @Test func skipAvailabilitySurvivesReEnable() {
+    let (controller, _) = makeController()
+    let center = MPRemoteCommandCenter.shared()
+
+    controller.enable(commands: [.next, .previous])
+    controller.setSkipAvailability(canNext: false, canPrevious: true)
+    #expect(!center.nextTrackCommand.isEnabled)
+    #expect(center.previousTrackCommand.isEnabled)
+
+    controller.enable(commands: [.next, .previous, .play])
+
+    #expect(!center.nextTrackCommand.isEnabled)
+    #expect(center.previousTrackCommand.isEnabled)
+  }
+
+  @Test func shuffleAndRepeatStateSurviveCommandCenterSwitch() {
+    let (controller, _) = makeController()
+    let center = MPRemoteCommandCenter.shared()
+
+    controller.enable(commands: [.changeShuffleMode, .changeRepeatMode])
+    controller.updateShuffleMode(true)
+    controller.updateRepeatMode(.queue)
+
+    // Same center — switchCommandCenter no-ops, but the restore path is the
+    // interesting part: state is re-applied from the stored values.
+    controller.switchCommandCenter(center)
+
+    #expect(center.changeShuffleModeCommand.currentShuffleType == .items)
+    #expect(center.changeRepeatModeCommand.currentRepeatType == .all)
+    #expect(center.changeShuffleModeCommand.isEnabled)
+    #expect(controller.commandTargetPointers["changeShuffleMode"] != nil)
+  }
+}

package/ios/Tests/RemoteCommandTests.swift

@@ -0,0 +1,67 @@
+import Foundation
+import Testing
+
+@testable import AudioBrowserTestable
+
+@Suite("RemoteCommand")
+struct RemoteCommandTests {
+  @Test func removedCommandsAreDisabled() {
+    let toDisable = RemoteCommand.commandsToDisable(
+      enabled: [.play, .pause, .next, .previous],
+      replacedBy: [.play, .pause],
+    )
+    #expect(toDisable.map(\.key) == ["nextTrack", "previousTrack"])
+  }
+
+  @Test func retainedCommandsAreNotDisabled() {
+    let toDisable = RemoteCommand.commandsToDisable(
+      enabled: [.play, .pause],
+      replacedBy: [.play, .pause, .stop],
+    )
+    #expect(toDisable.isEmpty)
+  }
+
+  /// A changed jump interval is the same command with a new associated value —
+  /// diffing by `==` would report it as removed and disable the button that the
+  /// update had just re-enabled.
+  @Test func changedJumpIntervalIsNotDisabled() {
+    let toDisable = RemoteCommand.commandsToDisable(
+      enabled: [.skipForward(preferredIntervals: [15]), .skipBackward(preferredIntervals: [15])],
+      replacedBy: [.skipForward(preferredIntervals: [30]), .skipBackward(preferredIntervals: [30])],
+    )
+    #expect(toDisable.isEmpty)
+  }
+
+  @Test func changedPlaybackRatesAreNotDisabled() {
+    let toDisable = RemoteCommand.commandsToDisable(
+      enabled: [.changePlaybackRate(supportedPlaybackRates: [1.0])],
+      replacedBy: [.changePlaybackRate(supportedPlaybackRates: [1.0, 1.5, 2.0])],
+    )
+    #expect(toDisable.isEmpty)
+  }
+
+  @Test func everyCommandIsDisabledWhenNoneRemain() {
+    let toDisable = RemoteCommand.commandsToDisable(
+      enabled: RemoteCommand.all(),
+      replacedBy: [],
+    )
+    #expect(toDisable.count == RemoteCommand.all().count)
+  }
+
+  /// `key` is the identity used both for the diff above and for the
+  /// `commandTargetPointers` slot each command's handler lives in. Two cases
+  /// sharing a key would silently share one slot: enabling one would remove the
+  /// other's handler.
+  @Test func keysAreUnique() {
+    let all = RemoteCommand.all()
+    #expect(Set(all.map(\.key)).count == all.count)
+  }
+
+  @Test func droppedJumpCommandIsStillDisabled() {
+    let toDisable = RemoteCommand.commandsToDisable(
+      enabled: [.play, .skipForward(preferredIntervals: [15])],
+      replacedBy: [.play],
+    )
+    #expect(toDisable.map(\.key) == ["skipForward"])
+  }
+}