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

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/InertStyleDiagnostic.kt

@@ -0,0 +1,267 @@
+package com.audiobrowser.browser
+
+import com.audiobrowser.BuildConfig
+import com.audiobrowser.util.toWireString
+import com.margelo.nitro.audiobrowser.GridTile
+import com.margelo.nitro.audiobrowser.Section
+import com.margelo.nitro.audiobrowser.SectionStyle
+import com.margelo.nitro.audiobrowser.StyleDisplay
+import com.margelo.nitro.audiobrowser.TrackStyle
+import timber.log.Timber
+
+/**
+ * Dev diagnostic (ADR 0011): the declarations on a resolved page that can never render.
+ *
+ * The block model deliberately gave up compile-time invalid-combination errors — combinations are
+ * not invalid, they are *inert*, the way `grid-template` on a non-grid element is inert in CSS.
+ * This is the recovery: at page resolution every declaration its own block makes unreadable is
+ * reported once, with the effective context and the fix.
+ *
+ * The line it draws, and never crosses: only **structural** inertness — a declaration the resolved
+ * block itself renders unreadable, on every surface (`gridWrap` outside a grid, `cardTint` with no
+ * card treatment in scope). *Surface* inertness is never reported, because declarations are
+ * aspirational: `imageShape` on Android Auto, or a card treatment on a pre-26 CarPlay, is intended
+ * usage — the renderer drops what it can't draw.
+ *
+ * Runs where every page passes regardless of its source (static config, route callback, or fetched
+ * browse JSON), and only on a cache miss, so a mistake is reported once per resolution rather than
+ * once per serve. Mirrors `ios/Browser/InertStyleDiagnostic.swift`.
+ *
+ * Debug builds only: [warn] is the whole seam, so a release build never even walks the page (the
+ * trade is that a page served only to a release build — an internal track, production browse JSON —
+ * reports nothing; reproduce it against a debug build).
+ */
+object InertStyleDiagnostic {
+  /**
+   * Reports every inert declaration on a resolved page. The one gate — the [BuildConfig] check is
+   * here rather than at the call sites so callers read unconditionally and the rule set stays free
+   * of build-configuration knowledge.
+   */
+  fun warn(path: String, pageStyle: SectionStyle?, sections: List<Section>) {
+    if (!BuildConfig.DEBUG) return
+    findings(path, pageStyle, sections).forEach { Timber.w(it) }
+  }
+
+  /**
+   * The declarations that carry a structural inertness condition.
+   *
+   * Two keys of the block are deliberately absent — `display` and `artworkRendering`, dispositioned
+   * below instead.
+   */
+  private enum class Property(val key: String, val isItemProperty: Boolean) {
+    // Container properties resolve by scope override (`section ?? page`) and never reach an item;
+    // item properties inherit (`track ?? section ?? page`), so they may also be declared per track.
+    GRID_WRAP("gridWrap", isItemProperty = false),
+    GRID_TILE("gridTile", isItemProperty = false),
+    IMAGE_SHAPE("imageShape", isItemProperty = true),
+    ACCESSORY_SYMBOL("accessorySymbol", isItemProperty = true),
+    CARD_TINT("cardTint", isItemProperty = true),
+    CARD_IMAGE("cardImage", isItemProperty = true);
+
+    /**
+     * Whether a value of this property, resolved into [context], has any rendering to affect. Each
+     * branch is the spec's own "inert unless" clause.
+     */
+    fun isInert(context: Context): Boolean =
+      when (this) {
+        GRID_WRAP,
+        GRID_TILE -> !context.isGrid
+        IMAGE_SHAPE -> !context.isGrid || context.isCard
+        ACCESSORY_SYMBOL -> context.isCard
+        CARD_TINT,
+        CARD_IMAGE -> !context.isCard
+      }
+
+    /** The rule the declaration falls foul of, stated positively. */
+    val rule: String
+      get() =
+        when (this) {
+          GRID_WRAP,
+          GRID_TILE -> "`$key` renders only in a grid"
+          IMAGE_SHAPE -> "only plain and condensed tiles have a shape"
+          ACCESSORY_SYMBOL -> "card tiles have no accessory slot"
+          CARD_TINT,
+          CARD_IMAGE -> "the card properties render only under `gridTile: 'card'`"
+        }
+
+    val hint: String
+      get() =
+        when (this) {
+          GRID_WRAP,
+          GRID_TILE -> "Declare `display: 'grid'` on the section or the page, or drop `$key`."
+          IMAGE_SHAPE -> "Render the items as plain or condensed grid tiles, or drop `imageShape`."
+          ACCESSORY_SYMBOL -> "Use `gridTile: 'plain'` or `'condensed'`, or drop `accessorySymbol`."
+          CARD_TINT,
+          CARD_IMAGE -> "Declare `display: 'grid'` with `gridTile: 'card'`, or drop `$key`."
+        }
+
+    fun declaredIn(style: SectionStyle?): Boolean =
+      when (this) {
+        GRID_WRAP -> style?.gridWrap != null
+        GRID_TILE -> style?.gridTile != null
+        IMAGE_SHAPE -> style?.imageShape != null
+        ACCESSORY_SYMBOL -> style?.accessorySymbol != null
+        CARD_TINT -> style?.cardTint != null
+        CARD_IMAGE -> style?.cardImage != null
+      }
+
+    // Nitro flattens the spec's `extends`, so the two blocks share no type — hence two lookups over
+    // the same key set rather than one interface.
+    fun declaredIn(style: TrackStyle?): Boolean =
+      when (this) {
+        // Container properties have no Track slot to be declared in.
+        GRID_WRAP,
+        GRID_TILE -> false
+        IMAGE_SHAPE -> style?.imageShape != null
+        ACCESSORY_SYMBOL -> style?.accessorySymbol != null
+        CARD_TINT -> style?.cardTint != null
+        CARD_IMAGE -> style?.cardImage != null
+      }
+  }
+
+  /**
+   * The rest of the block's keys, dispositioned rather than ruled on: `artworkRendering` has no
+   * structural inertness condition (artwork renders in every layout), and `display` is positional —
+   * inert only in the one position that opens no page (see [playableDisplayFinding]). Declared here
+   * so the spec-level completeness test can hold this file to the whole vocabulary: every key of
+   * the block is a rule, always renderable, or positional, and a newly added property is a decision
+   * rather than an omission.
+   */
+  val ALWAYS_RENDERABLE = listOf("artworkRendering")
+
+  val POSITIONAL = listOf("display")
+
+  /**
+   * A section's effective container context: the two container values every inertness condition is
+   * stated against.
+   *
+   * Folded through [StyleResolver] rather than re-deriving the scope override: the diagnostic
+   * predicts what a renderer will do with these declarations, so it has to resolve them the way the
+   * renderers do.
+   */
+  private class Context(section: SectionStyle?, page: SectionStyle?) {
+    private val folded = StyleResolver.sectionStyle(section, page)
+    val isGrid = folded.display == StyleDisplay.GRID
+    val tile = folded.gridTile ?: GridTile.PLAIN
+
+    /**
+     * Whether the card treatment is what this container renders — the `card*` family's condition.
+     */
+    val isCard: Boolean
+      get() = isGrid && tile == GridTile.CARD
+
+    /**
+     * The effective style, for the message — in the wire spelling the author types ([toWireString]
+     * is the decoder's own mapping). `gridTile` is quoted only where a grid gives it meaning:
+     * naming it on a list would be advice to fix the wrong property.
+     */
+    val described: String
+      get() = if (!isGrid) "display 'list'" else "display 'grid', gridTile '${tile.toWireString()}'"
+  }
+
+  /**
+   * Every inert declaration on a resolved page, as ready-to-log messages — pure, so the whole rule
+   * set is testable off-device; the caller logs.
+   *
+   * @param path the resolved path, named in every message.
+   * @param pageStyle the page's own block (`ResolvedTrack.style`).
+   * @param sections the page's normalized sections, blocks *unfolded* — the diagnostic attributes
+   *   each finding to the level that declared it, so it must see the levels before [StyleResolver]
+   *   merges them.
+   */
+  fun findings(path: String, pageStyle: SectionStyle?, sections: List<Section>): List<String> {
+    val findings = mutableListOf<String>()
+    // A page-level declaration is judged across the whole page: it is live if it renders in any
+    // section it reaches, however many others ignore it.
+    val pageReached = mutableSetOf<Property>()
+    val pageRendered = mutableSetOf<Property>()
+
+    sections.forEachIndexed { index, section ->
+      val context = Context(section.style, pageStyle)
+      val sectionLabel = label(section, index)
+
+      for (property in Property.entries) {
+        val inert = property.isInert(context)
+
+        if (property.declaredIn(section.style)) {
+          if (inert) {
+            findings +=
+              message(property, path, sectionLabel, "its effective style is ${context.described}")
+          }
+        } else if (property.declaredIn(pageStyle)) {
+          // The section takes the page's value (nothing closer overrode it).
+          pageReached += property
+          if (!inert) pageRendered += property
+        }
+
+        if (!property.isItemProperty || !inert) continue
+        val tracks = section.children.count { property.declaredIn(it.style) }
+        if (tracks > 0) {
+          findings +=
+            message(
+              property,
+              path,
+              "${trackCount(tracks)} in $sectionLabel",
+              "the section's effective style is ${context.described}",
+            )
+        }
+      }
+
+      playableDisplayFinding(section, path, sectionLabel)?.let { findings += it }
+    }
+
+    for (property in Property.entries) {
+      if (property in pageReached && property !in pageRendered) {
+        findings +=
+          message(property, path, "the page block", "no section that inherits it renders one")
+      }
+    }
+
+    return findings
+  }
+
+  /**
+   * `display` is positional, so it is never inert *in* a container — but on a track that renders
+   * playable (`src` wins the rendering) it promises the layout of a page that never opens.
+   */
+  private fun playableDisplayFinding(section: Section, path: String, label: String): String? {
+    val tracks = section.children.count { it.src != null && it.style?.display != null }
+    if (tracks == 0) return null
+    return message(
+      path = path,
+      owner = "${trackCount(tracks)} in $label",
+      key = "display",
+      reason =
+        "`display` is the layout promise for the page a track opens, and a track rendered playable " +
+          "opens none",
+      hint = "Drop `display`, or give the track a `path` if it should be browsable.",
+    )
+  }
+
+  private fun message(property: Property, path: String, owner: String, scope: String): String =
+    message(
+      path = path,
+      owner = owner,
+      key = property.key,
+      reason = "${property.rule}, but $scope",
+      hint = property.hint,
+    )
+
+  /**
+   * The one message skeleton — every finding names the page, the declaration, who declared it, why
+   * it can't render, and what to do about it.
+   */
+  private fun message(
+    path: String,
+    owner: String,
+    key: String,
+    reason: String,
+    hint: String,
+  ): String =
+    "Inert style declaration on page '$path': `style.$key` on $owner never renders — $reason. $hint"
+
+  private fun trackCount(count: Int): String = "$count ${if (count == 1) "track" else "tracks"}"
+
+  private fun label(section: Section, index: Int): String =
+    section.title?.takeIf { it.isNotEmpty() }?.let { "section '$it'" } ?: "section #${index + 1}"
+}

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

