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

package/android/src/main/java/com/audiobrowser/player/MediaSessionCallback.kt

@@ -11,22 +11,32 @@ import androidx.media3.session.MediaSession
 import androidx.media3.session.SessionCommand
 import androidx.media3.session.SessionError
 import androidx.media3.session.SessionResult
+import com.audiobrowser.browser.BrowserManager
 import com.audiobrowser.browser.handleTrackLoad
+import com.audiobrowser.browser.normalizedSections
+import com.audiobrowser.browser.styleResolvedSections
+import com.audiobrowser.browser.untitledSection
+import com.audiobrowser.extension.indexOfTappedTrack
 import com.audiobrowser.extension.toTrack
+import com.audiobrowser.navigationErrorFor
 import com.audiobrowser.util.BrowserPathHelper
 import com.audiobrowser.util.RatingFavorites
 import com.audiobrowser.util.TrackFactory
 import com.google.common.collect.ImmutableList
 import com.google.common.util.concurrent.Futures
 import com.google.common.util.concurrent.ListenableFuture
+import com.margelo.nitro.audiobrowser.FormattedNavigationError
 import com.margelo.nitro.audiobrowser.Gate
 import com.margelo.nitro.audiobrowser.GateEvent
 import com.margelo.nitro.audiobrowser.GateReason
 import com.margelo.nitro.audiobrowser.MediaReference
 import com.margelo.nitro.audiobrowser.NativeGateRequest
-import com.margelo.nitro.audiobrowser.NotificationButtonLayout
+import com.margelo.nitro.audiobrowser.NavigationError
+import com.margelo.nitro.audiobrowser.NavigationErrorType
 import com.margelo.nitro.audiobrowser.PlayerCapabilities
+import com.margelo.nitro.audiobrowser.RemoteButtonLayout
 import com.margelo.nitro.audiobrowser.SearchParams
+import com.margelo.nitro.audiobrowser.Section
 import com.margelo.nitro.audiobrowser.Track
 import kotlinx.coroutines.CancellationException
 import kotlinx.coroutines.CoroutineScope
@@ -40,8 +50,12 @@ import kotlinx.coroutines.withContext
 import timber.log.Timber
 
 /**
- * MediaLibrarySession callback that handles all media session interactions. All logic is handled
- * directly by the AudioBrowser.
+ * Everything the MediaLibrarySession serves except transport: browse, search, item lookup, queue
+ * building, playback resumption, and the favorite and rating commands. Transport does not arrive
+ * here — it reaches the player through [InterceptingPlayer], and Assistant's play-from-search
+ * arrives as an intent handled in the service. The callbacks that answer through [scope] run on IO,
+ * so anything touching the ExoPlayer instance hops back to [Dispatchers.Main]; the rest answer
+ * synchronously on the Media3 application thread.
  */
 class MediaSessionCallback(private val player: Player) :
   MediaLibraryService.MediaLibrarySession.Callback {
@@ -53,6 +67,8 @@ class MediaSessionCallback(private val player: Player) :
   // threads (network observer, JS-triggered notifies) — guard all access with synchronized(this).
   private val parentIdSubscriptions =
     mutableMapOf<String, MutableSet<MediaSession.ControllerInfo>>()
+  private val failedSearch = FailedSearchSlot()
+  private val offlineSearches = OfflineSearchRegistry()
   private var mediaLibrarySession: MediaLibraryService.MediaLibrarySession? = null
 
   /**
@@ -64,14 +80,15 @@ class MediaSessionCallback(private val player: Player) :
     private set
 
   init {
-    // Observe network state changes and notify subscribers
-    player.networkMonitor.observeOnline(scope) { _ -> notifySubscribedChildrenChanged() }
+    player.networkMonitor.observeOnline(scope) { online ->
+      notifySubscribedChildrenChanged()
+      // A browse level is re-queried through its subscription; a search has none, so its offline
+      // tile has to be taken off the screen by re-running the query.
+      if (online) scope.launch { reannounceOfflineSearches() }
+    }
   }
 
-  /**
-   * Apply pagination to a list of items. If pageSize is 0 or MAX_VALUE (Android Auto default),
-   * returns the full list.
-   */
+  /** Media3's legacy browse bridge asks for a whole list with pageSize [Int.MAX_VALUE]. */
   private fun <T> List<T>.paginate(page: Int, pageSize: Int): List<T> {
     return if (pageSize in 1 until Int.MAX_VALUE) {
       this.drop(page * pageSize).take(pageSize)
@@ -80,45 +97,6 @@ class MediaSessionCallback(private val player: Player) :
     }
   }
 
-  /** Creates an offline error MediaItem. */
-  private fun createOfflineMediaItem(): MediaItem =
-    createErrorMediaItem(
-      mediaId = BrowserPathHelper.OFFLINE_PATH,
-      title = player.context.getString(com.audiobrowser.R.string.audio_browser_offline_error),
-      subtitle =
-        player.context.getString(com.audiobrowser.R.string.audio_browser_offline_error_subtitle),
-    )
-
-  /**
-   * Builds a non-browsable, non-playable [MediaItem] used to surface an error inside an Android
-   * Auto / AAOS browse list. Rendered as a greyed-out, non-interactive tile, which is the only
-   * side-effect-free way to communicate a browse failure to legacy controllers (Media3 drops
-   * [LibraryResult.ofError] on the legacy browse bridge, leaving an empty "No items" screen).
-   */
-  private fun createErrorMediaItem(mediaId: String, title: String, subtitle: String): MediaItem =
-    MediaItem.Builder()
-      .setMediaId(mediaId)
-      .setMediaMetadata(
-        MediaMetadata.Builder()
-          .setTitle(title)
-          .setSubtitle(subtitle)
-          // Non-browsable, non-playable. Android Auto ignores these flags and still drills into a
-          // tapped tile, but onGetChildren returns an empty list for the sentinel paths so it's a
-          // harmless "No Items" dead-end rather than an endless stack of error pages.
-          .setIsBrowsable(false)
-          .setIsPlayable(false)
-          .build()
-      )
-      .build()
-
-  /**
-   * Builds the gate tile from a per-request chrome: while a gate is active, tabs stay visible but a
-   * gated browse/search level serves this single tile (see the gate checks in [onGetChildren] /
-   * [onGetSearchResult]). Same shape as the error tiles — non-browsable, non-playable — and
-   * deliberately NOT accompanied by a SessionError: a gate is deliberate app state, not a failure.
-   * The message renders as the tile's subtitle (newlines collapse to spaces — list rows are
-   * single-line).
-   */
   /**
    * Wraps a raw external-search query string into the structured [SearchParams] the gate request
    * carries. The car search surfaces only give a free-text query, so the other fields stay null —
@@ -136,40 +114,34 @@ class MediaSessionCallback(private val player: Player) :
       reference = MediaReference.UNKNOWN,
     )
 
-  private fun createGateMediaItem(gate: Gate): MediaItem =
-    createErrorMediaItem(
-      mediaId = BrowserPathHelper.GATE_PATH,
-      title = gate.title,
-      subtitle = gate.message?.replace('\n', ' ') ?: "",
-    )
-
   /**
-   * Builds a generic "something went wrong" error tile for a browse failure. The true offline case
-   * is handled separately by the [networkMonitor] guard in [onGetChildren]; anything reaching the
-   * catch block is an online-but-failed request (e.g. server down, bad status), so it must NOT be
-   * labelled "no internet connection".
+   * Builds the gate tile from a per-request chrome: while a gate is active, tabs stay visible but a
+   * gated browse/search level serves this single tile (see the gate checks in [onGetChildren] /
+   * [onGetSearchResult]). Same shape as the error tiles — non-browsable, non-playable — and
+   * deliberately NOT accompanied by a SessionError: a gate is deliberate app state, not a failure.
    */
-  private fun createBrowseErrorMediaItem(): MediaItem =
+  private fun createGateMediaItem(gate: Gate): MediaItem =
     createErrorMediaItem(
-      mediaId = BrowserPathHelper.ERROR_PATH,
-      title = player.context.getString(com.audiobrowser.R.string.audio_browser_browse_error),
-      subtitle =
-        player.context.getString(com.audiobrowser.R.string.audio_browser_browse_error_subtitle),
+      BrowserPathHelper.GATE_PATH,
+      FormattedNavigationError(gate.title, gate.message),
     )
 
   fun updateMediaSession(
     mediaSession: MediaSession,
     capabilities: PlayerCapabilities,
-    notificationButtons: NotificationButtonLayout?,
+    remoteButtonLayout: RemoteButtonLayout?,
     searchAvailable: Boolean,
+    forwardJumpInterval: Double,
+    backwardJumpInterval: Double,
   ) {
-    // Store as MediaLibrarySession for notifyChildrenChanged support
     this.mediaLibrarySession = mediaSession as? MediaLibraryService.MediaLibrarySession
     commandManager.updateMediaSession(
       mediaSession,
       capabilities,
-      notificationButtons,
+      remoteButtonLayout,
       searchAvailable,
+      forwardJumpInterval,
+      backwardJumpInterval,
     )
   }
 
@@ -181,18 +153,34 @@ class MediaSessionCallback(private val player: Player) :
     return commandManager.buildConnectionResult(session)
   }
 
