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

package/README.md

@@ -174,6 +174,16 @@ Full guides and the complete [API Reference](https://audiobrowser.dev/api/) live
 
 The example app in [`apps/example-native`](https://github.com/radio-garden/react-native-audio-browser/tree/main/apps/example-native) browses archive.org's audio collection — in-app, on CarPlay, and on Android Auto — with search, favorites, and the gate.
 
+### For coding agents
+
+Every page is also served as raw Markdown — append `.md` to any URL, e.g.
+[`audiobrowser.dev/guide/queue.md`](https://audiobrowser.dev/guide/queue.md).
+
+- [`/llms.txt`](https://audiobrowser.dev/llms.txt) — an index of every page with a one-line summary, to pick what to read.
+- [`/llms-full.txt`](https://audiobrowser.dev/llms-full.txt) — every guide in one file.
+
+The same guide Markdown ships in the package, so it can be read straight off disk without a network fetch: `node_modules/react-native-audio-browser/website/guide/`.
+
 ## Support
 
 Questions or bugs? [Open an issue](https://github.com/radio-garden/react-native-audio-browser/issues). Release notes live in the [changelog](CHANGELOG.md).

package/android/build.gradle

@@ -158,6 +158,13 @@ repositories {
   google()
 }
 
+// Mockito's inline mock maker needs a Byte Buddy agent in the running JVM. Left to itself it
+// installs one through the JVM attach mechanism, which binds a unix socket under $TMPDIR —
+// denied inside sandboxed shells, and disabled by default on JDK 24+. Resolving the agent as its
+// own configuration lets the test JVM pre-load it with -javaagent, so no attach is needed.
+configurations {
+  mockitoAgent
+}
 
 dependencies {
   // For < 0.71, this will be from the local maven repo
@@ -210,14 +217,26 @@ dependencies {
   implementation("io.coil-kt.coil3:coil-network-okhttp:3.3.0")
 
   // Testing dependencies
+  def mockitoVersion = "5.8.0"
   testImplementation 'junit:junit:4.13.2'
-  testImplementation 'org.mockito:mockito-core:5.8.0'
+  testImplementation "org.mockito:mockito-core:${mockitoVersion}"
+  // Resolved transitively so the agent jar always matches the Byte Buddy that Mockito uses.
+  mockitoAgent "org.mockito:mockito-core:${mockitoVersion}"
   testImplementation 'org.jetbrains.kotlinx:kotlinx-coroutines-test:1.7.3'
   testImplementation 'org.robolectric:robolectric:4.11.1'
 
   api 'com.jakewharton.timber:timber:5.0.1'
 }
 
+tasks.withType(Test).configureEach {
+  def agentJar = configurations.mockitoAgent.find { it.name.startsWith("byte-buddy-agent") }
+  if (agentJar == null) {
+    throw new GradleException("No byte-buddy-agent jar in the mockitoAgent configuration; " +
+        "Mockito would fall back to runtime self-attach. Check the mockito-core coordinates.")
+  }
+  jvmArgs "-javaagent:${agentJar}"
+}
+
 if (isNewArchitectureEnabled()) {
   react {
     jsRootDir = file("../src/")

package/android/src/main/java/com/audiobrowser/AudioBrowser.kt

@@ -20,6 +20,7 @@ import com.audiobrowser.browser.CallbackException
 import com.audiobrowser.browser.ContentNotFoundException
 import com.audiobrowser.browser.HttpStatusException
 import com.audiobrowser.browser.NetworkException
+import com.audiobrowser.browser.flattenedChildren
 import com.audiobrowser.browser.handleTrackLoad
 import com.audiobrowser.browser.resolveMediaUrl
 import com.audiobrowser.extension.NumberExt.Companion.toSeconds
@@ -757,7 +758,10 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
     return Promise.async(mainScope) {
       Timber.d("Searching for: $query")
       val searchResults = browserManager.search(query)
-      searchResults.children ?: emptyArray()
+      // Flattened, not `children`: a resolved page carries its rows in
+      // `sections` (ADR 0010) and search builds exactly one untitled section,
+      // so `children` is always null here and this returned nothing at all.
+      searchResults.flattenedChildren?.toTypedArray() ?: emptyArray()
     }
   }
 

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

@@ -562,6 +562,10 @@ class BrowserManager {
   /** Clears all cached content. */
   fun clearContentCache() {
     contentCache.evictAll()
+    // The search slot is content too: a locale switch or a re-auth changes titles, src, artwork
+    // and availability, and nothing else ever evicts it, so a repeated query returned
+    // pre-invalidation results forever. (Matches the Swift twin's clearContentCache.)
+    lastSearch = null
     // Bump the layer generation so request/browse resolver thunks are re-resolved on the next
     // request (invalidateAllContent → clearContentCache is the documented re-resolve trigger).
     layerGeneration += 1
@@ -594,6 +598,10 @@ class BrowserManager {
     // section — ADR 0010), then generate contextual paths and transform artwork
     // URLs. The output never carries `children`.
     val sections = resolvedTrack.normalizedSections ?: return resolvedTrack
+    // Dev diagnostic (ADR 0011) — before the blocks are folded, while each level is
+    // still attributable. Every page passes here whatever its source, and only on a
+    // cache miss. No-op outside debug builds.
+    InertStyleDiagnostic.warn(path, resolvedTrack.style, sections)
     // The contextual index is the flat page position — children concatenated in
     // section order (ADR 0009/0010).
     var flatIndex = 0

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,6 +1,11 @@
 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.ResolvedTrack
@@ -106,19 +111,32 @@ private fun JsonObject.booleanField(key: String): Boolean? =
  */
 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)
+    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 ->
-    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)
+    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? {

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

@@ -29,7 +29,12 @@ object StyleResolver {
     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,
     )
 
   /**
@@ -45,5 +50,11 @@ object StyleResolver {
       // 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

@@ -30,7 +30,17 @@ fun ResolvedTrack.toTrack(): Track =
     // 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) },
+    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,
     live = live,

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

@@ -4,8 +4,11 @@ import android.content.Context
 import android.content.SharedPreferences
 import androidx.core.content.edit
 import androidx.media3.common.C
+import com.audiobrowser.util.EMPTY_TRACK_STYLE
 import com.audiobrowser.util.artworkOf
 import com.audiobrowser.util.toArtworkRendering
+import com.audiobrowser.util.toCardImage
+import com.audiobrowser.util.toImageShape
 import com.audiobrowser.util.toStyleDisplay
 import com.audiobrowser.util.toWireString
 import com.audiobrowser.util.url
@@ -164,7 +167,11 @@ class PlaybackStateStore(private val player: Player) {
       // Apply player settings from persisted state
       player.repeatMode = state.repeatMode
       player.shuffleMode = state.shuffleEnabled
-      player.playbackSpeed = state.playbackSpeed
+      // Guarded because this input is untrusted: ExoPlayer's setPlaybackSpeed rejects a
+      // non-positive speed with IllegalArgumentException, and a snapshot holding one (a
+      // corrupted prefs file — the normal write path can't produce it) would then throw on
+      // every resume, permanently, since the bad value stays persisted.
+      if (state.playbackSpeed > 0f) player.playbackSpeed = state.playbackSpeed
 
       Timber.d(
         "Restored player settings: repeatMode=${state.repeatMode}, shuffle=${state.shuffleEnabled}, speed=${state.playbackSpeed}"
@@ -216,6 +223,10 @@ class PlaybackStateStore(private val player: Player) {
               JSONObject().apply {
                 put("display", style.display?.toWireString())
                 put("artworkRendering", style.artworkRendering?.toWireString())
+                put("imageShape", style.imageShape?.toWireString())
+                put("accessorySymbol", style.accessorySymbol)
+                put("cardTint", style.cardTint)
+                put("cardImage", style.cardImage?.toWireString())
               }
             },
           )
@@ -254,11 +265,15 @@ class PlaybackStateStore(private val player: Player) {
                   TrackStyle(
                     display = style.optString("display").toStyleDisplay(),
                     artworkRendering = style.optString("artworkRendering").toArtworkRendering(),
+                    imageShape = style.optString("imageShape").toImageShape(),
+                    accessorySymbol = style.optString("accessorySymbol").takeIf { it.isNotEmpty() },
+                    cardTint = style.optString("cardTint").takeIf { it.isNotEmpty() },
+                    cardImage = style.optString("cardImage").toCardImage(),
                   )
                 }
                 // An empty block collapses to "no declaration" — one shape on
                 // every platform, matching the browse decoders.
-                ?.takeIf { it.display != null || it.artworkRendering != null },
+                ?.takeIf { it != EMPTY_TRACK_STYLE },
             disabled =
               if (obj.has("disabled") && !obj.isNull("disabled")) obj.getBoolean("disabled")
               else null,

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

@@ -668,6 +668,9 @@ class Player(internal val context: Context) {
   ) {
     val mediaItems = TrackFactory.toMedia3(tracks).toMutableList()
     exoPlayer.setMediaItems(mediaItems, startIndex, startPositionMs)
+    if (mediaItems.isNotEmpty()) {
+      exoPlayer.setShuffleOrder(shuffleOrderLedBy(startIndex, mediaItems.size))
+    }
     queueSourcePath = sourcePath
     exoPlayer.prepare()
   }

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

@@ -0,0 +1,30 @@
+package com.audiobrowser.player
+
+import androidx.media3.exoplayer.source.ShuffleOrder
+import kotlin.random.Random
+
+/**
+ * A shuffle order over [count] items with [startIndex] pinned to shuffle position 0.
+ *
+ * Media3 does not do this for us. `ExoPlayerImpl.setMediaSources` hands the start index to
+ * `ShuffleOrder.cloneAndSet(insertionCount, startIndex)`, but that is an interface default of
+ * `cloneAndClear().cloneAndInsert(0, insertionCount)` — the start index is discarded — and
+ * `DefaultShuffleOrder` does not override it (verified against the pinned media3 build). So with
+ * shuffle on, the track playback starts from lands at a random position in the order, and a 1-in-N
+ * share of queues put it last: `nextMediaItemIndex` is then `INDEX_UNSET` from the very first
+ * track, so auto-advance ends the queue after one track and fires `onQueueEnded`. The
+ * voice-assistant cold resume expands a queue exactly this way, so it sits squarely on that path.
+ *
+ * Applied unconditionally by `Player.setQueue`, like the Swift twin's `adoptInitialCurrent`:
+ * enabling shuffle later does not regenerate the order, so it has to be sane whether or not shuffle
+ * is on right now.
+ */
+internal fun shuffleOrderLedBy(startIndex: Int, count: Int, random: Random = Random): ShuffleOrder {
+  val first = startIndex.coerceIn(0, (count - 1).coerceAtLeast(0))
+  val indices = IntArray(count)
+  if (count > 0) {
+    indices[0] = first
+    ((0 until count) - first).shuffled().forEachIndexed { i, index -> indices[i + 1] = index }
+  }
+  return ShuffleOrder.DefaultShuffleOrder(indices, random.nextLong())
+}

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

@@ -1,7 +1,39 @@
 package com.audiobrowser.util
 
 import com.margelo.nitro.audiobrowser.ArtworkRendering
+import com.margelo.nitro.audiobrowser.CardImage
+import com.margelo.nitro.audiobrowser.GridTile
+import com.margelo.nitro.audiobrowser.ImageShape
+import com.margelo.nitro.audiobrowser.SectionStyle
 import com.margelo.nitro.audiobrowser.StyleDisplay
+import com.margelo.nitro.audiobrowser.TrackStyle
+
+/**
+ * The all-nil blocks a decode collapses to "no declaration". Every field is listed exactly once
+ * here — the decoders and the persistence restore compare against these instead of re-enumerating
+ * the fields in each guard (a constructor gaining a field breaks this file, not silently a guard).
+ */
+internal val EMPTY_TRACK_STYLE =
+  TrackStyle(
+    display = null,
+    artworkRendering = null,
+    imageShape = null,
+    accessorySymbol = null,
+    cardTint = null,
+    cardImage = null,
+  )
+
+internal val EMPTY_SECTION_STYLE =
+  SectionStyle(
+    display = null,
+    artworkRendering = null,
+    imageShape = null,
+    accessorySymbol = null,
+    cardTint = null,
+    cardImage = null,
+    gridWrap = null,
+    gridTile = null,
+  )
 
 /**
  * The style block's wire strings (ADR 0011) ↔ Nitro enums, shared by the browse decoder and the
@@ -33,3 +65,44 @@ internal fun String?.toArtworkRendering(): ArtworkRendering? =
     "stencil" -> ArtworkRendering.STENCIL
     else -> null
   }
+
+internal fun ImageShape.toWireString(): String =
+  when (this) {
+    ImageShape.CIRCULAR -> "circular"
+    ImageShape.ROUNDED_RECTANGLE -> "rounded-rectangle"
+  }
+
+internal fun String?.toImageShape(): ImageShape? =
+  when (this?.takeIf { it.isNotEmpty() }?.lowercase()) {
+    "circular" -> ImageShape.CIRCULAR
+    "rounded-rectangle" -> ImageShape.ROUNDED_RECTANGLE
+    else -> null
+  }
+
+internal fun GridTile.toWireString(): String =
+  when (this) {
+    GridTile.PLAIN -> "plain"
+    GridTile.CARD -> "card"
+    GridTile.CONDENSED -> "condensed"
+  }
+
+internal fun String?.toGridTile(): GridTile? =
+  when (this?.takeIf { it.isNotEmpty() }?.lowercase()) {
+    "plain" -> GridTile.PLAIN
+    "card" -> GridTile.CARD
+    "condensed" -> GridTile.CONDENSED
+    else -> null
+  }
+
+internal fun CardImage.toWireString(): String =
+  when (this) {
+    CardImage.NORMAL -> "normal"
+    CardImage.BACKGROUND -> "background"
+  }
+
+internal fun String?.toCardImage(): CardImage? =
+  when (this?.takeIf { it.isNotEmpty() }?.lowercase()) {
+    "normal" -> CardImage.NORMAL
+    "background" -> CardImage.BACKGROUND
+    else -> null
+  }