@@ -1,30 +1,30 @@
 package com.audiobrowser.browser
 
+import com.audiobrowser.util.EMPTY_SECTION_STYLE
+import com.audiobrowser.util.EMPTY_TRACK_STYLE
+import com.audiobrowser.util.toArtworkRendering
+import com.audiobrowser.util.toCardImage
+import com.audiobrowser.util.toGridTile
+import com.audiobrowser.util.toImageShape
+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 +36,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 +72,72 @@ 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 ->
+    TrackStyle(
+        display = obj.stringField("display").toStyleDisplay(),
+        artworkRendering = obj.stringField("artworkRendering").toArtworkRendering(),
+        imageShape = obj.stringField("imageShape").toImageShape(),
+        // 'none' is a legitimate accessory value (the inheritance escape);
+        // only emptiness collapses.
+        accessorySymbol = obj.stringField("accessorySymbol")?.takeIf { it.isNotEmpty() },
+        cardTint = obj.stringField("cardTint")?.takeIf { it.isNotEmpty() },
+        cardImage = obj.stringField("cardImage").toCardImage(),
+      )
+      .takeIf { it != EMPTY_TRACK_STYLE }
+  }
+
+private fun JsonElement?.toSectionStyle(): SectionStyle? =
+  (this as? JsonObject)?.let { obj ->
+    SectionStyle(
+        display = obj.stringField("display").toStyleDisplay(),
+        artworkRendering = obj.stringField("artworkRendering").toArtworkRendering(),
+        imageShape = obj.stringField("imageShape").toImageShape(),
+        accessorySymbol = obj.stringField("accessorySymbol")?.takeIf { it.isNotEmpty() },
+        cardTint = obj.stringField("cardTint")?.takeIf { it.isNotEmpty() },
+        cardImage = obj.stringField("cardImage").toCardImage(),
+        gridWrap = obj.booleanField("gridWrap"),
+        gridTile = obj.stringField("gridTile").toGridTile(),
+      )
+      .takeIf { it != EMPTY_SECTION_STYLE }
   }
-}
 
 private fun String?.toCarPlaySiriListButtonPosition(): CarPlaySiriListButtonPosition? {
   return when (this?.lowercase()) {
@@ -99,26 +147,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 +170,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(),
   )
 }