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

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

@@ -1,5 +1,6 @@
 package com.audiobrowser.player
 
+import com.audiobrowser.extension.identity
 import com.audiobrowser.util.url
 import com.margelo.nitro.audiobrowser.FormatNowPlayingParams
 import com.margelo.nitro.audiobrowser.NowPlayingMetadata
@@ -105,10 +106,11 @@ class NowPlayingUpdater(private val surface: NowPlayingSurface, private val scop
   private var lastPublished: Published? = null
 
   /**
-   * The track id whose now-playing artwork has been resolved (or is being resolved), so a
-   * `nowPlayingArtwork` resolve runs once per track instead of on every render.
+   * The track identity (id-or-src, falling back to path — same key as [Published]) whose
+   * now-playing artwork has been resolved (or is being resolved), so a `nowPlayingArtwork` resolve
+   * runs once per track — id-less tracks included — instead of on every render.
    */
-  private var artworkResolvedForTrackId: String? = null
+  private var artworkResolvedForTrack: String? = null
 
   /** Size hint (px, square) for now-playing artwork. Mirrors iOS (screen-width-capped to 1200). */
   private val artworkSizePx = 1200.0
@@ -164,7 +166,7 @@ class NowPlayingUpdater(private val surface: NowPlayingSurface, private val scop
       duration = track.duration,
       artwork = track.artwork?.url,
       description = track.description,
-      mediaId = track.src ?: track.url,
+      mediaId = track.src ?: track.path,
       genre = track.genre,
     )
   }
