react-native-audio-browser 0.2.0-next.10 → 0.2.0-next.12

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

@@ -1,8 +1,10 @@
 package com.audiobrowser.browser
 
 import android.util.LruCache
+import androidx.media3.common.C
 import androidx.media3.common.MediaItem
 import androidx.media3.session.MediaSession
+import com.audiobrowser.extension.identity
 import com.audiobrowser.http.HttpClient
 import com.audiobrowser.http.RequestConfigBuilder
 import com.audiobrowser.util.BrowserPathHelper
@@ -10,7 +12,6 @@ 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
@@ -19,6 +20,8 @@ import com.margelo.nitro.audiobrowser.NativeRouteEntry
 import com.margelo.nitro.audiobrowser.RequestConfig
 import com.margelo.nitro.audiobrowser.ResolvedTrack
 import com.margelo.nitro.audiobrowser.SearchParams
+import com.margelo.nitro.audiobrowser.Section
+import com.margelo.nitro.audiobrowser.StyleDisplay
 import com.margelo.nitro.audiobrowser.Track
 import com.margelo.nitro.audiobrowser.TransformableRequestConfig
 import kotlinx.coroutines.Dispatchers
@@ -82,7 +85,7 @@ class BrowserManager {
       }
     }
 
-  // LRU cache for individual tracks - keyed by both url and src for O(1) lookup
+  // LRU cache for individual tracks - keyed by both path and src for O(1) lookup
   private val trackCache = LruCache<String, Track>(3000)
 
   // LRU cache for resolved content - keyed by path
