react-native-audio-browser 0.2.0-next.7 → 0.2.0-next.9

package/ios/HybridAudioBrowser.swift

@@ -16,6 +16,10 @@ import os.log
 /// Only safe when the caller blocks until the MainActor work completes (DispatchQueue.main.sync).
 private struct UncheckedSendableBox<T>: @unchecked Sendable { let value: T }
 
+/// `@unchecked Sendable` because it must be: the spec's requirements are all
+/// nonisolated and Nitro calls them synchronously on the JS thread, so the class
+/// can't be `@MainActor`. Isolation is therefore per-property, and `@unchecked`
+/// means the compiler won't tell you when a new one needs it.
 public class HybridAudioBrowser: HybridAudioBrowserSpec, @unchecked Sendable {
   private let logger = Logger(subsystem: "com.audiobrowser", category: "AudioBrowser")
 
@@ -32,6 +36,8 @@ public class HybridAudioBrowser: HybridAudioBrowserSpec, @unchecked Sendable {
 
   // MARK: - Private Properties
 
+  /// Main-confined by convention, not annotation: `deinit` reads it as a
+  /// safety net and can't hop. Reach it from `onMainActor` / `@MainActor`.
   private var player: TrackPlayer?
   private let networkMonitor = NetworkMonitor()
   private let playbackStateStore = PlaybackStateStore()
@@ -43,27 +49,31 @@ public class HybridAudioBrowser: HybridAudioBrowserSpec, @unchecked Sendable {
   private var mediaServicesResetObserver: NSObjectProtocol?
   /// Re-applies our resolved audio-session category. Captured at setup so a
   /// media-services reset (which clears the category) can restore it.
-  private var applyAudioSessionCategory: () -> Void = {}
-  private var nowPlayingOverride: NowPlayingUpdate?
+  @MainActor private var applyAudioSessionCategory: () -> Void = {}
+  @MainActor private var nowPlayingOverride: NowPlayingUpdate?
   /// When false, the now-playing surface uses the raw track fields (override + formatter ignored).
-  private var nowPlayingMetadataEnabled = true
+  @MainActor private var nowPlayingMetadataEnabled = true
   /// Customizes the now-playing title/subtitle from the track + live timed metadata + playback state.
-  private var nowPlayingMetadataFormatter: ((_ params: FormatNowPlayingParams) -> Promise<NowPlayingUpdate?>)?
-  /// Keep the media session controllable through a terminal error (see `keepSessionAliveOnError`).
-  private var keepSessionAliveOnError = true
+  @MainActor private var nowPlayingMetadataFormatter: ((_ params: FormatNowPlayingParams) -> Promise<NowPlayingUpdate?>)?
   /// Initial player state staged before the player exists — from setup options or the imperative
   /// setters called pre-setup. Strict last-write-wins; consumed when the player comes up.
-  private var pendingPlayWhenReady: Bool?
-  private var pendingRepeatMode: RepeatMode?
+  @MainActor private var pendingPlayWhenReady: Bool?
+  @MainActor private var pendingRepeatMode: RepeatMode?
   /// Latest live timed (ICY/ID3) metadata, passed to the formatter. Cleared on track change.
-  private var latestTimedMetadata: TimedMetadata?
-  private let playerOptions = PlayerUpdateOptions()
+  @MainActor private var latestTimedMetadata: TimedMetadata?
+  @MainActor private let playerOptions = PlayerUpdateOptions()
 
   /// Configured playback rates for the playback-rate capability (for CarPlay rate cycling)
-  var playbackRates: [Double] { playerOptions.playbackRates }
-  var carPlayUpNextButton: Bool { playerOptions.carPlayUpNextButton }
-  var carPlayNowPlayingButtons: [CarPlayNowPlayingButton] { playerOptions.carPlayNowPlayingButtons }
-  private var lastNavigationError: NavigationError? {
+  @MainActor var playbackRates: [Double] { playerOptions.playbackRates }
+  @MainActor var carPlayUpNextButton: Bool { playerOptions.carPlayUpNextButton }
+  @MainActor var carPlayNowPlayingButtons: [CarPlayNowPlayingButton] {
+    playerOptions.carPlayNowPlayingButtons
+  }
+
+  /// Written from the JS thread, the cooperative pool and MainActor, with a
+  /// `didSet` that calls back into Nitro. MainActor-isolated so the compiler
+  /// requires an `onMainActor` hop at every access.
+  @MainActor private var lastNavigationError: NavigationError? {
     didSet {
       // Skip if both nil (no real change)
       guard oldValue != nil || lastNavigationError != nil else { return }
@@ -71,7 +81,8 @@ public class HybridAudioBrowser: HybridAudioBrowserSpec, @unchecked Sendable {
     }
   }
 
-  private var lastFormattedNavigationError: FormattedNavigationError? {
+  /// Isolated for the same reason as ``lastNavigationError``.
+  @MainActor private var lastFormattedNavigationError: FormattedNavigationError? {
     didSet {
       // Skip if both nil (no real change)
       guard oldValue != nil || lastFormattedNavigationError != nil else { return }
@@ -156,6 +167,10 @@ public class HybridAudioBrowser: HybridAudioBrowserSpec, @unchecked Sendable {
     androidControllerOfflineError: nil, carPlayLoadingTitle: nil, resolveAlbumUrl: nil, formatNavigationError: nil,
   ) {
     didSet {
+      // Copied here, on the setter's thread: the Task below outlives this call,
+      // and Nitro can reassign `configuration` — a C++ struct holding
+      // std::string/std::function — from the JS thread while it runs.
+      let configuredPath = configuration.path
       onMainActor { browserManager.config = BrowserConfig(from: configuration) }
 
       // Query tabs and navigate to initial path after config is set (matches Kotlin behavior)
@@ -166,12 +181,9 @@ public class HybridAudioBrowser: HybridAudioBrowserSpec, @unchecked Sendable {
       Task {
         let tabs = try? await browserManager.queryTabs()
         // Navigate to configured path, first tab, or "/"
-        let initialPath = configuration.path ?? tabs?.first?.url ?? "/"
+        let initialPath = configuredPath ?? tabs?.first?.url ?? "/"
         // Clear error before navigation (matches Kotlin clearNavigationError())
-        await MainActor.run {
-          lastNavigationError = nil
-          lastFormattedNavigationError = nil
-        }
+        clearNavigationError()
         do {
           try await browserManager.navigate(initialPath)
         } catch {
@@ -370,7 +382,7 @@ public class HybridAudioBrowser: HybridAudioBrowserSpec, @unchecked Sendable {
   private func handleNavigationError(_ error: Error, path: String) {
     let navError = NavigationError.from(error)
 
-    lastNavigationError = navError
+    onMainActor { lastNavigationError = navError }
 
     // Format the error (async if using JS callback, sync for defaults)
     let defaultFormatted = navError.defaultFormatted()
@@ -380,27 +392,40 @@ public class HybridAudioBrowser: HybridAudioBrowserSpec, @unchecked Sendable {
       // The result callbacks are @Sendable: a plain closure would inherit MainActor
       // isolation from this block, and Nitro resolves its promises synchronously on the
       // JS thread — Swift 6.2's dynamic isolation check then traps on closure entry.
-      // The property is JS-thread-touched elsewhere too, so no hop back is needed.
+      // They therefore hop back explicitly, like every other writer.
       DispatchQueue.main.async { [weak self] in
         formatter(params)
           .then { @Sendable [weak self] customDisplay in
-            self?.lastFormattedNavigationError = customDisplay ?? defaultFormatted
+            self?.setFormattedNavigationError(customDisplay ?? defaultFormatted)
           }
           .catch { @Sendable [weak self] _ in
-            self?.lastFormattedNavigationError = defaultFormatted
+            self?.setFormattedNavigationError(defaultFormatted)
           }
       }
     } else {
-      lastFormattedNavigationError = defaultFormatted
+      setFormattedNavigationError(defaultFormatted)
+    }
+  }
+
+  /// Callable from any thread — the Nitro promise callbacks below resolve on
+  /// the JS thread.
+  private func setFormattedNavigationError(_ formatted: FormattedNavigationError?) {
+    onMainActor { lastFormattedNavigationError = formatted }
+  }
+
+  /// Synchronous on purpose: the `didSet`s notify JS, which has to happen
+  /// before the navigation that may set them again.
+  private func clearNavigationError() {
+    onMainActor {
+      lastNavigationError = nil
+      lastFormattedNavigationError = nil
     }
   }
 
   // MARK: - Browser Methods
 
   public func navigatePath(path: String) throws {
-    // Clear error synchronously before starting navigation (didSet notifies JS)
-    lastNavigationError = nil
-    lastFormattedNavigationError = nil
+    clearNavigationError()
     Task {
       do {
         try await browserManager.navigate(path)
@@ -411,7 +436,10 @@ public class HybridAudioBrowser: HybridAudioBrowserSpec, @unchecked Sendable {
   }
 
   public func navigateTrack(track: Track) throws {
-    Task {
+    // @MainActor: `player` is main-confined, and `trackSelector.select` is
+    // MainActor anyway — a bare Task read the reference off the cooperative
+    // pool, racing the assignment in `setupPlayer`.
+    Task { @MainActor in
       guard let player else { return }
       let result = await trackSelector.select(track: track, player: player)
       switch result {
@@ -445,9 +473,7 @@ public class HybridAudioBrowser: HybridAudioBrowserSpec, @unchecked Sendable {
   }
 
   private func navigateToBrowsableUrl(_ url: String) {
-    // Clear error synchronously before starting navigation (didSet notifies JS)
-    lastNavigationError = nil
-    lastFormattedNavigationError = nil
+    clearNavigationError()
     Task {
       do {
         try await browserManager.navigate(url)
@@ -470,11 +496,11 @@ public class HybridAudioBrowser: HybridAudioBrowserSpec, @unchecked Sendable {
   }
 
   public func getNavigationError() throws -> NavigationError? {
-    lastNavigationError
+    onMainActor { lastNavigationError }
   }
 
   public func getFormattedNavigationError() throws -> FormattedNavigationError? {
-    lastFormattedNavigationError
+    onMainActor { lastFormattedNavigationError }
   }
 
   /// Internal signal sent on `externalContentChangedEmitter` to tell CarPlay to
@@ -601,7 +627,7 @@ public class HybridAudioBrowser: HybridAudioBrowserSpec, @unchecked Sendable {
       // built-in so the gate page still renders rather than leaking content.
       return GateOutcome(gated: true, chrome: defaultChrome ?? Self.builtInGate)
     }
-    guard decision.gated else { return GateOutcome(gated: false, chrome: nil) }  // explicit allow
+    guard decision.gated else { return GateOutcome(gated: false, chrome: nil) } // explicit allow
     return GateOutcome(gated: true, chrome: decision.gate ?? defaultChrome ?? Self.builtInGate)
   }
 
@@ -649,7 +675,7 @@ public class HybridAudioBrowser: HybridAudioBrowserSpec, @unchecked Sendable {
         category: AVAudioSession.Category,
         mode: AVAudioSession.Mode,
         policy: AVAudioSession.RouteSharingPolicy,
-        options: AVAudioSession.CategoryOptions
+        options: AVAudioSession.CategoryOptions,
       ) = options.ios?.resolveAudioSessionConfig()
         ?? (category: .playback, mode: .default, policy: .default, options: [])
       // Capture category application once so a media-services reset (which
@@ -733,16 +759,16 @@ public class HybridAudioBrowser: HybridAudioBrowserSpec, @unchecked Sendable {
           self?.onSleepTimerChanged(state)
         }
 
-        // Now-playing: whether to manage metadata, the optional formatter that owns the rendered
-        // lines, and whether to keep the session alive through a terminal error.
+        // Now-playing: whether to manage metadata, and the optional formatter that owns the
+        // rendered lines.
         nowPlayingMetadataEnabled = options.autoUpdateNowPlayingMetadata ?? true
         nowPlayingMetadataFormatter = options.nowPlayingMetadataFormatter
-        // Stored for API symmetry, but iOS needs no masking: a terminal error resolves the playback
-        // state to *paused* (PlaybackCoordinator.applySideEffects), the now-playing info is retained
-        // (never cleared on error), and next/previous stay enabled (gated on queue position, not
-        // state). So the session stays controllable through errors by default — the behavior Android
-        // achieves via InterceptingPlayer is already the iOS norm.
-        keepSessionAliveOnError = options.keepSessionAliveOnError ?? true
+        // `options.keepSessionAliveOnError` is deliberately ignored here: iOS needs no masking.
+        // A terminal error resolves the playback state to *paused*
+        // (PlaybackCoordinator.applySideEffects), the now-playing info is retained (never cleared
+        // on error), and next/previous stay enabled (gated on queue position, not state). So the
+        // session stays controllable through errors by default — the behavior Android achieves via
+        // InterceptingPlayer is already the iOS norm.
 
         // The bundled runtime options and initial state are part of the atomic launch
         // description. Stage the state first so setup options and earlier pre-setup setter
@@ -819,7 +845,7 @@ public class HybridAudioBrowser: HybridAudioBrowserSpec, @unchecked Sendable {
   }
 
   public func getOptions() throws -> Options {
-    playerOptions.toOptions()
+    onMainActor { playerOptions.toOptions() }
   }
 
   public func setPlaybackIntervalEnabled(enabled: Bool) {
@@ -1121,11 +1147,11 @@ public class HybridAudioBrowser: HybridAudioBrowserSpec, @unchecked Sendable {
   /// metadata can't stomp it mid-flash. Reverted by a NATIVE timer — JS
   /// timers pause with a backgrounded host on Android, and the lock screen
   /// is exactly the backgrounded case — and cleared early on track change.
-  private var nowPlayingFlash: NowPlayingUpdate?
-  private var nowPlayingFlashRevert: DispatchWorkItem?
+  @MainActor private var nowPlayingFlash: NowPlayingUpdate?
+  @MainActor private var nowPlayingFlashRevert: DispatchWorkItem?
 
   /// Pending debounced audio-session release (see `playerShouldReleaseSession`).
-  private var sessionReleaseWork: DispatchWorkItem?
+  @MainActor private var sessionReleaseWork: DispatchWorkItem?
 
   public func flashNowPlaying(update: NowPlayingUpdate, durationMs: Double) throws {
     onMainActor {
@@ -1151,6 +1177,7 @@ public class HybridAudioBrowser: HybridAudioBrowserSpec, @unchecked Sendable {
     }
   }
 
+  @MainActor
   private func cancelNowPlayingFlash() {
     nowPlayingFlashRevert?.cancel()
     nowPlayingFlashRevert = nil
@@ -1354,8 +1381,10 @@ public class HybridAudioBrowser: HybridAudioBrowserSpec, @unchecked Sendable {
       guard let self else { return }
       // Re-apply our category (the reset cleared it), then have the player
       // recreate itself and reconnect the current stream.
-      self.applyAudioSessionCategory()
-      self.onMainActor { self.player?.handleMediaServicesReset() }
+      self.onMainActor {
+        self.applyAudioSessionCategory()
+        self.player?.handleMediaServicesReset()
+      }
     }
   }
 
@@ -1394,7 +1423,7 @@ public class HybridAudioBrowser: HybridAudioBrowserSpec, @unchecked Sendable {
 
   public func supportsOutputSwitcher() throws -> Bool {
     // iOS can always present the system route picker (AVRoutePickerView).
-    return true
+    true
   }
 
   public func openOutputPicker() throws {
@@ -1586,6 +1615,7 @@ extension HybridAudioBrowser: TrackPlayerCallbacks {
     DispatchQueue.main.asyncAfter(deadline: .now() + 3, execute: release)
   }
 
+  @MainActor
   private func cancelSessionRelease() {
     sessionReleaseWork?.cancel()
     sessionReleaseWork = nil
@@ -1786,7 +1816,8 @@ extension HybridAudioBrowser: TrackPlayerCallbacks {
           // URL (parent container → siblings + selected index). Fall back to the single
           // track when the url isn't contextual or expansion fails.
           if let url = state.track.url,
-             let expanded = try? await browser.browserManager.expandQueueFromContextualUrl(url) {
+             let expanded = try? await browser.browserManager.expandQueueFromContextualUrl(url)
+          {
             player.setQueue(expanded.tracks, initialIndex: expanded.selectedIndex, startPositionMs: startMs, playWhenReady: true)
           } else {
             player.setQueue([track], initialIndex: 0, startPositionMs: startMs, playWhenReady: true)
@@ -1795,7 +1826,7 @@ extension HybridAudioBrowser: TrackPlayerCallbacks {
           completion(true)
         } else {
           browser.logger.error("resume: nothing playing and nothing persisted → no-op")
-          completion(false)   // nothing playing and nothing persisted
+          completion(false) // nothing playing and nothing persisted
         }
         return
       }
@@ -1812,14 +1843,14 @@ extension HybridAudioBrowser: TrackPlayerCallbacks {
         title: criteria.title,
         playlist: criteria.playlist,
         // .currentlyPlaying can't reach here — isResume routed it to resume.
-        reference: criteria.reference == .my ? .my : .unknown
+        reference: criteria.reference == .my ? .my : .unknown,
       )
 
       // Search is *finding* new content — refused when the gate decides this
       // request is gated (resume above is unaffected: the gate never blocks
       // hearing, and the gate check stays after the resume check).
       let outcome = await browser.gateDecision(
-        for: NativeGateRequest(reason: .search, path: nil, search: params)
+        for: NativeGateRequest(reason: .search, path: nil, search: params),
       )
       guard !outcome.gated else {
         browser.logger.info("handlePlayMediaIntent: search refused — gated")

package/ios/Model/RemoteCommand.swift

@@ -48,6 +48,24 @@ enum RemoteCommand: CustomStringConvertible, Equatable {
 
   var key: String { description }
 
+  /**
+   Commands in `self` that are absent from `next` and so should be disabled.
+
+   Compared by `key`, not by `==`. `RemoteCommand` is `Equatable` including its
+   associated values, but every case with associated values maps onto a single
+   `MPRemoteCommand` addressed by `key`: `.skipForward([15])` and
+   `.skipForward([30])` are two different values of one command. Diffing by `==`
+   would report the old interval as removed and disable the command that the new
+   interval had just re-enabled.
+   */
+  static func commandsToDisable(
+    enabled: [RemoteCommand],
+    replacedBy next: [RemoteCommand],
+  ) -> [RemoteCommand] {
+    let nextKeys = Set(next.map(\.key))
+    return enabled.filter { !nextKeys.contains($0.key) }
+  }
+
   /**
    All values in an array for convenience.
    Don't use for associated values.

package/ios/Model/TrackPlayerError.swift

@@ -103,10 +103,10 @@ public extension TrackPlayerError.PlaybackError {
   static func kind(forHttpStatus status: Int) -> PlaybackErrorKind {
     switch status {
     case 404, 410: .notFound
-    case 500...599: .serverError
+    case 500 ... 599: .serverError
     // Every other 4xx is the server refusing us — auth, geo-blocking, a
     // rate limit. All of them mean "you can't have this stream", not "retry".
-    case 400...499: .rejected
+    case 400 ... 499: .rejected
     default: .unknown
     }
   }

package/ios/Option/SessionCategories.swift

@@ -99,7 +99,7 @@ extension NativeIOSSetupOptions {
     category: AVAudioSession.Category,
     mode: AVAudioSession.Mode,
     policy: AVAudioSession.RouteSharingPolicy,
-    options: AVAudioSession.CategoryOptions
+    options: AVAudioSession.CategoryOptions,
   ) {
     let category = self.category
       .flatMap { SessionCategory(rawValue: $0.stringValue) }?
@@ -113,7 +113,8 @@ extension NativeIOSSetupOptions {
     let options = (self.categoryOptions ?? [])
       .reduce(into: AVAudioSession.CategoryOptions()) { acc, option in
         if let mapped = SessionCategoryOptions(rawValue: option.stringValue)?
-          .mapConfigToAVAudioSessionCategoryOptions() {
+          .mapConfigToAVAudioSessionCategoryOptions()
+        {
           acc.insert(mapped)
         }
       }

package/ios/Player/MediaIntentCriteria.swift

@@ -43,7 +43,7 @@ public struct MediaIntentCriteria: Sendable {
     artist: String? = nil,
     album: String? = nil,
     title: String? = nil,
-    playlist: String? = nil
+    playlist: String? = nil,
   ) {
     self.query = query
     self.reference = reference
@@ -90,7 +90,7 @@ public struct MediaIntentCriteria: Sendable {
     mediaTypeMode: String?,
     reference: Reference,
     hasMediaType: Bool,
-    appName: String?
+    appName: String?,
   ) -> MediaIntentCriteria {
     let name = (mediaName ?? "").trimmingCharacters(in: .whitespacesAndNewlines)
     let trimmedNonEmpty: (String?) -> String? = {
@@ -115,12 +115,12 @@ public struct MediaIntentCriteria: Sendable {
       hasGenres: !genreNames.isEmpty,
       hasMediaType: hasMediaType,
       matchesAppName: queryMatchesAppName(query, appName: appName),
-      searchMode: mediaTypeMode,   // mode is the vertical, verbatim — no derivation
+      searchMode: mediaTypeMode, // mode is the vertical, verbatim — no derivation
       genre: genre,
       artist: artist,
       album: album,
       title: title,
-      playlist: playlist
+      playlist: playlist,
     )
   }
 

package/ios/Player/PlaybackErrorHandler.swift

@@ -138,7 +138,7 @@ public enum PlaybackErrorContext {
       }
     }
 
-    if let httpStatusCode, !(200...299).contains(httpStatusCode) {
+    if let httpStatusCode, !(200 ... 299).contains(httpStatusCode) {
       return .httpStatus(httpStatusCode)
     }
 
@@ -155,7 +155,7 @@ public enum PlaybackErrorContext {
   /// with HTTP statuses — so only in-range values count, and the newest wins:
   /// a live stream reconnects, and older entries describe earlier attempts.
   public static func httpStatusCode(fromErrorStatusCodes codes: [Int]) -> Int? {
-    codes.last { (100...599).contains($0) }
+    codes.last { (100 ... 599).contains($0) }
   }
 
   /// The stream was fetched but cannot be decoded — unknown container,

package/ios/Player/RetryManager.swift

@@ -170,7 +170,8 @@ class RetryManager {
       return "max retry duration (\(maxRetryDuration)s)"
     }
     if !hasPlayed, isOnline, let start = firstOnlineRetryTime,
-       now.timeIntervalSince(start) >= firstConnectMaxRetryDuration {
+       now.timeIntervalSince(start) >= firstConnectMaxRetryDuration
+    {
       return "first-connect retry duration (\(firstConnectMaxRetryDuration)s)"
     }
     return nil

package/ios/RemoteCommand/RemoteCommandCallbacks.swift

@@ -0,0 +1,47 @@
+#if canImport(NitroModules)
+  import NitroModules
+#endif
+
+/// The callbacks `RemoteCommandController` invokes when the system delivers a
+/// remote command (lock screen, Control Center, CarPlay, headset).
+///
+/// Split out of `TrackPlayerCallbacks` — which the controller does not otherwise
+/// use — so the controller depends only on what it calls. `TrackPlayerCallbacks`
+/// extends this protocol, so conformers implement both at once.
+@MainActor protocol RemoteCommandCallbacks: AnyObject {
+  /// Called when play is triggered remotely.
+  func remotePlay()
+
+  /// Called when pause is triggered remotely.
+  func remotePause()
+
+  /// Called when stop is triggered remotely.
+  func remoteStop()
+
+  /// Called when toggle play/pause is triggered remotely.
+  func remotePlayPause()
+
+  /// Called when next is triggered remotely.
+  func remoteNext()
+
+  /// Called when previous is triggered remotely.
+  func remotePrevious()
+
+  /// Called when jump forward is triggered remotely.
+  func remoteJumpForward(interval: Double)
+
+  /// Called when jump backward is triggered remotely.
+  func remoteJumpBackward(interval: Double)
+
+  /// Called when seek is triggered remotely.
+  func remoteSeek(position: Double)
+
+  /// Called when repeat mode change is triggered remotely (CarPlay/lock screen).
+  func remoteChangeRepeatMode(mode: RepeatMode)
+
+  /// Called when shuffle mode change is triggered remotely (CarPlay/lock screen).
+  func remoteChangeShuffleMode(enabled: Bool)
+
+  /// Called when playback rate change is triggered remotely (CarPlay/lock screen).
+  func remoteChangePlaybackRate(rate: Float)
+}

package/ios/RemoteCommand/RemoteCommandController.swift

@@ -46,7 +46,7 @@ class RemoteCommandController {
   private let logger = Logger(subsystem: "com.audiobrowser", category: "RemoteCommandController")
   private var center: MPRemoteCommandCenter
 
-  weak var callbacks: TrackPlayerCallbacks?
+  weak var callbacks: RemoteCommandCallbacks?
 
   var commandTargetPointers: [String: Any] = [:]
   private var enabledCommands: [RemoteCommand] = []
@@ -72,7 +72,7 @@ class RemoteCommandController {
    */
   init(
     remoteCommandCenter: MPRemoteCommandCenter = MPRemoteCommandCenter.shared(),
-    callbacks: TrackPlayerCallbacks? = nil,
+    callbacks: RemoteCommandCallbacks? = nil,
   ) {
     center = remoteCommandCenter
     self.callbacks = callbacks
@@ -112,13 +112,16 @@ class RemoteCommandController {
   }
 
   func enable(commands: [RemoteCommand]) {
-    let commandsToDisable = enabledCommands.filter { command in
-      !commands.contains(command)
-    }
+    let commandsToDisable = RemoteCommand.commandsToDisable(
+      enabled: enabledCommands, replacedBy: commands,
+    )
 
     enabledCommands = commands
-    commands.forEach { self.enable(command: $0) }
+    // Disable first. The key diff already makes the two sets disjoint, so this
+    // is belt-and-braces: it keeps a disable from tearing down a command the
+    // enable pass just configured should the two ever overlap again.
     disable(commands: commandsToDisable)
+    commands.forEach { self.enable(command: $0) }
   }
 
   func disable(commands: [RemoteCommand]) {

package/ios/Tests/LoadSeekCoordinatorTests.swift

@@ -246,7 +246,9 @@ struct ResetTests {
     c.capture(position: 25.0)
 
     // Let the (immediately-cancelled, itemless) seek completion drain.
-    for _ in 0 ..< 20 { await Task.yield() }
+    for _ in 0 ..< 20 {
+      await Task.yield()
+    }
 
     #expect(spy.calls.isEmpty)
     #expect(c.pendingTime == 25.0)

package/ios/Tests/MediaIntentCriteriaTests.swift

@@ -57,12 +57,12 @@ struct MediaIntentCriteriaFromTests {
     mediaTypeMode: String? = nil,
     reference: MediaIntentCriteria.Reference = .unknown,
     hasMediaType: Bool = false,
-    appName: String? = "Radio Garden"
+    appName: String? = "Radio Garden",
   ) -> MediaIntentCriteria {
     MediaIntentCriteria.from(
       mediaName: mediaName, genreNames: genreNames, artistName: artistName,
       albumName: albumName, mediaTypeMode: mediaTypeMode,
-      reference: reference, hasMediaType: hasMediaType, appName: appName
+      reference: reference, hasMediaType: hasMediaType, appName: appName,
     )
   }
 

package/ios/Tests/PlaybackCoordinatorTests.swift

@@ -120,7 +120,7 @@ struct TransitionTests {
 @MainActor
 private func makeRetrying() -> (
   PlaybackCoordinator, MockRetryHandling, MockPlaybackCoordinatorCallbacks,
-  MockPlaybackEffectHandler
+  MockPlaybackEffectHandler,
 ) {
   let retryHandler = MockRetryHandling()
   retryHandler.isRetryableResult = true