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

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

@@ -176,15 +176,22 @@ suspend fun BrowserManager.resolveArtworkUrl(
         )
     }
 
-    // `{id}` token substitution, only for a non-empty id. Mirrors iOS substituteTrackId.
+    // `{id}` token substitution. A track without a non-blank id leaves the token LITERALLY in
+    // place — the request then visibly 404s, which is intended (self-describing error trail) —
+    // with a single warning logged below once the URL is built. Mirrors iOS substituteTrackId.
     track.id
       ?.takeIf { it.isNotEmpty() }
       ?.let { transformedConfig = substituteTrackId(transformedConfig, it) }
+    val hasUnfilledIdToken = configContainsIdToken(transformedConfig)
 
     val uri = RequestConfigBuilder.buildUrl(transformedConfig)
     // If URI is empty, there's no valid artwork path
     if (uri.isEmpty()) return null
 
+    if (hasUnfilledIdToken) {
+      Timber.w("nowPlayingArtwork: track has no id — '{id}' left unfilled in %s", uri)
+    }
+
     ImageSource(
       uri = uri,
       method = transformedConfig.method,
@@ -265,15 +272,18 @@ private fun applyImageQueryParams(
   return config.copy(query = (config.query ?: emptyMap()) + contextQuery)
 }
 
+/** The `{id}` template token — see [substituteTrackId] / [configContainsIdToken]. */
+private const val ID_TOKEN = "{id}"
+
 /**
  * Replaces the `{id}` token with the track id in a request config's path, query values, and header
  * values. Used so a `nowPlayingArtwork` like `{ path: "/artwork/{id}" }` resolves. Configs without
  * the token are returned unchanged. Mirrors the iOS `substituteTrackId` helper.
  */
 private fun substituteTrackId(config: RequestConfig, id: String): RequestConfig {
-  fun sub(s: String?): String? = s?.replace("{id}", id)
+  fun sub(s: String?): String? = s?.replace(ID_TOKEN, id)
   fun subMap(m: Map<String, String>?): Map<String, String>? =
-    m?.mapValues { (_, value) -> value.replace("{id}", id) }
+    m?.mapValues { (_, value) -> value.replace(ID_TOKEN, id) }
   return config.copy(
     path = sub(config.path),
     headers = subMap(config.headers),
@@ -281,6 +291,16 @@ private fun substituteTrackId(config: RequestConfig, id: String): RequestConfig
   )
 }
 
+/**
+ * Whether the config still carries an unfilled `{id}` token in its path, query values, or header
+ * values (checked AFTER substitution, so it matches exactly when the track had no non-blank id and
+ * the config uses the token). Mirrors iOS `TrackIdTemplate.containsToken`.
+ */
+private fun configContainsIdToken(config: RequestConfig): Boolean =
+  config.path?.contains(ID_TOKEN) == true ||
+    config.query?.values?.any { it.contains(ID_TOKEN) } == true ||
+    config.headers?.values?.any { it.contains(ID_TOKEN) } == true
+
 /** Builds a headers map, merging explicit headers with userAgent and contentType. */
 private fun buildHeadersMap(
   headers: Map<String, String>?,

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

@@ -1,30 +1,25 @@
 package com.audiobrowser.browser
 
+import com.audiobrowser.util.toArtworkRendering
+import com.audiobrowser.util.toStyleDisplay
 import com.margelo.nitro.audiobrowser.CarPlaySiriListButtonPosition
-import com.margelo.nitro.audiobrowser.ImageRowItem
 import com.margelo.nitro.audiobrowser.ResolvedTrack
+import com.margelo.nitro.audiobrowser.Section
+import com.margelo.nitro.audiobrowser.SectionStyle
 import com.margelo.nitro.audiobrowser.Track
 import com.margelo.nitro.audiobrowser.TrackRequest
 import com.margelo.nitro.audiobrowser.TrackStyle
 import kotlinx.serialization.Serializable
+import kotlinx.serialization.json.JsonElement
+import kotlinx.serialization.json.JsonObject
+import kotlinx.serialization.json.JsonPrimitive
+import kotlinx.serialization.json.booleanOrNull
 
 /**
  * JSON serializable models for parsing API responses. These will be converted to Nitro types after
- * parsing.
+ * parsing. Legacy `groupTitle`/`imageRow` keys in payloads are simply unknown to these models and
+ * decode as ignored dead weight (ADR 0010).
  */
-@Serializable
-data class JsonImageRowItem(
-  val id: String? = null,
-  val url: String? = null,
-  val src: String? = null,
-  val artwork: String? = null,
-  val title: String,
-  val artist: String? = null,
-  val album: String? = null,
-  val albumUrl: String? = null,
-  val live: Boolean? = null,
-  val request: JsonTrackRequest? = null,
-)
 
 /** JSON model for a track's per-request HTTP override (identity/auth/signed-url). */
 @Serializable
@@ -36,25 +31,35 @@ data class JsonTrackRequest(
   fun toNitro(): TrackRequest = TrackRequest(userAgent, headers, query)
 }
 
+/** JSON model for a page section (ADR 0010). */
+@Serializable
+data class JsonSection(
+  val title: String? = null,
+  val subtitle: String? = null,
+  val style: JsonElement? = null,
+  val path: String? = null,
+  val children: List<JsonTrack>,
+)
+
 @Serializable
 data class JsonResolvedTrack(
   val id: String? = null,
-  val url: String,
+  val path: String,
   val title: String,
   val subtitle: String? = null,
   val icon: String? = null,
   val artwork: JsonArtwork? = null,
   val artist: String? = null,
-  val albumUrl: String? = null,
+  val albumPath: String? = null,
   val album: String? = null,
   val description: String? = null,
   val genre: String? = null,
   val duration: Double? = null,
+  val sections: List<JsonSection>? = null,
   val children: List<JsonTrack>? = null,
   val src: String? = null,
-  val style: String? = null,
-  val childrenStyle: String? = null,
-  val groupTitle: String? = null,
+  val style: JsonElement? = null,
+  val disabled: Boolean? = null,
   val live: Boolean? = null,
   val carPlaySiriListButton: String? = null,
 )
@@ -62,34 +67,59 @@ data class JsonResolvedTrack(
 @Serializable
 data class JsonTrack(
   val id: String? = null,
-  val url: String? = null,
+  val path: String? = null,
   val title: String,
   val subtitle: String? = null,
   val icon: String? = null,
   val artwork: JsonArtwork? = null,
   val artist: String? = null,
-  val albumUrl: String? = null,
+  val albumPath: String? = null,
   val album: String? = null,
   val description: String? = null,
   val genre: String? = null,
   val duration: Double? = null,
   val src: String? = null,
   val request: JsonTrackRequest? = null,
-  val style: String? = null,
-  val childrenStyle: String? = null,
-  val groupTitle: String? = null,
+  val style: JsonElement? = null,
+  val disabled: Boolean? = null,
   val live: Boolean? = null,
-  val imageRow: List<JsonImageRowItem>? = null,
 )
 
-/** Convert JSON models to Nitro types */
-private fun String?.toTrackStyle(): TrackStyle? {
-  return when (this?.lowercase()) {
-    "list" -> TrackStyle.LIST
-    "grid" -> TrackStyle.GRID
-    else -> null
+/**
+ * Convert JSON models to Nitro types.
+ *
+ * `style` rides the models as a raw [JsonElement] and maps leniently here — tolerant decoding by
+ * design (ADR 0011): a stale value (the retired string vocabulary), a wrong-typed field, or an
+ * unknown enum value is "no declaration", never a parse failure. A typed field would fail the whole
+ * page, since this decoder is otherwise strict.
+ */
+private fun JsonObject.stringField(key: String): String? =
+  (get(key) as? JsonPrimitive)?.takeIf { it.isString }?.content
+
+/** A strict JSON boolean — a quoted "false" is a wrong-typed field, i.e. no declaration. */
+private fun JsonObject.booleanField(key: String): Boolean? =
+  (get(key) as? JsonPrimitive)?.takeIf { !it.isString }?.booleanOrNull
+
+/**
+ * A block that resolves to no declarations at all — `{}` or all-unknown values — maps to null, so
+ * "no declaration" has one shape on every platform (iOS makes the same collapse).
+ */
+private fun JsonElement?.toTrackStyle(): TrackStyle? =
+  (this as? JsonObject)?.let { obj ->
+    val display = obj.stringField("display").toStyleDisplay()
+    val artworkRendering = obj.stringField("artworkRendering").toArtworkRendering()
+    if (display == null && artworkRendering == null) null
+    else TrackStyle(display = display, artworkRendering = artworkRendering)
+  }
+
+private fun JsonElement?.toSectionStyle(): SectionStyle? =
+  (this as? JsonObject)?.let { obj ->
+    val display = obj.stringField("display").toStyleDisplay()
+    val artworkRendering = obj.stringField("artworkRendering").toArtworkRendering()
+    val gridWrap = obj.booleanField("gridWrap")
+    if (display == null && artworkRendering == null && gridWrap == null) null
+    else SectionStyle(display = display, artworkRendering = artworkRendering, gridWrap = gridWrap)
   }
-}
 
 private fun String?.toCarPlaySiriListButtonPosition(): CarPlaySiriListButtonPosition? {
   return when (this?.lowercase()) {
@@ -99,26 +129,21 @@ private fun String?.toCarPlaySiriListButtonPosition(): CarPlaySiriListButtonPosi
   }
 }
 
-private fun JsonImageRowItem.toNitro(): ImageRowItem {
-  return ImageRowItem(
-    id = id,
-    url = url,
-    src = src,
-    artwork = artwork,
-    artworkSource = null,
+fun JsonSection.toNitro(): Section {
+  return Section(
     title = title,
-    artist = artist,
-    album = album,
-    albumUrl = albumUrl,
-    live = live,
-    request = request?.toNitro(),
+    subtitle = subtitle,
+    style = style.toSectionStyle(),
+    path = path,
+    children = children.map { it.toNitro() }.toTypedArray(),
   )
 }
 
 fun JsonResolvedTrack.toNitro(): ResolvedTrack {
   return ResolvedTrack(
     id = id,
-    url = url,
+    path = path,
+    sections = sections?.map { it.toNitro() }?.toTypedArray(),
     children = children?.map { it.toNitro() }?.toTypedArray(),
     carPlaySiriListButton = carPlaySiriListButton.toCarPlaySiriListButtonPosition(),
     title = title,
@@ -127,45 +152,39 @@ fun JsonResolvedTrack.toNitro(): ResolvedTrack {
     artworkSource = null,
     // Containers carry no per-track media-request override (mirrors iOS JsonResolvedTrack).
     request = null,
-    artworkCarPlayTinted = null,
     artist = artist,
-    albumUrl = albumUrl,
+    albumPath = albumPath,
     album = album,
     description = description,
     genre = genre,
     duration = duration,
     src = src,
-    style = style.toTrackStyle(),
-    childrenStyle = childrenStyle.toTrackStyle(),
+    style = style.toSectionStyle(),
+    disabled = disabled,
     favorited = null,
-    groupTitle = groupTitle,
     live = live,
-    imageRow = null,
   )
 }
 
 fun JsonTrack.toNitro(): Track {
   return Track(
     id = id,
-    url = url,
+    path = path,
     title = title,
     subtitle = subtitle,
     artwork = artwork?.toNitro(),
     artworkSource = null,
     request = request?.toNitro(),
-    artworkCarPlayTinted = null,
     artist = artist,
-    albumUrl = albumUrl,
+    albumPath = albumPath,
     album = album,
     description = description,
     genre = genre,
     duration = duration,
     src = src,
     style = style.toTrackStyle(),
-    childrenStyle = childrenStyle.toTrackStyle(),
+    disabled = disabled,
     favorited = null,
-    groupTitle = groupTitle,
     live = live,
-    imageRow = imageRow?.map { it.toNitro() }?.toTypedArray(),
   )
 }

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,49 @@
+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,
+      gridWrap = section?.gridWrap ?: page?.gridWrap,
+    )
+
+  /**
+   * 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,
+    )
+}

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,25 @@ 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) },
+    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