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

package/android/src/main/java/com/audiobrowser/AudioBrowser.kt

@@ -20,9 +20,11 @@ import com.audiobrowser.browser.CallbackException
 import com.audiobrowser.browser.ContentNotFoundException
 import com.audiobrowser.browser.HttpStatusException
 import com.audiobrowser.browser.NetworkException
+import com.audiobrowser.browser.flattenedChildren
 import com.audiobrowser.browser.handleTrackLoad
 import com.audiobrowser.browser.resolveMediaUrl
 import com.audiobrowser.extension.NumberExt.Companion.toSeconds
+import com.audiobrowser.extension.indexOfTappedTrack
 import com.audiobrowser.model.PlayerSetupOptions
 import com.audiobrowser.model.PlayerUpdateOptions
 import com.audiobrowser.player.Player
@@ -35,6 +37,7 @@ import com.audiobrowser.util.SystemVolumeMonitor
 import com.facebook.proguard.annotations.DoNotStrip
 import com.google.common.util.concurrent.ListenableFuture
 import com.margelo.nitro.NitroModules
+import com.margelo.nitro.audiobrowser.ArtworkRequestConfig
 import com.margelo.nitro.audiobrowser.BatteryOptimizationStatus
 import com.margelo.nitro.audiobrowser.BatteryOptimizationStatusChangedEvent
 import com.margelo.nitro.audiobrowser.BatteryWarningPendingChangedEvent
@@ -50,6 +53,7 @@ import com.margelo.nitro.audiobrowser.HybridAudioBrowserSpec
 import com.margelo.nitro.audiobrowser.MediaRequestConfig
 import com.margelo.nitro.audiobrowser.NativeBrowserConfiguration
 import com.margelo.nitro.audiobrowser.NativeGateRequest
+import com.margelo.nitro.audiobrowser.NativeRouteEntry
 import com.margelo.nitro.audiobrowser.NativeSetupPlayerOptions
 import com.margelo.nitro.audiobrowser.NativeUpdateOptions
 import com.margelo.nitro.audiobrowser.NavigationError
@@ -82,31 +86,105 @@ import com.margelo.nitro.audiobrowser.SleepTimer
 import com.margelo.nitro.audiobrowser.TimedMetadata
 import com.margelo.nitro.audiobrowser.Track
 import com.margelo.nitro.audiobrowser.TrackMetadata
+import com.margelo.nitro.audiobrowser.TransformableRequestConfig
 import com.margelo.nitro.core.Promise
 import java.util.concurrent.TimeUnit
+import java.util.concurrent.atomic.AtomicReference
 import kotlin.coroutines.resume
 import kotlin.coroutines.resumeWithException
 import kotlin.coroutines.suspendCoroutine
+import kotlin.time.Duration.Companion.seconds
 import kotlinx.coroutines.CancellationException
+import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.Job
 import kotlinx.coroutines.MainScope
+import kotlinx.coroutines.async
+import kotlinx.coroutines.cancel
 import kotlinx.coroutines.cancelChildren
-import kotlinx.coroutines.delay
 import kotlinx.coroutines.launch
 import kotlinx.coroutines.runBlocking
+import kotlinx.coroutines.withTimeoutOrNull
 import timber.log.Timber
 
 @Keep
 @DoNotStrip
 class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
 
