react-native-audio-browser 0.2.0-next.16 → 0.2.0-next.18

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

@@ -11,23 +11,28 @@ 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.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
@@ -45,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 {
@@ -58,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
 
   /**
@@ -69,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)
@@ -85,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 —
@@ -141,25 +114,16 @@ 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(
@@ -170,7 +134,6 @@ class MediaSessionCallback(private val player: Player) :
     forwardJumpInterval: Double,
     backwardJumpInterval: Double,
   ) {
-    // Store as MediaLibrarySession for notifyChildrenChanged support
     this.mediaLibrarySession = mediaSession as? MediaLibraryService.MediaLibrarySession
     commandManager.updateMediaSession(
       mediaSession,
@@ -190,15 +153,26 @@ 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. Report an honest result: a success here makes
-    // the controller flip its heart optimistically, so a no-op (no current
-    // track) must say INVALID_STATE instead of success-then-revert.
+    // 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 applied = player.toggleActiveTrackFavorited()
       Timber.d("Favorite button tapped - toggle applied=$applied")
@@ -241,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
@@ -290,7 +257,6 @@ class MediaSessionCallback(private val player: Player) :
       "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
@@ -317,35 +283,35 @@ 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.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?
-            // Disabled tabs hide (Track.disabled) — filtered before the cap so
-            // an unavailable tab never costs an available one its slot.
+            // 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(
@@ -354,15 +320,19 @@ class MediaSessionCallback(private val player: Player) :
             }
             toFlatMediaItems(tabs.take(4))
           } else {
-            // Resolve the specific path and flatten its sections to MediaItems
-            // (paths are already set to contextual paths). Section styles come
-            // page-folded (`section ?? page`, ADR 0011).
+            // Section styles arrive page-folded (`section ?? page`, ADR 0011).
             val resolvedTrack = browserManager.resolve(parentId)
             val sections =
               resolvedTrack.styleResolvedSections()
                 ?: throw IllegalStateException("Expected browsed ResolvedTrack to have sections")
             browserManager.warnIfGridPageLacksPromise(parentId, sections)
-            toMediaItems(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)
@@ -371,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,
+        )
       }
     }
   }
@@ -393,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.
    *
@@ -462,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) {
@@ -491,19 +501,6 @@ class MediaSessionCallback(private val player: Player) :
         return@future LibraryResult.ofItem(createGateMediaItem(outcome.chrome!!), null)
       }
 
-      if (mediaId == BrowserPathHelper.ROOT_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 path and src). Besides avoiding an HTTP
@@ -578,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.
    */
@@ -593,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")
@@ -614,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()
@@ -636,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()
@@ -659,33 +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)
-        // Count what onGetSearchResult will actually serve: disabled tracks
-        // hide on Android Auto, so they must not inflate the announced count.
-        val resultCount =
-          searchResults.normalizedSections?.sumOf { section ->
-            section.children.count { it.disabled != true }
-          } ?: 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)
     }
   }
 
@@ -723,21 +759,57 @@ class MediaSessionCallback(private val player: Player) :
         )
       }
 
+      // 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,
+        )
+      }
+
+      // 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 {
-        // Get cached search results from BrowserManager
-        browserManager.getCachedSearchResults(query)?.let { tracks ->
-          // Through the shared browse conversion, so search results get the
-          // same artwork routing as browse rows.
-          val mediaItems = toFlatMediaItems(tracks.toList())
-
-          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)
+        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")
@@ -766,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) }
@@ -788,14 +861,12 @@ class MediaSessionCallback(private val player: Player) :
           ?.takeIf { it.requestMetadata.searchQuery == null }
           ?.let { browserManager.contextualPathFor(it.mediaId) }
 
-      // Check if this is a single item from the current queue source
       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
-        // tapped surface (exact path first, identity for index-less paths —
-        // see indexOfTappedTrack)
+        // 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.indexOfTappedTrack(singleContextualPath, trackId)
@@ -809,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)
             }
@@ -830,8 +900,8 @@ class MediaSessionCallback(private val player: Player) :
         result.startIndex.toDouble(),
         ::currentPlayerState,
       ) {
-        // If this was a contextual path expansion, track the source path (only for default
-        // behavior)
+        // 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 }
@@ -849,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
@@ -881,9 +949,8 @@ class MediaSessionCallback(private val player: Player) :
         throw IllegalStateException("Persisted track is disabled")
       }
 
-      // 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.
+      // 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(
@@ -899,10 +966,8 @@ class MediaSessionCallback(private val player: Player) :
       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 path into a full queue
       val expanded = path?.let { browserManager.expandQueueFromContextualPath(it) }
 
       if (expanded != null) {
@@ -911,7 +976,6 @@ 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 path expansion
         if (BrowserPathHelper.isContextual(path)) {
           val parentPath = BrowserPathHelper.stripTrackId(path)
           withContext(Dispatchers.Main) { player.queueSourcePath = parentPath }
@@ -923,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)),
@@ -934,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
+}