react-native-audio-browser 0.2.0-next.3 → 0.2.0-next.31

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,106 @@ 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.NullType
 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 +208,9 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
       singleTrack = null,
       handleTrackLoad = null,
       androidControllerOfflineError = null,
+      viewMoreTitle = null,
       carPlayLoadingTitle = null,
-      resolveAlbumUrl = null,
+      resolveAlbumPath = null,
       formatNavigationError = null,
     )
 
@@ -149,7 +229,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 +259,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 +330,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 +379,7 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
       routes = _configuration.routes,
       singleTrack = _configuration.singleTrack ?: false,
       androidControllerOfflineError = _configuration.androidControllerOfflineError ?: true,
+      viewMoreTitle = _configuration.viewMoreTitle,
     )
   }
 
@@ -319,8 +413,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 +469,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 +508,56 @@ 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,
+            BrowserPathHelper.navigationErrorKind(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 +593,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 +642,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 +678,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 +695,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 +738,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 +754,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 +798,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 +847,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 +877,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 +893,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 {
@@ -847,25 +917,27 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
   // ============================================================================
 
   override fun load(track: Track) {
+    // Throws without a player, as on iOS: a track asked for and silently dropped hides a mistake.
+    val player = player
     launchInScope { player.load(track) }
   }
 
-  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".
-    player.setPlaybackState(PlaybackState.NONE)
-  }
+  override fun reset() =
+    commandPlayer("reset") { player ->
+      player.stop()
+      player.clear()
+      // clear() while IDLE emits no engine event, so the state machine never
+      // leaves STOPPED — a reset queue is "nothing loaded".
+      player.setPlaybackState(PlaybackState.NONE)
+    }
 
-  override fun play() = runBlockingOnMain { player.play() }
+  override fun play() = commandPlayer("play") { it.play() }
 
-  override fun pause() = runBlockingOnMain { player.pause() }
+  override fun pause() = commandPlayer("pause") { it.pause() }
 
-  override fun togglePlayback() = runBlockingOnMain { player.togglePlayback() }
+  override fun togglePlayback() = commandPlayer("togglePlayback") { it.togglePlayback() }
 
-  override fun stop() = runBlockingOnMain { player.stop() }
+  override fun stop() = commandPlayer("stop") { it.stop() }
 
   override fun setPlayWhenReady(playWhenReady: Boolean) = runBlockingOnMain {
     // Pre-setup this stages the intent for the player to come up with — never throws.
@@ -877,35 +949,41 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
     connectedService?.player?.playWhenReady ?: pendingPlayWhenReady ?: false
   }
 
-  override fun seekTo(position: Double) = runBlockingOnMain {
-    player.seekTo((position * 1000).toLong(), TimeUnit.MILLISECONDS)
-  }
+  override fun seekTo(position: Double) =
+    commandPlayer("seekTo") { player ->
+      player.seekTo((position * 1000).toLong(), TimeUnit.MILLISECONDS)
+    }
 
-  override fun seekBy(offset: Double) = runBlockingOnMain {
-    player.seekBy((offset * 1000).toLong(), TimeUnit.MILLISECONDS)
-  }
+  override fun seekBy(offset: Double) =
+    commandPlayer("seekBy") { player ->
+      player.seekBy((offset * 1000).toLong(), TimeUnit.MILLISECONDS)
+    }
 
-  override fun seekToLiveEdge() = runBlockingOnMain { player.seekToLiveEdge() }
+  override fun seekToLiveEdge() = commandPlayer("seekToLiveEdge") { it.seekToLiveEdge() }
 
-  override fun setVolume(level: Double) = runBlockingOnMain { player.volume = level.toFloat() }
+  override fun setVolume(level: Double) = commandPlayer("setVolume") { it.volume = level.toFloat() }
 
-  override fun getVolume(): Double = runBlockingOnMain { player.volume.toDouble() }
+  override fun getVolume(): Double = readPlayer(1.0) { it.volume.toDouble() }
 
-  override fun setRate(rate: Double) = runBlockingOnMain { player.playbackSpeed = rate.toFloat() }
+  override fun setRate(rate: Double) =
+    commandPlayer("setRate") { it.playbackSpeed = rate.toFloat() }
 
-  override fun getRate(): Double = runBlockingOnMain { player.playbackSpeed.toDouble() }
+  override fun getRate(): Double = readPlayer(1.0) { it.playbackSpeed.toDouble() }
 
-  override fun getProgress(): Progress = runBlockingOnMain {
-    Progress(
-      duration = player.duration.toSeconds(),
-      position = player.position.toSeconds(),
-      buffered = player.bufferedPosition.toSeconds(),
-    )
-  }
+  override fun getProgress(): Progress =
+    readPlayer(Progress(duration = 0.0, position = 0.0, buffered = 0.0)) { player ->
+      Progress(
+        duration = player.duration.toSeconds(),
+        position = player.position.toSeconds(),
+        buffered = player.bufferedPosition.toSeconds(),
+      )
+    }
 
-  override fun getPlayback(): Playback = runBlockingOnMain { player.getPlayback() }
+  override fun getPlayback(): Playback =
+    readPlayer(Playback(PlaybackState.NONE, null)) { it.getPlayback() }
 
-  override fun getPlayingState(): PlayingState = runBlockingOnMain { player.getPlayingState() }
+  override fun getPlayingState(): PlayingState =
+    readPlayer(PlayingState(playing = false, buffering = false)) { it.getPlayingState() }
 
   override fun getRepeatMode(): RepeatMode = runBlockingOnMain {
     connectedService?.player?.repeatMode ?: pendingRepeatMode ?: RepeatMode.OFF
@@ -916,118 +994,121 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
     connectedService?.player?.let { it.repeatMode = mode } ?: run { pendingRepeatMode = mode }
   }
 
-  override fun getShuffleEnabled(): Boolean = runBlockingOnMain { player.shuffleMode }
+  override fun getShuffleEnabled(): Boolean = readPlayer(false) { it.shuffleMode }
 
-  override fun setShuffleEnabled(enabled: Boolean) = runBlockingOnMain {
-    player.shuffleMode = enabled
-  }
+  override fun setShuffleEnabled(enabled: Boolean) =
+    commandPlayer("setShuffleEnabled") { player -> player.shuffleMode = enabled }
 
-  override fun setPlaybackIntervalEnabled(enabled: Boolean) = runBlockingOnMain {
-    player.setPlaybackIntervalEnabled(enabled)
-  }
+  override fun setPlaybackIntervalEnabled(enabled: Boolean) =
+    commandPlayer("setPlaybackIntervalEnabled") { player ->
+      player.setPlaybackIntervalEnabled(enabled)
+    }
 
-  override fun getPlaybackError(): PlaybackError? = runBlockingOnMain { player.playbackError }
+  override fun getPlaybackError(): PlaybackError? = readPlayer(null) { it.playbackError }
 
-  override fun retry() = runBlockingOnMain { player.prepare() }
+  override fun retry() = commandPlayer("retry") { it.prepare() }
 
   // ============================================================================
   // MARK: Queue Management
   // ============================================================================
 
-  override fun add(tracks: Array<Track>, insertBeforeIndex: Double?) = runBlockingOnMain {
-    val inputIndex = insertBeforeIndex?.toInt() ?: -1
-    player.add(tracks, inputIndex)
-  }
+  override fun add(tracks: Array<Track>, insertBeforeIndex: Double?) =
+    commandPlayer("add") { player ->
+      val inputIndex = insertBeforeIndex?.toInt() ?: -1
+      player.add(tracks, inputIndex)
+    }
 
-  override fun move(fromIndex: Double, toIndex: Double) = runBlockingOnMain {
-    player.move(fromIndex.toInt(), toIndex.toInt())
-  }
+  override fun move(fromIndex: Double, toIndex: Double) =
+    commandPlayer("move") { player -> player.move(fromIndex.toInt(), toIndex.toInt()) }
 
-  override fun remove(indexes: DoubleArray) = runBlockingOnMain {
-    val indexList = indexes.map { it.toInt() }
-    player.remove(indexList)
-  }
+  override fun remove(indexes: DoubleArray) =
+    commandPlayer("remove") { player ->
+      val indexList = indexes.map { it.toInt() }
+      player.remove(indexList)
+    }
 
-  override fun removeUpcomingTracks() = runBlockingOnMain { player.removeUpcomingTracks() }
+  override fun removeUpcomingTracks() =
+    commandPlayer("removeUpcomingTracks") { it.removeUpcomingTracks() }
 
-  override fun skip(index: Double, initialPosition: Double?) = runBlockingOnMain {
-    player.skipTo(index.toInt())
+  override fun skip(index: Double, initialPosition: Double?) =
+    commandPlayer("skip") { player ->
+      player.skipTo(index.toInt())
 
-    if (initialPosition != null && initialPosition >= 0) {
-      player.seekTo((initialPosition * 1000).toLong(), TimeUnit.MILLISECONDS)
+      if (initialPosition != null && initialPosition >= 0) {
+        player.seekTo((initialPosition * 1000).toLong(), TimeUnit.MILLISECONDS)
+      }
     }
-  }
 
-  override fun skipToNext(initialPosition: Double?) = runBlockingOnMain {
-    player.next()
+  override fun skipToNext(initialPosition: Double?) =
+    commandPlayer("skipToNext") { player ->
+      player.next()
 
-    if (initialPosition != null && initialPosition >= 0) {
-      player.seekTo((initialPosition * 1000).toLong(), TimeUnit.MILLISECONDS)
+      if (initialPosition != null && initialPosition >= 0) {
+        player.seekTo((initialPosition * 1000).toLong(), TimeUnit.MILLISECONDS)
+      }
     }
-  }
 
-  override fun skipToPrevious(initialPosition: Double?) = runBlockingOnMain {
-    player.previous()
+  override fun skipToPrevious(initialPosition: Double?) =
+    commandPlayer("skipToPrevious") { player ->
+      player.previous()
 
-    if (initialPosition != null && initialPosition >= 0) {
-      player.seekTo((initialPosition * 1000).toLong(), TimeUnit.MILLISECONDS)
+      if (initialPosition != null && initialPosition >= 0) {
+        player.seekTo((initialPosition * 1000).toLong(), TimeUnit.MILLISECONDS)
+      }
     }
-  }
 
   override fun setQueue(tracks: Array<Track>, startIndex: Double?, startPosition: Double?) =
-    runBlockingOnMain {
+    commandPlayer("setQueue") { player ->
       player.setQueue(tracks, startIndex?.toInt() ?: 0, ((startPosition ?: 0.0) * 1000).toLong())
     }
 
-  override fun setActiveTrackFavorited(favorited: Boolean) = runBlockingOnMain {
-    player.setActiveTrackFavorited(favorited)
-  }
+  override fun setActiveTrackFavorited(favorited: Boolean): Unit =
+    commandPlayer("setActiveTrackFavorited") { player ->
+      // Applied-result is for MediaSession honesty; the JS API stays fire-and-forget.
+      player.setActiveTrackFavorited(favorited)
+    }
 
-  override fun toggleActiveTrackFavorited() = runBlockingOnMain {
-    player.toggleActiveTrackFavorited()
-  }
+  override fun toggleActiveTrackFavorited(): Unit =
+    commandPlayer("toggleActiveTrackFavorited") { it.toggleActiveTrackFavorited() }
 
-  override fun getQueue(): Array<Track> = runBlockingOnMain { player.tracks }
+  override fun getQueue(): Array<Track> = readPlayer(emptyArray()) { it.tracks }
 
-  override fun getTrack(index: Double): Track? = runBlockingOnMain {
-    try {
-      player.getTrack(index.toInt())
-    } catch (e: IllegalArgumentException) {
-      null
+  override fun getTrack(index: Double): Track? =
+    readPlayer(null) { player ->
+      try {
+        player.getTrack(index.toInt())
+      } catch (e: IllegalArgumentException) {
+        null
+      }
     }
-  }
 
-  override fun getActiveTrackIndex(): Double? = runBlockingOnMain {
-    player.currentIndex?.toDouble()
-  }
+  override fun getActiveTrackIndex(): Double? = readPlayer(null) { it.currentIndex?.toDouble() }
 
-  override fun getActiveTrack(): Track? = runBlockingOnMain { player.currentTrack }
+  override fun getActiveTrack(): Track? = readPlayer(null) { it.currentTrack }
 
   // ============================================================================
   // MARK: Now Playing Metadata
   // ============================================================================
 
-  override fun updateNowPlaying(update: NowPlayingUpdate?) = runBlockingOnMain {
-    player.nowPlaying.updateNowPlaying(update)
-  }
+  override fun updateNowPlaying(update: NowPlayingUpdate?) =
+    commandPlayer("updateNowPlaying") { player -> player.nowPlaying.updateNowPlaying(update) }
 
-  override fun flashNowPlaying(update: NowPlayingUpdate, durationMs: Double) = runBlockingOnMain {
-    player.nowPlaying.flashNowPlaying(update, durationMs)
-  }
+  override fun flashNowPlaying(update: NowPlayingUpdate, durationMs: Double) =
+    commandPlayer("flashNowPlaying") { player ->
+      player.nowPlaying.flashNowPlaying(update, durationMs)
+    }
 
-  override fun clearNowPlayingFlash() = runBlockingOnMain {
-    player.nowPlaying.clearNowPlayingFlash()
-  }
+  override fun clearNowPlayingFlash() =
+    commandPlayer("clearNowPlayingFlash") { player -> player.nowPlaying.clearNowPlayingFlash() }
 
-  override fun getNowPlaying(): NowPlayingMetadata? = runBlockingOnMain {
-    player.nowPlaying.getNowPlaying()
-  }
+  override fun getNowPlaying(): NowPlayingMetadata? =
+    readPlayer(null) { player -> player.nowPlaying.getNowPlaying() }
 
   // ============================================================================
   // MARK: Network Connectivity
   // ============================================================================
 
-  override fun getOnline(): Boolean = runBlockingOnMain { player.getOnline() }
+  override fun getOnline(): Boolean = readPlayer(true) { it.getOnline() }
 
   // ============================================================================
   // MARK: System Volume
@@ -1053,35 +1134,32 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
   // MARK: Equalizer (Android only)
   // ============================================================================
 
-  override fun getEqualizerSettings(): EqualizerSettings? = runBlockingOnMain {
-    player.equalizer.getSettings()
-  }
+  override fun getEqualizerSettings(): EqualizerSettings? =
+    readPlayer(null) { player -> player.equalizer.getSettings() }
 
-  override fun setEqualizerEnabled(enabled: Boolean) = runBlockingOnMain {
-    player.equalizer.setEnabled(enabled)
-  }
+  override fun setEqualizerEnabled(enabled: Boolean) =
+    commandPlayer("setEqualizerEnabled") { player -> player.equalizer.setEnabled(enabled) }
 
-  override fun setEqualizerPreset(preset: String) = runBlockingOnMain {
-    player.equalizer.setPreset(preset)
-  }
+  override fun setEqualizerPreset(preset: String) =
+    commandPlayer("setEqualizerPreset") { player -> player.equalizer.setPreset(preset) }
 
-  override fun setEqualizerLevels(levels: DoubleArray) = runBlockingOnMain {
-    player.equalizer.setLevels(levels)
-  }
+  override fun setEqualizerLevels(levels: DoubleArray) =
+    commandPlayer("setEqualizerLevels") { player -> player.equalizer.setLevels(levels) }
 
   // ============================================================================
   // MARK: Sleep Timer
   // ============================================================================
 
-  override fun getSleepTimer(): SleepTimer = runBlockingOnMain { player.sleepTimer.get() }
+  override fun getSleepTimer(): SleepTimer =
+    readPlayer(SleepTimer.create(NullType.NULL)) { it.sleepTimer.get() }
 
-  override fun setSleepTimer(seconds: Double, fadeDuration: Double?) = runBlockingOnMain {
-    player.sleepTimer.setAfter(seconds, fadeDuration)
-  }
+  override fun setSleepTimer(seconds: Double, fadeDuration: Double?) =
+    commandPlayer("setSleepTimer") { player -> player.sleepTimer.setAfter(seconds, fadeDuration) }
 
-  override fun setSleepTimerToEndOfTrack() = runBlockingOnMain { player.sleepTimer.setEndOfTrack() }
+  override fun setSleepTimerToEndOfTrack() =
+    commandPlayer("setSleepTimerToEndOfTrack") { it.sleepTimer.setEndOfTrack() }
 
-  override fun clearSleepTimer(): Boolean = runBlockingOnMain { player.sleepTimer.clear() }
+  override fun clearSleepTimer(): Boolean = readPlayer(false) { it.sleepTimer.clear() }
 
   // ============================================================================
   // MARK: Battery Optimization (Android only)
@@ -1175,13 +1253,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()
@@ -1228,6 +1300,29 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
   private val service: Service
     get() = connectedService ?: throw Exception("Player not initialized")
 
+  /**
+   * The player while its service is connected: not before setupPlayer, nor while the service
+   * restarts.
+   */
+  private val connectedPlayer: Player?
+    get() = connectedService?.player
+
+  /** What [read] gets from the player, or without one [fallback], the answer iOS gives then. */
+  private fun <T> readPlayer(fallback: T, read: suspend (Player) -> T): T = runBlockingOnMain {
+    val player = connectedPlayer ?: return@runBlockingOnMain fallback
+    read(player)
+  }
+
+  /** Runs [command] on the player; without one it is dropped with a warning, as iOS drops it. */
+  private fun commandPlayer(name: String, command: suspend (Player) -> Unit) = runBlockingOnMain {
+    val player = connectedPlayer
+    if (player == null) {
+      Timber.w("$name before the player is set up, or while its service restarts: ignored")
+    } else {
+      command(player)
+    }
+  }
+
   internal val player
     get() = service.player
 
@@ -1436,9 +1531,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 +1562,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"
+  }
+}