-  /** Called by Nitro when the JS object is destroyed (incl. JS runtime reloads). */
+  /**
+   * Nitro calls this only when JS calls `dispose()` explicitly — never on runtime teardown, which
+   * is what [AudioBrowserLifecycleModule] is for. Both routes land here.
+   *
+   * The Service outlives this object, so everything registered in `init` or on connect has to be
+   * undone. Left alone, the running [Player] goes on invoking callbacks into a dead JSI runtime,
+   * and every reload strands another ServiceConnection and lifecycle observer, each retaining a
+   * BrowserManager.
+   *
+   * Runs the teardown on main: the state below is written from main-thread coroutines
+   * ([onServiceConnected], [onServiceDisconnected]), while dispose itself arrives on the JS thread
+   * or the teardown callback's thread.
+   */
   override fun dispose() {
+    current.compareAndSet(this, null)
     systemVolumeMonitor.destroy()
     outputMonitor.destroy()
+    // Only when still ours: on a reload the replacement may already own the slot.
+    carConnectionTarget.compareAndSet(onCarConnectedChanged, null)
+
+    // The runtime behind the config's JS functions is going away, but anything still holding
+    // this instance (an in-flight browse coroutine, the running player) can invoke them after
+    // it's gone — each invoke then throws instead of answering, so browse takes its error path
+    // rather than its fallback.
+    dropStaleJSCallbacks()
+
+    handler.post {
+      connectedService?.let { service ->
+        // Identity-guarded: both instances bind to the same singleton Service, so a late dispose
+        // must not strip the wiring a replacement has already installed.
+        if (service.player.getCallbacks() === callbacks) service.player.setCallbacks(null)
+        if (service.player.browser === this) {
+          service.player.browser = null
+          service.player.forgetBrowserRegistration()
+          // The formatter wraps a JS callback from this instance's runtime (installed by our
+          // setup(); browser still being ours means no replacement has run setup yet). Without
+          // this, every track change until the next setup() throws into the updater's fallback.
+          service.player.nowPlaying.formatter = null
+        }
+        if (service.onBatteryWarningPendingChanged === onBatteryWarningPending) {
+          service.onBatteryWarningPendingChanged = null
+        }
+      }
+      connectedService = null
+
+      // Dropping the reference disconnects nothing — the controller stays in the session's
+      // connected list, holding a binder and a listener.
+      mediaBrowserFuture?.let { MediaBrowser.releaseFuture(it) }
+      mediaBrowserFuture = null
+      setupPromise = null
+
+      serviceBinding.unbind(this)
+
+      ProcessLifecycleOwner.get().lifecycle.removeObserver(lifecycleObserver)
+      // After the observer removal, so this post is not the one dropped.
+      handler.removeCallbacksAndMessages(null)
+      mainScope.cancel()
+    }
     super.dispose()
   }
 
+  /**
+   * Demotes the config to data-only (deep strip of every JS function field) and reverts the JS
+   * callbacks stored outside the config tree ([resolveGate]; the now-playing formatter is cleared
+   * in [dispose]'s service block, identity-guarded). Stale paths then degrade the same way as a
+   * config that never had callbacks — static request/browse layers, default error copy, fail-closed
+   * gate — instead of throwing into the error path. Mirrors iOS `dropStaleJSCallbacks`, where the
+   * same invoke is fatal rather than a throw.
+   */
+  private fun dropStaleJSCallbacks() {
+    _configuration = _configuration.strippingJSCallbacks()
+    browserManager.config = buildConfig()
+    resolveGate = defaultResolveGate
+  }
+
   private val mainScope = MainScope()
   private var navigationJob: Job? = null
   private val handler = Handler(Looper.getMainLooper())
@@ -129,8 +207,9 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
       singleTrack = null,
       handleTrackLoad = null,
       androidControllerOfflineError = null,
+      viewMoreTitle = null,
       carPlayLoadingTitle = null,
-      resolveAlbumUrl = null,
+      resolveAlbumPath = null,
       formatNavigationError = null,
     )
 
@@ -149,7 +228,18 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
   private var updateOptions: PlayerUpdateOptions = PlayerUpdateOptions()
   private var mediaBrowserFuture: ListenableFuture<MediaBrowser>? = null
   private var setupOptions = PlayerSetupOptions()
-  private var connectedService: Service? = null
+  // Written only on the main thread (ServiceConnection callbacks, dispose); read from main or,
+  // in a few places, straight from the JS thread. @Volatile gives those reads visibility — they
+  // must still tolerate staleness in both directions (a just-detached service, or null while
+  // onServiceConnected is pending). Keep writes on main; no read-modify-write.
+  @Volatile private var connectedService: Service? = null
+
+  private val serviceBinding = ServiceBinding(context)
+
+  /** Held rather than inlined so [dispose] can tell its own wiring from a replacement's. */
+  private val onBatteryWarningPending: (Boolean) -> Unit = { pending ->
+    post { onBatteryWarningPendingChanged(BatteryWarningPendingChangedEvent(pending)) }
+  }
   private var setupPromise: ((Unit) -> Unit)? = null
 
   // Initial player state staged before the player exists — from setup options or the imperative
@@ -168,14 +258,14 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
   override var onFormattedNavigationError: (FormattedNavigationError?) -> Unit = {}
 
   // MARK: Gate callbacks (native→JS; set from JS, native CALLS them)
-  // Default resolver: only reachable in the init window where the native side has recorded
-  // hasResolver=true but JS hasn't yet assigned the real `resolveGate` slot. It DENIES by default
+  // Default resolver: only reachable while hasResolver=true but no live runtime has the real
+  // `resolveGate` bound — the init window before JS assigns it, or after [dispose] reverts a dead
+  // runtime's resolver. It DENIES by default
   // (gated=true) so an active gate never serves content during that window — same fail-closed
   // direction as the resolver-error path in [gateDecision]. The static-gate fast path skips it
   // entirely once a resolver-less gate is set.
