react-native-audio-browser 0.2.0-next.9 → 0.2.0

package/android/src/main/java/com/audiobrowser/browser/BrowserManager.kt

@@ -7,13 +7,10 @@ import com.audiobrowser.http.HttpClient
 import com.audiobrowser.http.RequestConfigBuilder
 import com.audiobrowser.util.BrowserPathHelper
 import com.audiobrowser.util.TrackFactory
-import com.audiobrowser.util.artworkOf
 import com.margelo.nitro.audiobrowser.ArtworkRequestConfig
 import com.margelo.nitro.audiobrowser.BrowserSourceCallbackParam
-import com.margelo.nitro.audiobrowser.FavoritesMatchMode
-import com.margelo.nitro.audiobrowser.Func_std__shared_ptr_Promise_std__shared_ptr_Promise_TransformableRequestConfig____
 import com.margelo.nitro.audiobrowser.ImageContext
-import com.margelo.nitro.audiobrowser.MediaReference
+import com.margelo.nitro.audiobrowser.ImageSource
 import com.margelo.nitro.audiobrowser.MediaRequestConfig
 import com.margelo.nitro.audiobrowser.NativeRouteEntry
 import com.margelo.nitro.audiobrowser.RequestConfig
@@ -49,7 +46,6 @@ class BrowserManager {
   private var onPathChanged: ((String) -> Unit)? = null
   private var onContentChanged: ((ResolvedTrack?) -> Unit)? = null
   private var onTabsChanged: ((Array<Track>) -> Unit)? = null
-  private var onArtworkRegistriesCleared: (() -> Unit)? = null
 
   private var path: String = "/"
     set(value) {
@@ -90,64 +86,28 @@ class BrowserManager {
   // Invalidated via invalidateContentCache() when content changes
   private val contentCache = LruCache<String, ResolvedTrack>(20)
 
-  // Cache for the most recent search - the query string and its results stored as one pair, so a
-  // concurrent reader never sees one query matched with another query's results.
-  @Volatile private var lastSearch: Pair<String, Array<Track>>? = null
+  // Cache for search results - keyed by query string
+  private var lastSearchQuery: String? = null
+  private var lastSearchResults: Array<Track>? = null
 
   // Set of favorited track identifiers (src)
   private var favoriteIds = setOf<String>()
 
-  // Favorite match mode, propagated from the player's `favorite` capability.
-  // null = favoriting disabled (no row hearts). Set via setFavoriteMatch.
-  private var favoriteMatch: FavoritesMatchMode? = null
-
   // Navigation tracking to prevent race conditions
   @Volatile private var currentNavigationId = 0
 
   /**
    * Browser configuration containing routes, search, tabs, and request settings. This can be
    * updated dynamically when the configuration changes.
-   *
-   * Setting a new config bumps [layerGeneration] so the cached request/browse resolver layers are
-   * re-resolved on the next request (the resolvers may close over config-derived state).
    */
   var config: BrowserConfig = BrowserConfig()
-    set(value) {
-      field = value
-      layerGeneration += 1
-      // Registered artwork resolutions pin configs (and their JS callback handles)
-      // from the previous configuration — never resolve through them again.
-      artworkResolutions.clear()
-      onArtworkRegistriesCleared?.invoke()
-    }
-
-  // Resolver-layer caching. The request/browse layers may be resolver thunks
-  // (config.requestResolver / config.browseResolver) resolved once per *content generation*:
-  // re-resolved when content is invalidated (clearContentCache, from invalidateAllContent) or when
-  // a new config is set, cached, and merged per request.
-  private var layerGeneration = 0
-  private var resolvedLayerGeneration = -1
-  private var resolvedRequestLayer: TransformableRequestConfig? = null
-  private var resolvedBrowseLayer: TransformableRequestConfig? = null
-
-  /** Test-only accessors for the resolver-layer cache state (see ensureLayersResolved). */
-  internal val layerGenerationForTest: Int
-    get() = layerGeneration
-
-  internal val resolvedLayerGenerationForTest: Int
-    get() = resolvedLayerGeneration
-
-  internal val resolvedRequestLayerForTest: TransformableRequestConfig?
-    get() = resolvedRequestLayer
-
-  internal val resolvedBrowseLayerForTest: TransformableRequestConfig?
-    get() = resolvedBrowseLayer
 
   /**
-   * Maps produced artwork URIs back to (Track, artwork-config kind) so display-time bitmap loading
-   * can re-resolve Track-first. See [ArtworkResolutionRegistry].
+   * Callback to transform artwork URLs for tracks. Takes a track and optional per-route artwork
+   * config, returns ImageSource or null. Injected by AudioBrowser when artwork config is set.
+   * The ImageContext parameter provides size hints for CDN URL generation.
    */
-  val artworkResolutions = ArtworkResolutionRegistry()
+  var artworkUrlResolver: (suspend (Track, ArtworkRequestConfig?, ImageContext?) -> ImageSource?)? = null
 
   /**
    * Sets the favorited track identifiers. Tracks will have their favorited field hydrated based on
@@ -158,14 +118,6 @@ class BrowserManager {
     Timber.d("Set ${favoriteIds.size} favorite IDs")
   }
 
-  /**
-   * Sets the favorite match mode (propagated from the `favorite` capability). null disables
-   * row-heart hydration.
-   */
-  fun setFavoriteMatch(match: FavoritesMatchMode?) {
-    favoriteMatch = match
-  }
-
   /**
    * Updates the favorite state for a single track identifier. Called when the heart button is
    * tapped in media controllers.
@@ -181,30 +133,40 @@ class BrowserManager {
   }
 
   /**
-   * Hydrates the favorited field on a track based on the favoriteIds set. No-op unless favoriting
-   * is enabled (the `favorite` capability). Only playable (src-bearing) tracks are favoritable; the
-   * flag is set to true OR false so non-favorited tracks still show an (empty) heart. Doesn't
-   * overwrite API-provided values.
+   * Hydrates the favorited field on a track based on the favoriteIds set. Only hydrates if
+   * track.favorited is null (doesn't overwrite API-provided values). Only tracks with src can be
+   * favorited.
    */
   private fun hydrateFavorite(track: Track): Track {
-    val match = favoriteMatch ?: return track
     // Don't overwrite API-provided favorites
     if (track.favorited != null) return track
-    // Only playable tracks are favoritable
-    val src = track.src ?: return track
-
-    val isFavorited = isFavorite(src, match)
-
-    return track.copy(favorited = isFavorited)
+    if (favoriteIds.isEmpty()) return track
+
+    val isFavorited = track.src?.let { favoriteIds.contains(it) } ?: false
+    if (!isFavorited) return track
+
+    return Track(
+      url = track.url,
+      src = track.src,
+      artwork = track.artwork,
+      artworkSource = track.artworkSource,
+      artworkCarPlayTinted = track.artworkCarPlayTinted,
+      title = track.title,
+      subtitle = track.subtitle,
+      artist = track.artist,
+      album = track.album,
+      description = track.description,
+      genre = track.genre,
+      duration = track.duration,
+      style = track.style,
+      childrenStyle = track.childrenStyle,
+      favorited = true,
+      groupTitle = track.groupTitle,
+      live = track.live,
+      imageRow = track.imageRow,
+    )
   }
 
-  /** Whether [src] is favorited under the given match mode. */
-  private fun isFavorite(src: String, match: FavoritesMatchMode): Boolean =
-    when (match) {
-      FavoritesMatchMode.EXACT -> favoriteIds.contains(src)
-      FavoritesMatchMode.PARTIAL -> favoriteIds.any { BrowserPathHelper.containsSegment(src, it) }
-    }
-
   /** Hydrates favorites on all children of a ResolvedTrack. */
   private fun hydrateChildren(resolvedTrack: ResolvedTrack): ResolvedTrack {
     val children = resolvedTrack.children ?: return resolvedTrack
@@ -212,29 +174,20 @@ class BrowserManager {
     return resolvedTrack.copy(children = hydratedChildren)
   }
 
-  /** Cache a track by id, url, and src for O(1) lookup from any mediaId form. */
+  /** Cache a track by both url and src for O(1) lookup from either key. */
   private fun cacheTrack(track: Track) {
-    track.id?.takeUnless { it.isBlank() }?.let { trackCache.put(it, track) }
     track.url?.let { trackCache.put(it, track) }
     track.src?.let { trackCache.put(it, track) }
   }
 
   private fun cacheChildren(resolvedTrack: ResolvedTrack) {
-    resolvedTrack.children?.forEach { track ->
-      cacheTrack(track)
-      // Image-row items are playable surfaces of their own: cache them (with
-      // their stamped contextual urls) so an id-keyed mediaId from an
-      // expanded Android Auto tile can find its way back to queue expansion.
-      track.imageRow?.forEach { item ->
-        cacheTrack(with(TrackFactory) { item.toTrack(groupTitle = track.title) })
-      }
-    }
+    resolvedTrack.children?.forEach { track -> cacheTrack(track) }
   }
 
   /**
-   * Get a cached Track by mediaId (stable id, url, or src), or null if not cached. Used by Media3
-   * to rehydrate MediaItem shells with full track metadata. Re-hydrates favorites in case
-   * setFavoriteStates was called after caching.
+   * Get a cached Track by mediaId (url or src), or null if not cached. Used by Media3 to rehydrate
+   * MediaItem shells with full track metadata. Re-hydrates favorites in case setFavoriteStates was
+   * called after caching.
    */
   fun getCachedTrack(mediaId: String): Track? {
     // Try direct lookup first (matches url or src)
@@ -259,76 +212,27 @@ class BrowserManager {
   }
 
   /**
-   * Resolves a tapped mediaId to the contextual url to expand a queue from, or null when there is
-   * none. A contextual mediaId is its own; a stable-id mediaId (see TrackFactory.buildMediaItem)
-   * resolves through the track cache to the contextual url of the container it was most recently
-   * browsed in — a legacy car controller round-trips only the mediaId, so the cache is what
-   * remembers which list the row came from.
-   */
-  fun contextualUrlFor(mediaId: String): String? {
-    if (BrowserPathHelper.isContextual(mediaId)) return mediaId
-    return getCachedTrack(mediaId)?.url?.takeIf { BrowserPathHelper.isContextual(it) }
-  }
-
-  /**
-   * Resolves a single Media3 MediaItem to a Track. Prefers the track cache (keyed by id, url, and
-   * src).
+   * Resolves multiple media IDs from cache. Throws IllegalStateException if any mediaId is not
+   * found in cache.
    *
-   * A cache miss is legitimately reachable: a controller can replay a mediaId this process never
-   * browsed — e.g. a search-result track after process death. When the mediaId is a playable URL,
-   * or the item's requestMetadata carries the playable uri (stamped by TrackFactory for stable-id
-   * mediaIds, and round-tripped by Media3 controllers), fall back to a minimal track built from the
-   * item's own metadata instead of failing playback.
-   *
-   * @throws IllegalStateException if the mediaId is not cached and no playable URL is available
+   * @param mediaIds The media IDs to resolve
+   * @return List of Track objects
    */
-  private fun resolveMediaItemToTrack(mediaItem: MediaItem): Track {
-    val mediaId = mediaItem.mediaId
-
-    getCachedTrack(mediaId)?.let { cachedTrack ->
-      Timber.d("Resolved mediaId='$mediaId' from cache: '${cachedTrack.title}'")
-      return cachedTrack
-    }
+  fun resolveMediaIdsFromCache(mediaIds: List<String>): List<Track> {
+    return mediaIds.map { mediaId ->
+      Timber.d("=== Resolving from cache: mediaId='$mediaId' ===")
 
-    val fallbackSrc =
-      if (mediaId.startsWith("http://") || mediaId.startsWith("https://")) {
-        mediaId
-      } else {
-        mediaItem.requestMetadata.mediaUri?.toString()
+      getCachedTrack(mediaId)?.let { cachedTrack ->
+        Timber.d("→ Found cached Track: '${cachedTrack.title}'")
+        return@map cachedTrack
       }
-    if (fallbackSrc != null) {
-      Timber.w("Cache MISS for mediaId='$mediaId' - building minimal track from media item")
-      val metadata = mediaItem.mediaMetadata
-      return hydrateFavorite(
-        Track(
-          // A mediaId distinct from the playable uri is the track's stable id —
-          // keep it so the item's identity (car now-playing row match) survives.
-          id = mediaId.takeIf { it != fallbackSrc },
-          url = null,
-          src = fallbackSrc,
-          artwork = artworkOf(metadata.artworkUri?.toString()),
-          artworkSource = null,
-          request = null,
-          artworkCarPlayTinted = null,
-          title = metadata.title?.toString() ?: mediaId,
-          subtitle = metadata.artist?.toString(),
-          artist = null,
-          albumUrl = null,
-          album = metadata.albumTitle?.toString(),
-          description = metadata.description?.toString(),
-          genre = metadata.genre?.toString(),
-          duration = null,
-          style = null,
-          childrenStyle = null,
-          favorited = null,
-          groupTitle = null,
-          live = null,
-          imageRow = null,
-        )
+
+      // Cache miss - this indicates a bug in our caching system
+      Timber.e("→ Cache MISS for mediaId='$mediaId' - this should not happen")
+      throw IllegalStateException(
+        "MediaItem not found in cache: $mediaId. This indicates a bug in the caching system."
       )
     }
-
-    throw IllegalStateException("MediaItem not found in cache: $mediaId")
   }
 
   /**
@@ -345,7 +249,7 @@ class BrowserManager {
    * @param startIndex Index of the item to start playing
    * @param startPositionMs Position within the start item to begin playback
    * @return MediaSession.MediaItemsWithStartPosition ready for Media3
-   * @throws IllegalStateException if a mediaId is neither cached nor a playable URL
+   * @throws IllegalStateException if any mediaId is not found in cache
    */
   suspend fun resolveMediaItemsForPlayback(
     mediaItems: List<MediaItem>,
@@ -366,13 +270,10 @@ class BrowserManager {
         val searchTracks = searchResults.children
 
         if (searchTracks != null && searchTracks.isNotEmpty()) {
-          // Find the selected track in search results (mediaId is the stable id
-          // when the track has one, else url/src — see TrackFactory)
+          // Find the selected track in search results
           val mediaId = mediaItem.mediaId
           val selectedIndex =
-            searchTracks.indexOfFirst { track ->
-              track.id == mediaId || track.url == mediaId || track.src == mediaId
-            }
+            searchTracks.indexOfFirst { track -> track.url == mediaId || track.src == mediaId }
 
           if (selectedIndex >= 0) {
             Timber.d(
@@ -396,14 +297,11 @@ class BrowserManager {
       }
 
       val mediaId = mediaItems[0].mediaId
-      // A failed search match falls through to plain resolution, never to browse
-      // expansion — the user asked for that one result, not a browsed list.
-      val contextualUrl = if (searchQuery == null) contextualUrlFor(mediaId) else null
 
-      if (contextualUrl != null) {
-        Timber.d("Attempting queue expansion for mediaId='$mediaId' via '$contextualUrl'")
+      if (BrowserPathHelper.isContextual(mediaId)) {
+        Timber.d("Attempting queue expansion for mediaId='$mediaId'")
 
-        val expanded = expandQueueFromContextualUrl(contextualUrl)
+        val expanded = expandQueueFromContextualUrl(mediaId)
 
         if (expanded != null) {
           val (tracks, selectedIndex) = expanded
@@ -420,11 +318,12 @@ class BrowserManager {
       }
     }
 
-    // No expansion - resolve from cache (with a minimal-track fallback for replayed mediaIds)
-    val resolvedTracks = mediaItems.map { resolveMediaItemToTrack(it) }
+    // No expansion - resolve from cache
+    val mediaIds = mediaItems.map { it.mediaId }
+    val cachedTracks = resolveMediaIdsFromCache(mediaIds)
 
     // Convert to Media3 MediaItems
-    val resolvedMediaItems = resolvedTracks.map { track -> TrackFactory.toMedia3(track) }
+    val resolvedMediaItems = cachedTracks.map { track -> TrackFactory.toMedia3(track) }
 
     return MediaSession.MediaItemsWithStartPosition(resolvedMediaItems, startIndex, startPositionMs)
   }
@@ -456,11 +355,6 @@ class BrowserManager {
     if (useCache) {
       contentCache.get(normalizedPath)?.let { cached ->
         Timber.d("Content cache HIT for path='$normalizedPath'")
-        // Re-key the track cache even on a hit: an id-keyed lookup (stable-id
-        // mediaId → contextual url, see contextualUrlFor) must reflect the
-        // most recently *browsed* container, which a cached re-display
-        // otherwise wouldn't re-register.
-        cacheChildren(cached)
         // Re-hydrate favorites in case they changed since caching
         return hydrateChildren(cached)
       }
@@ -493,37 +387,35 @@ class BrowserManager {
     Timber.d("Invalidated content cache for path='$path'")
   }
 
-  /** Clears all cached content. */
+  /** Clears all cached content. Used when artwork resolver is wired up to force re-fetch. */
   fun clearContentCache() {
     contentCache.evictAll()
-    // Bump the layer generation so request/browse resolver thunks are re-resolved on the next
-    // request (invalidateAllContent → clearContentCache is the documented re-resolve trigger).
-    layerGeneration += 1
-    // Invalidated content's artwork resolutions go with it (same staleness rule as the
-    // config setter).
-    artworkResolutions.clear()
-    onArtworkRegistriesCleared?.invoke()
     Timber.d("Cleared all content cache")
   }
 
   private suspend fun resolveUncached(path: String): ResolvedTrack {
-    // Match an explicit route (or the '*' default). With no match, fall back to
-    // the implicit default: fetch the path via the request + browse config.
-    val match = config.routes?.let { findBestRouteMatch(path, it) }
-
-    val resolvedTrack: ResolvedTrack
-    val effectiveArtworkConfig: ArtworkRequestConfig?
-    if (match != null) {
-      val (routeEntry, routeParams) = match
-      Timber.d("Matched route: ${routeEntry.path} with params: $routeParams")
-      resolvedTrack = resolveRouteEntry(routeEntry, path, routeParams)
-      effectiveArtworkConfig = routeEntry.artwork ?: config.artwork
-    } else {
-      Timber.d("No route matched for path: $path — using implicit default")
-      resolvedTrack = executeApiRequest(null, path, mapOf("path" to path))
-      effectiveArtworkConfig = config.artwork
+    val routes = config.routes
+    if (routes.isNullOrEmpty()) {
+      Timber.e("No routes configured for path: $path")
+      throw ContentNotFoundException(path)
     }
 
+    // Find best matching route
+    val (routeEntry, routeParams) =
+      findBestRouteMatch(path, routes)
+        ?: run {
+          Timber.e("No route matched for path: $path")
+          throw ContentNotFoundException(path)
+        }
+
+    Timber.d("Matched route: ${routeEntry.path} with params: $routeParams")
+
+    // Resolve the track from the route
+    val resolvedTrack = resolveRouteEntry(routeEntry, path, routeParams)
+
+    // Get effective artwork config: per-route overrides global
+    val effectiveArtworkConfig = routeEntry.artwork ?: config.artwork
+
     // Transform children: generate contextual URLs and transform artwork URLs
     val transformedChildren =
       resolvedTrack.children?.let { children ->
@@ -531,11 +423,8 @@ class BrowserManager {
           children
             .mapIndexed { index, track ->
               async {
-                // Validate that track has stable identifier. A track carrying an
-                // imageRow is exempt: a url-less row is a pure preview — never
-                // selected, navigated to, or cached (its items carry their own
-                // identity; on Android Auto it expands into them).
-                if (track.imageRow.isNullOrEmpty()) validateTrack(track, "Child track")
+                // Validate that track has stable identifier
+                validateTrack(track, "Child track")
 
                 var transformedTrack = track
 
@@ -557,35 +446,22 @@ class BrowserManager {
                   )
                 }
 
-                // Playable image-row items get contextual URLs like any list
-                // row, so a tile tap expands into its section's queue instead
-                // of a queue of one (ADR 0006).
-                transformedTrack.imageRow?.let { items ->
+                // Transform artwork URL if resolver is configured
+                // At browse-time, we don't have display size info
+                val resolver = artworkUrlResolver
+                if (resolver != null) {
+                  val browseContext = ImageContext(null, null)
                   transformedTrack =
-                    transformedTrack.copy(
-                      imageRow =
-                        items
-                          .map { item ->
-                            if (item.url == null && item.src != null) {
-                              item.copy(url = BrowserPathHelper.build(path, item.src))
-                            } else {
-                              item
-                            }
-                          }
-                          .toTypedArray()
+                    transformArtworkUrl(
+                      transformedTrack,
+                      effectiveArtworkConfig,
+                      resolver,
+                      path,
+                      index,
+                      browseContext,
                     )
                 }
 
-                // Transform artwork URL. At browse-time there is no display size info.
-                transformedTrack =
-                  transformArtworkUrl(
-                    transformedTrack,
-                    effectiveArtworkConfig,
-                    path,
-                    index,
-                    ImageContext(null, null),
-                  )
-
                 transformedTrack
               }
             }
@@ -602,7 +478,7 @@ class BrowserManager {
   }
 
   /**
-   * Transforms a track's artwork via [resolveArtworkUrl]. Populates artworkSource with the
+   * Transforms a track's artwork using the configured resolver. Populates artworkSource with the
    * transformed ImageSource, keeping artwork unchanged. Handles all edge cases: undefined returns,
    * errors, missing artwork.
    *
@@ -611,6 +487,7 @@ class BrowserManager {
   private suspend fun transformArtworkUrl(
     track: Track,
     artworkConfig: ArtworkRequestConfig?,
+    resolver: suspend (Track, ArtworkRequestConfig?, ImageContext?) -> ImageSource?,
     path: String,
     index: Int,
     imageContext: ImageContext? = null,
@@ -621,7 +498,7 @@ class BrowserManager {
     }
 
     return try {
-      val imageSource = resolveArtworkUrl(track, artworkConfig, imageContext)
+      val imageSource = resolver(track, artworkConfig, imageContext)
 
       when {
         // resolve returned null → no artwork source
@@ -634,15 +511,6 @@ class BrowserManager {
         // resolve returned ImageSource → set artworkSource
         else -> {
           Timber.d("[$path] Child[$index] '${track.title}': artworkSource set: ${imageSource.uri}")
-          // Remember how this URI was produced so display-time loading (which only
-          // gets a URI from Media3) can re-resolve Track-first with a size hint.
-          // Register the per-route config only when it isn't the global fallback,
-          // so display-time resolution reads the *current* config.artwork.
-          artworkResolutions.register(
-            imageSource.uri,
-            track,
-            artworkConfig?.takeIf { it !== config.artwork },
-          )
           track.copy(artworkSource = imageSource)
         }
       }
@@ -681,20 +549,8 @@ class BrowserManager {
         return null
       }
 
-      // Queue scope is the tapped section, not the whole page (ADR 0006). An
-      // id that no longer appears on the page aborts the expansion — the
-      // caller falls back to the stored single track; silently queueing the
-      // changed list would resume the wrong station.
-      val sectionTracks =
-        when (val section = SectionScope.section(children.toList(), trackId)) {
-          is SectionScope.Section.ImageRow ->
-            with(TrackFactory) { section.items.map { it.toTrack(groupTitle = null) } }
-          is SectionScope.Section.Run -> section.tracks
-          null -> return null
-        }
-
       // Filter to only playable tracks (tracks with src)
-      val playableTracks = sectionTracks.filter { track -> track.src != null }
+      val playableTracks = children.filter { track -> track.src != null }
 
       if (playableTracks.isEmpty()) {
         Timber.w("Parent has no playable tracks, cannot expand queue")
@@ -786,9 +642,8 @@ class BrowserManager {
    * @return Array of Track results, or null if not found
    */
   fun getCachedSearchResults(query: String): Array<Track>? {
-    val (cachedQuery, cachedResults) = lastSearch ?: return null
-    if (query != cachedQuery) return null
-    return cachedResults.map { hydrateFavorite(it) }.toTypedArray()
+    if (query != lastSearchQuery) return null
+    return lastSearchResults?.map { hydrateFavorite(it) }?.toTypedArray()
   }
 
   /**
@@ -807,7 +662,6 @@ class BrowserManager {
         album = null,
         title = null,
         playlist = null,
-        reference = MediaReference.UNKNOWN,
       )
     )
   }
@@ -832,11 +686,10 @@ class BrowserManager {
 
     // Check if result is browsable-only (container/route) vs playable
     // If it's browsable but also playable (has src or playable=true), treat it as playable
-    val firstResultUrl = firstResult.url
     val tracksToFilter =
-      if (firstResult.src == null && firstResultUrl != null) {
-        Timber.d("First search result is browsable-only, resolving: $firstResultUrl")
-        val resolvedTrack = resolve(firstResultUrl)
+      if (firstResult.src == null) {
+        Timber.d("First search result is browsable-only, resolving: ${firstResult.url}")
+        val resolvedTrack = resolve(firstResult.url!!)
         resolvedTrack.children
           ?.filter { it.src != null }
           ?.takeIf { it.isNotEmpty() }
@@ -864,7 +717,6 @@ class BrowserManager {
         album = null,
         title = null,
         playlist = null,
-        reference = MediaReference.UNKNOWN,
       )
     )
   }
@@ -883,34 +735,20 @@ class BrowserManager {
     val searchPath = BrowserPathHelper.createSearchPath(params.query)
 
     try {
-      // Execute search. Drop results without a stable identifier (url or src): search results come
-      // from server/JS data that doesn't pass through validateTrack like browse children do, and
-      // downstream conversion (TrackFactory.toMedia3) and browsable-result resolution require one.
-      val searchResults =
-        resolveSearch(params)
-          .filter { track ->
-            val valid = track.url != null || track.src != null
-            if (!valid) {
-              Timber.w("Dropping search result without url or src: '${track.title}'")
-            }
-            valid
-          }
-          .toTypedArray()
+      // Execute search
+      val searchResults = resolveSearch(params)
 
       // Create ResolvedTrack
       val searchResolvedTrack =
         ResolvedTrack(
-          id = null,
           url = searchPath,
           title = "Search: ${params.query}",
           children = searchResults,
           carPlaySiriListButton = null,
           artwork = null,
           artworkSource = null,
-          request = null,
           artworkCarPlayTinted = null,
           artist = null,
-          albumUrl = null,
           description = null,
           subtitle = null,
           album = null,
@@ -926,7 +764,8 @@ class BrowserManager {
         )
 
       // Cache search results for getCachedSearchResults()
-      lastSearch = params.query to searchResults
+      lastSearchQuery = params.query
+      lastSearchResults = searchResults
 
       // Cache individual tracks for Media3 lookups
       cacheChildren(searchResolvedTrack)
@@ -941,17 +780,14 @@ class BrowserManager {
       // Return empty search result on error
       val emptySearchResult =
         ResolvedTrack(
-          id = null,
           url = searchPath,
           title = "Search: ${params.query}",
           children = emptyArray(),
           carPlaySiriListButton = null,
           artwork = null,
           artworkSource = null,
-          request = null,
           artworkCarPlayTinted = null,
           artist = null,
-          albumUrl = null,
           description = null,
           subtitle = null,
           album = null,
@@ -1012,15 +848,6 @@ class BrowserManager {
     onTabsChanged = callback
   }
 
-  /**
-   * Set callback invoked whenever both [artworkResolutions] and the browse-artwork registry are
-   * cleared (config swap or content invalidation). The caller should clear any parallel
-   * [com.audiobrowser.browser.BrowseArtworkRegistry] instance it owns.
-   */
-  fun setOnArtworkRegistriesCleared(callback: () -> Unit) {
-    onArtworkRegistriesCleared = callback
-  }
-
   /**
    * Query navigation tabs from the configured tabs source. This is an async operation that resolves
    * the tabs configuration.
@@ -1098,25 +925,15 @@ class BrowserManager {
     entry.browseCallback?.let { callback ->
       Timber.d("Resolving route via callback")
       val param = BrowserSourceCallbackParam(path, routeParams)
-      // BrowserSourceCallback may return a BrowseResult synchronously or via a
-      // Promise. Nitro flattens (ResolvedTrack | BrowseError) | Promise<BrowseResult>
-      // into a 3-arm variant: sync track, sync error, or a Promise resolving to a
-      // BrowseResult (which is itself a ResolvedTrack | BrowseError variant).
-      return callback
-        .invoke(param)
-        .await()
-        .match(
-          first = { resolvedTrack -> resolvedTrack },
-          second = { browseError -> throw CallbackException(browseError.error) },
-          third = { promise ->
-            promise
-              .await()
-              .match(
-                first = { resolvedTrack -> resolvedTrack },
-                second = { browseError -> throw CallbackException(browseError.error) },
-              )
-          },
-        )
+      val promise = callback.invoke(param)
+      val innerPromise = promise.await()
+      val result = innerPromise.await()
+
+      // Handle BrowseResult variant: either ResolvedTrack or BrowseError
+      return result.match(
+        first = { resolvedTrack -> resolvedTrack },
+        second = { browseError -> throw CallbackException(browseError.error) }
+      )
     }
 
     entry.browseConfig?.let { apiConfig ->
@@ -1182,119 +999,34 @@ class BrowserManager {
   }
 
   /**
-   * Resolves a single request/browse layer. When a resolver thunk is present it is invoked and its
-   * result awaited. The resolver is Promise-only (the TS layer normalizes a sync-or-async thunk via
-   * Promise.resolve), so its native shape is `Promise<Promise<TransformableRequestConfig>>` — a
-   * double await. When there is no resolver the static layer config is returned as-is.
-   */
-  private suspend fun resolveLayer(
-    staticConfig: TransformableRequestConfig?,
-    resolver: Func_std__shared_ptr_Promise_std__shared_ptr_Promise_TransformableRequestConfig____?,
-  ): TransformableRequestConfig? {
-    if (resolver == null) return staticConfig
-    // Promise-only resolver (the TS layer wraps a sync-or-async thunk in
-    // Promise.resolve) → double await: the bridge promise, then the JS promise.
-    return resolver.invoke().await().await()
-  }
-
-  /**
-   * Ensures the request/browse resolver layers are resolved for the current [layerGeneration],
-   * caching the result. Re-resolves when the generation changes (config set or content
-   * invalidation). Uses a simple generation guard with no in-flight cache: a benign idempotent
-   * double-resolve under concurrent first-requests is acceptable, and on a thrown resolver nothing
-   * is cached so the next request retries naturally.
-   */
-  internal suspend fun ensureLayersResolved() {
-    if (resolvedLayerGeneration == layerGeneration) return
-    val generation = layerGeneration
-    val req = resolveLayer(config.request, config.requestResolver)
-    val brw = resolveLayer(config.browse, config.browseResolver)
-    // A newer generation started while we were awaiting — drop this stale result.
-    if (generation != layerGeneration) return
-    resolvedRequestLayer = req
-    resolvedBrowseLayer = brw
-    resolvedLayerGeneration = generation
-  }
-
-  /**
-   * Ensures the request layer is resolved for the current generation and returns it (the resolver
-   * result when a [BrowserConfig.requestResolver] is configured, else the static
-   * [BrowserConfig.request]).
-   *
-   * Consumers outside the browse path (media URL building, artwork) must obtain the request layer
-   * through this accessor rather than reading the static `config.request`, so a resolver-only
-   * consumer still gets a baseUrl/headers/transform for media, artwork, and now-playing artwork.
-   */
-  internal suspend fun resolvedRequestConfig(): TransformableRequestConfig? {
-    ensureLayersResolved()
-    return resolvedRequestLayer
-  }
-
-  /**
-   * Builds the HTTP request for an API-backed path by layering request (shared) → kind
-   * (browse/search) → route configs. Each layer's transform receives the previous layer's output; a
-   * layer with no transform merges its static fields.
-   *
-   * `initialQuery` seeds query params onto the BASE the kind layer receives (e.g. search q/mode/…):
-   * a layer with a transform "wins completely" and is handed only the base, so params placed on a
-   * layer's own static query would be dropped before the transform runs. The same goes for `path`:
-   * it is carried from the base through every layer (only a transform may change it), so a kind
-   * whose config supplies the path (search) must seed it via the `path` parameter. Mirrors iOS
-   * `buildApiRequest`.
-   *
-   * @throws ContentNotFoundException when no layer supplies a baseUrl — there is nothing to fetch,
-   *   so the path is genuinely "not found" rather than a network error (mirrors iOS's `guard let
-   *   baseUrl`).
-   */
-  internal suspend fun buildApiRequest(
-    kindConfig: TransformableRequestConfig?,
-    routeConfig: TransformableRequestConfig?,
-    path: String?,
-    params: Map<String, String>,
-    initialQuery: Map<String, String>? = null,
-  ): HttpClient.HttpRequest {
-    // Resolve the request/browse resolver thunks once per content generation (cached).
-    ensureLayersResolved()
-
-    var merged =
-      RequestConfig(
-        method = null,
-        path = path,
-        baseUrl = null,
-        headers = null,
-        query = null,
-        body = null,
-        contentType = null,
-        userAgent = null,
-      )
-    resolvedRequestLayer?.let { merged = RequestConfigBuilder.mergeConfig(merged, it, params) }
-    if (!initialQuery.isNullOrEmpty()) {
-      merged = merged.copy(query = (merged.query ?: emptyMap()) + initialQuery)
-    }
-    kindConfig?.let { merged = RequestConfigBuilder.mergeConfig(merged, it, params) }
-    routeConfig?.let { merged = RequestConfigBuilder.mergeConfig(merged, it, params) }
-
-    if (merged.baseUrl.isNullOrBlank()) {
-      throw ContentNotFoundException(path ?: "")
-    }
-    return RequestConfigBuilder.buildHttpRequest(merged)
-  }
-
-  /**
-   * Execute an API request for browser content. Request building (layering + transforms + baseUrl
-   * guard) lives in [buildApiRequest]; this adds the browse-specific response shape (a
-   * ResolvedTrack page object).
+   * Execute an API request for browser content. Handles URL parameter substitution, config merging,
+   * and transforms.
    */
   private suspend fun executeApiRequest(
-    apiConfig: TransformableRequestConfig?,
+    apiConfig: TransformableRequestConfig,
     path: String,
     routeParams: Map<String, String>,
   ): ResolvedTrack {
     return withContext(Dispatchers.IO) {
-      // request (shared) → browse (kind) → route. apiConfig is null for the
-      // implicit default (an unmatched browse path → fetch via request + browse + path).
-      ensureLayersResolved()
-      val httpRequest = buildApiRequest(resolvedBrowseLayer, apiConfig, path, routeParams)
+      // 1. Start with base config, using the navigation path as default
+      val baseConfig =
+        config.request?.let { req ->
+          RequestConfigBuilder.toRequestConfig(req).copy(path = req.path ?: path)
+        }
+          ?: RequestConfig(
+            path = path,
+            method = null,
+            baseUrl = null,
+            headers = null,
+            query = null,
+            body = null,
+            contentType = null,
+            userAgent = null,
+          )
+      val mergedConfig = RequestConfigBuilder.mergeConfig(baseConfig, apiConfig, routeParams)
+
+      // 2. Build and execute HTTP request
+      val httpRequest = RequestConfigBuilder.buildHttpRequest(mergedConfig)
       val response = httpClient.request(httpRequest)
 
       response.fold(
@@ -1334,10 +1066,24 @@ class BrowserManager {
   ): Array<Track> {
     return withContext(Dispatchers.IO) {
       try {
+        // 1. Start with base config
+        val baseConfig =
+          config.request?.let { RequestConfigBuilder.toRequestConfig(it) }
+            ?: RequestConfig(
+              method = null,
+              path = null,
+              baseUrl = null,
+              headers = null,
+              query = null,
+              body = null,
+              contentType = null,
+              userAgent = null,
+            )
+
+        // 2. Build query parameters from SearchParams
         val searchQueryParams = buildMap {
           put("q", params.query)
           params.mode?.let { put("mode", it.toString().lowercase()) }
-          if (params.reference == MediaReference.MY) put("reference", "my")
           params.genre?.let { put("genre", it) }
           params.artist?.let { put("artist", it) }
           params.album?.let { put("album", it) }
@@ -1345,26 +1091,31 @@ class BrowserManager {
           params.playlist?.let { put("playlist", it) }
         }
 
-        // request (shared) → search (kind); no browse layer and no route — search
-        // is its own kind. The search params seed the base (see buildApiRequest
-        // docs), and so does the search config's path: a layer's static path
-        // never applies (the path is carried from the base), so the caller
-        // seeds it — mirrors the web stub's fetchSearchResults.
-        val httpRequest =
-          buildApiRequest(
-            kindConfig = apiConfig,
-            routeConfig = null,
+        // 3. Create a copy of API config with added search parameters
+        val searchConfig =
+          TransformableRequestConfig(
+            transform = apiConfig.transform,
+            method = apiConfig.method,
             path = apiConfig.path,
-            params = emptyMap(),
-            initialQuery = searchQueryParams,
+            baseUrl = apiConfig.baseUrl,
+            headers = apiConfig.headers,
+            query = (apiConfig.query ?: emptyMap()) + searchQueryParams,
+            body = apiConfig.body,
+            contentType = apiConfig.contentType,
+            userAgent = apiConfig.userAgent,
           )
+
+        // 3. Merge configs and apply transform if provided
+        var mergedConfig = RequestConfigBuilder.mergeConfig(baseConfig, searchConfig, emptyMap())
+
+        // 4. Build and execute HTTP request
+        val httpRequest = RequestConfigBuilder.buildHttpRequest(mergedConfig)
         val response = httpClient.request(httpRequest)
 
         response.fold(
           onSuccess = { httpResponse ->
             if (httpResponse.isSuccessful) {
-              // The search endpoint returns a bare Track array (unlike browse,
-              // which returns a page object). iOS parses it the same way.
+              // 4. Parse response as Track array
               val jsonTracks = json.decodeFromString<List<JsonTrack>>(httpResponse.body)
               jsonTracks.map { it.toNitro() }.toTypedArray()
             } else {
@@ -1405,23 +1156,8 @@ class CallbackException(message: String) : Exception(message)
  */
 data class BrowserConfig(
   val request: TransformableRequestConfig? = null,
-  // Resolver thunk for the shared request layer. When set, it is resolved once per content
-  // generation (re-resolved after invalidateAllContent), cached, and merged per request — instead
-  // of carrying a static `request`. `request` and `requestResolver` are mutually exclusive in
-  // practice (the consumer sets one or the other), but both are merged if present.
-  val requestResolver:
-    Func_std__shared_ptr_Promise_std__shared_ptr_Promise_TransformableRequestConfig____? =
-    null,
-  val browse: TransformableRequestConfig? = null,
-  // Resolver thunk for the browse layer. See `requestResolver`.
-  val browseResolver:
-    Func_std__shared_ptr_Promise_std__shared_ptr_Promise_TransformableRequestConfig____? =
-    null,
   val media: MediaRequestConfig? = null,
   val artwork: ArtworkRequestConfig? = null,
-  // Now-playing-only artwork configuration (lock screen / notification / Android Auto now-playing).
-  // A distinct kind from `artwork`; the now-playing path falls back to `artwork` when this is null.
-  val nowPlayingArtwork: ArtworkRequestConfig? = null,
   // Routes as array with flattened entries (includes __tabs__, __search__, and __default__ special
   // routes)
   val routes: Array<NativeRouteEntry>? = null,