react-native-audio-browser 0.2.0-next.11 → 0.2.0-next.13

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

@@ -1,42 +1,84 @@
 package com.audiobrowser.browser
 
-import com.margelo.nitro.audiobrowser.ImageRowItem
+import com.audiobrowser.extension.identity
+import com.margelo.nitro.audiobrowser.ResolvedTrack
+import com.margelo.nitro.audiobrowser.Section
 import com.margelo.nitro.audiobrowser.Track
 
 /**
  * Queue scope is the tapped section, not the whole page (ADR 0006): the playback context a listener
  * expects is the list they tapped in — a page aggregating several sections must not leak
- * next/previous across them.
+ * next/previous across them. Sections are structural (ADR 0010), so scoping is a lookup, not a
+ * groupTitle-run derivation.
  */
 object SectionScope {
-  sealed class Section {
-    /** The tapped id lives inside an image row's items. */
-    data class ImageRow(val items: List<ImageRowItem>) : Section()
-
-    /**
-     * The contiguous `groupTitle` run around the tapped child (items with no group title form runs
-     * of their own).
-     */
-    data class Run(val tracks: List<Track>) : Section()
-  }
+  /**
+   * The section containing the tapped identity, plus the tapped child's offset within it — non-null
+   * only when the stamped flat index pinned the exact copy.
+   */
+  data class Scoped(val section: Section, val tappedOffset: Int?)
 
   /**
-   * The section of [children] containing the playable [trackId], or null when the id is not found.
+   * The section of [sections] containing the playable [trackId] (a track identity — id when
+   * non-blank, else src), or null when not found.
+   *
+   * [tappedIndex] — the flat page position stamped into the contextual URL (children concatenated
+   * in section order) — is a tie-breaker, never an identifier: when the child at that position
+   * still carries the tapped identity, it pins which section (and which copy) was tapped; when it
+   * doesn't (the list shifted), resolution falls back to the first section containing the identity.
+   * A stale index can therefore never select a different track — at worst a different copy of the
+   * same one.
    */
-  fun section(children: List<Track>, trackId: String): Section? {
-    for (child in children) {
-      val items = child.imageRow
-      if (items != null && items.any { it.src == trackId }) {
-        return Section.ImageRow(items.toList())
+  fun scoped(sections: List<Section>, trackId: String, tappedIndex: Int? = null): Scoped? {
+    if (tappedIndex != null && tappedIndex >= 0) {
+      var start = 0
+      for (section in sections) {
+        val offset = tappedIndex - start
+        if (offset < section.children.size) {
+          if (section.children[offset].identity == trackId) {
+            return Scoped(section, offset)
+          }
+          break
+        }
+        start += section.children.size
+      }
+    }
+    for (section in sections) {
+      if (section.children.any { it.identity == trackId }) {
+        return Scoped(section, null)
       }
     }
-    val index = children.indexOfFirst { it.src == trackId }
-    if (index < 0) return null
-    val group = children[index].groupTitle
-    var start = index
-    while (start > 0 && children[start - 1].groupTitle == group) start--
-    var end = index
-    while (end + 1 < children.size && children[end + 1].groupTitle == group) end++
-    return Section.Run(children.subList(start, end + 1).toList())
+    return null
   }
 }
+
+// Page shape helpers (ADR 0010)
+
+/**
+ * One untitled section — the canonical wrap of a flat track list (`children` authoring sugar,
+ * search results — ADR 0010).
+ */
+fun untitledSection(children: Array<Track>): Section =
+  Section(title = null, subtitle = null, style = null, path = null, children = children)
+
+/**
+ * The canonical sectioned shape: `sections` wins when present; plain `children` is authoring sugar
+ * for one untitled section.
+ */
+val ResolvedTrack.normalizedSections: List<Section>?
+  get() = sections?.toList() ?: children?.let { listOf(untitledSection(it)) }
+
+/**
+ * [normalizedSections] with the page block folded in: each section's style resolves `section ??
+ * page` per property ([StyleResolver], ADR 0011), so everything downstream sees only effective
+ * section blocks — a page is a Track that is also the container of its sections.
+ */
+fun ResolvedTrack.styleResolvedSections(): List<Section>? =
+  normalizedSections?.map { it.copy(style = StyleResolver.sectionStyle(it.style, style)) }
+
+/**
+ * The page's children concatenated in section order — the flattening that defines contextual
+ * `__index` positions and the flat views (tabs, search) of a sectioned page.
+ */
+val ResolvedTrack.flattenedChildren: List<Track>?
+  get() = normalizedSections?.flatMap { it.children.asList() }

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

@@ -0,0 +1,60 @@
+package com.audiobrowser.browser
+
+import com.margelo.nitro.audiobrowser.SectionStyle
+import com.margelo.nitro.audiobrowser.TrackStyle
+
+/**
+ * The one place style declarations resolve to effective values (ADR 0011).
+ *
+ * Two mechanisms, deliberately distinct:
+ * - **Inherited item properties** resolve `track ?? section ?? page`, per property — a track's own
+ *   declaration wins over the blocks that contain it.
+ * - **Container properties and the positional `display`** resolve by scope override: `section ??
+ *   page` — the page declares for its whole scope, a section overrides for its own children.
+ *   `display` is never inherited item-to-container: each holder describes its own children, and a
+ *   track's `display` is the promise for the page *it* opens, not its rendering inside this
+ *   section.
+ *
+ * Every key of `SectionStyle` must be read by [sectionStyle] and every inherited key of
+ * `TrackStyle` by [trackStyle] — Nitro flattens the spec's `extends`, so
+ * `src/style-resolution.test.ts` enforces this completeness, not the type system.
+ */
+object StyleResolver {
+  /**
+   * Folds the page block into a section's block: every `SectionStyle` key resolves `section ??
+   * page`. The result is the section's effective block; item resolution then only needs `track ??
+   * section`.
+   */
+  fun sectionStyle(section: SectionStyle?, page: SectionStyle?): SectionStyle =
+    SectionStyle(
+      display = section?.display ?: page?.display,
+      artworkRendering = section?.artworkRendering ?: page?.artworkRendering,
+      imageShape = section?.imageShape ?: page?.imageShape,
+      accessorySymbol = section?.accessorySymbol ?: page?.accessorySymbol,
+      cardTint = section?.cardTint ?: page?.cardTint,
+      cardImage = section?.cardImage ?: page?.cardImage,
+      gridWrap = section?.gridWrap ?: page?.gridWrap,
+      gridTile = section?.gridTile ?: page?.gridTile,
+    )
+
+  /**
+   * Resolves a track's effective item properties against its (page-folded) section block.
+   *
+   * No Android renderer consumes the result yet — today's only inherited property
+   * (`artworkRendering`) is CarPlay-rendered — but the resolver ships on both platforms so the
+   * completeness test can hold every future inherited key to the same rule from day one.
+   */
+  fun trackStyle(track: TrackStyle?, section: SectionStyle?): TrackStyle =
+    TrackStyle(
+      // Positional deny-list: `display` is never inherited onto an item — resolved null, so no
+      // renderer can mistake the handle's page promise for this item's own layout.
+      display = null,
+      artworkRendering = track?.artworkRendering ?: section?.artworkRendering,
+      imageShape = track?.imageShape ?: section?.imageShape,
+      // 'none' resolves like any value — a renderer treats it as "no accessory, derived
+      // behavior" (the inheritance escape). No Android surface draws these properties today.
+      accessorySymbol = track?.accessorySymbol ?: section?.accessorySymbol,
+      cardTint = track?.cardTint ?: section?.cardTint,
+      cardImage = track?.cardImage ?: section?.cardImage,
+    )
+}

package/android/src/main/java/com/audiobrowser/extension/ResolvedTrackExt.kt

@@ -2,6 +2,7 @@ package com.audiobrowser.extension
 
 import com.margelo.nitro.audiobrowser.ResolvedTrack
 import com.margelo.nitro.audiobrowser.Track
+import com.margelo.nitro.audiobrowser.TrackStyle
 
 /**
  * The Track view of a ResolvedTrack: every display/playback field carried over, the browse-only
@@ -12,24 +13,35 @@ import com.margelo.nitro.audiobrowser.Track
 fun ResolvedTrack.toTrack(): Track =
   Track(
     id = id,
-    url = url,
+    path = path,
     src = src,
     artwork = artwork,
     artworkSource = artworkSource,
     request = request,
-    artworkCarPlayTinted = artworkCarPlayTinted,
     title = title,
     subtitle = subtitle,
     artist = artist,
-    albumUrl = albumUrl,
+    albumPath = albumPath,
     album = album,
     description = description,
     genre = genre,
     duration = duration,
-    style = style,
-    childrenStyle = childrenStyle,
+    // An explicit SectionStyle → TrackStyle projection: the page's container
+    // properties (gridWrap) have no meaning on a plain Track, so they drop —
+    // Nitro flattens the spec's `extends`, making this narrowing a hand-written
+    // field list rather than an upcast (ADR 0011).
+    style =
+      style?.let {
+        TrackStyle(
+          display = it.display,
+          artworkRendering = it.artworkRendering,
+          imageShape = it.imageShape,
+          accessorySymbol = it.accessorySymbol,
+          cardTint = it.cardTint,
+          cardImage = it.cardImage,
+        )
+      },
+    disabled = disabled,
     favorited = favorited,
-    groupTitle = groupTitle,
     live = live,
-    imageRow = imageRow,
   )

package/android/src/main/java/com/audiobrowser/extension/TappedTrack.kt

@@ -0,0 +1,20 @@
+package com.audiobrowser.extension
+
+import com.audiobrowser.util.BrowserPathHelper
+import com.margelo.nitro.audiobrowser.Track
+
+/**
+ * The queue position of the tapped surface, for skip-in-place. Exact-surface match first: a
+ * contextual path carries the tapped page position (`__index`), so path equality pins the exact
+ * copy when the page holds the same identity more than once. The identity match remains for
+ * index-less paths (e.g. pre-stamp persisted state); an index-stamped path with no exact match
+ * returns -1, and the caller falls through to expansion, which re-scopes the queue to the tapped
+ * section (ADR 0009).
+ */
+fun Array<Track>.indexOfTappedTrack(contextualPath: String, trackId: String?): Int {
+  val index = indexOfFirst { it.path == contextualPath }
+  if (index >= 0 || BrowserPathHelper.extractIndex(contextualPath) != null || trackId == null) {
+    return index
+  }
+  return indexOfFirst { it.identity == trackId }
+}

package/android/src/main/java/com/audiobrowser/extension/TrackIdentity.kt

@@ -0,0 +1,15 @@
+package com.audiobrowser.extension
+
+import com.margelo.nitro.audiobrowser.Track
+
+/**
+ * A track's identity: the opaque `id` when present (non-blank), else the playable `src`. Two tracks
+ * refer to the same item iff their identities are equal. Browsable-only tracks (neither `id` nor
+ * `src`) have no identity — they are addressed by `path` instead.
+ *
+ * This is THE comparison rule for favorites matching, section scoping, skip-in-place, the car
+ * now-playing row indicator, and the contextual `__trackId` — see ADR 0008. Mirrors the TS
+ * `trackIdentity` helper.
+ */
+val Track.identity: String?
+  get() = id?.takeUnless { it.isBlank() } ?: src

package/android/src/main/java/com/audiobrowser/model/PlayerUpdateOptions.kt

@@ -20,7 +20,7 @@ data class PlayerUpdateOptions(
   var progressUpdateEventInterval: Double? = null,
 
   // Player capabilities - most enabled by default, only false values disable
-  // Exceptions: bookmark, jumpForward, jumpBackward default to false
+  // Exceptions: jumpForward, jumpBackward default to false
   var capabilities: PlayerCapabilities =
     PlayerCapabilities(
       play = null,

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

@@ -12,6 +12,10 @@ import androidx.media3.session.SessionCommand
 import androidx.media3.session.SessionError
 import androidx.media3.session.SessionResult
 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.util.BrowserPathHelper
 import com.audiobrowser.util.RatingFavorites
@@ -27,6 +31,8 @@ import com.margelo.nitro.audiobrowser.NativeGateRequest
 import com.margelo.nitro.audiobrowser.PlayerCapabilities
 import com.margelo.nitro.audiobrowser.RemoteButtonLayout
 import com.margelo.nitro.audiobrowser.SearchParams
+import com.margelo.nitro.audiobrowser.Section
+import com.margelo.nitro.audiobrowser.StyleDisplay
 import com.margelo.nitro.audiobrowser.Track
 import kotlinx.coroutines.CancellationException
 import kotlinx.coroutines.CoroutineScope
@@ -191,12 +197,17 @@ class MediaSessionCallback(private val player: Player) :
     command: SessionCommand,
     args: Bundle,
   ): ListenableFuture<SessionResult> {
-    // Handle favorite button tap
+    // 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.
     if (command.customAction == MediaSessionCommandManager.CUSTOM_ACTION_FAVORITE) {
-      val currentFavorited = player.currentTrack?.favorited ?: false
-      Timber.d("Favorite button tapped - toggling from $currentFavorited to ${!currentFavorited}")
-      player.setActiveTrackFavorited(!currentFavorited)
-      return Futures.immediateFuture(SessionResult(SessionResult.RESULT_SUCCESS))
+      val applied = player.toggleActiveTrackFavorited()
+      Timber.d("Favorite button tapped - toggle applied=$applied")
+      return Futures.immediateFuture(
+        SessionResult(
+          if (applied) SessionResult.RESULT_SUCCESS else SessionResult.RESULT_ERROR_INVALID_STATE
+        )
+      )
     }
 
     if (commandManager.handleCustomCommand(command, player)) {
@@ -212,8 +223,16 @@ class MediaSessionCallback(private val player: Player) :
   ): ListenableFuture<SessionResult> {
     // A heart rating from a controller (e.g. Google Assistant "I like this") toggles the
     // now-playing favorite. setActiveTrackFavorited fires onFavoriteChanged so the consumer
-    // persists it — the same path as the notification / CarPlay heart button.
-    RatingFavorites.favoritedFor(rating)?.let { player.setActiveTrackFavorited(it) }
+    // persists it — the same path as the notification / CarPlay heart button. Report an honest
+    // result (see onCustomCommand): INVALID_STATE when there is no current track to favorite.
+    RatingFavorites.favoritedFor(rating)?.let { favorited ->
+      val applied = player.setActiveTrackFavorited(favorited)
+      return Futures.immediateFuture(
+        SessionResult(
+          if (applied) SessionResult.RESULT_SUCCESS else SessionResult.RESULT_ERROR_INVALID_STATE
+        )
+      )
+    }
     return super.onSetRating(session, controller, rating)
   }
 
@@ -238,13 +257,11 @@ class MediaSessionCallback(private val player: Player) :
     }
 
     if (params?.isRecent == true) {
-      // TODO: support recent queries through something like onRecent and return a MediaItem with
-      // .setMediaId("__RECENT__") here - when onRecent is not configured we can keep returning an
-      // error here:
-
-      // The service currently does not support playback resumption. Tell System UI by returning
-      // an error of type 'RESULT_ERROR_NOT_SUPPORTED' for a `params.isRecent` request. See
-      // https://github.com/androidx/media/issues/355
+      // Playback resumption is served by media3 itself: it intercepts System UI's EXTRA_RECENT
+      // root request internally and answers through onPlaybackResumption, so that request never
+      // reaches this callback. Any other browser asking for a recent root gets
+      // ERROR_NOT_SUPPORTED — there is no browsable recents tree; recents are ordinary consumer
+      // content (a tab or route).
       return Futures.immediateFuture(LibraryResult.ofError(SessionError.ERROR_NOT_SUPPORTED))
     }
 
@@ -271,7 +288,7 @@ class MediaSessionCallback(private val player: Player) :
     params: MediaLibraryService.LibraryParams?,
   ): ListenableFuture<LibraryResult<ImmutableList<MediaItem>>> {
     Timber.d(
-      "onGetChildren: {parentId: $parentId, page: $page, pageSize: $pageSize, isSearchPath: ${BrowserPathHelper.isSpecialPath(parentId)} }"
+      "onGetChildren: {parentId: $parentId, page: $page, pageSize: $pageSize, isSpecialPath: ${BrowserPathHelper.isSpecialPath(parentId)} }"
     )
     return scope.future {
       // Wait for browser to be registered if it's not available yet
@@ -325,30 +342,28 @@ class MediaSessionCallback(private val player: Player) :
 
       try {
         val children =
-          if (parentId == BrowserPathHelper.RECENT_PATH) {
-            // TODO: implement recent media items
-            emptyList<MediaItem>()
-          } else if (parentId == BrowserPathHelper.ROOT_PATH) {
+          if (parentId == BrowserPathHelper.ROOT_PATH) {
             // Return tabs as root children (limited to 4 for automotive platform compatibility)
             // TODO: Check what Android Auto does with empty tabs list - may need to return error?
-            val tabs = browserManager.queryTabs()
+            // Disabled tabs hide (Track.disabled) — filtered before the cap so
+            // an unavailable tab never costs an available one its slot.
+            val tabs = browserManager.queryTabs().filterNot { it.disabled == true }
             if (tabs.size > 4) {
               Timber.w(
                 "Root has ${tabs.size} tabs; dropping ${tabs.size - 4} (Android Auto root limit)"
               )
             }
-            toMediaItems(tabs.take(4))
+            toFlatMediaItems(tabs.take(4))
           } else {
-            // Resolve the specific path and get its children
+            // 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).
             val resolvedTrack = browserManager.resolve(parentId)
-
-            // Convert children to MediaItems (url is already set to contextual URL)
-            val trackChildren =
-              resolvedTrack.children
-                ?: throw IllegalStateException(
-                  "Expected browsed ResolvedTrack to have a children array"
-                )
-            toMediaItems(trackChildren.toList())
+            val sections =
+              resolvedTrack.styleResolvedSections()
+                ?: throw IllegalStateException("Expected browsed ResolvedTrack to have sections")
+            browserManager.warnIfGridPageLacksPromise(parentId, sections)
+            toMediaItems(sections)
           }
 
         LibraryResult.ofItemList(ImmutableList.copyOf(children.paginate(page, pageSize)), params)
@@ -402,19 +417,45 @@ class MediaSessionCallback(private val player: Player) :
   }
 
   /**
-   * Converts tracks to MediaItems for browse delivery, routing http(s) artwork through the
-   * content:// provider so Android Auto can load it via the ArtworkContentProvider. Image-row
-   * tracks (a CarPlay-only rendering) are expanded into their items as regular grouped rows first —
-   * see [TrackFactory.expandImageRows].
+   * Flattens a page's sections to MediaItems for browse delivery — the Media3 boundary where
+   * sections die (ADR 0010): the MediaBrowser protocol has no section node, so each child is
+   * stamped with its owning section's title/style hints. A grid-displayed section with a `path`
+   * gains a browsable "view all" link under the same header. Http(s) artwork routes through the
+   * content:// provider so Android Auto can load it via the ArtworkContentProvider.
    */
-  private fun toMediaItems(tracks: List<Track>): List<MediaItem> {
+  private fun toMediaItems(sections: List<Section>): List<MediaItem> {
     val registry = player.browseArtworkRegistry
     val authority = com.audiobrowser.util.ArtworkUris.authorityFor(player.context.packageName)
-    return TrackFactory.expandImageRows(tracks).map {
-      TrackFactory.toBrowseMediaItem(it, registry, authority)
+    return sections.flatMap { section ->
+      // Android Auto has no disabled affordance, so an unavailable track hides
+      // — never a normal-looking dead row (Track.disabled's rendering ladder).
+      val visibleChildren = section.children.filter { it.disabled != true }
+      val items =
+        visibleChildren.map { TrackFactory.toBrowseMediaItem(it, registry, authority, section) }
+      val isTileSection = section.style?.display == StyleDisplay.GRID
+      // No "view all" under an empty section — CarPlay skips empty sections
+      // outright, and a lone navigation tile under a header is a dead end.
+      if (isTileSection && section.path != null && visibleChildren.isNotEmpty()) {
+        items +
+          TrackFactory.toBrowseMediaItem(
+            TrackFactory.navigationTrack(section),
+            registry,
+            authority,
+            section,
+          )
+      } else {
+        items
+      }
     }
   }
 
+  /**
+   * Flat lists (tabs, search results) convert as one untitled list section — which contributes no
+   * group or style hints — so exactly one Track→MediaItem path exists at the Media3 boundary.
+   */
+  private fun toFlatMediaItems(tracks: List<Track>): List<MediaItem> =
+    toMediaItems(listOf(untitledSection(tracks.toTypedArray())))
+
   override fun onGetItem(
     session: MediaLibraryService.MediaLibrarySession,
     browser: MediaSession.ControllerInfo,
@@ -451,7 +492,7 @@ class MediaSessionCallback(private val player: Player) :
         return@future LibraryResult.ofItem(createGateMediaItem(outcome.chrome!!), null)
       }
 
-      if (mediaId == BrowserPathHelper.ROOT_PATH || mediaId == BrowserPathHelper.RECENT_PATH) {
+      if (mediaId == BrowserPathHelper.ROOT_PATH) {
         return@future LibraryResult.ofItem(
           MediaItem.Builder()
             .setMediaId(mediaId)
@@ -466,7 +507,7 @@ class MediaSessionCallback(private val player: Player) :
       // Wait for browser to be registered if it's not available yet
       val browserManager = player.awaitBrowser().browserManager
 
-      // Serve tracks from the track cache first (keyed by url and src). Besides avoiding an HTTP
+      // Serve tracks from the track cache first (keyed by path and src). Besides avoiding an HTTP
       // resolve, this keeps item identity correct for contextual mediaIds: resolve() strips
       // __trackId and would return the *parent container's* metadata as the item.
       val browseAuthority =
@@ -628,7 +669,12 @@ class MediaSessionCallback(private val player: Player) :
       try {
         // Execute search (automatically caches results at /__search?q=query)
         val searchResults = browserManager.search(query)
-        val resultCount = searchResults.children?.size ?: 0
+        // 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'")
 
@@ -681,14 +727,9 @@ class MediaSessionCallback(private val player: Player) :
       try {
         // Get cached search results from BrowserManager
         browserManager.getCachedSearchResults(query)?.let { tracks ->
-          // Convert to MediaItems
-          val searchAuthority =
-            com.audiobrowser.util.ArtworkUris.authorityFor(player.context.packageName)
-          val mediaItems =
-            tracks.map { track ->
-              Timber.d("Search result: ${track.title} (url=${track.url}, src=${track.src})")
-              TrackFactory.toBrowseMediaItem(track, player.browseArtworkRegistry, searchAuthority)
-            }
+          // 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")
@@ -737,26 +778,28 @@ class MediaSessionCallback(private val player: Player) :
 
       val browserManager = audioBrowser.browserManager
 
-      // A single tapped item resolves to the contextual url of the list it was
+      // A single tapped item resolves to the contextual path of the list it was
       // tapped in: directly for contextual mediaIds, via the track cache for
-      // stable-id mediaIds (see BrowserManager.contextualUrlFor). A search
+      // stable-id mediaIds (see BrowserManager.contextualPathFor). A search
       // selection is not a list tap — its queue comes from the search results
       // (resolveMediaItemsForPlayback), never from a browsed container.
-      val singleContextualUrl =
+      val singleContextualPath =
         mediaItems
           .singleOrNull()
           ?.takeIf { it.requestMetadata.searchQuery == null }
-          ?.let { browserManager.contextualUrlFor(it.mediaId) }
+          ?.let { browserManager.contextualPathFor(it.mediaId) }
 
       // Check if this is a single item from the current queue source
-      if (singleContextualUrl != null) {
-        val parentPath = BrowserPathHelper.stripTrackId(singleContextualUrl)
-        val trackId = BrowserPathHelper.extractTrackId(singleContextualUrl)
+      if (singleContextualPath != null) {
+        val parentPath = BrowserPathHelper.stripTrackId(singleContextualPath)
+        val trackId = BrowserPathHelper.extractTrackId(singleContextualPath)
 
-        // Check if queue already came from this parent path - just skip to the track
+        // Check if queue already came from this parent path - just skip to the
+        // tapped surface (exact path first, identity for index-less paths —
+        // see indexOfTappedTrack)
         if (trackId != null && parentPath == player.queueSourcePath) {
           val queueTracks = withContext(Dispatchers.Main) { player.tracks }
-          val index = queueTracks.indexOfFirst { it.src == trackId }
+          val index = queueTracks.indexOfTappedTrack(singleContextualPath, trackId)
           if (index >= 0) {
             Timber.d("Queue already from $parentPath, skipping to index $index")
             val track = queueTracks[index]
@@ -788,9 +831,10 @@ class MediaSessionCallback(private val player: Player) :
         result.startIndex.toDouble(),
         ::currentPlayerState,
       ) {
-        // If this was a contextual URL expansion, track the source path (only for default behavior)
-        if (singleContextualUrl != null) {
-          val parentPath = BrowserPathHelper.stripTrackId(singleContextualUrl)
+        // If this was a contextual path expansion, track the source path (only for default
+        // behavior)
+        if (singleContextualPath != null) {
+          val parentPath = BrowserPathHelper.stripTrackId(singleContextualPath)
           withContext(Dispatchers.Main) { player.queueSourcePath = parentPath }
         }
         result
@@ -829,6 +873,15 @@ class MediaSessionCallback(private val player: Player) :
             throw IllegalStateException("No playback state to resume")
           }
 
+      // The persisted track can carry `disabled` — it became unavailable after
+      // it was saved. A disabled track never plays, resumption included
+      // (Track.disabled); failing the future refuses without touching the
+      // player.
+      if (state.track.disabled == true) {
+        Timber.w("Refusing resumption of disabled track: ${state.track.title}")
+        throw IllegalStateException("Persisted track is disabled")
+      }
+
       // 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.
@@ -844,14 +897,14 @@ class MediaSessionCallback(private val player: Player) :
       // restore() sets player properties which must happen on main thread
       withContext(Dispatchers.Main) { player.playbackStateStore.restore() }
 
-      val url = state.track.url
-      Timber.d("Resuming from url=$url, positionMs=${state.positionMs}")
+      val path = state.track.path
+      Timber.d("Resuming from path=$path, positionMs=${state.positionMs}")
 
       // Wait for browser to be available (JS needs to have configured it)
       val browserManager = player.awaitBrowser().browserManager
 
-      // Try to expand the URL into a full queue
-      val expanded = url?.let { browserManager.expandQueueFromContextualUrl(it) }
+      // Try to expand the path into a full queue
+      val expanded = path?.let { browserManager.expandQueueFromContextualPath(it) }
 
       if (expanded != null) {
         val (tracks, selectedIndex) = expanded
@@ -859,9 +912,9 @@ class MediaSessionCallback(private val player: Player) :
           "Restored ${tracks.size} tracks, starting at index $selectedIndex at ${state.positionMs}ms"
         )
 
-        // Track the source path if this was a contextual URL expansion
-        if (BrowserPathHelper.isContextual(url)) {
-          val parentPath = BrowserPathHelper.stripTrackId(url)
+        // 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 }
         }