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

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

@@ -32,7 +32,6 @@ import com.margelo.nitro.audiobrowser.PlayerCapabilities
 import com.margelo.nitro.audiobrowser.RemoteButtonLayout
 import com.margelo.nitro.audiobrowser.SearchParams
 import com.margelo.nitro.audiobrowser.Section
-import com.margelo.nitro.audiobrowser.StyleDisplay
 import com.margelo.nitro.audiobrowser.Track
 import kotlinx.coroutines.CancellationException
 import kotlinx.coroutines.CoroutineScope
@@ -419,33 +418,33 @@ class MediaSessionCallback(private val player: Player) :
   /**
    * Flattens a page's sections to MediaItems for browse delivery — the Media3 boundary where
    * sections die (ADR 0010): the MediaBrowser protocol has no section node, so each child is
-   * stamped with its owning section's title/style hints. A grid-displayed section with a `path`
-   * gains a browsable "view all" link under the same header. Http(s) artwork routes through the
-   * content:// provider so Android Auto can load it via the ArtworkContentProvider.
+   * stamped with its owning section's title/style hints. A section with a `path` gains a browsable
+   * "view more" row under the same header — at every `display`, because no Android Auto header is
+   * tappable at any of them, so the row is the section's only "view all" affordance here. Http(s)
+   * artwork routes through the content:// provider so Android Auto can load it via the
+   * ArtworkContentProvider.
    */
