react-native-audio-browser 0.2.0-next.2 → 0.2.0-next.20

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")
 
@@ -30,8 +34,28 @@ public class HybridAudioBrowser: HybridAudioBrowserSpec, @unchecked Sendable {
   /// silent.
   static let instanceChangedEmitter = Emitter<Void>()
 
+  /// Installed once, on first instance creation. React Native posts this
+  /// notification (from `RCTReloadCommand`) when a JS reload — dev or
+  /// OTA-update restart — is triggered, *before* the old runtime is destroyed:
+  /// the earliest signal that this instance's JS callbacks are about to go
+  /// stale. `init` of the replacement instance drops them too, but only after
+  /// the new runtime is up; this observer closes the window in between.
+  /// Observed by name so the library needs no React-Core dependency (and
+  /// stays inert under SPM tests, where nothing posts it).
+  @MainActor private static let reloadObserver: NSObjectProtocol = NotificationCenter.default.addObserver(
+    forName: Notification.Name("RCTTriggerReloadCommandNotification"),
+    object: nil,
+    queue: .main,
+  ) { _ in
+    MainActor.assumeIsolated {
+      HybridAudioBrowser.shared?.dropStaleJSCallbacks()
+    }
+  }
+
   // 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 +67,35 @@ 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
+  }
+
+  @MainActor var carPlayPlayingIndicatorLocation: CarPlayPlayingIndicatorLocation {
+    playerOptions.carPlayPlayingIndicatorLocation
+  }
+
+  /// 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 +103,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 }
@@ -153,9 +186,14 @@ public class HybridAudioBrowser: HybridAudioBrowserSpec, @unchecked Sendable {
   public var configuration: NativeBrowserConfiguration = .init(
     path: nil, request: nil, requestResolver: nil, browse: nil, browseResolver: nil, media: nil, artwork: nil, nowPlayingArtwork: nil, routes: nil,
     singleTrack: nil, handleTrackLoad: nil,
-    androidControllerOfflineError: nil, carPlayLoadingTitle: nil, resolveAlbumUrl: nil, formatNavigationError: nil,
+    androidControllerOfflineError: nil, viewMoreTitle: nil, carPlayLoadingTitle: nil, resolveAlbumPath: 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 +204,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?.path ?? "/"
         // Clear error before navigation (matches Kotlin clearNavigationError())
-        await MainActor.run {
-          lastNavigationError = nil
-          lastFormattedNavigationError = nil
-        }
+        clearNavigationError()
         do {
           try await browserManager.navigate(initialPath)
         } catch {
@@ -201,8 +236,14 @@ public class HybridAudioBrowser: HybridAudioBrowserSpec, @unchecked Sendable {
   /// state, e.g. CarPlay re-seeding `isGated` at scene connect). Serving content
   /// in that window would be a fail-open leak — same direction as the
   /// resolver-error path in `gateDecision`. Matches Android's default.
-  public var resolveGate: (NativeGateRequest) -> Promise<Promise<GateDecision>> = { _ in
-    Promise.resolved(withResult: Promise.resolved(withResult: GateDecision(gated: true, gate: nil)))
+  public var resolveGate: (NativeGateRequest) -> Promise<Promise<GateDecision>> = HybridAudioBrowser.defaultResolveGate
+
+  // Computed, not stored: a nonisolated static holding a non-Sendable closure
+  // is rejected under Swift 6 concurrency checking.
+  static var defaultResolveGate: (NativeGateRequest) -> Promise<Promise<GateDecision>> {
+    { _ in
+      Promise.resolved(withResult: Promise.resolved(withResult: GateDecision(gated: true, gate: nil)))
+    }
   }
 
   /// Fired when a request is gated (served the gate). Set by JS.
@@ -294,7 +335,11 @@ public class HybridAudioBrowser: HybridAudioBrowserSpec, @unchecked Sendable {
     // playerAndConfiguredBrowser OnceValue, so we must explicitly stop
     // its player to prevent two audio streams running simultaneously.
     onMainActor {
+      // Statics are lazy — touch the observer so it's installed from the first
+      // instance onward.
+      _ = HybridAudioBrowser.reloadObserver
       HybridAudioBrowser.shared?.player?.destroy()
+      HybridAudioBrowser.shared?.dropStaleJSCallbacks()
       playerAndConfiguredBrowser.reset()
       HybridAudioBrowser.shared = self
       // Tell connected external controllers (CarPlay) to re-subscribe against
@@ -307,7 +352,52 @@ public class HybridAudioBrowser: HybridAudioBrowserSpec, @unchecked Sendable {
     setupBrowserCallbacks()
   }
 
+  /// Drops every JS-provided callback that native code can invoke on its own
+  /// initiative (browse resolvers, `handleTrackLoad`, `resolveAlbumPath`,
+  /// `formatNavigationError`, `resolveGate`, the now-playing formatter).
+  ///
+  /// Called on the *previous* instance when a new one takes over: its JS runtime
+  /// is gone, and invoking a callback from a dead runtime aborts the process —
+  /// Nitro's `AsyncJSCallback` throws on a destroyed Dispatcher, and the throw
+  /// crosses the generated bridge wrapper's `noexcept` boundary. Native code
+  /// (e.g. a CarPlay controller still bound to this instance mid-reload) keeps
+  /// working off the data-only config with built-in fallbacks; `resolveGate`
+  /// reverts to the fail-closed default it documents for exactly this window.
+  /// One-shot: on a normal reload both triggers hit the same dying instance
+  /// (the reload notification, then the replacement's `init`), and the second
+  /// strip would re-fire the config-setter cascade — another `onConfigChanged`
+  /// → CarPlay now-playing button rebuild — for nothing.
+  @MainActor private var didDropJSCallbacks = false
+
+  @MainActor
+  private func dropStaleJSCallbacks() {
+    guard !didDropJSCallbacks else { return }
+    didDropJSCallbacks = true
+    // Guarded: assigning `config` marks the browser configured (the setter's
+    // didSet), and a never-configured browser must keep cold-start waiters
+    // (CarPlay, Siri) blocked on the readiness gate rather than resolve them
+    // against an empty config.
+    if browserManager.isConfigured {
+      browserManager.config = browserManager.config.strippingJSCallbacks()
+    }
+    resolveGate = Self.defaultResolveGate
+    nowPlayingMetadataFormatter = nil
+  }
+
   deinit {
+    // Block-based notification observers are retained by the center until an
+    // explicit removeObserver — observer death isn't detected — so without this
+    // every JS reload strands another token + closure. They capture `self`
+    // weakly, so a stranded one no-ops rather than misbehaving; what accumulates
+    // is the tokens and a wasted main-queue dispatch per interruption / route
+    // change / media-services reset. (`volumeObservation` needs no counterpart:
+    // NSKeyValueObservation invalidates itself when this instance releases it.)
+    for observer in [interruptionObserver, routeChangeObserver, mediaServicesResetObserver]
+      .compactMap(\.self)
+    {
+      NotificationCenter.default.removeObserver(observer)
+    }
+
     // Safety net: ensure the AVPlayer is stopped if this instance is deallocated.
     let player = self.player
     if Thread.isMainThread {
@@ -370,7 +460,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 +470,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 +514,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 {
@@ -419,8 +525,8 @@ public class HybridAudioBrowser: HybridAudioBrowserSpec, @unchecked Sendable {
         executePlayback(intent)
       case .intercepted:
         break
-      case let .browse(url):
-        navigateToBrowsableUrl(url)
+      case let .browse(path):
+        navigateToBrowsablePath(path)
       case .none:
         break
       }
@@ -444,24 +550,22 @@ public class HybridAudioBrowser: HybridAudioBrowserSpec, @unchecked Sendable {
     }
   }
 
-  private func navigateToBrowsableUrl(_ url: String) {
-    // Clear error synchronously before starting navigation (didSet notifies JS)
-    lastNavigationError = nil
-    lastFormattedNavigationError = nil
+  private func navigateToBrowsablePath(_ path: String) {
+    clearNavigationError()
     Task {
       do {
-        try await browserManager.navigate(url)
+        try await browserManager.navigate(path)
       } catch {
-        handleNavigationError(error, path: url)
+        handleNavigationError(error, path: path)
       }
     }
   }
 
-  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)
-      return resolved.children ?? []
+      return resolved.flattenedChildren ?? []
     }
   }
 
@@ -470,11 +574,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
@@ -484,7 +588,9 @@ public class HybridAudioBrowser: HybridAudioBrowserSpec, @unchecked Sendable {
   static let invalidateAllSentinel = "__rnab_invalidate_all__"
 
   public func notifyContentChanged(path: String) throws {
-    onMainActor { browserManager.invalidateContentCache(path) }
+    // Throws on a contextual path (matching Android's `require`) — the caller
+    // must pass the container path, or the invalidation silently hits nothing.
+    try onMainActor { try browserManager.invalidateContentCache(path) }
 
     // Notify external controllers (CarPlay) that content changed
     externalContentChangedEmitter.emit(path)
@@ -601,7 +707,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 +755,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
@@ -664,6 +770,16 @@ public class HybridAudioBrowser: HybridAudioBrowserSpec, @unchecked Sendable {
         guard let self else { return }
         self.applyAudioSessionCategory = applyCategory
 
+        // A re-setup REPLACES the player, so the outgoing one has to be torn down
+        // and un-published first. `TrackPlayer` has no deinit: dropping the
+        // reference alone would leave its AVPlayer and MPNowPlayingSession alive.
+        // And `playerAndConfiguredBrowser` holds the old player strongly — its
+        // `resolve` is a one-shot, so without the reset the gate would keep
+        // handing the dead player to the CarPlay controller and Siri intents,
+        // which both await it. No-op on first setup.
+        player?.destroy()
+        playerAndConfiguredBrowser.reset()
+
         // Create player with self as callbacks delegate
         player = TrackPlayer(callbacks: self)
 
@@ -713,11 +829,16 @@ public class HybridAudioBrowser: HybridAudioBrowserSpec, @unchecked Sendable {
           return await browserManager.resolveMediaUrl(src, track: track)
         }
 
-        // Configure artwork URL resolver for Now Playing (with size context)
+        // Configure artwork URL resolver for Now Playing (with size context). The
+        // `nowPlayingArtwork` config runs for EVERY playing track, id or not — an id-less track
+        // leaves any `{id}` token unfilled (resolveArtworkUrl warns and the request visibly
+        // 404s) rather than skipping the config.
         player?.nowPlayingUpdater.artworkUrlResolver = { [weak self] track, imageContext in
           guard let self else { return nil }
-          let perRoute = (track.id?.isEmpty == false) ? browserManager.config.nowPlayingArtwork : nil
-          return await browserManager.resolveArtworkUrl(track: track, perRouteConfig: perRoute, imageContext: imageContext)
+          return await browserManager.resolveArtworkUrl(
+            track: track, perRouteConfig: browserManager.config.nowPlayingArtwork,
+            imageContext: imageContext,
+          )
         }
 
         // Emit the JS `onNowPlayingChanged` event when the rendered text lines change. The updater
@@ -733,16 +854,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
@@ -758,6 +879,13 @@ public class HybridAudioBrowser: HybridAudioBrowserSpec, @unchecked Sendable {
         if let intent = options.playWhenReady { pendingPlayWhenReady = intent }
         applyPendingPlayerState()
 
+        // Push the resolved event cadence unconditionally. `updateOptions` applies
+        // the interval only when it *differs* from the stored one, but the store
+        // outlives the player — so on a re-setup with unchanged options the new
+        // player would come up with no progress timer at all.
+        player?.setProgressUpdateInterval(playerOptions.progressUpdateEventInterval)
+        player?.setPlaybackIntervalEnabled(playbackIntervalEnabled)
+
         // Notify listeners that player is ready (e.g., CarPlay)
         playerAndConfiguredBrowser.check()
       }
@@ -787,9 +915,9 @@ public class HybridAudioBrowser: HybridAudioBrowserSpec, @unchecked Sendable {
       // Update stored options
       playerOptions.update(from: options)
 
-      // Propagate the favorite match mode to the browser so it can hydrate
+      // Propagate the favorite flag to the browser so it can hydrate
       // row hearts (the `favorite` capability is the single favoriting switch).
-      browserManager.setFavoriteMatch(playerOptions.capabilities.favoriteMatch)
+      browserManager.setFavoriteEnabled(playerOptions.capabilities.favoriteEnabled)
 
       // Apply remote commands to player
       applyRemoteCommands()
@@ -819,11 +947,19 @@ public class HybridAudioBrowser: HybridAudioBrowserSpec, @unchecked Sendable {
   }
 
   public func getOptions() throws -> Options {
-    playerOptions.toOptions()
+    onMainActor { playerOptions.toOptions() }
   }
 
+  /// Stored so a re-setup can re-apply it: unlike the other runtime options this
+  /// one has no home in `playerOptions`, and the player it was pushed to does not
+  /// survive `setupPlayer`.
+  @MainActor private var playbackIntervalEnabled = false
+
   public func setPlaybackIntervalEnabled(enabled: Bool) {
-    onMainActor { player?.setPlaybackIntervalEnabled(enabled) }
+    onMainActor {
+      playbackIntervalEnabled = enabled
+      player?.setPlaybackIntervalEnabled(enabled)
+    }
   }
 
   // MARK: - Playback Control
@@ -1037,24 +1173,25 @@ public class HybridAudioBrowser: HybridAudioBrowserSpec, @unchecked Sendable {
   }
 
   public func setActiveTrackFavorited(favorited: Bool) throws {
-    onMainActor {
-      guard let track = player?.currentTrack, let src = track.src else { return }
+    try onMainActor {
+      guard let track = player?.currentTrack, let identity = track.identity else { return }
       guard let index = player?.currentIndex, index >= 0 else { return }
-      // Optimistically reflect in the authoritative match set so the now-playing
-      // heart (hydrated from it in getActiveTrack) flips immediately; native
-      // reconciles to its canonical ids on the next setFavorites.
-      browserManager.setFavorited(src: src, favorited: favorited)
+      // Optimistically reflect in the authoritative favorite set so the
+      // now-playing heart (hydrated from it in getActiveTrack) flips
+      // immediately; the consumer reconciles to its canonical identities on
+      // the next setFavorites.
+      browserManager.setFavorited(identity: identity, favorited: favorited)
       let updatedTrack = track.copying(favorited: favorited)
+      // Hydration never overrides a caller-set `favorited`, so the queued
+      // track must itself carry the latest explicit value (as Android's tag
+      // swap and web's replaceTrack do).
+      try player?.replace(index, updatedTrack)
+      // The ONLY emit: a favorite toggle is an in-place mutation of the active
+      // track, not a transition — onPlaybackActiveTrackChanged stays
+      // transition-only, and the useActiveTrack / useQueue hooks subscribe to
+      // onFavoriteChanged themselves. Native surfaces (CarPlay heart) observe
+      // favoriteChangedEmitter / onFavoritesChanged directly.
       favoriteChangedEmitter.emit(FavoriteChangedEvent(track: updatedTrack, favorited: favorited))
-      // Fire active track changed so the now-playing heart + useActiveTrack() refresh.
-      let position = player?.currentTime ?? 0
-      activeTrackChangedEmitter.emit(PlaybackActiveTrackChangedEvent(
-        lastIndex: Double(index),
-        lastTrack: track,
-        lastPosition: position,
-        index: Double(index),
-        track: updatedTrack,
-      ))
     }
   }
 
@@ -1121,11 +1258,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 +1288,7 @@ public class HybridAudioBrowser: HybridAudioBrowserSpec, @unchecked Sendable {
     }
   }
 
+  @MainActor
   private func cancelNowPlayingFlash() {
     nowPlayingFlashRevert?.cancel()
     nowPlayingFlashRevert = nil
@@ -1193,7 +1331,7 @@ public class HybridAudioBrowser: HybridAudioBrowserSpec, @unchecked Sendable {
       duration: track.duration,
       artwork: nowPlayingArtwork(for: track),
       description: track.description,
-      mediaId: track.src ?? track.url,
+      mediaId: track.src ?? track.path,
       genre: track.genre,
     )
   }
@@ -1206,7 +1344,7 @@ public class HybridAudioBrowser: HybridAudioBrowserSpec, @unchecked Sendable {
     // Classify a stall by connectivity so the formatter can show "No internet connection" vs
     // "Reconnecting…" without a separate read. nil while not stalled.
     let stalled: StallReason? =
-      player.isStalled ? (networkMonitor.getOnline() ? .buffering : .offline) : nil
+      player.isStalled ? (networkMonitor.isOnline ? .buffering : .offline) : nil
     player.nowPlayingUpdater.render(
       track: track,
       timedMetadata: latestTimedMetadata,
@@ -1222,7 +1360,9 @@ public class HybridAudioBrowser: HybridAudioBrowserSpec, @unchecked Sendable {
   // MARK: - Network
 
   public func getOnline() throws -> Bool {
-    networkMonitor.getOnline()
+    // No `onMainActor` hop: `isOnline` is lock-protected, so this stays a
+    // cheap read on the JS thread instead of blocking on the main queue.
+    networkMonitor.isOnline
   }
 
   // MARK: - System Volume
@@ -1354,8 +1494,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,17 +1536,15 @@ 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 {
     DispatchQueue.main.async { [weak self] in
       guard let self else { return }
-      guard let windowScene = UIApplication.shared.connectedScenes
-        .compactMap({ $0 as? UIWindowScene })
-        .first(where: { $0.activationState == .foregroundActive }),
-        let window = windowScene.windows.first(where: { $0.isKeyWindow }),
-        var topController = window.rootViewController
+      guard let windowScene = UIApplication.shared.activeWindowScene,
+            let window = windowScene.windows.first(where: { $0.isKeyWindow }),
+            var topController = window.rootViewController
       else {
         self.logger.error("openOutputPicker: no active window scene / root view controller")
         return
@@ -1586,6 +1726,7 @@ extension HybridAudioBrowser: TrackPlayerCallbacks {
     DispatchQueue.main.asyncAfter(deadline: .now() + 3, execute: release)
   }
 
+  @MainActor
   private func cancelSessionRelease() {
     sessionReleaseWork?.cancel()
     sessionReleaseWork = nil
@@ -1619,7 +1760,7 @@ extension HybridAudioBrowser: TrackPlayerCallbacks {
 
   public func playerDidReceiveTimedMetadata(_ groups: [AVTimedMetadataGroup]) {
     for group in groups {
-      if let metadata = TimedMetadata.from(items: group.items) {
+      if let metadata = TimedMetadata.from(items: group.items, icyCharset: player?.currentTrack?.icyCharset) {
         latestTimedMetadata = metadata
         onTimedMetadata(metadata)
         // Re-render the now-playing so the formatter can reflect the live song.
@@ -1779,14 +1920,26 @@ extension HybridAudioBrowser: TrackPlayerCallbacks {
           browser.showNowPlayingRequestedEmitter.emit(())
           completion(true)
         } else if let state = browser.playbackStateStore.load() {
-          browser.logger.info("resume: cold — restoring persisted track")
           let track = state.track.toNitro()
+          // The persisted track can carry `disabled` — it became unavailable
+          // after it was saved. A disabled track never plays, resumption
+          // included (Track.disabled).
+          if track.disabled == true {
+            browser.logger.info("resume: persisted track is disabled — refusing")
+            completion(false)
+            return
+          }
+          browser.logger.info("resume: cold — restoring persisted track")
+          // Repeat / shuffle / speed come back before the queue is built — see
+          // `restorePlaybackSettings(from:)` for why that ordering matters.
+          player.restorePlaybackSettings(from: state)
           let startMs = (track.live == true) ? nil : state.positionMs
           // Match Android resume: re-expand the full queue from the track's contextual
-          // 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) {
+          // path (parent container → siblings + selected index). Fall back to the single
+          // track when the path isn't contextual or expansion fails.
+          if let path = state.track.path,
+             let expanded = try? await browser.browserManager.expandQueueFromContextualPath(path)
+          {
             player.setQueue(expanded.tracks, initialIndex: expanded.selectedIndex, startPositionMs: startMs, playWhenReady: true)
           } else {
             player.setQueue([track], initialIndex: 0, startPositionMs: startMs, playWhenReady: true)
@@ -1795,7 +1948,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 +1965,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")