-  override var resolveGate: (request: NativeGateRequest) -> Promise<Promise<GateDecision>> = {
-    Promise.resolved(Promise.resolved(GateDecision(gated = true, gate = null)))
-  }
+  override var resolveGate: (request: NativeGateRequest) -> Promise<Promise<GateDecision>> =
+    defaultResolveGate
   override var onGate: (event: GateEvent) -> Unit = {}
 
   // MARK: Player callbacks
@@ -239,12 +329,14 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
     }
 
   init {
+    current.set(this)
+
     // Auto-bind to service if it's already running
     launchInScope {
       try {
         Timber.d("Attempting to auto-bind to existing AudioBrowserService from AudioBrowser")
         val intent = Intent(context, Service::class.java)
-        val bound = context.bindService(intent, this@AudioBrowser, Context.BIND_AUTO_CREATE)
+        val bound = serviceBinding.bind(intent, this@AudioBrowser)
         Timber.d("Auto-bind result: $bound")
 
         if (!bound) {
@@ -286,6 +378,7 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
       routes = _configuration.routes,
       singleTrack = _configuration.singleTrack ?: false,
       androidControllerOfflineError = _configuration.androidControllerOfflineError ?: true,
+      viewMoreTitle = _configuration.viewMoreTitle,
     )
   }
 
@@ -319,8 +412,8 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
       browserManager.config = buildConfig()
       val tabs = browserManager.queryTabs()
       if (tabs.isNotEmpty()) {
-        Timber.d("Using first tab as default path: ${tabs[0].url}")
-        tabs[0].url
+        Timber.d("Using first tab as default path: ${tabs[0].path}")
+        tabs[0].path
       } else {
         Timber.d("Using root path as default: /")
         "/"
@@ -375,8 +468,14 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
       browserManager.config = buildConfig()
 
       // Notify player that browser configuration is ready (routes/tabs available)
-      // This allows Android Auto to start browsing content
-      connectedService?.player?.notifyBrowserConfigurationReady()
+      // This allows Android Auto to start browsing content.
+      // This reaches MediaSession.getConnectedControllers, which asserts the
+      // main thread, and this setter runs on the JS thread. Hop without
+      // blocking -- runBlockingOnMain would deadlock here for the same reason
+      // described for the navigation below (JS callbacks can't run while the
+      // JS thread waits). Ordering with navigationJob is preserved: both are
+      // queued on mainScope.
+      launchInScope { connectedService?.player?.notifyBrowserConfigurationReady() }
 
       clearNavigationError()
 
@@ -408,121 +507,48 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
 
   override fun getFormattedNavigationError(): FormattedNavigationError? = formattedNavigationError
 
-  /** Creates a default formatted error from a NavigationError */
-  private fun defaultFormattedError(error: NavigationError): FormattedNavigationError {
-    val title =
-      when (error.code) {
-        NavigationErrorType.CONTENT_NOT_FOUND -> "Content Not Found"
-        NavigationErrorType.NETWORK_ERROR -> "Network Error"
-        NavigationErrorType.HTTP_ERROR -> {
-          // Use system-localized HTTP status text (e.g., "Not Found", "Service Unavailable")
-          error.statusCode?.let { httpStatusText(it.toInt()) } ?: "Server Error"
-        }
-        NavigationErrorType.CALLBACK_ERROR -> "Error"
-        NavigationErrorType.UNKNOWN_ERROR -> "Error"
-        // Not a failure — a container that resolved with no children. Neutral copy. See ADR 0001.
-        NavigationErrorType.EMPTY_CONTENT -> "Nothing here"
-        NavigationErrorType.TIMEOUT -> "Couldn't load"
-      }
-    // Omit an empty message so it renders as title-only (e.g. the empty-content case).
-    return FormattedNavigationError(title, error.message.takeIf { it.isNotEmpty() })
-  }
-
-  /** Returns localized HTTP status text for the given status code */
-  private fun httpStatusText(statusCode: Int): String {
-    return when (statusCode) {
-      400 -> "Bad Request"
-      401 -> "Unauthorized"
-      403 -> "Forbidden"
-      404 -> "Not Found"
-      405 -> "Method Not Allowed"
-      408 -> "Request Timeout"
-      429 -> "Too Many Requests"
-      500 -> "Internal Server Error"
-      502 -> "Bad Gateway"
-      503 -> "Service Unavailable"
-      504 -> "Gateway Timeout"
-      else -> "Server Error"
+  /**
+   * Resolves a navigation error to its display form: the app's `formatNavigationError` for the
+   * given [path] when one is configured, else the built-in default. Shared by [setNavigationError]
+   * and the Android Auto empty tile so in-app and in-car copy cannot drift (ADR 0001).
+   */
+  internal suspend fun resolveFormattedError(
+    error: NavigationError,
+    path: String,
+  ): FormattedNavigationError {
+    val default = defaultFormattedError(error)
+    val formatter = _configuration.formatNavigationError ?: return default
+    return formattedOrDefault(mainScope, default) {
+      formatter(FormatNavigationErrorParams(error, default, path)).await()
     }
   }
 
-  private fun setNavigationError(
-    code: NavigationErrorType,
-    message: String,
-    path: String,
-    statusCode: Double? = null,
-    statusCodeSuccess: Boolean? = null,
-  ) {
-    val navError = NavigationError(code, message, statusCode, statusCodeSuccess)
+  private fun setNavigationError(navError: NavigationError, path: String) {
     navigationError = navError
     onNavigationError(NavigationErrorEvent(navigationError))
 
-    // Format the error (async if using JS callback, sync for defaults)
-    val defaultFormatted = defaultFormattedError(navError)
-    val formatter = _configuration.formatNavigationError
-    if (formatter != null) {
-      mainScope.launch {
-        try {
-          val params = FormatNavigationErrorParams(navError, defaultFormatted, path)
-          val customFormatted = formatter(params).await()
-          formattedNavigationError = customFormatted ?: defaultFormatted
-        } catch (e: Exception) {
-          formattedNavigationError = defaultFormatted
-        }
-        onFormattedNavigationError(formattedNavigationError)
-      }
-    } else {
-      formattedNavigationError = defaultFormatted
-      onFormattedNavigationError(formattedNavigationError)
+    // No formatter means no hop, and the field and event land in this turn: a same-turn
+    // getFormattedNavigationError, or a clearNavigationError right after, must not race a
+    // launch that has yet to run.
+    if (_configuration.formatNavigationError == null) {
+      val default = defaultFormattedError(navError)
+      formattedNavigationError = default
+      onFormattedNavigationError(default)
+      return
+    }
+
+    mainScope.launch {
+      val formatted = resolveFormattedError(navError, path)
+      formattedNavigationError = formatted
+      onFormattedNavigationError(formatted)
     }
   }
 
-  /** Maps common browser exceptions to navigation errors */
+  /** Raises the navigation error [e] maps to, for a failed navigation to [path]. */
   private fun handleBrowserException(e: Exception, path: String, logContext: String) {
-    when (e) {
-      is HttpStatusException -> {
-        Timber.e(e, "HTTP error $logContext")
-        setNavigationError(
-          NavigationErrorType.HTTP_ERROR,
-          e.message ?: "Server error",
-          path,
-          e.statusCode.toDouble(),
-          e.statusCode in 200..299,
-        )
-      }
-      is NetworkException -> {
-        Timber.e(e, "Network error $logContext")
-        setNavigationError(
-          NavigationErrorType.NETWORK_ERROR,
-          e.message ?: "Network request failed",
-          path,
-        )
-      }
-      is ContentNotFoundException -> {
-        Timber.e(e, "Content not found $logContext")
-        setNavigationError(
-          NavigationErrorType.CONTENT_NOT_FOUND,
-          e.message ?: "Content not found",
-          path,
-        )
-      }
-      is CallbackException -> {
-        Timber.e(e, "Callback error $logContext")
-        setNavigationError(
-          NavigationErrorType.CALLBACK_ERROR,
-          e.message ?: "An error occurred",
-          path,
-        )
-      }
-      else -> {
-        Timber.e(e, "Unexpected error $logContext")
-        setNavigationError(
-          NavigationErrorType.UNKNOWN_ERROR,
-          e.message ?: "An unexpected error occurred",
-          path,
-        )
-      }
-    }
+    val navError = navigationErrorFor(e)
+    Timber.e(e, "${navError.code} $logContext")
+    setNavigationError(navError, path)
   }
 
   private fun clearNavigationError() {
@@ -558,26 +584,38 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
   }
 
   override fun navigateTrack(track: Track) {
+    // A disabled track is unavailable — it never plays, whichever surface or
+    // stale resume path delivered the selection (Track.disabled; mirrors iOS
+    // TrackSelector.select). Refused before any state changes: an inert tap
+    // must not clear an unrelated navigation error or cancel an in-flight
+    // navigation.
+    if (track.disabled == true) {
+      Timber.d("Ignoring selection of disabled track: ${track.title}")
+      return
+    }
+
     clearNavigationError()
 
     // Cancel previous navigation to avoid race conditions
     navigationJob?.cancel()
 
-    val url = track.url
+    val path = track.path
     navigationJob =
       mainScope.launch {
         try {
           when {
-            // Check if this is a contextual URL (playable-only track with queue context)
-            url != null && BrowserPathHelper.isContextual(url) -> {
-              Timber.d("Navigating to contextual track URL: $url")
+            // Check if this is a contextual path (playable-only track with queue context)
+            path != null && BrowserPathHelper.isContextual(path) -> {
+              Timber.d("Navigating to contextual track path: $path")
 
-              val parentPath = BrowserPathHelper.stripTrackId(url)
-              val trackId = BrowserPathHelper.extractTrackId(url)
+              val parentPath = BrowserPathHelper.stripTrackId(path)
+              val trackId = BrowserPathHelper.extractTrackId(path)
 
-              // Check if queue already came from this parent path - just skip to the track
+              // Check if queue already came from this parent path - just skip
+              // to the tapped surface (exact path first, identity for
+              // index-less paths — see indexOfTappedTrack)
               if (trackId != null && parentPath == player.queueSourcePath) {
-                val index = player.tracks.indexOfFirst { it.src == trackId }
+                val index = player.tracks.indexOfTappedTrack(path, trackId)
                 if (index >= 0) {
                   Timber.d("Queue already from $parentPath, skipping to index $index")
                   handleTrackLoad(
@@ -595,8 +633,8 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
                 }
               }
 
-              // Expand the queue from the contextual URL
-              val expanded = browserManager.expandQueueFromContextualUrl(url)
+              // Expand the queue from the contextual path
+              val expanded = browserManager.expandQueueFromContextualPath(path)
 
               if (expanded != null) {
                 val (tracks, startIndex) = expanded
@@ -631,9 +669,9 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
               }
             }
             // Navigate to browsable track to show browsing UI
-            url != null -> {
-              Timber.d("Navigating to browsable track: $url")
-              browserManager.navigate(url)
+            path != null -> {
+              Timber.d("Navigating to browsable track: $path")
+              browserManager.navigate(path)
             }
             // If track is playable (has src), load it into player
             track.src != null -> {
@@ -648,22 +686,36 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
               )
             }
             else -> {
-              throw IllegalArgumentException("Track must have either an 'url' or an 'src' property")
+              throw IllegalArgumentException("Track must have either a 'path' or an 'src' property")
             }
           }
         } catch (e: CancellationException) {
           throw e // Rethrow to properly cancel
         } catch (e: Exception) {
-          handleBrowserException(e, url ?: track.src ?: "", "navigating to track: ${track.title}")
+          handleBrowserException(e, path ?: track.src ?: "", "navigating to track: ${track.title}")
         }
       }
   }
 
-  override fun onSearch(query: String): Promise<Array<Track>> {
+  override fun search(query: String): Promise<Array<Track>> {
     return Promise.async(mainScope) {
       Timber.d("Searching for: $query")
-      val searchResults = browserManager.search(query)
-      searchResults.children ?: emptyArray()
+      // Rejects with the error the browse surface would raise, but leaves the navigation error
+      // itself unset: a search is not a navigation, and its failure must not replace the
+      // displayed page's state (mirrors HybridAudioBrowser.search).
+      val searchResults =
+        try {
+          browserManager.search(query)
+        } catch (e: CancellationException) {
+          throw e
+        } catch (e: Exception) {
+          Timber.e(e, "Search failed for query: $query")
+          throw NavigationErrorException(navigationErrorFor(e))
+        }
+      // Flattened, not `children`: a resolved page carries its rows in
+      // `sections` (ADR 0010) and search builds exactly one untitled section,
+      // so `children` is always null here and this returned nothing at all.
+      searchResults.flattenedChildren?.toTypedArray() ?: emptyArray()
     }
   }
 
@@ -677,8 +729,9 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
     // Invalidate cached content so future navigations fetch fresh data
     browserManager.invalidateContentCache(path)
 
-    // Notify external media controllers (Android Auto)
-    connectedService?.player?.notifyContentChanged(path)
+    // Notify external media controllers (Android Auto). Reaches MediaSession,
+    // which asserts the main thread; this override runs on the JS thread.
+    launchInScope { connectedService?.player?.notifyContentChanged(path) }
 
     // If we're currently viewing this path, refresh the content
     if (browserManager.getPath() == path) {
@@ -692,8 +745,10 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
     // Clear all cached content so every path re-fetches fresh data
     browserManager.clearContentCache()
 
-    // Notify external media controllers (Android Auto) to refresh subscribed paths
-    connectedService?.player?.invalidateAllContent()
+    // Notify external media controllers (Android Auto) to refresh subscribed paths.
+    // Reaches MediaSession, which asserts the main thread; this override runs on
+    // the JS thread.
+    launchInScope { connectedService?.player?.invalidateAllContent() }
 
     // Refresh whatever the browser is currently viewing
     mainScope.launch { browserManager.refresh() }
@@ -734,14 +789,16 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
     // Re-query every subscribed parent so a connected controller (Android
     // Auto) swaps its lists for the gate tile without reconnecting. Notify
     // only — the content cache stays warm for when the gate clears.
-    connectedService?.player?.invalidateAllContent()
+    // MediaSession asserts the main thread; this override runs on the JS thread.
+    launchInScope { connectedService?.player?.invalidateAllContent() }
   }
 
   override fun clearGate() {
     if (!gateState.active) return
     // Single atomic assignment — readers never see a half-cleared triple.
     gateState = GateState(active = false, chrome = null, hasResolver = false)
-    connectedService?.player?.invalidateAllContent()
+    // MediaSession asserts the main thread; this override runs on the JS thread.
+    launchInScope { connectedService?.player?.invalidateAllContent() }
   }
 
   /**
@@ -781,7 +838,7 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
   override var onCarConnectedChanged: (Boolean) -> Unit = {}
     set(value) {
       field = value
-      carConnectionTarget = value
+      carConnectionTarget.set(value)
       // Immediately notify current state (the car may have connected before
       // this JS runtime subscribed) — mirrors the iOS behavior.
       value(carConnected)
@@ -811,12 +868,7 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
       // Service not connected yet, bind to service
       suspendCoroutine<Unit> { continuation ->
         Timber.d("Binding to AudioBrowserService")
-        val bound =
-          context.bindService(
-            Intent(context, Service::class.java),
-            this@AudioBrowser,
-            Context.BIND_AUTO_CREATE,
-          )
+        val bound = serviceBinding.bind(Intent(context, Service::class.java), this@AudioBrowser)
 
         if (!bound) {
           continuation.resumeWithException(
@@ -832,8 +884,17 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
 
   override fun updateOptions(options: NativeUpdateOptions) {
     updateOptions.updateFromBridge(options)
-    // Only update the options if the service is around
-    connectedService?.let { player.applyOptions(updateOptions) }
+    // Only update the options if the service is around.
+    // applyOptions touches the Media3 player, which asserts it is only ever
+    // driven from the main thread ("Player callback method is called from a
+    // wrong thread"). Nitro invokes this from the JS thread, so hop.
+    //
+    // The hop blocks rather than launching because `updateOptions` is a single
+    // mutable holder: updateFromBridge mutates it in place on the JS thread and
+    // applyOptions reads it on main. Blocking is what keeps the two ordered.
+    connectedService?.let { service ->
+      runBlockingOnMain { service.player.applyOptions(updateOptions) }
+    }
   }
 
   override fun getOptions(): Options {
@@ -852,7 +913,6 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
 
   override fun reset() = runBlockingOnMain {
     player.stop()
-    delay(300) // Allow playback to stop
     player.clear()
     // clear() while IDLE emits no engine event, so the state machine never
     // leaves STOPPED — a reset queue is "nothing loaded".
@@ -979,12 +1039,15 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
       player.setQueue(tracks, startIndex?.toInt() ?: 0, ((startPosition ?: 0.0) * 1000).toLong())
     }
 
-  override fun setActiveTrackFavorited(favorited: Boolean) = runBlockingOnMain {
+  override fun setActiveTrackFavorited(favorited: Boolean): Unit = runBlockingOnMain {
+    // Applied-result is for MediaSession honesty; the JS API stays fire-and-forget.
     player.setActiveTrackFavorited(favorited)
+    Unit
   }
 
-  override fun toggleActiveTrackFavorited() = runBlockingOnMain {
+  override fun toggleActiveTrackFavorited(): Unit = runBlockingOnMain {
     player.toggleActiveTrackFavorited()
+    Unit
   }
 
   override fun getQueue(): Array<Track> = runBlockingOnMain { player.tracks }
@@ -1175,13 +1238,7 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
         }
 
       // Wire up battery warning callback from service
-      connectedService?.onBatteryWarningPendingChanged = { pending ->
-        post {
-          this@AudioBrowser.onBatteryWarningPendingChanged(
-            BatteryWarningPendingChangedEvent(pending)
-          )
-        }
-      }
+      connectedService?.onBatteryWarningPendingChanged = onBatteryWarningPending
 
       val sessionToken = SessionToken(context, ComponentName(context, Service::class.java))
       mediaBrowserFuture = MediaBrowser.Builder(context, sessionToken).buildAsync()
@@ -1436,9 +1493,27 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
     // callback registers as the single notification target (mirrors the iOS
     // static + shared-instance pattern).
     @Volatile private var carConnected = false
-    @Volatile private var carConnectionTarget: ((Boolean) -> Unit)? = null
+    // Compare-and-set, not @Volatile: a disposing instance clears the slot only if it still owns
+    // it, and a replacement may be claiming it at the same moment.
+    private val carConnectionTarget = AtomicReference<((Boolean) -> Unit)?>(null)
     private var carConnectionObserverStarted = false
 
+    /**
+     * The instance the current JS runtime is using. Nitro hands out no registry, and the teardown
+     * callback has nothing to dispose without one.
+     */
+    private val current = AtomicReference<AudioBrowser?>(null)
+
+    /** Called by [AudioBrowserLifecycleModule] when the React instance is torn down. */
+    internal fun disposeCurrent() {
+      current.getAndSet(null)?.dispose()
+    }
+
+    /** Shared by the [resolveGate] initializer and [dispose], which reverts to it. */
+    private val defaultResolveGate: (NativeGateRequest) -> Promise<Promise<GateDecision>> = {
+      Promise.resolved(Promise.resolved(GateDecision(gated = true, gate = null)))
+    }
+
     private fun startCarConnectionObserver(context: Context, handler: Handler) {
       // Posted to main: LiveData observation is main-thread only, and the
       // single-start guard is then only ever touched from one thread.
@@ -1449,9 +1524,159 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
           val connected = type != CarConnection.CONNECTION_TYPE_NOT_CONNECTED
           if (connected == carConnected) return@observeForever
           carConnected = connected
-          carConnectionTarget?.invoke(connected)
+          carConnectionTarget.get()?.invoke(connected)
         }
       }
     }
   }
 }
+
+// MARK: Deep JS-callback stripping (used by dispose)
+// Functions live at every level of the config, not just the top; each type's strip nils its own.
+
+private fun NativeBrowserConfiguration.strippingJSCallbacks() =
+  copy(
+    requestResolver = null,
+    browseResolver = null,
+    handleTrackLoad = null,
+    viewMoreTitle = null,
+    resolveAlbumPath = null,
+    formatNavigationError = null,
+    request = request?.strippingJSCallbacks(),
+    browse = browse?.strippingJSCallbacks(),
+    media = media?.strippingJSCallbacks(),
+    artwork = artwork?.strippingJSCallbacks(),
+    nowPlayingArtwork = nowPlayingArtwork?.strippingJSCallbacks(),
+    routes = routes?.map { it.strippingJSCallbacks() }?.toTypedArray(),
+  )
+
+private fun TransformableRequestConfig.strippingJSCallbacks() =
+  copy(transform = null, transformSync = null)
+
+private fun MediaRequestConfig.strippingJSCallbacks() =
+  copy(resolve = null, resolveSync = null, transform = null, transformSync = null)
+
+private fun ArtworkRequestConfig.strippingJSCallbacks() =
+  copy(resolve = null, resolveSync = null, transform = null, transformSync = null)
+
+private fun NativeRouteEntry.strippingJSCallbacks() =
+  copy(
+    browseCallback = null,
+    browseConfig = browseConfig?.strippingJSCallbacks(),
+    searchCallback = null,
+    searchConfig = searchConfig?.strippingJSCallbacks(),
+    media = media?.strippingJSCallbacks(),
+    artwork = artwork?.strippingJSCallbacks(),
+  )
+
+/**
+ * Ceiling on the app's `formatNavigationError` hop. Same budget [Player.awaitBrowser] gives the JS
+ * side, the only other JS wait a browse serve already blocks on.
+ */
+private val FORMATTER_TIMEOUT = 10.seconds
+
+/**
+ * The navigation error an exception raises. Shared by [AudioBrowser]'s failed navigations, the
+ * rejection [AudioBrowser.search] hands JS, and the Android Auto browse-error tile, so one failure
+ * is named one way wherever it surfaces.
+ */
+internal fun navigationErrorFor(e: Exception): NavigationError =
+  when (e) {
+    is HttpStatusException ->
+      NavigationError(
+        NavigationErrorType.HTTP_ERROR,
+        e.message ?: "Server error",
+        e.statusCode.toDouble(),
+        e.statusCode in 200..299,
+      )
+    is NetworkException ->
+      NavigationError(
+        NavigationErrorType.NETWORK_ERROR,
+        e.message ?: "Network request failed",
+        null,
+        null,
+      )
+    is ContentNotFoundException ->
+      NavigationError(
+        NavigationErrorType.CONTENT_NOT_FOUND,
+        e.message ?: "Content not found",
+        null,
+        null,
+      )
+    is CallbackException ->
+      NavigationError(
+        NavigationErrorType.CALLBACK_ERROR,
+        e.message ?: "An error occurred",
+        null,
+        null,
+      )
+    else ->
+      NavigationError(
+        NavigationErrorType.UNKNOWN_ERROR,
+        e.message ?: "An unexpected error occurred",
+        null,
+        null,
+      )
+  }
+
+/** Carries a [NavigationError] across a rejected Promise, whose JS error keeps its message. */
+class NavigationErrorException(val error: NavigationError) : Exception(error.message)
+
+/**
+ * The built-in display copy for a navigation error, and the fallback when the app's is unusable.
+ */
+internal fun defaultFormattedError(error: NavigationError): FormattedNavigationError {
+  val title =
+    when (error.code) {
+      NavigationErrorType.CONTENT_NOT_FOUND -> "Content Not Found"
+      NavigationErrorType.NETWORK_ERROR -> "Network Error"
+      NavigationErrorType.HTTP_ERROR -> {
+        // Use system-localized HTTP status text (e.g., "Not Found", "Service Unavailable")
+        error.statusCode?.let { httpStatusText(it.toInt()) } ?: "Server Error"
+      }
+      NavigationErrorType.CALLBACK_ERROR -> "Error"
+      NavigationErrorType.UNKNOWN_ERROR -> "Error"
+      // Not a failure — a container that resolved with no children. Neutral copy. See ADR 0001.
+      NavigationErrorType.EMPTY_CONTENT -> "Nothing here"
+      NavigationErrorType.TIMEOUT -> "Couldn't load"
+    }
+  // Omit an empty message so it renders as title-only (e.g. the empty-content case).
+  return FormattedNavigationError(title, error.message.takeIf { it.isNotEmpty() })
+}
+
+/**
+ * The formatter hop's fallback rule: the app's answer when it produces one, [default] when it
+ * answers null, throws, or outruns [FORMATTER_TIMEOUT]. Kept off the JS edge so the rule is
+ * exercisable without a Nitro Promise.
+ *
+ * The hop runs in [scope] and is awaited through its [kotlinx.coroutines.Deferred], because Nitro's
+ * `Promise.await` parks in a plain `suspendCoroutine`: cancelling it does not unpark it. Awaiting
+ * the Deferred is cancellable, so the timeout leaves the orphan to finish unobserved instead of
+ * holding the caller open until JS answers — which for a browse serve would be forever.
+ */
+internal suspend fun formattedOrDefault(
+  scope: CoroutineScope,
+  default: FormattedNavigationError,
+  format: suspend () -> FormattedNavigationError?,
+): FormattedNavigationError {
+  val hop = scope.async { runCatching { format() }.getOrNull() }
+  return withTimeoutOrNull(FORMATTER_TIMEOUT) { hop.await() } ?: default
+}
+
+/** Returns localized HTTP status text for the given status code */
+private fun httpStatusText(statusCode: Int): String {
+  return when (statusCode) {
+    400 -> "Bad Request"
+    401 -> "Unauthorized"
+    403 -> "Forbidden"
+    404 -> "Not Found"
+    405 -> "Method Not Allowed"
+    408 -> "Request Timeout"
+    429 -> "Too Many Requests"
+    500 -> "Internal Server Error"
+    502 -> "Bad Gateway"
+    503 -> "Service Unavailable"
+    504 -> "Gateway Timeout"
+    else -> "Server Error"
+  }
+}