@@ -227,7 +229,7 @@ class NowPlayingUpdater(private val surface: NowPlayingSurface, private val scop
     // default on null/throw.
     val activeFormatter = if (enabled) formatter else null
     if (activeFormatter != null) {
-      val capturedId = track.src ?: track.url
+      val capturedId = track.src ?: track.path
       // Gate the raw load-control signal to the buffering state so `stalled` is correct on its
       // own: ExoPlayer's rebuffering flag is polled on a different cadence than state transitions
       // and can linger true into the PLAYING transition as a rebuffer recovers. Classify by
@@ -266,7 +268,7 @@ class NowPlayingUpdater(private val surface: NowPlayingSurface, private val scop
           formatted != null &&
             current != null &&
             currentIdx != null &&
-            (current.src ?: current.url) == capturedId &&
+            (current.src ?: current.path) == capturedId &&
             renderGeneration == generation
         ) {
           applyFields(
@@ -293,7 +295,7 @@ class NowPlayingUpdater(private val surface: NowPlayingSurface, private val scop
     // the same fields are recomputed often; an unconditional stamp would churn the MediaSession
     // (and flicker Android Auto / now-playing) for no visible change. Keyed on the track identity
     // so a new track with a coincidentally identical line still publishes.
-    val published = Published(index, track.src ?: track.url, title, secondaryLine, album)
+    val published = Published(index, track.identity ?: track.path, title, secondaryLine, album)
     if (published == lastPublished) return
     lastPublished = published
 
@@ -307,28 +309,23 @@ class NowPlayingUpdater(private val surface: NowPlayingSurface, private val scop
 
   /**
    * Resolves the playing track's now-playing artwork and stamps it onto the playing media item.
-   * Guarded exactly like iOS: only when `nowPlayingArtwork` is configured AND the track has a
-   * non-empty id (so the `{id}` token never resolves to an empty string). Otherwise the existing
-   * artworkUri — which came from `artwork` (browse list path) — is left in place.
+   * Runs for EVERY playing track when `nowPlayingArtwork` is configured — id or not, exactly like
+   * iOS (an id-less track leaves any `{id}` token unfilled; the resolver warns and the request
+   * visibly 404s). Without a config, the existing artworkUri — which came from `artwork` (browse
+   * list path) — is left in place.
    */
   private fun maybeResolveArtwork(track: Track) {
-    val trackId =
-      track.id?.takeIf { it.isNotEmpty() }
-        ?: run {
-          // No id → skip nowPlayingArtwork entirely; keep the existing (browse) artworkUri.
-          artworkResolvedForTrackId = null
-          return
-        }
-
     if (!surface.hasNowPlayingArtworkConfig) {
       // No now-playing artwork config (or no browser) → fall back to the existing artworkUri.
-      artworkResolvedForTrackId = null
+      artworkResolvedForTrack = null
       return
     }
 
-    // Already resolved (or resolving) for this track id — avoid a redundant resolve per render.
-    if (artworkResolvedForTrackId == trackId) return
-    artworkResolvedForTrackId = trackId
+    // Already resolved (or resolving) for this track — avoid a redundant resolve per render.
+    // Keyed on track identity (id-or-src, falling back to path) so id-less tracks dedupe too.
+    val trackKey = track.identity ?: track.path
+    if (trackKey != null && artworkResolvedForTrack == trackKey) return
+    artworkResolvedForTrack = trackKey
 
     scope.launch {
       val uri =
@@ -336,10 +333,10 @@ class NowPlayingUpdater(private val surface: NowPlayingSurface, private val scop
           ?: return@launch
 
       // Apply only if still the same track (a fast skip must not be overwritten by a stale
-      // result).
+      // result), compared on the same identity key the resolve was launched under.
       val currentIdx = surface.currentIndex ?: return@launch
       val current = surface.currentTrack ?: return@launch
-      if (current.id != trackId) return@launch
+      if ((current.identity ?: current.path) != trackKey) return@launch
 
       surface.stampArtwork(currentIdx, current, uri)
     }

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

@@ -4,7 +4,13 @@ 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
 import com.margelo.nitro.audiobrowser.PlaybackState
 import com.margelo.nitro.audiobrowser.RepeatMode
@@ -18,12 +24,12 @@ import org.json.JSONObject
 import timber.log.Timber
 
 /**
- * Persists playback state for resumption after app restart. Stores the current track URL, position,
- * and player settings to enable playback resumption via MediaButtonReceiver (Bluetooth play button,
- * etc.).
+ * Persists playback state for resumption after app restart. Stores the current track (including its
+ * path), position, and player settings to enable playback resumption via MediaButtonReceiver
+ * (Bluetooth play button, etc.).
  *
  * Settings (repeatMode, shuffleEnabled, playbackSpeed) are auto-persisted when set via properties.
- * Position/URL are persisted via save() on pause or track change.
+ * Position/track are persisted via save() on pause or track change.
  */
 class PlaybackStateStore(private val player: Player) {
   private val prefs: SharedPreferences =
@@ -32,7 +38,7 @@ class PlaybackStateStore(private val player: Player) {
   /**
    * Persisted playback state for resumption.
    *
-   * @param track The track being played (includes url for queue expansion)
+   * @param track The track being played (includes path for queue expansion)
    * @param positionMs The playback position in milliseconds (C.TIME_UNSET for default/live edge)
    * @param repeatMode The repeat mode setting
    * @param shuffleEnabled Whether shuffle mode was enabled
@@ -148,78 +154,11 @@ class PlaybackStateStore(private val player: Player) {
     Timber.d("Saved position: positionMs=0 (queue ended)")
   }
 
-  private fun trackToJson(track: Track): String =
-    JSONObject()
-      .apply {
-        put("id", track.id)
-        put("url", track.url)
-        put("src", track.src)
-        put("title", track.title)
-        put("subtitle", track.subtitle)
-        put("artist", track.artist)
-        put("albumUrl", track.albumUrl)
-        put("album", track.album)
-        put("artwork", track.artwork?.url)
-        put("description", track.description)
-        put("genre", track.genre)
-        put("duration", track.duration)
-        put("style", track.style?.name)
-        put("childrenStyle", track.childrenStyle?.name)
-        put("favorited", track.favorited)
-        put("groupTitle", track.groupTitle)
-        put("live", track.live)
-      }
-      .toString()
-
-  private fun trackFromJson(json: String): Track? =
-    runCatching {
-        val obj = JSONObject(json)
-        Track(
-          id = obj.optString("id").takeIf { it.isNotEmpty() },
-          url = obj.optString("url").takeIf { it.isNotEmpty() },
-          src = obj.optString("src").takeIf { it.isNotEmpty() },
-          title = obj.getString("title"),
-          subtitle = obj.optString("subtitle").takeIf { it.isNotEmpty() },
-          artist = obj.optString("artist").takeIf { it.isNotEmpty() },
-          albumUrl = obj.optString("albumUrl").takeIf { it.isNotEmpty() },
-          album = obj.optString("album").takeIf { it.isNotEmpty() },
-          artwork = artworkOf(obj.optString("artwork").takeIf { it.isNotEmpty() }),
-          artworkSource = null, // Not persisted - will be re-transformed on browse
-          artworkCarPlayTinted = null, // iOS-only, not persisted
-          description = obj.optString("description").takeIf { it.isNotEmpty() },
-          genre = obj.optString("genre").takeIf { it.isNotEmpty() },
-          duration =
-            if (obj.has("duration") && !obj.isNull("duration")) obj.getDouble("duration") else null,
-          style =
-            obj
-              .optString("style")
-              .takeIf { it.isNotEmpty() }
-              ?.let { runCatching { TrackStyle.valueOf(it) }.getOrNull() },
-          childrenStyle =
-            obj
-              .optString("childrenStyle")
-              .takeIf { it.isNotEmpty() }
-              ?.let { runCatching { TrackStyle.valueOf(it) }.getOrNull() },
-          favorited =
-            if (obj.has("favorited") && !obj.isNull("favorited")) obj.getBoolean("favorited")
-            else null,
-          groupTitle = obj.optString("groupTitle").takeIf { it.isNotEmpty() },
-          live = if (obj.has("live") && !obj.isNull("live")) obj.getBoolean("live") else null,
-          // Not persisted: on resumption the contextual URL is re-browsed
-          // (expandQueueFromContextualUrl), which re-parses each track's request
-          // from the API's current response and re-caches it.
-          request = null,
-          imageRow = null, // Not persisted
-        )
-      }
-      .onFailure { e -> Timber.w(e, "Failed to parse persisted track JSON") }
-      .getOrNull()
-
   /**
    * Restores player settings from persisted state and returns the state for queue setup.
    *
    * Applies repeatMode, shuffleMode, and playbackSpeed to the player. The caller is responsible for
-   * using the returned url and positionMs to set up the playback queue.
+   * using the returned path and positionMs to set up the playback queue.
    *
    * @return PersistedState if available, null otherwise
    */
@@ -228,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}"
@@ -255,6 +198,98 @@ class PlaybackStateStore(private val player: Player) {
   }
 
   companion object {
+    // Internal (not private) so the round-trip is testable without a Player.
+    internal fun trackToJson(track: Track): String =
+      JSONObject()
+        .apply {
+          put("id", track.id)
+          put("path", track.path)
+          put("src", track.src)
+          put("title", track.title)
+          put("subtitle", track.subtitle)
+          put("artist", track.artist)
+          put("albumPath", track.albumPath)
+          put("album", track.album)
+          put("artwork", track.artwork?.url)
+          put("description", track.description)
+          put("genre", track.genre)
+          put("duration", track.duration)
+          // The style block persists as its wire shape (nested object, wire
+          // strings) and `disabled` beside it: a restored queue keeps its
+          // visible fidelity across process death (ADR 0011).
+          put(
+            "style",
+            track.style?.let { style ->
+              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())
+              }
+            },
+          )
+          put("disabled", track.disabled)
+          put("favorited", track.favorited)
+          put("live", track.live)
+        }
+        .toString()
+
+    internal fun trackFromJson(json: String): Track? =
+      runCatching {
+          val obj = JSONObject(json)
+          Track(
+            id = obj.optString("id").takeIf { it.isNotEmpty() },
+            path = obj.optString("path").takeIf { it.isNotEmpty() },
+            src = obj.optString("src").takeIf { it.isNotEmpty() },
+            title = obj.getString("title"),
+            subtitle = obj.optString("subtitle").takeIf { it.isNotEmpty() },
+            artist = obj.optString("artist").takeIf { it.isNotEmpty() },
+            albumPath = obj.optString("albumPath").takeIf { it.isNotEmpty() },
+            album = obj.optString("album").takeIf { it.isNotEmpty() },
+            artwork = artworkOf(obj.optString("artwork").takeIf { it.isNotEmpty() }),
+            artworkSource = null, // Not persisted - will be re-transformed on browse
+            description = obj.optString("description").takeIf { it.isNotEmpty() },
+            genre = obj.optString("genre").takeIf { it.isNotEmpty() },
+            duration =
+              if (obj.has("duration") && !obj.isNull("duration")) obj.getDouble("duration")
+              else null,
+            // Tolerant (ADR 0011): a snapshot written before the block model —
+            // `style` as an enum-name string — is not an object, so optJSONObject
+            // yields null and the track restores without a declaration.
+            style =
+              obj
+                .optJSONObject("style")
+                ?.let { style ->
+                  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 != EMPTY_TRACK_STYLE },
+            disabled =
+              if (obj.has("disabled") && !obj.isNull("disabled")) obj.getBoolean("disabled")
+              else null,
+            favorited =
+              if (obj.has("favorited") && !obj.isNull("favorited")) obj.getBoolean("favorited")
+              else null,
+            live = if (obj.has("live") && !obj.isNull("live")) obj.getBoolean("live") else null,
+            // Not persisted: on resumption the contextual path is re-browsed
+            // (expandQueueFromContextualPath), which re-parses each track's request
+            // from the API's current response and re-caches it.
+            request = null,
+          )
+        }
+        .onFailure { e -> Timber.w(e, "Failed to parse persisted track JSON") }
+        .getOrNull()
+
     private const val PREFS_NAME = "audio_browser_playback_state_v3"
     private const val KEY_POSITION_MS = "position_ms"
     private const val KEY_REPEAT_MODE = "repeat_mode"

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

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

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

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

package/android/src/main/java/com/audiobrowser/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())
+}