-  private fun toMediaItems(sections: List<Section>): List<MediaItem> {
+  private suspend fun toMediaItems(sections: List<Section>): List<MediaItem> {
     val registry = player.browseArtworkRegistry
     val authority = com.audiobrowser.util.ArtworkUris.authorityFor(player.context.packageName)
     return sections.flatMap { section ->
       // Android Auto has no disabled affordance, so an unavailable track hides
       // — never a normal-looking dead row (Track.disabled's rendering ladder).
-      val visibleChildren = section.children.filter { it.disabled != true }
-      val items =
-        visibleChildren.map { TrackFactory.toBrowseMediaItem(it, registry, authority, section) }
-      val isTileSection = section.style?.display == StyleDisplay.GRID
-      // No "view all" under an empty section — CarPlay skips empty sections
+      val children = section.children.filter { it.disabled != true }
+      val items = children.map { TrackFactory.toBrowseMediaItem(it, registry, authority, section) }
+      // No "view more" under an empty section — CarPlay skips empty sections
       // outright, and a lone navigation tile under a header is a dead end.
-      if (isTileSection && section.path != null && visibleChildren.isNotEmpty()) {
-        items +
-          TrackFactory.toBrowseMediaItem(
-            TrackFactory.navigationTrack(section),
-            registry,
-            authority,
-            section,
-          )
-      } else {
-        items
-      }
+      if (section.path == null || children.isEmpty()) return@flatMap items
+      // The browser is already up at every call site, so awaiting it here is a field read, and
+      // viewMoreTitle is memoized per content generation — both are free after the first row.
+      val title = player.awaitBrowser().browserManager.viewMoreTitle()
+      items +
+        TrackFactory.toBrowseMediaItem(
+          TrackFactory.navigationTrack(section, title),
+          registry,
+          authority,
+          section,
+        )
     }
   }
 
@@ -453,7 +452,7 @@ class MediaSessionCallback(private val player: Player) :
    * Flat lists (tabs, search results) convert as one untitled list section — which contributes no
    * group or style hints — so exactly one Track→MediaItem path exists at the Media3 boundary.
    */
-  private fun toFlatMediaItems(tracks: List<Track>): List<MediaItem> =
+  private suspend fun toFlatMediaItems(tracks: List<Track>): List<MediaItem> =
     toMediaItems(listOf(untitledSection(tracks.toTypedArray())))
 
   override fun onGetItem(

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
+  }

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

@@ -25,13 +25,16 @@ object TrackFactory {
   }
 
   /**
-   * 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,
+   * A synthetic browsable Track for a section's "view more" row — the section has a path but no
+   * Track to hang it on (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.
+   *
+   * [title] is the consumer's `viewMoreTitle`, one string for every section — not the section's own
+   * title, which the group header above the row already shows.
    */
-  fun navigationTrack(section: Section): Track =
+  fun navigationTrack(section: Section, title: String): Track =
     Track(
       id = null,
       path = section.path,
@@ -39,8 +42,8 @@ object TrackFactory {
       artwork = null,
       artworkSource = null,
       request = null,
-      title = section.title ?: "",
-      subtitle = section.subtitle,
+      title = title,
+      subtitle = null,
       artist = null,
       albumPath = null,
       album = null,
@@ -49,7 +52,14 @@ object TrackFactory {
       duration = null,
       style =
         section.style?.let {
-          TrackStyle(display = it.display, artworkRendering = it.artworkRendering)
+          TrackStyle(
+            display = it.display,
+            artworkRendering = it.artworkRendering,
+            imageShape = it.imageShape,
+            accessorySymbol = it.accessorySymbol,
+            cardTint = it.cardTint,
+            cardImage = it.cardImage,
+          )
         },
       disabled = null,
       favorited = null,

package/android/src/main/res/values/strings.xml

@@ -1,10 +1,45 @@
 <?xml version="1.0" encoding="utf-8"?>
+<!--
+  Default copy for the two error tiles the library invents in the Android Auto
+  browse list. These rows have no consumer-authored Track behind them, so there
+  is nothing in the browse tree to read a title from; English here because a
+  default that renders beats a blank row.
+
+  Resources rather than a browser-config option — the route the library's
+  cross-platform copy takes (`formatNavigationError`, `carPlayLoadingTitle`,
+  `viewMoreTitle`) — because these two are not cross-platform. They exist only
+  because Media3 drops the message from `LibraryResult.ofError` on the legacy
+  browse bridge, so a row is the sole signal available; CarPlay has no
+  counterpart, stating failures in the list's centered empty view instead
+  (CarPlayController.showMessage). Android-only copy in the Android-idiomatic
+  place: an app re-skins either by declaring the same name in its own
+  strings.xml, and a `values-<locale>/` file can add translations later without
+  touching the API.
+-->
 <resources>
-    <!-- Error message shown in Android Auto when network is offline -->
+    <!--
+      The offline tile: shown in place of a page's contents when the device is
+      offline and the consumer left `androidControllerOfflineError` on. Distinct
+      from the browse-error tile below — this one is used only when the network
+      monitor says we are actually offline, so it may name the cause. The
+      subtitle is the tile's second line.
+    -->
     <string name="audio_browser_offline_error">No internet connection</string>
     <string name="audio_browser_offline_error_subtitle">Check your connection and try again</string>
 
-    <!-- Generic error message shown in Android Auto when browsing fails -->
+    <!--
+      The browse-error tile: shown when a browse fails while ONLINE — a server
+      error, a bad status, a timeout waiting for the JS browser. Deliberately
+      vague, and deliberately not "no internet connection": the genuinely-offline
+      case is caught earlier and gets the tile above, so anything reaching this
+      one has a working connection and would be misdiagnosed by that wording.
+
+      A tile rather than an error dialog because Media3 drops the message from
+      `LibraryResult.ofError` on the legacy browse bridge, which would leave a
+      bare "No items" screen. Verified on a head unit (2026-06): the Android Auto
+      browse list never renders error text by any other route, so tiles are the
+      only in-browse signal the library controls.
+    -->
     <string name="audio_browser_browse_error">Something went wrong</string>
     <string name="audio_browser_browse_error_subtitle">Please try again later</string>
 </resources>

package/android/src/test/java/com/audiobrowser/TestFixtures.kt

@@ -1,15 +1,21 @@
 package com.audiobrowser
 
 import com.audiobrowser.util.artworkOf
+import com.margelo.nitro.audiobrowser.ArtworkRendering
 import com.margelo.nitro.audiobrowser.ArtworkRequestConfig
+import com.margelo.nitro.audiobrowser.CardImage
+import com.margelo.nitro.audiobrowser.GridTile
 import com.margelo.nitro.audiobrowser.ImageQueryParams
+import com.margelo.nitro.audiobrowser.ImageShape
 import com.margelo.nitro.audiobrowser.ImageSource
 import com.margelo.nitro.audiobrowser.MediaRequestConfig
 import com.margelo.nitro.audiobrowser.NativeRouteEntry
 import com.margelo.nitro.audiobrowser.ResolvedTrack
 import com.margelo.nitro.audiobrowser.Section
 import com.margelo.nitro.audiobrowser.SectionStyle
+import com.margelo.nitro.audiobrowser.StyleDisplay
 import com.margelo.nitro.audiobrowser.Track
+import com.margelo.nitro.audiobrowser.TrackStyle
 import com.margelo.nitro.audiobrowser.TransformableRequestConfig
 
 /**
@@ -28,6 +34,7 @@ object TestFixtures {
     album: String? = null,
     favorited: Boolean? = null,
     disabled: Boolean? = null,
+    style: TrackStyle? = null,
   ) =
     Track(
       id = id,
@@ -44,7 +51,7 @@ object TestFixtures {
       description = null,
       genre = null,
       duration = null,
-      style = null,
+      style = style,
       disabled = disabled,
       favorited = favorited,
       live = null,
@@ -52,12 +59,11 @@ object TestFixtures {
 
   /** A page [Section] — plain list by default. */
   fun section(
-    children: Array<Track>,
+    children: Array<Track> = emptyArray(),
     title: String? = null,
-    subtitle: String? = null,
     style: SectionStyle? = null,
     path: String? = null,
-  ) = Section(title = title, subtitle = subtitle, style = style, path = path, children = children)
+  ) = Section(title = title, style = style, path = path, children = children)
 
   fun transformableConfig(
     baseUrl: String? = null,
@@ -109,6 +115,7 @@ object TestFixtures {
     path: String = "https://api.example.com/channel/abc",
     artwork: String? = null,
     artworkSource: ImageSource? = null,
+    style: TrackStyle? = null,
   ) =
     Track(
       id = null,
@@ -125,7 +132,7 @@ object TestFixtures {
       description = null,
       genre = null,
       duration = null,
-      style = null,
+      style = style,
       disabled = null,
       favorited = null,
       live = null,
@@ -201,4 +208,42 @@ object TestFixtures {
       contentType = null,
       userAgent = null,
     )
+
+  fun trackStyle(
+    display: StyleDisplay? = null,
+    artworkRendering: ArtworkRendering? = null,
+    imageShape: ImageShape? = null,
+    accessorySymbol: String? = null,
+    cardTint: String? = null,
+    cardImage: CardImage? = null,
+  ) =
+    TrackStyle(
+      display = display,
+      artworkRendering = artworkRendering,
+      imageShape = imageShape,
+      accessorySymbol = accessorySymbol,
+      cardTint = cardTint,
+      cardImage = cardImage,
+    )
+
+  fun sectionStyle(
+    display: StyleDisplay? = null,
+    artworkRendering: ArtworkRendering? = null,
+    imageShape: ImageShape? = null,
+    accessorySymbol: String? = null,
+    cardTint: String? = null,
+    cardImage: CardImage? = null,
+    gridWrap: Boolean? = null,
+    gridTile: GridTile? = null,
+  ) =
+    SectionStyle(
+      gridWrap = gridWrap,
+      gridTile = gridTile,
+      display = display,
+      artworkRendering = artworkRendering,
+      imageShape = imageShape,
+      accessorySymbol = accessorySymbol,
+      cardTint = cardTint,
+      cardImage = cardImage,
+    )
 }

package/android/src/test/java/com/audiobrowser/browser/BrowserManagerLayerResolutionTest.kt

@@ -144,4 +144,13 @@ class BrowserManagerLayerResolutionTest {
     assertSame(request, browserManager.resolvedRequestLayerForTest)
     assertNull(browserManager.resolvedBrowseLayerForTest)
   }
+
+  @Test
+  fun `viewMoreTitle falls back to the in-code default when unconfigured`() = runTest {
+    // The only viewMoreTitle path a JVM test can reach — a configured callback returns a Nitro
+    // Promise, see the resolver-thunk gap noted above.
+    browserManager.config = BrowserConfig()
+
+    assertEquals(BrowserManager.DEFAULT_VIEW_MORE_TITLE, browserManager.viewMoreTitle())
+  }
 }

package/android/src/test/java/com/audiobrowser/browser/BrowserManagerTest.kt

@@ -4,6 +4,7 @@ import androidx.media3.common.C
 import androidx.media3.common.MediaItem
 import com.audiobrowser.TestFixtures.resolvedTrack
 import com.audiobrowser.TestFixtures.section
+import com.audiobrowser.TestFixtures.sectionStyle
 import com.audiobrowser.TestFixtures.staticRoute
 import com.audiobrowser.TestFixtures.track
 import com.audiobrowser.util.BrowserPathHelper
@@ -183,7 +184,7 @@ class BrowserManagerTest {
         section(
           title = "Row",
           style =
-            com.margelo.nitro.audiobrowser.SectionStyle(
+            sectionStyle(
               display = com.margelo.nitro.audiobrowser.StyleDisplay.GRID,
               artworkRendering = null,
               gridWrap = false,
@@ -252,7 +253,7 @@ class BrowserManagerTest {
       section(
         title = "Most Played",
         style =
-          com.margelo.nitro.audiobrowser.SectionStyle(
+          sectionStyle(
             display = com.margelo.nitro.audiobrowser.StyleDisplay.GRID,
             artworkRendering = null,
             gridWrap = false,