+  override fun onDisconnected(session: MediaSession, controller: MediaSession.ControllerInfo) {
+    Timber.Forest.d("MediaSession disconnect: ${controller.packageName}")
+    // A controller that leaves without unsubscribing (Android Auto's normal exit) would otherwise
+    // be notified — and held — forever.
+    offlineSearches.forget(controller)
+    synchronized(this) {
+      parentIdSubscriptions.values.forEach { it.remove(controller) }
+      parentIdSubscriptions.entries.removeAll { (_, browsers) -> browsers.isEmpty() }
+    }
+    super.onDisconnected(session, controller)
+  }
+
   override fun onCustomCommand(
     session: MediaSession,
     controller: MediaSession.ControllerInfo,
     command: SessionCommand,
     args: Bundle,
   ): ListenableFuture<SessionResult> {
-    // Handle favorite button tap
+    // A success here makes the controller flip its heart optimistically, so a no-op (no current
+    // track) must report INVALID_STATE instead of success-then-revert.
     if (command.customAction == MediaSessionCommandManager.CUSTOM_ACTION_FAVORITE) {
-      val currentFavorited = player.currentTrack?.favorited ?: false
-      Timber.d("Favorite button tapped - toggling from $currentFavorited to ${!currentFavorited}")
-      player.setActiveTrackFavorited(!currentFavorited)
-      return Futures.immediateFuture(SessionResult(SessionResult.RESULT_SUCCESS))
+      val applied = player.toggleActiveTrackFavorited()
+      Timber.d("Favorite button tapped - toggle applied=$applied")
+      return Futures.immediateFuture(
+        SessionResult(
+          if (applied) SessionResult.RESULT_SUCCESS else SessionResult.RESULT_ERROR_INVALID_STATE
+        )
+      )
     }
 
     if (commandManager.handleCustomCommand(command, player)) {
@@ -208,8 +196,16 @@ class MediaSessionCallback(private val player: Player) :
   ): ListenableFuture<SessionResult> {
     // A heart rating from a controller (e.g. Google Assistant "I like this") toggles the
     // now-playing favorite. setActiveTrackFavorited fires onFavoriteChanged so the consumer
-    // persists it — the same path as the notification / CarPlay heart button.
-    RatingFavorites.favoritedFor(rating)?.let { player.setActiveTrackFavorited(it) }
+    // persists it — the same path as the notification / CarPlay heart button. Report an honest
+    // result (see onCustomCommand): INVALID_STATE when there is no current track to favorite.
+    RatingFavorites.favoritedFor(rating)?.let { favorited ->
+      val applied = player.setActiveTrackFavorited(favorited)
+      return Futures.immediateFuture(
+        SessionResult(
+          if (applied) SessionResult.RESULT_SUCCESS else SessionResult.RESULT_ERROR_INVALID_STATE
+        )
+      )
+    }
     return super.onSetRating(session, controller, rating)
   }
 
@@ -219,13 +215,6 @@ class MediaSessionCallback(private val player: Player) :
     browser: MediaSession.ControllerInfo,
     params: MediaLibraryService.LibraryParams?,
   ): ListenableFuture<LibraryResult<MediaItem>> {
-    // Extract artwork size hint from root hints (e.g., from Android Auto)
-    // TODO: Also consider these other root hints in the future:
-    // - KEY_ROOT_HINT_MEDIA_HOST_VERSION
-    // - KEY_ROOT_HINT_MEDIA_SESSION_API
-    // - BROWSER_ROOT_HINTS_KEY_CUSTOM_BROWSER_ACTION_LIMIT
-    // - BROWSER_ROOT_HINTS_KEY_ROOT_CHILDREN_LIMIT
-    // - KEY_ROOT_HINT_MAX_QUEUE_ITEMS_WHILE_RESTRICTED
     params?.extras?.getInt(MediaConstants.EXTRAS_KEY_MEDIA_ART_SIZE_PIXELS, 0)?.let { size ->
       if (size > 0) {
         artworkSizeHintPixels = size
@@ -234,13 +223,11 @@ class MediaSessionCallback(private val player: Player) :
     }
 
     if (params?.isRecent == true) {
-      // TODO: support recent queries through something like onRecent and return a MediaItem with
-      // .setMediaId("__RECENT__") here - when onRecent is not configured we can keep returning an
-      // error here:
-
-      // The service currently does not support playback resumption. Tell System UI by returning
-      // an error of type 'RESULT_ERROR_NOT_SUPPORTED' for a `params.isRecent` request. See
-      // https://github.com/androidx/media/issues/355
+      // Playback resumption is served by media3 itself: it intercepts System UI's EXTRA_RECENT
+      // root request internally and answers through onPlaybackResumption, so that request never
+      // reaches this callback. Any other browser asking for a recent root gets
+      // ERROR_NOT_SUPPORTED — there is no browsable recents tree; recents are ordinary consumer
+      // content (a tab or route).
       return Futures.immediateFuture(LibraryResult.ofError(SessionError.ERROR_NOT_SUPPORTED))
     }
 
@@ -267,10 +254,9 @@ class MediaSessionCallback(private val player: Player) :
     params: MediaLibraryService.LibraryParams?,
   ): ListenableFuture<LibraryResult<ImmutableList<MediaItem>>> {
     Timber.d(
-      "onGetChildren: {parentId: $parentId, page: $page, pageSize: $pageSize, isSearchPath: ${BrowserPathHelper.isSpecialPath(parentId)} }"
+      "onGetChildren: {parentId: $parentId, page: $page, pageSize: $pageSize, isSpecialPath: ${BrowserPathHelper.isSpecialPath(parentId)} }"
     )
     return scope.future {
-      // Wait for browser to be registered if it's not available yet
       val audioBrowser =
         player.awaitBrowser().also { Timber.d("Browser ready, proceeding with onGetChildren") }
       val browserManager = audioBrowser.browserManager
@@ -297,54 +283,56 @@ class MediaSessionCallback(private val player: Player) :
         }
       }
 
-      // The error / offline tiles are dead-ends. Some controllers (e.g. Android Auto when online)
-      // treat a non-browsable tile as tappable and subscribe to its mediaId anyway; returning the
-      // error tile again here would push an endless stack of error pages. Return nothing instead.
-      // For the offline tile, re-send the alert when still offline so a tap surfaces the
-      // explanation again — but only then, since these paths are also re-queried by
-      // notifyChildrenChanged (e.g. when connectivity returns) without any user action.
-      if (parentId == BrowserPathHelper.OFFLINE_PATH || parentId == BrowserPathHelper.ERROR_PATH) {
+      // A drill-in on the error / offline / empty tile returns nothing (see isDeadEndPath). For
+      // the offline tile, re-send the alert when still offline so a tap surfaces the explanation
+      // again — but only then, since these paths are also re-queried by notifyChildrenChanged
+      // (e.g. when connectivity returns) without any user action.
+      if (BrowserPathHelper.isDeadEndPath(parentId)) {
         if (parentId == BrowserPathHelper.OFFLINE_PATH && !player.networkMonitor.isOnline.value) {
           sendBrowseError(session, browser, offline = true)
         }
         return@future LibraryResult.ofItemList(ImmutableList.of<MediaItem>(), params)
       }
 
-      // Show offline error when offline:
       if (
         !player.networkMonitor.isOnline.value && browserManager.config.androidControllerOfflineError
       ) {
         Timber.w("Network offline - returning error message for: $parentId")
         sendBrowseError(session, browser, offline = true)
-        return@future LibraryResult.ofItemList(ImmutableList.of(createOfflineMediaItem()), params)
+        return@future LibraryResult.ofItemList(
+          ImmutableList.of(
+            createOfflineMediaItem(audioBrowser.resolveFormattedError(offlineError(), parentId))
+          ),
+          params,
+        )
       }
 
       try {
         val children =
-          if (parentId == BrowserPathHelper.RECENT_PATH) {
-            // TODO: implement recent media items
-            emptyList<MediaItem>()
-          } else if (parentId == BrowserPathHelper.ROOT_PATH) {
-            // Return tabs as root children (limited to 4 for automotive platform compatibility)
-            // TODO: Check what Android Auto does with empty tabs list - may need to return error?
-            val tabs = browserManager.queryTabs()
+          if (parentId == BrowserPathHelper.ROOT_PATH) {
+            // Disabled tabs hide (Track.disabled) — filtered before the four-tab cap so an
+            // unavailable tab never costs an available one its slot.
+            val tabs = browserManager.queryTabs().filterNot { it.disabled == true }
             if (tabs.size > 4) {
               Timber.w(
                 "Root has ${tabs.size} tabs; dropping ${tabs.size - 4} (Android Auto root limit)"
               )
             }
-            toMediaItems(tabs.take(4))
+            toFlatMediaItems(tabs.take(4))
           } else {
-            // Resolve the specific path and get its children
+            // Section styles arrive page-folded (`section ?? page`, ADR 0011).
             val resolvedTrack = browserManager.resolve(parentId)
-
-            // Convert children to MediaItems (url is already set to contextual URL)
-            val trackChildren =
-              resolvedTrack.children
-                ?: throw IllegalStateException(
-                  "Expected browsed ResolvedTrack to have a children array"
-                )
-            toMediaItems(trackChildren.toList())
+            val sections =
+              resolvedTrack.styleResolvedSections()
+                ?: throw IllegalStateException("Expected browsed ResolvedTrack to have sections")
+            browserManager.warnIfGridPageLacksPromise(parentId, sections)
+            // A page with no children resolved fine, so it raises no SessionError and no event —
+            // notifyChildrenChanged re-queries these paths without any user action. It serves the
+            // app's path-aware `empty-content` copy as one inert tile (ADR 0001) instead of
+            // Android Auto's bare "No items".
+            browseLevelItems(toMediaItems(sections)) {
+              audioBrowser.resolveFormattedError(emptyContentError(), parentId)
+            }
           }
 
         LibraryResult.ofItemList(ImmutableList.copyOf(children.paginate(page, pageSize)), params)
@@ -353,18 +341,17 @@ class MediaSessionCallback(private val player: Player) :
         // error tile. awaitBrowser's TimeoutCancellationException IS a real failure, keep that.
         if (e is CancellationException && e !is TimeoutCancellationException) throw e
         Timber.e(e, "Error getting children for parentId: $parentId")
-        // Surface an error tile instead of a bare ofError(): Media3 drops the error message on the
-        // legacy browse bridge, which would otherwise leave an empty "No items" screen in Android
-        // Auto. See https://github.com/androidx/media/issues/2901
-        //
-        // Verified on a head unit (2026-06): the AA browse list NEVER renders error text — not for
-        // transient sendError, sticky non-fatal replication, or fatal replication
-        // (setLibraryErrorReplicationMode). Fatal replication does show the message on the
-        // playback screen, but presents the session as STATE_ERROR with no actions, hiding the
-        // now-playing item and transport controls — not worth it. Tiles remain the only in-browse
-        // signal we control.
+        // A tile rather than a bare ofError() — see createErrorMediaItem and
+        // https://github.com/androidx/media/issues/2901
         sendBrowseError(session, browser, offline = false)
-        LibraryResult.ofItemList(ImmutableList.of(createBrowseErrorMediaItem()), params)
+        LibraryResult.ofItemList(
+          ImmutableList.of(
+            createBrowseErrorMediaItem(
+              audioBrowser.resolveFormattedError(navigationErrorFor(e), parentId)
+            )
+          ),
+          params,
+        )
       }
     }
   }
@@ -375,8 +362,8 @@ class MediaSessionCallback(private val player: Player) :
    * Media3 transiently attaches the error code/message to the platform session's playback state
    * without entering STATE_ERROR.
    *
-   * NOTE: current Android Auto renders NOTHING for this (verified on a head unit — see
-   * androidx/media#2901; the transient state is cleared microseconds after being set). It is kept
+   * NOTE: current Android Auto renders nothing for this — its transient state is cleared
+   * microseconds after being set (see [createErrorMediaItem], androidx/media#2901). It is kept
    * because it is the correct Media3-API error signal, costs nothing, and becomes user-visible if
    * Android Auto moves to consuming SessionError via the Media3 controller API.
    *
@@ -398,19 +385,45 @@ class MediaSessionCallback(private val player: Player) :
   }
 
   /**
-   * Converts tracks to MediaItems for browse delivery, routing http(s) artwork through the
-   * content:// provider so Android Auto can load it via the ArtworkContentProvider. Image-row
-   * tracks (a CarPlay-only rendering) are expanded into their items as regular grouped rows
-   * first — see [TrackFactory.expandImageRows].
+   * Flattens a page's sections to MediaItems for browse delivery — the Media3 boundary where
+   * sections die (ADR 0010): the MediaBrowser protocol has no section node, so each child is
+   * stamped with its owning section's title/style hints. A section with a `path` gains a browsable
+   * "view more" row under the same header — at every `display`, because no Android Auto header is
+   * tappable at any of them, so the row is the section's only "view all" affordance here. Http(s)
+   * artwork routes through the content:// provider so Android Auto can load it via the
+   * ArtworkContentProvider.
    */
-  private fun toMediaItems(tracks: List<Track>): List<MediaItem> {
+  private suspend fun toMediaItems(sections: List<Section>): List<MediaItem> {
     val registry = player.browseArtworkRegistry
     val authority = com.audiobrowser.util.ArtworkUris.authorityFor(player.context.packageName)
-    return TrackFactory.expandImageRows(tracks).map {
-      TrackFactory.toBrowseMediaItem(it, registry, authority)
+    return sections.flatMap { section ->
+      // Android Auto has no disabled affordance, so an unavailable track hides
+      // — never a normal-looking dead row (Track.disabled's rendering ladder).
+      val children = section.children.filter { it.disabled != true }
+      val items = children.map { TrackFactory.toBrowseMediaItem(it, registry, authority, section) }
+      // No "view more" under an empty section — CarPlay skips empty sections
+      // outright, and a lone navigation tile under a header is a dead end.
+      if (section.path == null || children.isEmpty()) return@flatMap items
+      // The browser is already up at every call site, so awaiting it here is a field read, and
+      // viewMoreTitle is memoized per content generation — both are free after the first row.
+      val title = player.awaitBrowser().browserManager.viewMoreTitle()
+      items +
+        TrackFactory.toBrowseMediaItem(
+          TrackFactory.navigationTrack(section, title),
+          registry,
+          authority,
+          section,
+        )
     }
   }
 
+  /**
+   * Flat lists (tabs, search results) convert as one untitled list section — which contributes no
+   * group or style hints — so exactly one Track→MediaItem path exists at the Media3 boundary.
+   */
+  private suspend fun toFlatMediaItems(tracks: List<Track>): List<MediaItem> =
+    toMediaItems(listOf(untitledSection(tracks.toTypedArray())))
+
   override fun onGetItem(
     session: MediaLibraryService.MediaLibrarySession,
     browser: MediaSession.ControllerInfo,
@@ -418,15 +431,56 @@ class MediaSessionCallback(private val player: Player) :
   ): ListenableFuture<LibraryResult<MediaItem>> {
     Timber.Forest.d("onGetItem: ${browser.packageName}, mediaId = $mediaId")
     return scope.future {
-      // Handle special paths first (these don't need browser)
+      // Only the root answers ahead of awaitBrowser: it needs no browser. Every tile sentinel
+      // below does — for the formatter hop, and the gate one for gateDecision.
+      if (mediaId == BrowserPathHelper.ROOT_PATH) {
+        return@future LibraryResult.ofItem(
+          MediaItem.Builder()
+            .setMediaId(mediaId)
+            .setMediaMetadata(
+              MediaMetadata.Builder().setIsBrowsable(true).setIsPlayable(false).build()
+            )
+            .build(),
+          null,
+        )
+      }
+
       if (mediaId == BrowserPathHelper.OFFLINE_PATH) {
-        return@future LibraryResult.ofItem(createOfflineMediaItem(), null)
+        return@future LibraryResult.ofItem(
+          createOfflineMediaItem(
+            player
+              .awaitBrowser()
+              .resolveFormattedError(offlineError(), BrowserPathHelper.OFFLINE_PATH)
+          ),
+          null,
+        )
       }
 
-      // Return the error tile as a non-browsable item so tapping it can't re-browse into a
-      // failing path (which would push another error page onto the stack).
       if (mediaId == BrowserPathHelper.ERROR_PATH) {
-        return@future LibraryResult.ofItem(createBrowseErrorMediaItem(), null)
+        // The exception that produced the tile is gone by now — the sentinel is all the controller
+        // hands back — so the copy formats for the sentinel under the generic failure code.
+        return@future LibraryResult.ofItem(
+          createBrowseErrorMediaItem(
+            player
+              .awaitBrowser()
+              .resolveFormattedError(browseFailureError(), BrowserPathHelper.ERROR_PATH)
+          ),
+          null,
+        )
+      }
+
+      if (mediaId == BrowserPathHelper.EMPTY_PATH) {
+        // A controller re-reading the tile it was served. The page's path is gone by now — the
+        // sentinel is all it hands back — so the copy formats for the sentinel and lands on the
+        // app's generic empty wording, or the default.
+        return@future LibraryResult.ofItem(
+          createEmptyMediaItem(
+            player
+              .awaitBrowser()
+              .resolveFormattedError(emptyContentError(), BrowserPathHelper.EMPTY_PATH)
+          ),
+          null,
+        )
       }
 
       if (mediaId == BrowserPathHelper.GATE_PATH) {
@@ -447,22 +501,9 @@ class MediaSessionCallback(private val player: Player) :
         return@future LibraryResult.ofItem(createGateMediaItem(outcome.chrome!!), null)
       }
 
-      if (mediaId == BrowserPathHelper.ROOT_PATH || mediaId == BrowserPathHelper.RECENT_PATH) {
-        return@future LibraryResult.ofItem(
-          MediaItem.Builder()
-            .setMediaId(mediaId)
-            .setMediaMetadata(
-              MediaMetadata.Builder().setIsBrowsable(true).setIsPlayable(false).build()
-            )
-            .build(),
-          null,
-        )
-      }
-
-      // Wait for browser to be registered if it's not available yet
       val browserManager = player.awaitBrowser().browserManager
 
-      // Serve tracks from the track cache first (keyed by url and src). Besides avoiding an HTTP
+      // Serve tracks from the track cache first (keyed by path and src). Besides avoiding an HTTP
       // resolve, this keeps item identity correct for contextual mediaIds: resolve() strips
       // __trackId and would return the *parent container's* metadata as the item.
       val browseAuthority =
@@ -534,9 +575,6 @@ class MediaSessionCallback(private val player: Player) :
   }
 
   /**
-   * Notifies all subscribed controllers to refresh their content. Called internally when network
-   * state changes to refresh all subscribed paths.
-   *
    * Safe to call from any thread: snapshots the subscribed paths and dispatches the session calls
    * to the main (Media3 application) thread.
    */
@@ -549,10 +587,8 @@ class MediaSessionCallback(private val player: Player) :
   }
 
   /**
-   * Notifies external controllers that content at the given path has changed. Controllers
-   * subscribed to this path will refresh their UI. Safe to call from any thread.
-   *
-   * @param path The path where content has changed
+   * Notifies external controllers that content at the given path has changed, so controllers
+   * subscribed to it refresh their UI. Safe to call from any thread.
    */
   fun notifyContentChanged(path: String) {
     Timber.d("Notifying content changed for path: $path")
@@ -570,10 +606,6 @@ class MediaSessionCallback(private val player: Player) :
     notifySubscribedChildrenChanged()
   }
 
-  /**
-   * Called when the browser becomes available after a cold start. Notifies all subscribed
-   * controllers to refresh their content.
-   */
   fun notifyBrowserReady() {
     Timber.d("Browser ready - notifying all subscribed paths")
     notifySubscribedChildrenChanged()
@@ -592,8 +624,6 @@ class MediaSessionCallback(private val player: Player) :
   ): ListenableFuture<LibraryResult<Void>> {
     Timber.d("onSearch: ${browser.packageName}, query = $query")
     return scope.future {
-      // Wait for browser registration like onGetChildren does, so a cold-start voice search
-      // doesn't fail before JS has configured the browser.
       val audioBrowser =
         try {
           player.awaitBrowser()
@@ -615,28 +645,83 @@ class MediaSessionCallback(private val player: Player) :
         return@future LibraryResult.ofVoid()
       }
 
-      // Check if search is configured
+      // Before the offline branch inside announceSearch: with no search source configured the
+      // answer is not-supported, online or not.
       if (!browserManager.config.hasSearch) {
         Timber.w("Search requested but no search source configured")
         return@future LibraryResult.ofError(SessionError.ERROR_NOT_SUPPORTED)
       }
 
-      try {
-        // Execute search (automatically caches results at /__search?q=query)
-        val searchResults = browserManager.search(query)
-        val resultCount = searchResults.children?.size ?: 0
-
-        Timber.d("Search completed: $resultCount results for query '$query'")
+      announceSearch(session, browser, browserManager, query, params)
+      LibraryResult.ofVoid()
+    }
+  }
 
-        // Notify Media3 of search results
-        session.notifySearchResultChanged(browser, query, resultCount, params)
+  /**
+   * Runs [query] and tells [browser] how many items [onGetSearchResult] will serve for it: the
+   * search's own hits, or the single tile standing in for them — a controller told zero never asks
+   * for items. Offline keeps the query for [reannounceOfflineSearches]; every other outcome drops
+   * it, so one controller holds at most its latest unanswered search.
+   */
+  private suspend fun announceSearch(
+    session: MediaLibraryService.MediaLibrarySession,
+    browser: MediaSession.ControllerInfo,
+    browserManager: BrowserManager,
+    query: String,
+    params: MediaLibraryService.LibraryParams?,
+  ) {
+    if (
+      !player.networkMonitor.isOnline.value && browserManager.config.androidControllerOfflineError
+    ) {
+      Timber.w("Network offline - announcing the offline tile for query: $query")
+      offlineSearches.record(browser, query, params)
+      session.notifySearchResultChanged(browser, query, 1, params)
+      return
+    }
+    offlineSearches.forget(browser)
+
+    try {
+      // Caches the result set under the query, which onGetSearchResult reads back through
+      // getCachedSearchResults.
+      val searchResults = browserManager.search(query)
+      failedSearch.clear()
+      val resultCount = announcedSearchCount(searchResults.normalizedSections)
+
+      Timber.d("Search announced $resultCount item(s) for query '$query'")
+
+      session.notifySearchResultChanged(browser, query, resultCount, params)
+    } catch (e: Exception) {
+      if (e is CancellationException && e !is TimeoutCancellationException) throw e
+      Timber.e(e, "Error during search for query: $query")
+      // A failed search announces its one item — the browse-error tile onGetSearchResult
+      // serves — rather than an ofError the browse list renders as nothing at all. Without
+      // the slot the failure is indistinguishable from an empty page by the time that call
+      // arrives, and a server error would read as the app's "no results" copy.
+      failedSearch.record(query, navigationErrorFor(e))
+      session.notifySearchResultChanged(browser, query, 1, params)
+    }
+  }
 
-        LibraryResult.ofVoid()
-      } catch (e: Exception) {
-        if (e is CancellationException && e !is TimeoutCancellationException) throw e
-        Timber.e(e, "Error during search for query: $query")
-        LibraryResult.ofError(SessionError.ERROR_UNKNOWN)
+  /**
+   * Re-runs every search that was served the offline tile, now that the network is back. Announcing
+   * what the fresh search found — rather than a bare "one item" — keeps the announced count equal
+   * to what [onGetSearchResult] will then serve from the cache this fills.
+   */
+  private suspend fun reannounceOfflineSearches() {
+    val pending = offlineSearches.drain()
+    if (pending.isEmpty()) return
+    val session = mediaLibrarySession ?: return
+    val browserManager =
+      try {
+        player.awaitBrowser().browserManager
+      } catch (e: TimeoutCancellationException) {
+        Timber.w("Timed out waiting for browser - offline searches not re-announced")
+        return
       }
+
+    pending.forEach { search ->
+      Timber.d("Network back - re-running search: ${search.query}")
+      announceSearch(session, search.browser, browserManager, search.query, search.params)
     }
   }
 
@@ -674,26 +759,57 @@ class MediaSessionCallback(private val player: Player) :
         )
       }
 
-      try {
-        // Get cached search results from BrowserManager
-        browserManager.getCachedSearchResults(query)?.let { tracks ->
-          // Convert to MediaItems
-          val searchAuthority =
-            com.audiobrowser.util.ArtworkUris.authorityFor(player.context.packageName)
-          val mediaItems =
-            tracks.map { track ->
-              Timber.d("Search result: ${track.title} (url=${track.url}, src=${track.src})")
-              TrackFactory.toBrowseMediaItem(track, player.browseArtworkRegistry, searchAuthority)
-            }
+      // Checked before the failure slot, as in onGetChildren: a search that never reached the
+      // network is not a server failure, and connectivity returning is what fixes it.
+      if (
+        !player.networkMonitor.isOnline.value && browserManager.config.androidControllerOfflineError
+      ) {
+        Timber.w("Network offline - returning the offline tile for query: $query")
+        sendBrowseError(session, browser, offline = true)
+        return@future LibraryResult.ofItemList(
+          ImmutableList.of(
+            createOfflineMediaItem(
+              audioBrowser.resolveFormattedError(
+                offlineError(),
+                BrowserPathHelper.createSearchPath(query),
+              )
+            )
+          ),
+          params,
+        )
+      }
 
-          val paginatedItems = mediaItems.paginate(page, pageSize)
-          Timber.d("Returning ${paginatedItems.size} search results")
-          LibraryResult.ofItemList(ImmutableList.copyOf(paginatedItems), params)
-        }
-          ?: run {
-            Timber.w("No cached search results for query: $query")
-            LibraryResult.ofItemList(ImmutableList.of(), params)
+      // The search itself failed, so this is a failure, not an empty page — same tile and same
+      // SessionError the browse catch sends, worded for the error its exception mapped to.
+      failedSearch.errorFor(query)?.let { error ->
+        sendBrowseError(session, browser, offline = false)
+        return@future LibraryResult.ofItemList(
+          ImmutableList.of(
+            createBrowseErrorMediaItem(
+              audioBrowser.resolveFormattedError(error, BrowserPathHelper.createSearchPath(query))
+            )
+          ),
+          params,
+        )
+      }
+
+      try {
+        val tracks = browserManager.getCachedSearchResults(query)
+        if (tracks == null) Timber.w("No cached search results for query: $query")
+        // A search with nothing servable — no hits, every hit disabled, or nothing cached under
+        // this query — serves the app's copy for the search path instead of the car's bare "No
+        // items" (ADR 0001). Something must always come back: onSearch announced one item.
+        val mediaItems =
+          browseLevelItems(toFlatMediaItems(tracks?.toList().orEmpty())) {
+            audioBrowser.resolveFormattedError(
+              emptyContentError(),
+              BrowserPathHelper.createSearchPath(query),
+            )
           }
+
+        val paginatedItems = mediaItems.paginate(page, pageSize)
+        Timber.d("Returning ${paginatedItems.size} search results")
+        LibraryResult.ofItemList(ImmutableList.copyOf(paginatedItems), params)
       } catch (e: Exception) {
         if (e is CancellationException && e !is TimeoutCancellationException) throw e
         Timber.e(e, "Error getting search results for query: $query")
@@ -722,8 +838,9 @@ class MediaSessionCallback(private val player: Player) :
     return scope.future {
       val audioBrowser = player.awaitBrowser()
 
-      // Helper: returns the current player state unchanged so Media3 doesn't modify playback.
-      // ExoPlayer is main-thread confined; this future runs on IO, so hop to Main for the reads.
+      // The "leave playback alone" answer for handleTrackLoad: returning the current state
+      // unchanged is how Media3 is told to do nothing. ExoPlayer is main-thread confined and this
+      // future runs on IO, so the reads hop to Main.
       suspend fun currentPlayerState(): MediaSession.MediaItemsWithStartPosition =
         withContext(Dispatchers.Main) {
           val currentItems = player.tracks.map { TrackFactory.toMedia3(it) }
@@ -733,26 +850,26 @@ class MediaSessionCallback(private val player: Player) :
 
       val browserManager = audioBrowser.browserManager
 
-      // A single tapped item resolves to the contextual url of the list it was
+      // A single tapped item resolves to the contextual path of the list it was
       // tapped in: directly for contextual mediaIds, via the track cache for
-      // stable-id mediaIds (see BrowserManager.contextualUrlFor). A search
+      // stable-id mediaIds (see BrowserManager.contextualPathFor). A search
       // selection is not a list tap — its queue comes from the search results
       // (resolveMediaItemsForPlayback), never from a browsed container.
-      val singleContextualUrl =
+      val singleContextualPath =
         mediaItems
           .singleOrNull()
           ?.takeIf { it.requestMetadata.searchQuery == null }
-          ?.let { browserManager.contextualUrlFor(it.mediaId) }
+          ?.let { browserManager.contextualPathFor(it.mediaId) }
 
-      // Check if this is a single item from the current queue source
-      if (singleContextualUrl != null) {
-        val parentPath = BrowserPathHelper.stripTrackId(singleContextualUrl)
-        val trackId = BrowserPathHelper.extractTrackId(singleContextualUrl)
+      if (singleContextualPath != null) {
+        val parentPath = BrowserPathHelper.stripTrackId(singleContextualPath)
+        val trackId = BrowserPathHelper.extractTrackId(singleContextualPath)
 
-        // Check if queue already came from this parent path - just skip to the track
+        // A tap inside the queue's own source list skips rather than rebuilds (exact path first,
+        // identity for index-less paths — see indexOfTappedTrack).
         if (trackId != null && parentPath == player.queueSourcePath) {
           val queueTracks = withContext(Dispatchers.Main) { player.tracks }
-          val index = queueTracks.indexOfFirst { it.src == trackId }
+          val index = queueTracks.indexOfTappedTrack(singleContextualPath, trackId)
           if (index >= 0) {
             Timber.d("Queue already from $parentPath, skipping to index $index")
             val track = queueTracks[index]
@@ -763,7 +880,6 @@ class MediaSessionCallback(private val player: Player) :
               index.toDouble(),
               ::currentPlayerState,
             ) {
-              // Return the existing queue items with the new start index
               val existingItems = queueTracks.map { TrackFactory.toMedia3(it) }
               MediaSession.MediaItemsWithStartPosition(existingItems, index, startPositionMs)
             }
@@ -784,9 +900,10 @@ class MediaSessionCallback(private val player: Player) :
         result.startIndex.toDouble(),
         ::currentPlayerState,
       ) {
-        // If this was a contextual URL expansion, track the source path (only for default behavior)
-        if (singleContextualUrl != null) {
-          val parentPath = BrowserPathHelper.stripTrackId(singleContextualUrl)
+        // Inside handleTrackLoad's default branch: a consumer that handles the load itself owns
+        // the queue, so queueSourcePath must not claim this path on its behalf.
+        if (singleContextualPath != null) {
+          val parentPath = BrowserPathHelper.stripTrackId(singleContextualPath)
           withContext(Dispatchers.Main) { player.queueSourcePath = parentPath }
         }
         result
@@ -802,8 +919,6 @@ class MediaSessionCallback(private val player: Player) :
    * using the browse callback. This enables seamless resumption after app restart with the same
    * player settings (repeat mode, shuffle, playback speed).
    *
-   * @param mediaSession The media session
-   * @param controller The controller requesting resumption
    * @param isForPlayback True if this should start playback; false if just gathering info for the
    *   boot-time resumption notification (no network; local metadata only).
    * @see https://developer.android.com/media/media3/session/background-playback#resumption
@@ -825,9 +940,17 @@ class MediaSessionCallback(private val player: Player) :
             throw IllegalStateException("No playback state to resume")
           }
 
-      // isForPlayback == false is the device-boot-time notification case: network may be
-      // unavailable and we must not start playback. Return just the locally-stored track with its
-      // already-local metadata; skip the settings restore and network queue expansion below.
+      // The persisted track can carry `disabled` — it became unavailable after
+      // it was saved. A disabled track never plays, resumption included
+      // (Track.disabled); failing the future refuses without touching the
+      // player.
+      if (state.track.disabled == true) {
+        Timber.w("Refusing resumption of disabled track: ${state.track.title}")
+        throw IllegalStateException("Persisted track is disabled")
+      }
+
+      // Info-gathering returns before the settings restore and the queue expansion below: both
+      // touch the live player or the network, and neither is permitted here.
       if (!isForPlayback) {
         Timber.d("Info-gathering resumption (boot-time); returning stored track without expansion")
         return@future MediaSession.MediaItemsWithStartPosition(
@@ -840,14 +963,12 @@ class MediaSessionCallback(private val player: Player) :
       // restore() sets player properties which must happen on main thread
       withContext(Dispatchers.Main) { player.playbackStateStore.restore() }
 
-      val url = state.track.url
-      Timber.d("Resuming from url=$url, positionMs=${state.positionMs}")
+      val path = state.track.path
+      Timber.d("Resuming from path=$path, positionMs=${state.positionMs}")
 
-      // Wait for browser to be available (JS needs to have configured it)
       val browserManager = player.awaitBrowser().browserManager
 
-      // Try to expand the URL into a full queue
-      val expanded = url?.let { browserManager.expandQueueFromContextualUrl(it) }
+      val expanded = path?.let { browserManager.expandQueueFromContextualPath(it) }
 
       if (expanded != null) {
         val (tracks, selectedIndex) = expanded
@@ -855,9 +976,8 @@ class MediaSessionCallback(private val player: Player) :
           "Restored ${tracks.size} tracks, starting at index $selectedIndex at ${state.positionMs}ms"
         )
 
-        // Track the source path if this was a contextual URL expansion
-        if (BrowserPathHelper.isContextual(url)) {
-          val parentPath = BrowserPathHelper.stripTrackId(url)
+        if (BrowserPathHelper.isContextual(path)) {
+          val parentPath = BrowserPathHelper.stripTrackId(path)
           withContext(Dispatchers.Main) { player.queueSourcePath = parentPath }
         }
 
@@ -867,7 +987,6 @@ class MediaSessionCallback(private val player: Player) :
           state.positionMs,
         )
       } else {
-        // Fallback: play just the stored track
         Timber.d("Queue expansion failed, using stored track: ${state.track.title}")
         MediaSession.MediaItemsWithStartPosition(
           ImmutableList.of(TrackFactory.toMedia3(state.track)),
@@ -878,3 +997,163 @@ class MediaSessionCallback(private val player: Player) :
     }
   }
 }
+
+/**
+ * Builds a non-browsable, non-playable [MediaItem] used to surface an error inside an Android Auto
+ * / AAOS browse list. Rendered as a greyed-out, non-interactive tile, which is the only
+ * side-effect-free way to communicate a browse failure to legacy controllers (Media3 drops
+ * [LibraryResult.ofError] on the legacy browse bridge, leaving an empty "No items" screen).
+ *
+ * Tiles are the only in-browse error signal that exists. Verified on a head unit (2026-06): the
+ * Android Auto browse list renders no error text for a transient [SessionError], for sticky
+ * non-fatal replication, or for fatal replication (setLibraryErrorReplicationMode). Fatal
+ * replication does surface the message on the playback screen, but at the cost of presenting the
+ * session as STATE_ERROR with no actions, hiding the now-playing item and transport controls.
+ */
+internal fun createErrorMediaItem(mediaId: String, title: String, subtitle: String): MediaItem =
+  MediaItem.Builder()
+    .setMediaId(mediaId)
+    .setMediaMetadata(
+      MediaMetadata.Builder()
+        .setTitle(title)
+        .setSubtitle(subtitle)
+        // Android Auto ignores these flags and drills into a tapped tile anyway; onGetChildren
+        // returns an empty list for the sentinel paths, so it dead-ends at "No Items" rather
+        // than stacking error pages.
+        .setIsBrowsable(false)
+        .setIsPlayable(false)
+        .build()
+    )
+    .build()
+
+/**
+ * The formatted form every tile is built from: the message renders as the subtitle, with newlines
+ * collapsed to spaces — list rows are single-line.
+ */
+private fun createErrorMediaItem(mediaId: String, formatted: FormattedNavigationError): MediaItem =
+  createErrorMediaItem(
+    mediaId = mediaId,
+    title = formatted.title,
+    subtitle = formatted.message?.replace('\n', ' ') ?: "",
+  )
+
+/**
+ * Builds the empty tile from the app's formatted `empty-content` copy for the page's path, so an
+ * empty Favorites tab and an empty search can be worded apart (ADR 0001). Same shape as the error
+ * tiles — non-browsable, non-playable — and deliberately NOT accompanied by a SessionError: an
+ * empty page is a successful resolve.
+ */
+internal fun createEmptyMediaItem(formatted: FormattedNavigationError): MediaItem =
+  createErrorMediaItem(BrowserPathHelper.EMPTY_PATH, formatted)
+
+/**
+ * Builds the offline tile from the app's formatted `network-error` copy for the path being served,
+ * so one browse list never mixes the app's locale with the device's.
+ */
+internal fun createOfflineMediaItem(formatted: FormattedNavigationError): MediaItem =
+  createErrorMediaItem(BrowserPathHelper.OFFLINE_PATH, formatted)
+
+/**
+ * Builds the tile a failed browse or search serves, from the formatted copy for the error the
+ * request's exception mapped to. The true offline case is handled separately by the networkMonitor
+ * guards; anything reaching a catch block is an online-but-failed request (e.g. server down, bad
+ * status), so it must NOT be labelled "no internet connection".
+ */
+internal fun createBrowseErrorMediaItem(formatted: FormattedNavigationError): MediaItem =
+  createErrorMediaItem(BrowserPathHelper.ERROR_PATH, formatted)
+
+/**
+ * What a non-root browse level or a search serves: its own items, or the lone empty tile when it
+ * came back with none. [formatted] is a JS hop, so it runs only when there is nothing to show. The
+ * root is not served through here — an empty tab list is a different condition.
+ */
+internal suspend fun browseLevelItems(
+  children: List<MediaItem>,
+  formatted: suspend () -> FormattedNavigationError,
+): List<MediaItem> = children.ifEmpty { listOf(createEmptyMediaItem(formatted())) }
+
+/** The navigation error an empty page raises: no message of its own, the path carries the copy. */
+internal fun emptyContentError(): NavigationError =
+  NavigationError(NavigationErrorType.EMPTY_CONTENT, "", null, null)
+
+/** The navigation error a browse or search served while offline raises. */
+internal fun offlineError(): NavigationError =
+  NavigationError(NavigationErrorType.NETWORK_ERROR, "", null, null)
+
+/** The failure a re-read of the browse-error tile stands on, its own exception long gone. */
+internal fun browseFailureError(): NavigationError =
+  NavigationError(NavigationErrorType.UNKNOWN_ERROR, "", null, null)
+
+/**
+ * The item count [MediaSessionCallback.onSearch] announces for a search that ran. Disabled tracks
+ * hide on Android Auto (Track.disabled), so they never inflate it; and a search with nothing
+ * servable announces one — the empty tile [MediaSessionCallback.onGetSearchResult] serves in their
+ * place — because a controller told zero never asks for items. The gate and failure branches
+ * announce their own single tile by the same rule.
+ */
+internal fun announcedSearchCount(sections: List<Section>?): Int =
+  (sections?.sumOf { section -> section.children.count { it.disabled != true } } ?: 0)
+    .coerceAtLeast(1)
+
+/**
+ * The search each controller was last served the offline tile for. Media3 addresses a search result
+ * by (controller, query) and keeps no record of its own, and a search has no subscription the way a
+ * browse level does — so without this the offline tile stays on screen until the user searches
+ * again. Only an offline-served query is kept: a search that ran found what it found, and one that
+ * failed did so with a network.
+ *
+ * Written from the callback's IO scope and read from the connectivity observer, so every accessor
+ * is synchronized.
+ */
+internal class OfflineSearchRegistry {
+  private val searches = mutableMapOf<MediaSession.ControllerInfo, OfflineSearch>()
+
+  @Synchronized
+  fun record(
+    browser: MediaSession.ControllerInfo,
+    query: String,
+    params: MediaLibraryService.LibraryParams?,
+  ) {
+    searches[browser] = OfflineSearch(browser, query, params)
+  }
+
+  @Synchronized
+  fun forget(browser: MediaSession.ControllerInfo) {
+    searches.remove(browser)
+  }
+
+  /** Takes every record: a re-run that finds the network gone again records its own. */
+  @Synchronized
+  fun drain(): List<OfflineSearch> = searches.values.toList().also { searches.clear() }
+}
+
+/** One controller's unanswered search: everything announcing it again needs. */
+internal data class OfflineSearch(
+  val browser: MediaSession.ControllerInfo,
+  val query: String,
+  val params: MediaLibraryService.LibraryParams?,
+)
+
+/**
+ * Remembers the query whose search threw, so [MediaSessionCallback.onGetSearchResult] serves the
+ * browse-error tile instead of the empty one — by then the failure is otherwise indistinguishable
+ * from a page that found nothing. Written and read from the callback's IO scope.
+ *
+ * One slot, matching BrowserManager's single-entry result cache: two failures in a row leave only
+ * the later query recorded, so a late fetch of the earlier one serves the empty tile instead of the
+ * error tile. Acceptable while only the most recent search's results are retrievable at all.
+ */
+internal class FailedSearchSlot {
+  @Volatile private var failed: Pair<String, NavigationError>? = null
+
+  fun record(query: String, error: NavigationError) {
+    failed = query to error
+  }
+
+  fun clear() {
+    failed = null
+  }
+
+  /** The error [query] failed with, or null when it is not the query that failed. */
+  fun errorFor(query: String): NavigationError? = failed?.takeIf { it.first == query }?.second
+}