react-native-audio-browser 0.2.0-next.1 → 0.2.0-next.11

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)
@@ -457,7 +483,7 @@ public class HybridAudioBrowser: HybridAudioBrowserSpec, @unchecked Sendable {
     }
   }
 
-  public func onSearch(query: String) throws -> Promise<[Track]> {
+  public func search(query: String) throws -> Promise<[Track]> {
     Promise.async { [weak self] in
       guard let self else { return [] }
       let resolved = try await browserManager.search(query)
@@ -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/NitroTypeStubs.swift

@@ -5,6 +5,12 @@
   /// These stubs declare `Equatable` for test ergonomics — the generated
   /// Nitro types do NOT. Shared `ios/` sources must not rely on conformances
   /// that exist only here: `swift test` compiles, the app build breaks.
+  ///
+  /// Property names and types ARE checked against `nitrogen/generated/ios/swift`
+  /// by `src/nitro-stub-drift.test.ts`, which runs in the JS CI job — neither
+  /// native job can see both files at once. Declaring fewer properties than the
+  /// real type is fine and deliberate; spelling one differently is what that
+  /// test catches. Conformances and default values are still on you.
 
   struct ArtworkVariants: Equatable {
     var light: String
@@ -23,7 +29,7 @@
   }
 
   struct Track: Equatable {
-    var id: String
+    var id: String?
     var url: String?
     var src: String?
     var request: TrackRequest?
@@ -63,9 +69,19 @@
     }
   }
 
+  enum HttpMethod {
+    case get
+    case post
+    case put
+    case patch
+    case delete
+    case head
+    case options
+  }
+
   struct ImageSource: Equatable {
     var uri: String
-    var method: String?
+    var method: HttpMethod?
     var headers: [String: String]?
     var body: String?
   }

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/MediaLoader.swift

@@ -25,7 +25,9 @@ final class MediaLoader {
 
   weak var delegate: MediaLoaderDelegate?
 
-  private var mediaResolverTask: Task<Void, Never>?
+  /// The in-flight resolve. Readable so tests can await the resolve-then-load
+  /// chain instead of sleeping past it; only this type starts and cancels it.
+  private(set) var mediaResolverTask: Task<Void, Never>?
   private var metadataLoadTask: Task<Void, Never>?
   private var playableLoadTask: Task<Void, Never>?
   private var url: URL?

package/ios/Player/PlaybackCoordinator.swift

@@ -76,7 +76,10 @@ class PlaybackCoordinator {
   /// the window/attempt counters otherwise reset only on track change.
   /// Overridable in tests.
   var healthyPlaybackDuration: TimeInterval = 20
-  private var healthyPlaybackTask: Task<Void, Never>?
+
+  /// The pending refill. Readable so tests can await the window instead of
+  /// sleeping past it; only this type arms and cancels it.
+  private(set) var healthyPlaybackTask: Task<Void, Never>?
 
   /// Playback rate (1.0 = normal speed).
   var rate: Float = 1.0

package/ios/Player/PlaybackErrorHandler.swift

@@ -8,7 +8,7 @@ import os.log
   var isEnabled: Bool { get }
   /// Whether the current load has produced audio — selects the retry budget.
   var hasPlayed: Bool { get set }
-  func isRetryable(_ error: Error?) -> Bool
+  func isRetryable(_ error: Error?, httpStatusCode: Int?) -> Bool
   func attemptRetry(startFromCurrentTime: Bool) async -> Bool
   func reset()
 }
@@ -62,7 +62,7 @@ public enum PlaybackErrorContext {
       logger.error("[\(String(describing: context))] failure with nil error")
     }
 
-    if retryHandler.isEnabled, retryHandler.isRetryable(error) {
+    if retryHandler.isEnabled, retryHandler.isRetryable(error, httpStatusCode: httpStatusCode) {
       onRetryingError?(PlaybackErrorHandler.classify(
         error: error, fallback: context.fallbackError, httpStatusCode: httpStatusCode,
       ))
@@ -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/QueueManager.swift

@@ -45,8 +45,15 @@ class QueueManager {
   /// The repeat mode for the queue. Plain property — no side effects.
   var repeatMode: RepeatMode = .off
 
-  /// Whether shuffle mode is enabled. Plain property — no side effects.
-  var shuffleEnabled: Bool = false
+  /// Whether shuffle mode is enabled.
+  var shuffleEnabled: Bool = false {
+    didSet {
+      // Re-pin on enable: the existing order has the current track wherever it happened to land,
+      // so without this, turning shuffle on near the end of the queue ends it right away.
+      guard shuffleEnabled, shuffleEnabled != oldValue else { return }
+      shuffleOrder.reshuffle(keepingFirst: currentIndex)
+    }
+  }
 
   // MARK: - Computed Properties
 
@@ -206,7 +213,7 @@ class QueueManager {
     currentIndex = clampedIndex
     queueSourcePath = sourcePath
     tracks = newTracks
-    shuffleOrder = ShuffleOrder(length: newTracks.count)
+    shuffleOrder = ShuffleOrder(length: newTracks.count, firstIndex: clampedIndex)
     return true
   }