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

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

@@ -20,6 +20,7 @@ import com.audiobrowser.browser.displayArtworkSource
 import com.audiobrowser.browser.resolveArtworkUrl
 import com.audiobrowser.browser.unattributedArtworkSource
 import com.audiobrowser.extension.NumberExt.Companion.toSeconds
+import com.audiobrowser.extension.identity
 import com.audiobrowser.model.PlayerSetupOptions
 import com.audiobrowser.model.PlayerUpdateOptions
 import com.audiobrowser.util.CoilBitmapLoader
@@ -36,7 +37,6 @@ import com.margelo.nitro.audiobrowser.ImageSource
 import com.margelo.nitro.audiobrowser.NativeGateRequest
 import com.margelo.nitro.audiobrowser.NowPlayingMetadata
 import com.margelo.nitro.audiobrowser.Playback
-import com.margelo.nitro.audiobrowser.PlaybackActiveTrackChangedEvent
 import com.margelo.nitro.audiobrowser.PlaybackError
 import com.margelo.nitro.audiobrowser.PlaybackPlayWhenReadyChangedEvent
 import com.margelo.nitro.audiobrowser.PlaybackProgressUpdatedEvent
@@ -351,7 +351,7 @@ class Player(internal val context: Context) {
     get() = exoPlayer.nextMediaItemIndex == C.INDEX_UNSET
 
   /**
-   * The source path from which the current queue was expanded (e.g., from a contextual URL). Used
+   * The source path from which the current queue was expanded (e.g., from a contextual path). Used
    * to avoid re-expanding the queue when selecting tracks from the same source.
    */
   var queueSourcePath: String? = null
@@ -657,7 +657,7 @@ class Player(internal val context: Context) {
    * @param tracks The tracks to set as the new queue.
    * @param startIndex The index to start playback from (default: 0).
    * @param startPositionMs The position in milliseconds to start from (default: 0).
-   * @param sourcePath Optional path from which this queue was expanded (for contextual URL
+   * @param sourcePath Optional path from which this queue was expanded (for contextual path
    *   optimization).
    */
   fun setQueue(
@@ -685,17 +685,27 @@ class Player(internal val context: Context) {
   /**
    * Sets the favorited state of the currently playing track. Updates the heart icon in media
    * controllers without interrupting playback.
+   *
+   * @return whether the gesture applied — false only when there is no current track (nothing to
+   *   favorite), so MediaSession callers can report an invalid state instead of a success the
+   *   controller then watches revert.
    */
-  fun setActiveTrackFavorited(favorited: Boolean) {
-    val currentTrack = this.currentTrack ?: return
+  fun setActiveTrackFavorited(favorited: Boolean): Boolean {
+    val currentTrack = this.currentTrack ?: return false
 
     // Persist to the native favorites cache regardless of player state — the
     // user's gesture is durable even when there's no active media item to
-    // update (queue tear-down, between-track gaps, etc.).
-    currentTrack.src?.let { src -> browser?.browserManager?.updateFavorite(src, favorited) }
+    // update (queue tear-down, between-track gaps, etc.). Keyed by the track
+    // identity (id when non-blank, else src).
+    currentTrack.identity?.let { identity ->
+      browser?.browserManager?.updateFavorite(identity, favorited)
+    }
 
+    // Cache written above: the gesture is durably recorded even without a media
+    // item to restamp (queue tear-down, between-track gaps) — that counts as
+    // applied; there is also no visible heart to revert in that state.
     val index = exoPlayer.currentMediaItemIndex
-    if (index == C.INDEX_UNSET) return
+    if (index == C.INDEX_UNSET) return true
 
     // Create updated Track with new favorited state
     val updatedTrack = currentTrack.copy(favorited = favorited)
@@ -719,28 +729,23 @@ class Player(internal val context: Context) {
     // Update the heart button icon in notification/Android Auto
     updateFavoriteButtonState(favorited)
 
-    // Notify JS of the favorite state change
+    // Notify JS of the favorite state change. This is the ONLY emit: a favorite
+    // toggle is an in-place mutation of the active track, not a transition —
+    // onPlaybackActiveTrackChanged / onPlaybackQueueChanged stay
+    // transition-only, and the useActiveTrack / useQueue hooks subscribe to
+    // onFavoriteChanged themselves.
     callbacks?.onFavoriteChanged(FavoriteChangedEvent(updatedTrack, favorited))
-
-    // Emit active track changed so useActiveTrack() hook updates
-    val activeTrackEvent =
-      PlaybackActiveTrackChangedEvent(
-        lastIndex = index.toDouble(),
-        lastTrack = currentTrack,
-        lastPosition = exoPlayer.currentPosition.toSeconds(),
-        index = index.toDouble(),
-        track = updatedTrack,
-      )
-    callbacks?.onPlaybackActiveTrackChanged(activeTrackEvent)
-
-    // Emit queue changed so useQueue() hook updates
-    callbacks?.onPlaybackQueueChanged(tracks)
+    return true
   }
 
-  /** Toggles the favorited state of the currently playing track. */
-  fun toggleActiveTrackFavorited() {
-    val currentTrack = this.currentTrack ?: return
-    setActiveTrackFavorited(currentTrack.favorited != true)
+  /**
+   * Toggles the favorited state of the currently playing track.
+   *
+   * @return whether the toggle applied — false when there is no current track.
+   */
+  fun toggleActiveTrackFavorited(): Boolean {
+    val currentTrack = this.currentTrack ?: return false
+    return setActiveTrackFavorited(currentTrack.favorited != true)
   }
 
   // MARK: - Now Playing Metadata
@@ -926,10 +931,23 @@ class Player(internal val context: Context) {
     }
   }
 
-  /** Jump to the live edge (default position) of a live item; no-op otherwise. */
+  /**
+   * Jump to the live edge of the current track; no-op unless it declares `live` — the track's own
+   * declaration is the gate (matching iOS and the spec), not ExoPlayer's stream-derived liveness,
+   * which never marks progressive ICY radio live. A stream with a live window seeks to its edge;
+   * anything else reconnects — for a non-seekable stream a fresh connection IS the live edge. A
+   * stale URL recovers through the failure-armed re-resolve in [TransformingDataSource].
+   */
   fun seekToLiveEdge() {
+    if (currentTrack?.live != true) return
     if (exoPlayer.isCurrentMediaItemLive) {
       exoPlayer.seekToDefaultPosition()
+    } else {
+      // ExoPlayer.prepare() only re-prepares from STATE_IDLE, hence the raw stop() — not
+      // Player.stop(), which would drop the play intent this reconnect must preserve.
+      exoPlayer.stop()
+      exoPlayer.seekToDefaultPosition()
+      exoPlayer.prepare()
     }
   }
 
@@ -1249,8 +1267,8 @@ class Player(internal val context: Context) {
 
     if (capabilitiesChanged) {
       // The `favorite` capability is the single favoriting switch — propagate
-      // its match mode to the browser so it can hydrate row hearts.
-      browser?.browserManager?.setFavoriteMatch(options.capabilities.favoriteMatch)
+      // it to the browser so it can hydrate row hearts.
+      browser?.browserManager?.setFavoriteEnabled(options.capabilities.favoriteEnabled)
     }
 
     if (progressUpdateEventIntervalChanged) {

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

@@ -1,20 +1,7 @@
 package com.audiobrowser.player
 
-import com.margelo.nitro.audiobrowser.FavoritesMatchMode
 import com.margelo.nitro.audiobrowser.PlayerCapabilities
 
-/**
- * Resolved favorite match mode, or null when favoriting is disabled.
- *
- * `false`/unset → null; `true` → EXACT; `{ match }` → that match.
- */
-val PlayerCapabilities.favoriteMatch: FavoritesMatchMode?
-  get() =
-    favorite?.match(
-      first = { enabled -> if (enabled) FavoritesMatchMode.EXACT else null },
-      second = { config -> config.match },
-    )
-
-/** Whether the favorite/like control is enabled. */
+/** Whether the favorite/like control is enabled. Opt-in: only an explicit `true` enables it. */
 val PlayerCapabilities.favoriteEnabled: Boolean
-  get() = favoriteMatch != null
+  get() = favorite == true

package/android/src/main/java/com/audiobrowser/util/BrowserPathHelper.kt

@@ -8,14 +8,19 @@ import java.net.URLEncoder
  * Utility for handling browser paths and contextual URLs in the media browser system.
  *
  * Handles two types of special paths:
- * 1. System paths (prefixed with `/__`): Root, recent, and search paths
+ * 1. System paths (prefixed with `/__`): root, search, offline, error, and gate paths
  * 2. Contextual URLs: Embed parent context in track identifiers for Media3 integration
  *
- * Contextual URL format: `{parentPath}?__trackId={trackSrc}` Example:
- * "/library/radio?__trackId=song.mp3"
+ * Contextual URL format: `{parentPath}?__trackId={trackIdentity}&__index={childIndex}` (the
+ * identity is the track's `id` when non-blank, else its `src`) Example:
+ * "/library/radio?__trackId=song.mp3&__index=2"
+ *
+ * `__trackId` is the identity check; `__index` (the child's position on the page at stamp time) is
+ * only a tie-breaker between surfaces that carry the same identity — a stale index never selects a
+ * different track.
  *
  * This allows:
- * - Media3 to reference playable-only tracks (tracks with `src` but no `url`)
+ * - Media3 to reference playable-only tracks (tracks with `src` but no `path`)
  * - Cache lookup to work consistently
  * - Parent context to be preserved for queue restoration
  */
@@ -23,9 +28,6 @@ object BrowserPathHelper {
   /** Root path for media browsing */
   const val ROOT_PATH = "/__root"
 
-  /** Recent media path for playback resumption */
-  const val RECENT_PATH = "/__recent"
-
   /** Search path prefix (full path is /__search?q=query) */
   const val SEARCH_PATH_PREFIX = "/__search"
 
@@ -41,9 +43,12 @@ object BrowserPathHelper {
   // Query parameter name for contextual track identifiers
   private const val CONTEXTUAL_TRACK_PARAM = "__trackId"
 
+  // Query parameter name for the tapped child's page position (tie-breaker)
+  private const val CONTEXTUAL_INDEX_PARAM = "__index"
+
   /** Check if a path is a special system path (not a regular navigation path) */
   fun isSpecialPath(path: String): Boolean {
-    return path == ROOT_PATH || path == RECENT_PATH || path.startsWith("$SEARCH_PATH_PREFIX?")
+    return path == ROOT_PATH || path.startsWith("$SEARCH_PATH_PREFIX?")
   }
 
   /** Create a search path for a given query */
@@ -63,13 +68,13 @@ object BrowserPathHelper {
   }
 
   /**
-   * Strips the __trackId parameter from a contextual URL to get the parent path. If the URL is not
-   * contextual, returns it unchanged.
+   * Strips the contextual parameters (__trackId and __index) from a contextual URL to get the
+   * parent path. If the URL is not contextual, returns it unchanged.
    *
    * @param url The URL to process
-   * @return The URL without the __trackId parameter
+   * @return The URL without the contextual parameters
    *
-   * Example: "/library/radio?__trackId=song.mp3" → "/library/radio" Example:
+   * Example: "/library/radio?__trackId=song.mp3&__index=2" → "/library/radio" Example:
    * "/search?q=jazz&__trackId=song.mp3" → "/search?q=jazz"
    */
   fun stripTrackId(url: String): String {
@@ -79,13 +84,13 @@ object BrowserPathHelper {
 
     val uri = url.toUri()
 
-    // Build URL preserving everything except __trackId parameter
+    // Build URL preserving everything except the contextual parameters
     val builder = uri.buildUpon()
     builder.clearQuery()
 
-    // Re-add all query params except __trackId
+    // Re-add all query params except __trackId and __index
     uri.queryParameterNames.forEach { paramName ->
-      if (paramName != CONTEXTUAL_TRACK_PARAM) {
+      if (paramName != CONTEXTUAL_TRACK_PARAM && paramName != CONTEXTUAL_INDEX_PARAM) {
         uri.getQueryParameters(paramName).forEach { value ->
           builder.appendQueryParameter(paramName, value)
         }
@@ -96,19 +101,21 @@ object BrowserPathHelper {
   }
 
   /**
-   * Builds a contextual URL by appending a track identifier to a parent path. Handles existing
-   * query parameters correctly.
+   * Builds a contextual URL by appending a track identifier — and optionally the tapped child's
+   * page position — to a parent path. Handles existing query parameters correctly.
    *
    * @param parentPath The parent container path
-   * @param trackId The track identifier (typically the `src` value)
-   * @return A contextual URL combining parent path and track ID
+   * @param trackId The track identity (`id` when non-blank, else `src` — see Track.identity)
+   * @param index The child's position on the page at stamp time (tie-breaker)
+   * @return A contextual URL combining parent path, track ID, and index
    *
-   * Example: build("/library", "song.mp3") → "/library?__trackId=song.mp3" Example:
+   * Example: build("/library", "song.mp3", 2) → "/library?__trackId=song.mp3&__index=2" Example:
    * build("/search?q=jazz", "song.mp3") → "/search?q=jazz&__trackId=song.mp3"
    */
-  fun build(parentPath: String, trackId: String): String {
+  fun build(parentPath: String, trackId: String, index: Int? = null): String {
     val separator = if (parentPath.contains('?')) '&' else '?'
-    return "$parentPath$separator$CONTEXTUAL_TRACK_PARAM=${Uri.encode(trackId)}"
+    val indexParam = if (index != null) "&$CONTEXTUAL_INDEX_PARAM=$index" else ""
+    return "$parentPath$separator$CONTEXTUAL_TRACK_PARAM=${Uri.encode(trackId)}$indexParam"
   }
 
   /**
@@ -129,6 +136,21 @@ object BrowserPathHelper {
     return uri.getQueryParameter(CONTEXTUAL_TRACK_PARAM)
   }
 
+  /**
+   * Extracts the stamped page index from a contextual URL, or null when the URL is not contextual
+   * or carries no (valid, non-negative) index.
+   *
+   * Example: "/library/radio?__trackId=song.mp3&__index=2" → 2
+   */
+  fun extractIndex(path: String): Int? {
+    if (!isContextual(path)) {
+      return null
+    }
+
+    val raw = Uri.parse(path).getQueryParameter(CONTEXTUAL_INDEX_PARAM) ?: return null
+    return raw.toIntOrNull()?.takeIf { it >= 0 }
+  }
+
   /**
    * Combines a base URL with a path, ensuring proper slash handling.
    *
@@ -158,22 +180,4 @@ object BrowserPathHelper {
     val normalizedPath = path.trimStart('/')
     return "$normalizedBase$normalizedPath"
   }
-
-  /**
-   * True if [segment] appears in [path] as a complete path segment — bounded on the left by the
-   * string start or `/`, and on the right by the string end or one of `/`, `?`, `#`.
-   */
-  fun containsSegment(path: String, segment: String): Boolean {
-    if (segment.isEmpty()) return false
-    var from = 0
-    while (true) {
-      val idx = path.indexOf(segment, from)
-      if (idx < 0) return false
-      val beforeOk = idx == 0 || path[idx - 1] == '/'
-      val end = idx + segment.length
-      val afterOk = end == path.length || path[end] == '/' || path[end] == '?' || path[end] == '#'
-      if (beforeOk && afterOk) return true
-      from = idx + 1
-    }
-  }
 }

package/android/src/main/java/com/audiobrowser/util/MediaExtrasBuilder.kt

@@ -2,30 +2,31 @@ package com.audiobrowser.util
 
 import android.os.Bundle
 import androidx.media.utils.MediaConstants
-import com.margelo.nitro.audiobrowser.ResolvedTrack
+import com.margelo.nitro.audiobrowser.Section
+import com.margelo.nitro.audiobrowser.StyleDisplay
 import com.margelo.nitro.audiobrowser.Track
-import com.margelo.nitro.audiobrowser.TrackStyle
 
 /** Builds MediaMetadata extras bundle for Android Auto/AAOS content styling. */
 object MediaExtrasBuilder {
 
   /**
-   * Maps TrackStyle to MediaConstants content style value. When artwork is an android.resource://
-   * URI, uses CATEGORY_* variants which add margins around icons (better for small vector icons).
+   * Maps a display mode to the MediaConstants content style value. When artwork is an
+   * android.resource:// URI, uses CATEGORY_* variants which add margins around icons (better for
+   * small vector icons).
    *
    * @see <a href="https://developer.android.com/training/cars/media#default-content-style">Default
    *   content style</a>
    */
-  private fun TrackStyle.toContentStyleValue(artwork: String?): Int {
+  private fun StyleDisplay.toContentStyleValue(artwork: String?): Int {
     val isAndroidResource = artwork?.startsWith("android.resource://") == true
     return when (this) {
-      TrackStyle.LIST ->
+      StyleDisplay.LIST ->
         if (isAndroidResource) {
           MediaConstants.DESCRIPTION_EXTRAS_VALUE_CONTENT_STYLE_CATEGORY_LIST_ITEM
         } else {
           MediaConstants.DESCRIPTION_EXTRAS_VALUE_CONTENT_STYLE_LIST_ITEM
         }
-      TrackStyle.GRID ->
+      StyleDisplay.GRID ->
         if (isAndroidResource) {
           MediaConstants.DESCRIPTION_EXTRAS_VALUE_CONTENT_STYLE_CATEGORY_GRID_ITEM
         } else {
@@ -34,39 +35,43 @@ object MediaExtrasBuilder {
     }
   }
 
-  fun build(track: Track): Bundle =
+  /**
+   * Extras for a track rendered on a browse surface. The owning [section] supplies the Android Auto
+   * group-title header hint (grouping is a per-item advisory in the flat MediaBrowser protocol —
+   * the section dies here, ADR 0010) and, from its page-folded style block, the per-item display
+   * hint: per-item hints derive from the section resolution, never from the track's own `display`,
+   * which is positional (ADR 0011).
+   *
+   * The track's own declared `display` is the page-layout *promise* for the page a browsable track
+   * opens — emitted as the parent-level BROWSABLE/PLAYABLE hint, the only below-root hint
+   * AOSP-derived AAOS media UIs honor. Declared or it doesn't exist: the library never derives a
+   * promise from pages it hasn't resolved, and never back-fills from ones it has.
+   */
+  fun build(track: Track, section: Section? = null): Bundle =
     build(
-      groupTitle = track.groupTitle,
-      style = track.style,
-      childrenStyle = track.childrenStyle,
+      groupTitle = section?.title,
+      itemDisplay = section?.style?.display,
+      promisedDisplay = if (track.src == null) track.style?.display else null,
       artwork = track.artwork?.url,
     )
 
-  fun build(resolvedTrack: ResolvedTrack): Bundle =
-    build(
-      groupTitle = resolvedTrack.groupTitle,
-      style = resolvedTrack.style,
-      childrenStyle = resolvedTrack.childrenStyle,
-      artwork = resolvedTrack.artwork?.url,
-    )
-
   private fun build(
     groupTitle: String?,
-    style: TrackStyle?,
-    childrenStyle: TrackStyle?,
+    itemDisplay: StyleDisplay?,
+    promisedDisplay: StyleDisplay?,
     artwork: String?,
   ): Bundle =
     Bundle().apply {
       groupTitle?.let {
         putString(MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_GROUP_TITLE, it)
       }
-      style?.let {
+      itemDisplay?.let {
         putInt(
           MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_SINGLE_ITEM,
           it.toContentStyleValue(artwork),
         )
       }
-      childrenStyle?.let {
+      promisedDisplay?.let {
         val styleValue = it.toContentStyleValue(artwork)
         putInt(MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_BROWSABLE, styleValue)
         putInt(MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_PLAYABLE, styleValue)

package/android/src/main/java/com/audiobrowser/util/StyleWire.kt

@@ -0,0 +1,35 @@
+package com.audiobrowser.util
+
+import com.margelo.nitro.audiobrowser.ArtworkRendering
+import com.margelo.nitro.audiobrowser.StyleDisplay
+
+/**
+ * The style block's wire strings (ADR 0011) ↔ Nitro enums, shared by the browse decoder and the
+ * playback-state store. Inbound mapping is lenient: an unknown or empty value is "no declaration",
+ * never an error.
+ */
+internal fun StyleDisplay.toWireString(): String =
+  when (this) {
+    StyleDisplay.LIST -> "list"
+    StyleDisplay.GRID -> "grid"
+  }
+
+internal fun ArtworkRendering.toWireString(): String =
+  when (this) {
+    ArtworkRendering.ORIGINAL -> "original"
+    ArtworkRendering.STENCIL -> "stencil"
+  }
+
+internal fun String?.toStyleDisplay(): StyleDisplay? =
+  when (this?.takeIf { it.isNotEmpty() }?.lowercase()) {
+    "list" -> StyleDisplay.LIST
+    "grid" -> StyleDisplay.GRID
+    else -> null
+  }
+
+internal fun String?.toArtworkRendering(): ArtworkRendering? =
+  when (this?.takeIf { it.isNotEmpty() }?.lowercase()) {
+    "original" -> ArtworkRendering.ORIGINAL
+    "stencil" -> ArtworkRendering.STENCIL
+    else -> null
+  }

package/android/src/main/java/com/audiobrowser/util/TrackFactory.kt

@@ -7,17 +7,16 @@ import androidx.media3.common.MediaItem
 import androidx.media3.common.MediaMetadata
 import com.audiobrowser.browser.BrowseArtworkRegistry
 import com.audiobrowser.browser.ResolvedArtwork
-import com.margelo.nitro.audiobrowser.ImageRowItem
+import com.margelo.nitro.audiobrowser.Section
 import com.margelo.nitro.audiobrowser.Track
 import com.margelo.nitro.audiobrowser.TrackStyle
-import com.margelo.nitro.audiobrowser.Variant_String_ArtworkVariants
 
 /**
  * The single Track → Media3 [MediaItem] conversion. Owns the two easy-to-drift fallbacks: the
  * displayed artwork is the transformed `artworkSource.uri` falling back to the raw `artwork` field,
- * and the mediaId is the stable `id` for playable tracks, falling back to `url` then `src` (a Track
- * must have one of the latter two — see the `src` vs `url` note in CONTEXT.md). The list line
- * renders from `subtitle` (the now-playing line is re-stamped from `artist` by the now-playing
+ * and the mediaId is the stable `id` for playable tracks, falling back to `path` then `src` (a
+ * Track must have one of the latter two — see the `src` vs `path` note in CONTEXT.md). The list
+ * line renders from `subtitle` (the now-playing line is re-stamped from `artist` by the now-playing
  * pipeline; see the Now Playing Metadata guide).
  */
 object TrackFactory {
@@ -26,49 +25,35 @@ object TrackFactory {
   }
 
   /**
-   * Android Auto has no image-row rendering; its closest equivalent is a grid of artwork tiles. A
-   * track carrying `imageRow` expands into its items as grid-styled rows (the per-item
-   * content-style hint — hosts that ignore it fall back to list rows) grouped under the row's
-   * title, followed by the row itself as a browsable "view all" link when it has a `url` (a
-   * url-less row is a pure preview and contributes only its items). Tracks without an `imageRow`
-   * pass through unchanged.
+   * A synthetic browsable Track for a section's "view all" surface — the section has a path, title,
+   * and label, but no Track (ADR 0010). It carries the section's declared item block as its own,
+   * `display` included: the section's declaration about this content's layout is the only declared
+   * promise the "view all" page can ever have (there is no consumer-authored handle to declare one
+   * on), and without it Android Auto would always render that page as a list.
    */
-  fun expandImageRows(tracks: List<Track>): List<Track> =
-    tracks.flatMap { track ->
-      val items = track.imageRow
-      if (items.isNullOrEmpty()) return@flatMap listOf(track)
-      val expanded = items.map { it.toTrack(groupTitle = track.title) }
-      if (track.url != null) {
-        expanded + track.copy(imageRow = null, groupTitle = track.title)
-      } else {
-        expanded
-      }
-    }
-
-  /** The row-item equivalent of a full Track, for surfaces that render items as plain rows. */
-  fun ImageRowItem.toTrack(groupTitle: String?): Track =
+  fun navigationTrack(section: Section): Track =
     Track(
-      id = id,
-      url = url,
-      src = src,
-      artwork = artwork?.let { Variant_String_ArtworkVariants.First(it) },
-      artworkSource = artworkSource,
-      request = request,
-      artworkCarPlayTinted = null,
-      title = title,
-      subtitle = null,
-      artist = artist,
-      albumUrl = albumUrl,
-      album = album,
+      id = null,
+      path = section.path,
+      src = null,
+      artwork = null,
+      artworkSource = null,
+      request = null,
+      title = section.title ?: "",
+      subtitle = section.subtitle,
+      artist = null,
+      albumPath = null,
+      album = null,
       description = null,
       genre = null,
       duration = null,
-      style = TrackStyle.GRID,
-      childrenStyle = null,
+      style =
+        section.style?.let {
+          TrackStyle(display = it.display, artworkRendering = it.artworkRendering)
+        },
+      disabled = null,
       favorited = null,
-      groupTitle = groupTitle,
-      live = live,
-      imageRow = null,
+      live = null,
     )
 
   fun toMedia3(tracks: Array<Track>): List<MediaItem> {
@@ -90,10 +75,11 @@ object TrackFactory {
     track: Track,
     registry: BrowseArtworkRegistry,
     authority: String,
+    section: Section? = null,
   ): MediaItem {
     val rawUrl = artworkUri(track) // artworkSource.uri ?: artwork
     val scheme = rawUrl?.let { Uri.parse(it).scheme?.lowercase() }
-    val builder = metadataBuilder(track)
+    val builder = metadataBuilder(track, section)
     if (rawUrl != null && (scheme == "http" || scheme == "https")) {
       val isSvg =
         SvgArtworkRenderer.isSvgUrl(rawUrl) || SvgArtworkRenderer.isSvgUrl(track.artwork?.url)
@@ -109,8 +95,11 @@ object TrackFactory {
   /** The transformed artworkSource wins over the raw artwork field. */
   private fun artworkUri(track: Track): String? = track.artworkSource?.uri ?: track.artwork?.url
 
-  /** All metadata except artwork. */
-  private fun metadataBuilder(track: Track): MediaMetadata.Builder =
+  /**
+   * All metadata except artwork. The owning [section] (browse surfaces only) supplies the
+   * group-title header hint and the per-item style default (ADR 0010).
+   */
+  private fun metadataBuilder(track: Track, section: Section? = null): MediaMetadata.Builder =
     MediaMetadata.Builder()
       .setTitle(track.title)
       .setArtist(track.subtitle)
@@ -119,26 +108,29 @@ object TrackFactory {
       .setGenre(track.genre)
       .setIsBrowsable(track.src == null)
       .setIsPlayable(track.src != null)
-      .setExtras(MediaExtrasBuilder.build(track))
+      .setExtras(MediaExtrasBuilder.build(track, section))
       .apply { track.favorited?.let { setUserRating(HeartRating(it)) } }
 
   private fun buildMediaItem(track: Track, metadata: MediaMetadata): MediaItem {
-    // A playable track's mediaId is the consumer's stable `id` when it has one.
-    // Android Auto marks the "now playing" browse row by exact mediaId equality
-    // between the row and the player's current item (media3 announces
-    // `currentMediaItem.mediaId` in the legacy playback state), and a
+    // A playable track's mediaId is the consumer's stable `id` when it has one —
+    // the identity rule (id when non-blank, else src; see Track.identity /
+    // ADR 0008), except that an id-less playable track prefers its contextual
+    // `path` over `src` here, so this is deliberately NOT expressed via
+    // Track.identity. Android Auto marks the "now playing" browse row by exact
+    // mediaId equality between the row and the player's current item (media3
+    // announces `currentMediaItem.mediaId` in the legacy playback state), and a
     // consumer-loaded track's `src` can differ textually from the browse row's
     // for the same item (absolute vs relative, extra query params) — the id is
     // the one string both sides share. It is also context-free, so the same
     // station gets the same mediaId in every tab. Browsable-only tracks keep
-    // `url` so navigation parentIds stay resolvable paths.
+    // `path` so navigation parentIds stay resolvable paths.
     val stableId = if (track.src != null) track.id?.takeUnless { it.isBlank() } else null
     val mediaId =
       stableId
-        ?: track.url
+        ?: track.path
         ?: track.src
         ?: throw IllegalArgumentException(
-          "Track must have either url or src defined. Track: title='${track.title}', artist='${track.artist}'"
+          "Track must have either path or src defined. Track: title='${track.title}', artist='${track.artist}'"
         )
     return MediaItem.Builder()
       .setMediaId(mediaId)