@@ -94,12 +97,12 @@ class BrowserManager {
   // concurrent reader never sees one query matched with another query's results.
   @Volatile private var lastSearch: Pair<String, Array<Track>>? = null
 
-  // Set of favorited track identifiers (src)
+  // Set of favorited track identities (id when non-blank, else src — see Track.identity)
   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
+  // Whether favoriting is enabled, propagated from the player's `favorite` capability.
+  // false = favoriting disabled (no row hearts). Set via setFavoriteEnabled.
+  private var favoriteEnabled: Boolean = false
 
   // Navigation tracking to prevent race conditions
   @Volatile private var currentNavigationId = 0
@@ -150,8 +153,8 @@ class BrowserManager {
   val artworkResolutions = ArtworkResolutionRegistry()
 
   /**
-   * Sets the favorited track identifiers. Tracks will have their favorited field hydrated based on
-   * this list during browsing.
+   * Sets the favorited track identities (id when non-blank, else src). Tracks will have their
+   * favorited field hydrated based on this list during browsing.
    */
   fun setFavorites(favorites: List<String>) {
     favoriteIds = favorites.toSet()
@@ -159,97 +162,125 @@ class BrowserManager {
   }
 
   /**
-   * Sets the favorite match mode (propagated from the `favorite` capability). null disables
+   * Enables or disables favoriting (propagated from the `favorite` capability). false disables
    * row-heart hydration.
    */
-  fun setFavoriteMatch(match: FavoritesMatchMode?) {
-    favoriteMatch = match
+  fun setFavoriteEnabled(enabled: Boolean) {
+    favoriteEnabled = enabled
   }
 
   /**
-   * Updates the favorite state for a single track identifier. Called when the heart button is
-   * tapped in media controllers.
+   * Updates the favorite state for a single track identity (id when non-blank, else src). Called
+   * when the heart button is tapped in media controllers.
    */
-  fun updateFavorite(id: String, favorited: Boolean) {
+  fun updateFavorite(identity: String, favorited: Boolean) {
     favoriteIds =
       if (favorited) {
-        favoriteIds + id
+        favoriteIds + identity
       } else {
-        favoriteIds - id
+        favoriteIds - identity
       }
-    Timber.d("Updated favorite for '$id' to $favorited (total: ${favoriteIds.size})")
+    Timber.d("Updated favorite for '$identity' to $favorited (total: ${favoriteIds.size})")
   }
 
   /**
    * 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.
+   * is enabled (the `favorite` capability). Only tracks with an identity (id or src) 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.
    */
   private fun hydrateFavorite(track: Track): Track {
-    val match = favoriteMatch ?: return track
+    if (!favoriteEnabled) 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
+    // Only identity-bearing tracks are favoritable
+    if (track.identity == null) return track
 
-    val isFavorited = isFavorite(src, match)
-
-    return track.copy(favorited = isFavorited)
+    return track.copy(favorited = isFavorite(track))
   }
 
-  /** 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) }
-    }
+  /** Whether [track]'s identity is in the favorites set. */
+  private fun isFavorite(track: Track): Boolean =
+    track.identity?.let { favoriteIds.contains(it) } == true
 
-  /** Hydrates favorites on all children of a ResolvedTrack. */
+  /**
+   * Hydrates favorites on all tracks of a resolved page. Pages reach hydration normalized (ADR
+   * 0010), so `sections` is the only structure to walk.
+   */
   private fun hydrateChildren(resolvedTrack: ResolvedTrack): ResolvedTrack {
-    val children = resolvedTrack.children ?: return resolvedTrack
-    val hydratedChildren = children.map { hydrateFavorite(it) }.toTypedArray()
-    return resolvedTrack.copy(children = hydratedChildren)
+    val sections = resolvedTrack.sections ?: return resolvedTrack
+    return resolvedTrack.copy(
+      sections =
+        sections
+          .map { section ->
+            section.copy(children = section.children.map { hydrateFavorite(it) }.toTypedArray())
+          }
+          .toTypedArray()
+    )
   }
 
-  /** Cache a track by id, url, and src for O(1) lookup from any mediaId form. */
+  /** Cache a track by id, path, and src for O(1) lookup from any mediaId form. */
   private fun cacheTrack(track: Track) {
     track.id?.takeUnless { it.isBlank() }?.let { trackCache.put(it, track) }
-    track.url?.let { trackCache.put(it, track) }
+    track.path?.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.flattenedChildren?.forEach { cacheTrack(it) }
+  }
+
+  // Pages already warned about by warnIfGridPageLacksPromise — the mismatch
+  // re-observes on every onGetChildren serve, and once is a diagnostic while
+  // every-scroll is noise. Concurrent: onGetChildren serves run on the IO
+  // pool, several in flight at once.
+  private val promiseWarnedPaths = java.util.concurrent.ConcurrentHashMap.newKeySet<String>()
+
+  /**
+   * Dev diagnostic (ADR 0011): a page serving grid sections under a browsable handle that declared
+   * no `style.display` promise still renders its parent-level layout as a list on Android Auto —
+   * the parent hint is emitted only when declared, never derived from resolved pages and never
+   * back-filled. Warns at the one site where the mismatch is observable; a cache miss for the
+   * handle (cold start straight into the page) just skips the check.
+   *
+   * Only an all-grid page warns: the parent-level hint lays out the WHOLE page, so on a mixed page
+   * (a teaser shelf above list sections) there is no correct promise to advise — grid would tile
+   * the list sections too.
+   */
+  fun warnIfGridPageLacksPromise(path: String, sections: List<Section>) {
+    if (sections.isEmpty() || !sections.all { it.style?.display == StyleDisplay.GRID }) return
+    val handle = trackCache.get(path) ?: return
+    if (handle.src != null) return // rendered playable — opens no page, promises nothing
+    if (handle.style?.display == null && promiseWarnedPaths.add(path)) {
+      Timber.w(
+        "Page '%s' serves grid sections, but its browsable handle declares no style.display — " +
+          "Android Auto's parent-level hint was not emitted, so this page renders as a list " +
+          "there. Declare `style: { display: 'grid' }` on the handle track.",
+        path,
+      )
     }
   }
 
   /**
-   * Get a cached Track by mediaId (stable id, url, or src), or null if not cached. Used by Media3
+   * Get a cached Track by mediaId (stable id, path, 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)
+    // Try direct lookup first (matches path or src)
     trackCache.get(mediaId)?.let { track ->
       val hydratedTrack = hydrateFavorite(track)
       Timber.d("Cache HIT for mediaId='$mediaId' → '${track.title}'")
       return hydratedTrack
     }
 
-    // Try extracting src from contextual URL
+    // Try extracting the track identity (id when non-blank, else src) from a contextual path —
+    // the cache is keyed by id AND src, so either identity form resolves.
     val trackId = BrowserPathHelper.extractTrackId(mediaId)
     if (trackId != null) {
       trackCache.get(trackId)?.let { track ->
         val hydratedTrack = hydrateFavorite(track)
-        Timber.d("Cache HIT (extracted src) for mediaId='$mediaId' → '${track.title}'")
+        Timber.d("Cache HIT (extracted identity) for mediaId='$mediaId' → '${track.title}'")
         return hydratedTrack
       }
     }
@@ -259,19 +290,19 @@ class BrowserManager {
   }
 
   /**
-   * Resolves a tapped mediaId to the contextual url to expand a queue from, or null when there is
+   * Resolves a tapped mediaId to the contextual path 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
+   * resolves through the track cache to the contextual path 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? {
+  fun contextualPathFor(mediaId: String): String? {
     if (BrowserPathHelper.isContextual(mediaId)) return mediaId
-    return getCachedTrack(mediaId)?.url?.takeIf { BrowserPathHelper.isContextual(it) }
+    return getCachedTrack(mediaId)?.path?.takeIf { BrowserPathHelper.isContextual(it) }
   }
 
   /**
-   * Resolves a single Media3 MediaItem to a Track. Prefers the track cache (keyed by id, url, and
+   * Resolves a single Media3 MediaItem to a Track. Prefers the track cache (keyed by id, path, and
    * src).
    *
    * A cache miss is legitimately reachable: a controller can replay a mediaId this process never
@@ -304,26 +335,23 @@ class BrowserManager {
           // 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,
+          path = 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,
+          albumPath = null,
           album = metadata.albumTitle?.toString(),
           description = metadata.description?.toString(),
           genre = metadata.genre?.toString(),
           duration = null,
           style = null,
-          childrenStyle = null,
+          disabled = null,
           favorited = null,
-          groupTitle = null,
           live = null,
-          imageRow = null,
         )
       )
     }
@@ -361,17 +389,19 @@ class BrowserManager {
       if (searchQuery != null) {
         Timber.d("Handling search playback request for query: $searchQuery")
 
-        // Execute search (will hit cache if already performed)
+        // Execute search (will hit cache if already performed). Disabled
+        // tracks never play, so they never enter a search-built queue.
         val searchResults = search(searchQuery)
-        val searchTracks = searchResults.children
+        val searchTracks =
+          searchResults.flattenedChildren?.filterNot { it.disabled == true }?.toTypedArray()
 
         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)
+          // when the track has one, else path/src — see TrackFactory)
           val mediaId = mediaItem.mediaId
           val selectedIndex =
             searchTracks.indexOfFirst { track ->
-              track.id == mediaId || track.url == mediaId || track.src == mediaId
+              track.id == mediaId || track.path == mediaId || track.src == mediaId
             }
 
           if (selectedIndex >= 0) {
@@ -398,12 +428,12 @@ 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
+      val contextualPath = if (searchQuery == null) contextualPathFor(mediaId) else null
 
-      if (contextualUrl != null) {
-        Timber.d("Attempting queue expansion for mediaId='$mediaId' via '$contextualUrl'")
+      if (contextualPath != null) {
+        Timber.d("Attempting queue expansion for mediaId='$mediaId' via '$contextualPath'")
 
-        val expanded = expandQueueFromContextualUrl(contextualUrl)
+        val expanded = expandQueueFromContextualPath(contextualPath)
 
         if (expanded != null) {
           val (tracks, selectedIndex) = expanded
@@ -423,20 +453,56 @@ class BrowserManager {
     // No expansion - resolve from cache (with a minimal-track fallback for replayed mediaIds)
     val resolvedTracks = mediaItems.map { resolveMediaItemToTrack(it) }
 
+    // A disabled track is unavailable — it never plays, even by a stale or
+    // replayed mediaId (Track.disabled). Refusal fails the future: Media3
+    // surfaces an error to the controller and the current playback stays
+    // untouched (an empty item list would clear the live timeline instead).
+    //
+    // Media3's legacy path — how Android Auto and Assistant actually request
+    // playback (onPlayFromMediaId et al.) — passes C.INDEX_UNSET, meaning
+    // "the default item", i.e. the first. Normalize before the guard, or the
+    // refusal is dead on exactly the path that serves cars.
+    val effectiveStartIndex = if (startIndex == C.INDEX_UNSET) 0 else startIndex
+    val startTrack = resolvedTracks.getOrNull(effectiveStartIndex)
+    if (startTrack != null && startTrack.disabled == true) {
+      Timber.w("Refusing playback of disabled track: ${startTrack.title}")
+      throw IllegalStateException("Refusing playback of disabled track: ${startTrack.title}")
+    }
+    val playableTracks = resolvedTracks.filterNot { it.disabled == true }
+    if (playableTracks.isEmpty()) {
+      // Belt over the start-item guard: never hand Media3 an empty timeline.
+      Timber.w("Refusing playback: every requested track is disabled")
+      throw IllegalStateException("Refusing playback: every requested track is disabled")
+    }
+    // Positional, not indexOf: value equality would alias a duplicated track
+    // (the same station twice in a queue) to its first copy. An unset index
+    // stays unset — Media3's "default item" semantics pass through as they
+    // did before the filter existed.
+    val adjustedStartIndex =
+      when {
+        startIndex == C.INDEX_UNSET -> C.INDEX_UNSET
+        startTrack == null -> 0
+        else -> resolvedTracks.take(effectiveStartIndex).count { it.disabled != true }
+      }
+
     // Convert to Media3 MediaItems
-    val resolvedMediaItems = resolvedTracks.map { track -> TrackFactory.toMedia3(track) }
+    val resolvedMediaItems = playableTracks.map { track -> TrackFactory.toMedia3(track) }
 
-    return MediaSession.MediaItemsWithStartPosition(resolvedMediaItems, startIndex, startPositionMs)
+    return MediaSession.MediaItemsWithStartPosition(
+      resolvedMediaItems,
+      adjustedStartIndex,
+      startPositionMs,
+    )
   }
 
   /**
-   * Validates that a track has either url or src for stable identification. Throws
+   * Validates that a track has either path or src for stable identification. Throws
    * IllegalStateException if validation fails.
    */
   private fun validateTrack(track: Track, context: String) {
-    if (track.url == null && track.src == null) {
+    if (track.path == null && track.src == null) {
       throw IllegalStateException(
-        "$context must have either 'url' or 'src' property for stable identification. Track: ${track.title}"
+        "$context must have either 'path' or 'src' property for stable identification. Track: ${track.title}"
       )
     }
   }
@@ -444,12 +510,12 @@ class BrowserManager {
   suspend fun resolve(path: String, useCache: Boolean = true): ResolvedTrack {
     Timber.d("=== RESOLVE: path='$path' (useCache=$useCache) ===")
 
-    // Strip __trackId from contextual URLs (e.g., "/library/radio?__trackId=song.mp3" →
+    // Strip __trackId from contextual paths (e.g., "/library/radio?__trackId=song.mp3" →
     // "/library/radio")
-    // This allows resolving the parent container for tracks referenced by contextual URL
+    // This allows resolving the parent container for tracks referenced by contextual path
     val normalizedPath = BrowserPathHelper.stripTrackId(path)
     if (normalizedPath != path) {
-      Timber.d("Stripped __trackId from contextual URL: '$normalizedPath'")
+      Timber.d("Stripped __trackId from contextual path: '$normalizedPath'")
     }
 
     // Check content cache first
@@ -457,7 +523,7 @@ class BrowserManager {
       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
+        // mediaId → contextual path, see contextualPathFor) must reflect the
         // most recently *browsed* container, which a cached re-display
         // otherwise wouldn't re-register.
         cacheChildren(cached)
@@ -483,11 +549,11 @@ class BrowserManager {
    * (e.g., via notifyContentChanged).
    *
    * @param path The container path to invalidate (e.g., "/library/radio")
-   * @throws IllegalArgumentException if passed a contextual URL (contains __trackId)
+   * @throws IllegalArgumentException if passed a contextual path (contains __trackId)
    */
   fun invalidateContentCache(path: String) {
     require(!BrowserPathHelper.isContextual(path)) {
-      "invalidateContentCache() expects a container path, not a contextual URL: $path"
+      "invalidateContentCache() expects a container path, not a contextual path: $path"
     }
     contentCache.remove(path)
     Timber.d("Invalidated content cache for path='$path'")
@@ -524,81 +590,67 @@ class BrowserManager {
       effectiveArtworkConfig = config.artwork
     }
 
-    // Transform children: generate contextual URLs and transform artwork URLs
-    val transformedChildren =
-      resolvedTrack.children?.let { children ->
-        coroutineScope {
-          children
-            .mapIndexed { index, track ->
+    // Normalize to the canonical sectioned shape (children sugar → one untitled
+    // section — ADR 0010), then generate contextual paths and transform artwork
+    // URLs. The output never carries `children`.
+    val sections = resolvedTrack.normalizedSections ?: return resolvedTrack
+    // The contextual index is the flat page position — children concatenated in
+    // section order (ADR 0009/0010).
+    var flatIndex = 0
+    // One scope for the whole page: every child's transform (which can suspend
+    // on artwork resolution) launches up front across all sections, then the
+    // sections reassemble — a slow section doesn't serialize the ones after it.
+    val transformedSections = coroutineScope {
+      sections
+        .map { section ->
+          val base = flatIndex
+          flatIndex += section.children.size
+          section to
+            section.children.mapIndexed { offset, 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")
+                val index = base + offset
+                // Validate that track has stable identifier.
+                validateTrack(track, "Child track")
 
                 var transformedTrack = track
 
-                // Generate contextual URLs for playable tracks
+                // Generate contextual paths for playable tracks
                 // Always regenerate to reflect the current browsing context, not the original
                 // context
                 // (e.g., a track favorited from an album should use /favorites context when browsed
                 // there)
-                if (track.src != null) {
-                  val contextualUrl = BrowserPathHelper.build(path, track.src)
-                  transformedTrack = transformedTrack.copy(url = contextualUrl)
+                // The flat page position rides along as a duplicate-identity tie-breaker.
+                val trackIdentity = track.identity
+                if (track.src != null && trackIdentity != null) {
+                  val contextualPath = BrowserPathHelper.build(path, trackIdentity, index)
+                  transformedTrack = transformedTrack.copy(path = contextualPath)
 
                   Timber.d(
-                    "[$path] Child[$index] '${track.title}': Playable, contextualUrl=$contextualUrl (src=${track.src})"
+                    "[$path] Child[$index] '${track.title}': Playable, contextualPath=$contextualPath (identity=$trackIdentity)"
                   )
                 } else {
                   Timber.d(
-                    "[$path] Child[$index] '${track.title}': Browsable with url=${track.url}"
+                    "[$path] Child[$index] '${track.title}': Browsable with path=${track.path}"
                   )
                 }
 
-                // 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 ->
-                  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()
-                    )
-                }
-
                 // Transform artwork URL. At browse-time there is no display size info.
-                transformedTrack =
-                  transformArtworkUrl(
-                    transformedTrack,
-                    effectiveArtworkConfig,
-                    path,
-                    index,
-                    ImageContext(null, null),
-                  )
-
-                transformedTrack
+                transformArtworkUrl(
+                  transformedTrack,
+                  effectiveArtworkConfig,
+                  path,
+                  index,
+                  ImageContext(null, null),
+                )
               }
             }
-            .awaitAll()
         }
-      }
-
-    // Return resolved track with transformed children
-    return if (transformedChildren != null) {
-      resolvedTrack.copy(children = transformedChildren.toTypedArray())
-    } else {
-      resolvedTrack
+        .map { (section, transformedChildren) ->
+          section.copy(children = transformedChildren.awaitAll().toTypedArray())
+        }
     }
+
+    return resolvedTrack.copy(sections = transformedSections.toTypedArray(), children = null)
   }
 
   /**
@@ -657,55 +709,68 @@ class BrowserManager {
   }
 
   /**
-   * Expands a contextual URL into a queue of playable tracks.
+   * Expands a contextual path into a queue of playable tracks.
    *
    * Used when navigating to a track to load it with its full album/playlist context. Returns only
    * the selected track if singleTrack is true.
    *
-   * @param contextualUrl The contextual URL (e.g., "/album?__trackId=song.mp3")
+   * @param contextualPath The contextual path (e.g., "/album?__trackId=song.mp3")
    * @return Pair of (tracks array, selected track index), or null if expansion fails
    */
-  suspend fun expandQueueFromContextualUrl(contextualUrl: String): Pair<Array<Track>, Int>? {
-    val trackId = BrowserPathHelper.extractTrackId(contextualUrl) ?: return null
+  suspend fun expandQueueFromContextualPath(contextualPath: String): Pair<Array<Track>, Int>? {
+    val trackId = BrowserPathHelper.extractTrackId(contextualPath) ?: return null
 
-    Timber.d("Expanding queue from contextual URL: $contextualUrl (trackId=$trackId)")
+    Timber.d("Expanding queue from contextual path: $contextualPath (trackId=$trackId)")
 
     try {
       // Resolve the parent container to get all siblings
-      val parentPath = BrowserPathHelper.stripTrackId(contextualUrl)
+      val parentPath = BrowserPathHelper.stripTrackId(contextualPath)
       val parentResolvedTrack = resolve(parentPath)
-      val children = parentResolvedTrack.children
+      val sections = parentResolvedTrack.normalizedSections
 
-      if (children.isNullOrEmpty()) {
+      if (sections.isNullOrEmpty()) {
         Timber.w("Parent has no children, cannot expand queue")
         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 }
+      // Queue scope is the tapped section, not the whole page (ADR 0006). The
+      // stamped flat index pins which section (and which copy) was tapped when
+      // the same identity appears more than once; it is only a tie-breaker — a
+      // stale index falls back to the first identity match. An id that no
+      // longer appears on the page at all aborts the expansion — the caller
+      // falls back to the stored single track; silently queueing the changed
+      // list would resume the wrong station.
+      val tappedIndex = BrowserPathHelper.extractIndex(contextualPath)
+      val scoped = SectionScope.scoped(sections, trackId, tappedIndex) ?: return null
+      val sectionTracks = scoped.section.children.toList()
+      val tappedOffset = scoped.tappedOffset
+
+      // Filter to only playable tracks (tracks with src). A disabled track is
+      // unavailable — queue expansion excludes it, so auto-advance never meets
+      // one.
+      val playableTracks =
+        sectionTracks.filter { track -> track.src != null && track.disabled != true }
 
       if (playableTracks.isEmpty()) {
         Timber.w("Parent has no playable tracks, cannot expand queue")
         return null
       }
 
-      // Find the index of the selected track in the playable tracks array
-      val selectedIndex = playableTracks.indexOfFirst { track -> track.src == trackId }
+      // Find the index of the selected track in the playable tracks array:
+      // the pinned copy when the stamp survived, else the first identity match
+      val selectedIndex =
+        if (
+          tappedOffset != null &&
+            sectionTracks[tappedOffset].src != null &&
+            sectionTracks[tappedOffset].disabled != true
+        ) {
+          sectionTracks.take(tappedOffset + 1).count { it.src != null && it.disabled != true } - 1
+        } else {
+          playableTracks.indexOfFirst { track -> track.identity == trackId }
+        }
 
       if (selectedIndex < 0) {
-        Timber.w("Track with src='$trackId' not found in playable children")
+        Timber.w("Track with identity='$trackId' not found in playable children")
         return null
       }
 
@@ -716,11 +781,11 @@ class BrowserManager {
       }
 
       Timber.d(
-        "singleTrack=false - returning ${playableTracks.size} playable tracks (from ${children.size} total), starting at index $selectedIndex"
+        "singleTrack=false - returning ${playableTracks.size} playable tracks (from ${sectionTracks.size} in section), starting at index $selectedIndex"
       )
       return Pair(playableTracks.toTypedArray(), selectedIndex)
     } catch (e: Exception) {
-      Timber.e(e, "Error expanding queue from contextual URL: $contextualUrl")
+      Timber.e(e, "Error expanding queue from contextual path: $contextualPath")
       return null
     }
   }
@@ -822,7 +887,10 @@ class BrowserManager {
    */
   suspend fun searchPlayable(params: SearchParams): Array<Track>? {
     val searchResults = search(params)
-    val tracks = searchResults.children
+    // Voice search never matches a disabled track (Track.disabled) — filtered
+    // before the first result is picked, so an unavailable one can't capture
+    // the play.
+    val tracks = searchResults.flattenedChildren?.filter { it.disabled != true }?.toTypedArray()
 
     if (tracks.isNullOrEmpty()) {
       return null
@@ -832,13 +900,13 @@ 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 firstResultPath = firstResult.path
     val tracksToFilter =
-      if (firstResult.src == null && firstResultUrl != null) {
-        Timber.d("First search result is browsable-only, resolving: $firstResultUrl")
-        val resolvedTrack = resolve(firstResultUrl)
-        resolvedTrack.children
-          ?.filter { it.src != null }
+      if (firstResult.src == null && firstResultPath != null) {
+        Timber.d("First search result is browsable-only, resolving: $firstResultPath")
+        val resolvedTrack = resolve(firstResultPath)
+        resolvedTrack.flattenedChildren
+          ?.filter { it.src != null && it.disabled != true }
           ?.takeIf { it.isNotEmpty() }
           ?.toTypedArray() ?: tracks
       } else {
@@ -883,34 +951,35 @@ class BrowserManager {
     val searchPath = BrowserPathHelper.createSearchPath(params.query)
 
     try {
-      // Execute search. Drop results without a stable identifier (url or src): search results come
+      // Execute search. Drop results without a stable identifier (path 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
+            val valid = track.path != null || track.src != null
             if (!valid) {
-              Timber.w("Dropping search result without url or src: '${track.title}'")
+              Timber.w("Dropping search result without path or src: '${track.title}'")
             }
             valid
           }
           .toTypedArray()
 
-      // Create ResolvedTrack
+      // Search results are a flat list; as a resolved page they are one
+      // untitled section (ADR 0010).
       val searchResolvedTrack =
         ResolvedTrack(
           id = null,
-          url = searchPath,
+          path = searchPath,
           title = "Search: ${params.query}",
-          children = searchResults,
+          sections = arrayOf(untitledSection(searchResults)),
+          children = null,
           carPlaySiriListButton = null,
           artwork = null,
           artworkSource = null,
           request = null,
-          artworkCarPlayTinted = null,
           artist = null,
-          albumUrl = null,
+          albumPath = null,
           description = null,
           subtitle = null,
           album = null,
@@ -918,11 +987,9 @@ class BrowserManager {
           duration = null,
           src = null,
           style = null,
-          childrenStyle = null,
+          disabled = null,
           favorited = null,
-          groupTitle = null,
           live = null,
-          imageRow = null,
         )
 
       // Cache search results for getCachedSearchResults()
@@ -942,16 +1009,16 @@ class BrowserManager {
       val emptySearchResult =
         ResolvedTrack(
           id = null,
-          url = searchPath,
+          path = searchPath,
           title = "Search: ${params.query}",
-          children = emptyArray(),
+          sections = arrayOf(untitledSection(emptyArray())),
+          children = null,
           carPlaySiriListButton = null,
           artwork = null,
           artworkSource = null,
           request = null,
-          artworkCarPlayTinted = null,
           artist = null,
-          albumUrl = null,
+          albumPath = null,
           description = null,
           subtitle = null,
           album = null,
@@ -959,11 +1026,9 @@ class BrowserManager {
           duration = null,
           src = null,
           style = null,
-          childrenStyle = null,
+          disabled = null,
           favorited = null,
-          groupTitle = null,
           live = null,
-          imageRow = null,
         )
 
       return emptySearchResult
@@ -1040,7 +1105,7 @@ class BrowserManager {
     // Validate tabs have stable identifiers
     tabs.forEachIndexed { index, tab ->
       validateTrack(tab, "Tab")
-      Timber.d("[TABS] Tab[$index] '${tab.title}': url=${tab.url}")
+      Timber.d("[TABS] Tab[$index] '${tab.title}': path=${tab.path}")
     }
 
     this.tabs = tabs
@@ -1178,7 +1243,8 @@ class BrowserManager {
     Timber.d("Resolving tabs via route entry")
     val resolvedTrack = resolveRouteEntry(tabsEntry, TABS_ROUTE_PATH, emptyMap())
 
-    return resolvedTrack.children ?: emptyArray()
+    // Tabs are a flat list, not a page — a sectioned tabs source flattens.
+    return resolvedTrack.flattenedChildren?.toTypedArray() ?: emptyArray()
   }
 
   /**