react-native-queue-player 1.0.4 → 1.0.6

package/android/src/main/java/com/margelo/nitro/queueplayer/NotificationProvider.kt

@@ -18,6 +18,12 @@ import androidx.media3.session.DefaultMediaNotificationProvider
  * `setMediaButtonPreferences(...)` builder call; this provider reads
  * those preferences directly.
  *
+ * This provider only pins the channel + notification id — it does NOT
+ * restyle transport buttons. On API 33+ the System UI media control is
+ * derived from the media session, so `MediaNotification.Provider` layout
+ * changes take effect only pre-33; transport customization belongs in the
+ * session's available commands + media button preferences, never here.
+ *
  * Artwork loading is wired separately on the [androidx.media3.session.MediaSession]
  * via `setBitmapLoader(...)` — the provider routes artwork requests
  * through that loader chain

package/android/src/main/java/com/margelo/nitro/queueplayer/PlaybackService.kt

@@ -788,20 +788,18 @@ class PlaybackService : HeadlessJsMediaService() {
     )
 
   /**
-   * The compact notification view shows three buttons in priority
-   * order: prev / play-pause / next. Media3 1.9+ resolves these from
-   * standard player commands set via [CommandButton.Builder.setPlayerCommand]
-   * — no custom command handlers required. The expanded view shows
-   * the same three buttons plus the scrub progress bar that
-   * `DefaultMediaNotificationProvider` adds automatically when the
-   * session reports a known duration.
+   * The back + forward buttons for the notification compact view and the
+   * Android Auto control row. Play/pause is intentionally NOT supplied:
+   * Media3 owns the central slot (`CommandButton.SLOT_CENTRAL`) and
+   * synthesizes a state-aware play/pause from `COMMAND_PLAY_PAUSE`. A
+   * caller-supplied central button is dropped on the notification path
+   * (`DefaultMediaNotificationProvider` builds its own play/pause) and on
+   * Android Auto forces a static, non-toggling icon — so supplying only
+   * back/forward lets Media3 render the toggling play/pause on both
+   * surfaces. The expanded view adds the scrub progress bar automatically
+   * when the session reports a known duration.
    */
   private fun buildMediaButtonPreferences(): List<CommandButton> {
-    val playPause = CommandButton.Builder(CommandButton.ICON_PLAY)
-      .setPlayerCommand(Player.COMMAND_PLAY_PAUSE)
-      .setSlots(CommandButton.SLOT_CENTRAL)
-      .setDisplayName(getString(R.string.rnqp_action_play_pause))
-      .build()
     // In `interval` mode the back/forward slots jump within the current track
     // (COMMAND_SEEK_BACK / COMMAND_SEEK_FORWARD, honored by
     // [SessionCommandForwardingPlayer] with the runtime interval); in `track`
@@ -813,7 +811,6 @@ class PlaybackService : HeadlessJsMediaService() {
           .setSlots(CommandButton.SLOT_BACK)
           .setDisplayName(getString(R.string.rnqp_action_jump_backward))
           .build(),
-        playPause,
         CommandButton.Builder(CommandButton.ICON_SKIP_FORWARD)
           .setPlayerCommand(Player.COMMAND_SEEK_FORWARD)
           .setSlots(CommandButton.SLOT_FORWARD)
@@ -826,7 +823,6 @@ class PlaybackService : HeadlessJsMediaService() {
           .setSlots(CommandButton.SLOT_BACK)
           .setDisplayName(getString(R.string.rnqp_action_previous))
           .build(),
-        playPause,
         CommandButton.Builder(CommandButton.ICON_NEXT)
           .setPlayerCommand(Player.COMMAND_SEEK_TO_NEXT)
           .setSlots(CommandButton.SLOT_FORWARD)
@@ -1620,6 +1616,13 @@ class PlaybackService : HeadlessJsMediaService() {
       // Once both are zero, AA lands on the Library/Browse surface
       // instead of "Now Playing — To play something, tap the icon at
       // the top left."
+      //
+      // This rides Media3 1.10.0's internal Player.Commands →
+      // PlaybackStateCompat action-mask translation, which is not a public
+      // contract — re-validate on a Media3 upgrade. Unit tests cover the
+      // command-strip input; the resulting action mask is verified on the
+      // Android Auto lane, since the legacy bridge only populates for a
+      // connected controller that can't be driven under Robolectric.
       builder.remove(Player.COMMAND_PLAY_PAUSE)
       builder.remove(Player.COMMAND_PREPARE)
       builder.remove(Player.COMMAND_STOP)
@@ -1646,11 +1649,11 @@ class PlaybackService : HeadlessJsMediaService() {
   /**
    * Hook the [PlaybackCallback] consults before letting Media3 route
    * a controller-initiated command to the bound player. Calls run on
-   * the service main looper. Skip-next / skip-previous return true
-   * when the implementation has handled the skip itself, so the
-   * default routing is suppressed; the transport hook fires for play /
-   * pause / seek / setPlaybackSpeed and is purely a side-channel
-   * notification (no return value).
+   * the service main looper. Skip-next / skip-previous / seek-to-queue-item
+   * return true when the implementation has handled the command itself,
+   * so the default routing is suppressed; the transport hook fires for
+   * play / pause / in-item seek / setPlaybackSpeed and is purely a
+   * side-channel notification (no return value).
    */
   internal interface MediaSessionCommandHandler {
     /** Stamps `system` on the state-change channel for the upcoming
@@ -1662,6 +1665,12 @@ class PlaybackService : HeadlessJsMediaService() {
     /** Returns true if the lib intercepted the skip and the default
      *  routing should be suppressed. */
     fun onSkipToPreviousCommand(): Boolean
+    /** Routes an external controller's tap on a queue row (Android Auto's
+     *  "seek to this item") through the lib's `skipToIndex` path so the
+     *  canonical current index + track-change reason land. Returns true
+     *  when handled so the default per-item seek is suppressed; returns
+     *  false for an out-of-range index so the default routing no-ops it. */
+    fun onSeekToMediaItemCommand(mediaItemIndex: Int): Boolean
 
     /**
      * Returns the lib's current authoritative skip capability —

package/android/src/main/java/com/margelo/nitro/queueplayer/PlaybackServiceCallback.kt

@@ -368,6 +368,14 @@ internal class PlaybackServiceCallback(
     return dispatch.handle(intent, RemoteCommandDeduper.Channel.SESSION_KEY)
   }
 
+  /**
+   * Cold-start playback resumption: a hardware / Bluetooth media button that
+   * wakes the service while nothing is loaded. Returns an empty queue by
+   * design — the lib does not reconstruct a queue here; a consumer that wants
+   * resume-from-cold restores its own queue on launch via `setQueue`. The
+   * override exists (rather than being omitted) because Media3 requires a
+   * declared `MediaButtonReceiver` to pair with an `onPlaybackResumption`.
+   */
   override fun onPlaybackResumption(
     mediaSession: MediaSession,
     controller: MediaSession.ControllerInfo,

package/android/src/main/java/com/margelo/nitro/queueplayer/SessionCommandForwardingPlayer.kt

@@ -89,6 +89,15 @@ internal class SessionCommandForwardingPlayer(
       Player.COMMAND_SEEK_TO_PREVIOUS_MEDIA_ITEM ->
         if (commandHandler()?.onSkipToPreviousCommand() == true) Futures.immediateVoidFuture()
         else super.handleSeek(mediaItemIndex, positionMs, seekCommand)
+      // Android Auto's queue-row tap. A raw per-item seek would move the
+      // player without updating the lib's canonical current index — the
+      // SEEK transition handler only syncs the index for player-originated
+      // transitions, not controller seeks. Route through the skip path so
+      // the index + track-change reason land; an index the lib declines
+      // (out of range) falls through to the default seek.
+      Player.COMMAND_SEEK_TO_MEDIA_ITEM ->
+        if (commandHandler()?.onSeekToMediaItemCommand(mediaItemIndex) == true) Futures.immediateVoidFuture()
+        else super.handleSeek(mediaItemIndex, positionMs, seekCommand)
       // Interval-skip mode: recompute the target with the runtime jump interval
       // rather than the wrapped player's build-time seek increment, so the value
       // is adjustable at runtime.

package/android/src/main/java/com/margelo/nitro/queueplayer/TrackPlayer.kt

@@ -991,6 +991,25 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
         return true
       }
 
+      override fun onSeekToMediaItemCommand(mediaItemIndex: Int): Boolean {
+        // Decline an out-of-range index so the default per-item seek
+        // no-ops it (Media3 passes C.INDEX_UNSET when the seek implies
+        // no move).
+        if (mediaItemIndex < 0 || mediaItemIndex >= tracks.size) return false
+        pendingStateChangeReason = StateChangeReason.SYSTEM
+        // Same path as the public skipToIndex: jump the receiver while
+        // casting, else the local engine. Both write currentTrackIndex +
+        // the USER_SKIP_TO_INDEX reason that a raw controller seek skips.
+        // The tapped track starts at position 0 — the controller's
+        // positionMs is intentionally not threaded through, matching the
+        // public skipToIndex "play this track" contract.
+        if (com.margelo.nitro.queueplayer.cast.CastTransportRouter.routeSkipToIndex(mediaItemIndex)) {
+          return true
+        }
+        skipToIndexInternal(mediaItemIndex)
+        return true
+      }
+
       override fun onMediaPlay() {
         pendingStateChangeReason = StateChangeReason.SYSTEM
         serviceBinder?.engine?.play()

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

@@ -11,9 +11,6 @@
        transport button. Shown by TalkBack and by pre-Media3 controllers
        that read the platform PlaybackStateCompat custom-action name. -->
   <string name="rnqp_action_previous">Previous</string>
-  <!-- Accessibility / legacy-controller label for the play-pause
-       transport button. -->
-  <string name="rnqp_action_play_pause">Play or pause</string>
   <!-- Accessibility / legacy-controller label for the next-track
        transport button. -->
   <string name="rnqp_action_next">Next</string>

package/android/src/test/java/com/margelo/nitro/queueplayer/AvrcpMetadataTest.kt

@@ -252,6 +252,7 @@ class AvrcpMetadataTest {
     override fun onTransportCommand() {}
     override fun onSkipToNextCommand(): Boolean = false
     override fun onSkipToPreviousCommand(): Boolean = false
+    override fun onSeekToMediaItemCommand(mediaItemIndex: Int): Boolean = false
     override fun getCachedSkipCapability(): SkipCapability = capability
     override fun onMediaPlay() {}
     override fun onMediaPause() {}

package/android/src/test/java/com/margelo/nitro/queueplayer/MediaButtonDispatchTest.kt

@@ -179,6 +179,7 @@ class MediaButtonDispatchTest {
     override fun onTransportCommand() { transportCalls++ }
     override fun onSkipToNextCommand(): Boolean { skipNextCmdCalls++; return true }
     override fun onSkipToPreviousCommand(): Boolean { skipPreviousCmdCalls++; return true }
+    override fun onSeekToMediaItemCommand(mediaItemIndex: Int): Boolean = false
     override fun getCachedSkipCapability(): SkipCapability =
       SkipCapability(canSkipPrevious = true, canSkipNext = true)
     override fun onMediaPlay() { playCalls++ }

package/android/src/test/java/com/margelo/nitro/queueplayer/MediaButtonPreferencesTest.kt

@@ -0,0 +1,99 @@
+package com.margelo.nitro.queueplayer
+
+import android.content.Intent
+import androidx.media3.common.Player
+import androidx.media3.common.util.UnstableApi
+import androidx.media3.session.CommandButton
+import androidx.media3.session.MediaSession
+import androidx.test.core.app.ApplicationProvider
+import org.junit.After
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertTrue
+import org.junit.Before
+import org.junit.Test
+import org.junit.runner.RunWith
+import org.robolectric.Robolectric
+import org.robolectric.RobolectricTestRunner
+import org.robolectric.android.controller.ServiceController
+import org.robolectric.annotation.Config
+
+/**
+ * Robolectric coverage for the media button preferences the notification
+ * compact view + Android Auto control row consume, produced by
+ * [PlaybackService.buildMediaButtonPreferences] and read back off the
+ * session's public `mediaButtonPreferences`.
+ *
+ * The lib supplies only the back / forward buttons. Play/pause belongs to
+ * Media3's central slot: `DefaultMediaNotificationProvider` synthesizes a
+ * state-aware play/pause from `COMMAND_PLAY_PAUSE`, and Android Auto fills
+ * the empty central slot the same way — so a lib-supplied `SLOT_CENTRAL`
+ * button is dropped on the notification and forces a static, non-toggling
+ * icon on Android Auto.
+ */
+@RunWith(RobolectricTestRunner::class)
+@Config(sdk = [34])
+@UnstableApi
+class MediaButtonPreferencesTest {
+
+  private lateinit var controller: ServiceController<PlaybackService>
+  private lateinit var service: PlaybackService
+  private lateinit var session: MediaSession
+
+  @Before
+  fun setUp() {
+    controller = Robolectric.buildService(PlaybackService::class.java).create()
+    service = controller.get()
+    val intent = Intent(
+      ApplicationProvider.getApplicationContext<android.content.Context>(),
+      PlaybackService::class.java,
+    ).setAction(PlaybackService.ACTION_LOCAL_BIND)
+    val binder = service.onBind(intent) as PlaybackService.LocalBinder
+    session = binder.session
+  }
+
+  @After
+  fun tearDown() {
+    controller.destroy()
+  }
+
+  @Test
+  fun `track mode supplies previous plus next and leaves play-pause to Media3`() {
+    service.applyRemoteControls(RemoteSkipMode.TRACK, 15_000L, 15_000L)
+    val prefs = session.mediaButtonPreferences
+    assertNoLibPlayPause(prefs)
+    assertTrue(
+      "previous occupies the back slot",
+      prefs.any { it.slots.contains(CommandButton.SLOT_BACK) },
+    )
+    assertTrue(
+      "next occupies the forward slot",
+      prefs.any { it.slots.contains(CommandButton.SLOT_FORWARD) },
+    )
+  }
+
+  @Test
+  fun `interval mode supplies skip-back plus skip-forward and leaves play-pause to Media3`() {
+    service.applyRemoteControls(RemoteSkipMode.INTERVAL, 15_000L, 10_000L)
+    val prefs = session.mediaButtonPreferences
+    assertNoLibPlayPause(prefs)
+    assertTrue(
+      "skip-back occupies the back slot",
+      prefs.any { it.slots.contains(CommandButton.SLOT_BACK) },
+    )
+    assertTrue(
+      "skip-forward occupies the forward slot",
+      prefs.any { it.slots.contains(CommandButton.SLOT_FORWARD) },
+    )
+  }
+
+  private fun assertNoLibPlayPause(prefs: List<CommandButton>) {
+    assertFalse(
+      "play/pause is Media3's central-slot button, never supplied by the lib",
+      prefs.any { it.playerCommand == Player.COMMAND_PLAY_PAUSE },
+    )
+    assertFalse(
+      "the lib never claims SLOT_CENTRAL — Media3 owns it",
+      prefs.any { it.slots.contains(CommandButton.SLOT_CENTRAL) },
+    )
+  }
+}

package/android/src/test/java/com/margelo/nitro/queueplayer/PlaybackServiceCallbackTest.kt

@@ -375,6 +375,76 @@ class PlaybackServiceCallbackTest {
     }
   }
 
+  @Test
+  fun `TrackPlayer onSeekToMediaItemCommand jumps to the tapped index and stamps reasons`() {
+    val player = newConfiguredPlayer()
+    try {
+      player.tracks = listOf(
+        TrackItem("a", "https://example.com/a.m4a", null, null, null, null, null, null),
+        TrackItem("b", "https://example.com/b.m4a", null, null, null, null, null, null),
+        TrackItem("c", "https://example.com/c.m4a", null, null, null, null, null, null),
+      )
+      player.currentTrackIndex = 0
+
+      val intercepted = player.mediaSessionCommandHandler.onSeekToMediaItemCommand(2)
+
+      assertTrue(
+        "an Android Auto queue-row tap is queue-aware and reports interception",
+        intercepted
+      )
+      assertEquals(2, player.currentTrackIndex)
+      assertEquals(StateChangeReason.SYSTEM, player.pendingStateChangeReason)
+      assertEquals(
+        TrackChangeReason.USER_SKIP_TO_INDEX, player.pendingTrackChangeReason
+      )
+    } finally {
+      tearDownPlayer(player)
+    }
+  }
+
+  @Test
+  fun `TrackPlayer onSeekToMediaItemCommand declines an out-of-range index and leaves the current index`() {
+    val player = newConfiguredPlayer()
+    try {
+      player.tracks = listOf(
+        TrackItem("a", "https://example.com/a.m4a", null, null, null, null, null, null),
+        TrackItem("b", "https://example.com/b.m4a", null, null, null, null, null, null),
+      )
+      player.currentTrackIndex = 1
+
+      val intercepted = player.mediaSessionCommandHandler.onSeekToMediaItemCommand(5)
+
+      assertFalse(
+        "an out-of-range tap is declined so the default routing no-ops it",
+        intercepted
+      )
+      assertEquals(1, player.currentTrackIndex)
+    } finally {
+      tearDownPlayer(player)
+    }
+  }
+
+  @Test
+  fun `TrackPlayer onSeekToMediaItemCommand on the current index is handled and keeps the index`() {
+    val player = newConfiguredPlayer()
+    try {
+      player.tracks = listOf(
+        TrackItem("a", "https://example.com/a.m4a", null, null, null, null, null, null),
+        TrackItem("b", "https://example.com/b.m4a", null, null, null, null, null, null),
+      )
+      player.currentTrackIndex = 1
+
+      val intercepted = player.mediaSessionCommandHandler.onSeekToMediaItemCommand(1)
+
+      // Tapping the playing row behaves like skipToIndex(current): handled,
+      // index unchanged, the engine restarts the track from the top.
+      assertTrue(intercepted)
+      assertEquals(1, player.currentTrackIndex)
+    } finally {
+      tearDownPlayer(player)
+    }
+  }
+
   // --- Voice / browse-leaf routing through onAddMediaItems / onSetMediaItems
 
   @Test
@@ -759,6 +829,8 @@ class PlaybackServiceCallbackTest {
       return skipPreviousHandled
     }
 
+    override fun onSeekToMediaItemCommand(mediaItemIndex: Int): Boolean = false
+
     override fun getCachedSkipCapability(): SkipCapability = capability
 
     // This suite covers the controller-driven callback routing only.

package/android/src/test/java/com/margelo/nitro/queueplayer/PlaybackServiceLifecycleTest.kt

@@ -300,6 +300,8 @@ class PlaybackServiceLifecycleTest {
       return true
     }
 
+    override fun onSeekToMediaItemCommand(mediaItemIndex: Int): Boolean = false
+
     override fun getCachedSkipCapability(): SkipCapability =
       SkipCapability(canSkipPrevious = true, canSkipNext = true)
 

package/android/src/test/java/com/margelo/nitro/queueplayer/SessionCommandForwardingPlayerTest.kt

@@ -135,6 +135,37 @@ class SessionCommandForwardingPlayerTest {
     }
   }
 
+  // --- Controller seek-to-queue-item (Android Auto queue-row tap): queue-aware veto
+  // (COMMAND_SEEK_TO_MEDIA_ITEM routes through onSeekToMediaItemCommand rather than
+  // the raw per-item seek, so the lib's current index + track-change reason land.)
+
+  @Test
+  fun `controller seek-to-queue-item runs queue-aware skip and vetoes the default seek when handled`() {
+    val wrapped = RecordingPlayer()
+    val handler = RecordingHandler(seekToMediaItemHandled = true)
+    val wrapper = newWrapper(wrapped, handler)
+
+    asController { wrapper.handleSeek(2, 0L, Player.COMMAND_SEEK_TO_MEDIA_ITEM) }
+
+    assertEquals("seek-to-queue-item routes into onSeekToMediaItemCommand", 1, handler.seekToMediaItemCalls)
+    assertEquals("the tapped queue index is forwarded", 2, handler.lastSeekToMediaItemIndex)
+    assertTrue("a handled queue tap vetoes the default seek", wrapped.seekCommands.isEmpty())
+    assertEquals(0, handler.transportCalls)
+  }
+
+  @Test
+  fun `controller seek-to-queue-item falls through to the default seek when not handled`() {
+    val wrapped = RecordingPlayer()
+    val handler = RecordingHandler(seekToMediaItemHandled = false)
+    val wrapper = newWrapper(wrapped, handler)
+
+    asController { wrapper.handleSeek(2, 0L, Player.COMMAND_SEEK_TO_MEDIA_ITEM) }
+
+    assertEquals(1, handler.seekToMediaItemCalls)
+    assertEquals("a declined queue tap delegates one seek to the wrapped player",
+      listOf(Player.COMMAND_SEEK_TO_MEDIA_ITEM), wrapped.seekCommands)
+  }
+
   // --- Controller transport seeks: stamp system then delegate
   // (SEEK_BACK / SEEK_FORWARD are recomputed to the runtime interval — see the
   // interval-skip tests above — so they are not part of this pass-through set.)
@@ -144,7 +175,6 @@ class SessionCommandForwardingPlayerTest {
     val transportSeeks = listOf(
       Player.COMMAND_SEEK_IN_CURRENT_MEDIA_ITEM,
       Player.COMMAND_SEEK_TO_DEFAULT_POSITION,
-      Player.COMMAND_SEEK_TO_MEDIA_ITEM,
     )
     for (command in transportSeeks) {
       val wrapped = RecordingPlayer()
@@ -319,6 +349,21 @@ class SessionCommandForwardingPlayerTest {
     }
   }
 
+  @Test
+  fun `non-controller seek-to-queue-item delegates straight through without consulting the handler`() {
+    val wrapped = RecordingPlayer()
+    val handler = RecordingHandler(seekToMediaItemHandled = true)
+    val wrapper = newWrapper(wrapped, handler)
+
+    // No controller-request scope: models the JS bridge / engine driving
+    // the player directly, which must never re-enter the skip path.
+    wrapper.handleSeek(C_INDEX, 0L, Player.COMMAND_SEEK_TO_MEDIA_ITEM)
+
+    assertEquals("internal seek never consults onSeekToMediaItemCommand", 0, handler.seekToMediaItemCalls)
+    assertEquals("internal seek delegates straight to the wrapped player",
+      listOf(Player.COMMAND_SEEK_TO_MEDIA_ITEM), wrapped.seekCommands)
+  }
+
   @Test
   fun `non-controller transport delegates straight through without consulting the handler`() {
     val wrapped = RecordingPlayer()
@@ -344,16 +389,18 @@ class SessionCommandForwardingPlayerTest {
 
     asController { wrapper.handleSeek(C_INDEX, 0L, Player.COMMAND_SEEK_TO_NEXT) }
     asController { wrapper.handleSeek(C_INDEX, 0L, Player.COMMAND_SEEK_TO_PREVIOUS) }
+    asController { wrapper.handleSeek(C_INDEX, 0L, Player.COMMAND_SEEK_TO_MEDIA_ITEM) }
     asController { wrapper.handleSeek(C_INDEX, 0L, Player.COMMAND_SEEK_BACK) }
     asController { wrapper.handleSetPlayWhenReady(true) }
     asController { wrapper.handleSetPlaybackParameters(PlaybackParameters(1.25f)) }
 
-    // With no handler the skip cannot be vetoed, so all five delegate.
+    // With no handler the skip / queue-tap cannot be vetoed, so all delegate.
     // SEEK_BACK is recomputed to the interval and forwarded as an in-item seek.
     assertEquals(
       listOf(
         Player.COMMAND_SEEK_TO_NEXT,
         Player.COMMAND_SEEK_TO_PREVIOUS,
+        Player.COMMAND_SEEK_TO_MEDIA_ITEM,
         Player.COMMAND_SEEK_IN_CURRENT_MEDIA_ITEM,
       ),
       wrapped.seekCommands
@@ -482,10 +529,13 @@ class SessionCommandForwardingPlayerTest {
   private class RecordingHandler(
     private val skipNextHandled: Boolean = true,
     private val skipPreviousHandled: Boolean = true,
+    private val seekToMediaItemHandled: Boolean = true,
   ) : PlaybackService.MediaSessionCommandHandler {
     var transportCalls = 0
     var skipNextCalls = 0
     var skipPreviousCalls = 0
+    var seekToMediaItemCalls = 0
+    var lastSeekToMediaItemIndex = Int.MIN_VALUE
 
     override fun onTransportCommand() {
       transportCalls++
@@ -501,6 +551,12 @@ class SessionCommandForwardingPlayerTest {
       return skipPreviousHandled
     }
 
+    override fun onSeekToMediaItemCommand(mediaItemIndex: Int): Boolean {
+      seekToMediaItemCalls++
+      lastSeekToMediaItemIndex = mediaItemIndex
+      return seekToMediaItemHandled
+    }
+
     override fun getCachedSkipCapability(): SkipCapability =
       SkipCapability(canSkipPrevious = true, canSkipNext = true)
 

package/ios/CarPlayCoordinator.swift

@@ -29,17 +29,27 @@ final class CarPlayCoordinator {
   static let shared = CarPlayCoordinator()
 
   let dataProvider: CarPlayBrowseDataProvider
+  let queueProvider: CarPlayQueueProvider
   let bridge: CarPlayBridge
   let pending: PendingBrowseRequests
   let loader: ArtworkLoader
 
   private init() {
     self.dataProvider = CarPlayBrowseDataProvider()
+    self.queueProvider = CarPlayQueueProvider()
     self.bridge = CarPlayBridge()
     self.pending = PendingBrowseRequests()
     self.loader = ArtworkLoader()
   }
 
+  // MARK: - Queue skip
+
+  /// Skip playback to a queue index. `TrackPlayer` registers this at
+  /// configure; the CarPlay scene delegate invokes it when the user
+  /// taps a row in the Up Next list. Set and called on the main thread
+  /// only, so no lock is needed.
+  var skipToIndexHandler: ((Int) -> Void)?
+
   // MARK: - Connection state
 
   /// Whether the CarPlay scene is currently connected. Written by

package/ios/CarPlayQueueBuilder.swift

@@ -0,0 +1,82 @@
+import CarPlay
+import UIKit
+
+/// Convert a [CarPlayQueueSnapshot] into the CarPlay "Up Next" list
+/// template shown when the user taps the Now Playing queue button.
+/// Single-section `CPListTemplate` — one `CPListItem` per queue entry,
+/// with the currently-playing entry marked via `isPlaying`.
+///
+/// Audio-app list cap: CarPlay reports the runtime row limit via
+/// `CPListTemplate.maximumItemCount`. Over-cap queues are truncated to
+/// the first N rows; the current entry's index still maps 1:1 to the
+/// list row as long as it falls inside the cap.
+///
+/// Stateless helper. The owning scene delegate pushes the returned
+/// template onto the interface controller.
+final class CarPlayQueueBuilder {
+
+  /// Maximum rows per Up Next list. Reads the SDK property so the cap
+  /// tracks whatever the running CarPlay framework enforces.
+  static var maximumItemCount: Int { CPListTemplate.maximumItemCount }
+
+  /// Build the Up Next `CPListTemplate` from [snapshot]. Each row's
+  /// tap handler invokes [skip] with that row's queue index, then the
+  /// caller pops back to Now Playing. The entry at
+  /// `snapshot.currentIndex` is marked `isPlaying`. Rows beyond
+  /// [maximumItemCount] are dropped.
+  func buildQueueTemplate(
+    snapshot: CarPlayQueueSnapshot,
+    loader: ArtworkLoader,
+    maximumItemCount: Int = CarPlayQueueBuilder.maximumItemCount,
+    skip: @escaping (Int) -> Void
+  ) -> CPListTemplate {
+    let cap = max(0, maximumItemCount)
+    let visible = snapshot.entries.prefix(cap)
+    let items = visible.enumerated().map { index, entry in
+      makeQueueItem(
+        entry: entry,
+        index: index,
+        isCurrent: index == snapshot.currentIndex,
+        loader: loader,
+        skip: skip
+      )
+    }
+    return CPListTemplate(
+      title: upNextTitle,
+      sections: [CPListSection(items: items)]
+    )
+  }
+
+  /// Build a single Up Next row. Text = entry title, detail = subtitle.
+  /// Tap fires [skip] with [index]. The current row shows the playing
+  /// indicator; artwork loads asynchronously via [loader].
+  func makeQueueItem(
+    entry: CarPlayQueueEntry,
+    index: Int,
+    isCurrent: Bool,
+    loader: ArtworkLoader,
+    skip: @escaping (Int) -> Void
+  ) -> CPListItem {
+    let listItem = CPListItem(
+      text: entry.title,
+      detailText: entry.subtitle,
+      image: nil
+    )
+    listItem.isPlaying = isCurrent
+    if let artworkUrl = entry.artworkUrl, !artworkUrl.isEmpty {
+      loader.load(uri: artworkUrl) { [weak listItem] image in
+        guard let listItem = listItem, let image = image else { return }
+        listItem.setImage(image)
+      }
+    }
+    listItem.handler = { _, completion in
+      skip(index)
+      completion()
+    }
+    return listItem
+  }
+
+  private var upNextTitle: String {
+    NSLocalizedString("Up Next", comment: "CarPlay queue list title")
+  }
+}

package/ios/CarPlayQueueProvider.swift

@@ -0,0 +1,73 @@
+import Foundation
+
+/// One queue entry mirrored for the CarPlay Up Next surface. A plain
+/// value type decoupled from the Nitro `TrackItem` — the mirror holds
+/// only what the list template renders, so the CarPlay scene reads
+/// display data without reaching back into the Hybrid.
+struct CarPlayQueueEntry {
+  let title: String
+  let subtitle: String?
+  let artworkUrl: String?
+}
+
+/// Immutable mirror of the live play queue for the CarPlay Up Next
+/// list. `currentIndex` is the index of the playing track, or -1 when
+/// nothing is current. Snapshot replacement is atomic (see
+/// [CarPlayQueueProvider]).
+struct CarPlayQueueSnapshot {
+  let entries: [CarPlayQueueEntry]
+  let currentIndex: Int
+}
+
+/// Native cache for the most-recent [CarPlayQueueSnapshot] pushed by
+/// `TrackPlayer` whenever the queue or current index changes. The
+/// CarPlay scene delegate reads from this cache to build the Up Next
+/// list so a queue-button tap does not have to round-trip through JS.
+///
+/// Snapshot replacement is atomic: a single `NSLock` guards the stored
+/// reference. Concurrent readers see either the prior snapshot in full
+/// or the new one in full, never a torn mix.
+///
+/// Update notifications: a `Notification` named
+/// [CarPlayQueueProvider.didUpdateNotification] fires on the main queue
+/// after every `setSnapshot`. The scene delegate observes it to
+/// re-evaluate the Up Next button's enabled state as the queue changes.
+final class CarPlayQueueProvider {
+
+  /// Notification posted on the main queue after `setSnapshot`.
+  static let didUpdateNotification = Notification.Name(
+    "com.margelo.nitro.queueplayer.CarPlayQueueProvider.didUpdate"
+  )
+
+  /// Replace the cached snapshot. Pass `nil` to clear. Posts
+  /// [didUpdateNotification] on the main queue (dispatched to main if
+  /// the caller is off-main) so observers re-evaluate against the new
+  /// snapshot on a stable thread.
+  func setSnapshot(_ snapshot: CarPlayQueueSnapshot?) {
+    lock.lock()
+    self.snapshot = snapshot
+    lock.unlock()
+
+    let notify = {
+      NotificationCenter.default.post(
+        name: CarPlayQueueProvider.didUpdateNotification,
+        object: self
+      )
+    }
+    if Thread.isMainThread {
+      notify()
+    } else {
+      DispatchQueue.main.async(execute: notify)
+    }
+  }
+
+  /// Read the current snapshot, or `nil` if none has been set.
+  func getSnapshot() -> CarPlayQueueSnapshot? {
+    lock.lock()
+    defer { lock.unlock() }
+    return snapshot
+  }
+
+  private var snapshot: CarPlayQueueSnapshot?
+  private let lock = NSLock()
+}

package/ios/CarPlaySceneDelegate.swift

@@ -52,11 +52,19 @@ internal class CarPlaySceneDelegate: UIResponder, CPTemplateApplicationSceneDele
   /// delegate doesn't leak past its scene's lifetime.
   private var snapshotObserver: NSObjectProtocol?
 
+  /// Queue-mirror observer. Fires when the play queue or current index
+  /// changes so the Up Next button's enabled state re-evaluates.
+  /// Removed on scene disconnect.
+  private var queueObserver: NSObjectProtocol?
+
   /// Cached scene-construction template builder. Stateless; the
   /// live tab-bar reference above is what survives across snapshot
   /// updates.
   private let builder = CarPlayBrowseBuilder()
 
+  /// Stateless builder for the Up Next queue list template.
+  private let queueBuilder = CarPlayQueueBuilder()
+
   // MARK: - CPTemplateApplicationSceneDelegate
 
   public func templateApplicationScene(
@@ -122,6 +130,14 @@ internal class CarPlaySceneDelegate: UIResponder, CPTemplateApplicationSceneDele
       self?.refreshRootTemplate()
     }
 
+    queueObserver = NotificationCenter.default.addObserver(
+      forName: CarPlayQueueProvider.didUpdateNotification,
+      object: coordinator.queueProvider,
+      queue: .main
+    ) { [weak self] _ in
+      self?.refreshUpNextButton()
+    }
+
     coordinator.setCarConnected(true)
     coordinator.bridge.carConnectCallback()?()
   }
@@ -138,6 +154,11 @@ internal class CarPlaySceneDelegate: UIResponder, CPTemplateApplicationSceneDele
       NotificationCenter.default.removeObserver(observer)
       snapshotObserver = nil
     }
+    if let observer = queueObserver {
+      NotificationCenter.default.removeObserver(observer)
+      queueObserver = nil
+    }
+    CPNowPlayingTemplate.shared.remove(self)
     self.interfaceController = nil
     self.rootTabBar = nil
     CarPlayCoordinator.shared.setCarConnected(false)
@@ -188,14 +209,65 @@ internal class CarPlaySceneDelegate: UIResponder, CPTemplateApplicationSceneDele
   /// nav stack via `pushTemplate(CPNowPlayingTemplate.shared, ...)`
   /// is the supported path for `com.apple.developer.carplay-audio`
   /// apps; embedding the same template in a `CPTabBarTemplate` root
-  /// is NOT — that raises `NSInvalidArgumentException`. Property
-  /// mutation here is intentionally avoided — earlier iOS 26 sim
-  /// experiments setting `isUpNextButtonEnabled = false` /
-  /// `isAlbumArtistButtonEnabled = false` left the template rendering
-  /// blank; baseline defaults work.
+  /// is NOT — that raises `NSInvalidArgumentException`.
+  ///
+  /// Registers self as a `CPNowPlayingTemplateObserver` so the Up Next
+  /// button tap routes into [nowPlayingTemplateUpNextButtonTapped].
+  /// Enables only the Up Next flag + title (when the mirrored queue is
+  /// non-empty); every other Now Playing button keeps baseline defaults.
   private func configureNowPlayingTemplate() {
-    _ = CPNowPlayingTemplate.shared
-    NSLog("[RNQP-CarPlay] CPNowPlayingTemplate.shared touched")
+    CPNowPlayingTemplate.shared.add(self)
+    refreshUpNextButton()
+    NSLog("[RNQP-CarPlay] CPNowPlayingTemplate.shared configured")
+  }
+
+  /// Enable the Up Next button when the mirrored queue has entries.
+  /// Re-run from the queue-mirror observer so the button reflects the
+  /// live queue.
+  private func refreshUpNextButton() {
+    let hasQueue = !(
+      CarPlayCoordinator.shared.queueProvider.getSnapshot()?.entries.isEmpty ?? true
+    )
+    CPNowPlayingTemplate.shared.isUpNextButtonEnabled = hasQueue
+    CPNowPlayingTemplate.shared.upNextTitle = upNextTitle
+  }
+
+  private var upNextTitle: String {
+    NSLocalizedString("Up Next", comment: "CarPlay queue button title")
   }
 
 }
+
+// MARK: - CPNowPlayingTemplateObserver
+
+@available(iOS 14.0, *)
+extension CarPlaySceneDelegate: CPNowPlayingTemplateObserver {
+
+  /// Build the Up Next list from the mirrored queue snapshot and push
+  /// it. Each row taps back to Now Playing after routing the skip
+  /// through the coordinator's `skipToIndexHandler`, which `TrackPlayer`
+  /// registers. No-op when no queue is mirrored yet.
+  func nowPlayingTemplateUpNextButtonTapped(
+    _ nowPlayingTemplate: CPNowPlayingTemplate
+  ) {
+    guard let controller = interfaceController else { return }
+    // Only push from the Now Playing surface — guards against a
+    // spurious double-push if the tap re-fires while the list is up.
+    guard controller.topTemplate === CPNowPlayingTemplate.shared else { return }
+    guard let snapshot = CarPlayCoordinator.shared.queueProvider.getSnapshot(),
+          !snapshot.entries.isEmpty else {
+      return
+    }
+    let list = queueBuilder.buildQueueTemplate(
+      snapshot: snapshot,
+      loader: CarPlayCoordinator.shared.loader,
+      skip: { [weak self] index in
+        CarPlayCoordinator.shared.skipToIndexHandler?(index)
+        // Return to Now Playing — pop the Up Next list off the nav
+        // stack; the Now Playing surface is already beneath it.
+        self?.interfaceController?.popTemplate(animated: true) { _, _ in }
+      }
+    )
+    controller.pushTemplate(list, animated: true) { _, _ in }
+  }
+}

package/ios/Tests/CarPlayQueueBuilderTests.swift

@@ -0,0 +1,145 @@
+import CarPlay
+import XCTest
+@testable import QueuePlayer
+
+/// Coverage for [CarPlayQueueBuilder] — snapshot → Up Next template
+/// conversion, row count + title/detail mapping, truncation at
+/// `CPListTemplate.maximumItemCount`, current-index marking, and the
+/// row-tap skip closure — plus a [CarPlayQueueProvider] round-trip.
+final class CarPlayQueueBuilderTests: XCTestCase {
+
+  private func entry(
+    _ title: String,
+    subtitle: String? = nil,
+    artworkUrl: String? = nil
+  ) -> CarPlayQueueEntry {
+    CarPlayQueueEntry(title: title, subtitle: subtitle, artworkUrl: artworkUrl)
+  }
+
+  private func snapshot(
+    _ entries: [CarPlayQueueEntry],
+    currentIndex: Int
+  ) -> CarPlayQueueSnapshot {
+    CarPlayQueueSnapshot(entries: entries, currentIndex: currentIndex)
+  }
+
+  // MARK: - Template construction
+
+  func testBuildQueueTemplateMapsEntriesToRows() {
+    let builder = CarPlayQueueBuilder()
+    let loader = ArtworkLoader()
+    let template = builder.buildQueueTemplate(
+      snapshot: snapshot(
+        [
+          entry("Everlong", subtitle: "Foo Fighters"),
+          entry("Monkey Wrench", subtitle: "Foo Fighters"),
+        ],
+        currentIndex: 0
+      ),
+      loader: loader,
+      skip: { _ in }
+    )
+    let items = (template.sections.first?.items ?? []).compactMap { $0 as? CPListItem }
+    XCTAssertEqual(items.count, 2)
+    XCTAssertEqual(items[0].text, "Everlong")
+    XCTAssertEqual(items[0].detailText, "Foo Fighters")
+    XCTAssertEqual(items[1].text, "Monkey Wrench")
+  }
+
+  func testBuildQueueTemplateCapsRowsAtMaximumItemCount() {
+    let builder = CarPlayQueueBuilder()
+    let loader = ArtworkLoader()
+    let cap = 5
+    let entries = (0..<cap + 4).map { entry("T-\($0)") }
+    let template = builder.buildQueueTemplate(
+      snapshot: snapshot(entries, currentIndex: 0),
+      loader: loader,
+      maximumItemCount: cap,
+      skip: { _ in }
+    )
+    let items = template.sections.first?.items ?? []
+    XCTAssertEqual(items.count, cap)
+  }
+
+  func testBuildQueueTemplateMarksCurrentIndex() {
+    let builder = CarPlayQueueBuilder()
+    let loader = ArtworkLoader()
+    let template = builder.buildQueueTemplate(
+      snapshot: snapshot(
+        [entry("A"), entry("B"), entry("C")],
+        currentIndex: 1
+      ),
+      loader: loader,
+      skip: { _ in }
+    )
+    let items = (template.sections.first?.items ?? []).compactMap { $0 as? CPListItem }
+    XCTAssertFalse(items[0].isPlaying)
+    XCTAssertTrue(items[1].isPlaying)
+    XCTAssertFalse(items[2].isPlaying)
+  }
+
+  func testBuildQueueTemplateMarksNothingWhenIndexOutOfRange() {
+    let builder = CarPlayQueueBuilder()
+    let loader = ArtworkLoader()
+    let template = builder.buildQueueTemplate(
+      snapshot: snapshot([entry("A"), entry("B")], currentIndex: -1),
+      loader: loader,
+      skip: { _ in }
+    )
+    let items = (template.sections.first?.items ?? []).compactMap { $0 as? CPListItem }
+    XCTAssertTrue(items.allSatisfy { !$0.isPlaying })
+  }
+
+  // MARK: - Row-tap skip
+
+  func testRowTapInvokesSkipWithRowIndex() {
+    let builder = CarPlayQueueBuilder()
+    let loader = ArtworkLoader()
+    var skippedTo: Int?
+    let template = builder.buildQueueTemplate(
+      snapshot: snapshot([entry("A"), entry("B"), entry("C")], currentIndex: 0),
+      loader: loader,
+      skip: { skippedTo = $0 }
+    )
+    let items = (template.sections.first?.items ?? []).compactMap { $0 as? CPListItem }
+    let exp = expectation(description: "row handler completes")
+    items[2].handler?(items[2]) { exp.fulfill() }
+    wait(for: [exp], timeout: 2)
+    XCTAssertEqual(skippedTo, 2)
+  }
+
+  // MARK: - Provider round-trip
+
+  func testProviderSetSnapshotMakesSnapshotReadable() {
+    let provider = CarPlayQueueProvider()
+    XCTAssertNil(provider.getSnapshot())
+    provider.setSnapshot(
+      snapshot([entry("A", subtitle: "sub")], currentIndex: 0)
+    )
+    let read = provider.getSnapshot()
+    XCTAssertEqual(read?.entries.count, 1)
+    XCTAssertEqual(read?.entries.first?.title, "A")
+    XCTAssertEqual(read?.entries.first?.subtitle, "sub")
+    XCTAssertEqual(read?.currentIndex, 0)
+  }
+
+  func testProviderSetSnapshotNilClearsCache() {
+    let provider = CarPlayQueueProvider()
+    provider.setSnapshot(snapshot([entry("A")], currentIndex: 0))
+    provider.setSnapshot(nil)
+    XCTAssertNil(provider.getSnapshot())
+  }
+
+  func testProviderSetSnapshotPostsDidUpdateNotification() {
+    let provider = CarPlayQueueProvider()
+    let exp = expectation(
+      forNotification: CarPlayQueueProvider.didUpdateNotification,
+      object: provider,
+      handler: nil
+    )
+    DispatchQueue.global().async {
+      provider.setSnapshot(self.snapshot([self.entry("A")], currentIndex: 0))
+    }
+    wait(for: [exp], timeout: 2)
+  }
+}

package/ios/Tests/FFTProcessorTests.swift

@@ -33,7 +33,7 @@ final class FFTProcessorTests: XCTestCase {
     samples.withUnsafeBufferPointer { p in
       proc.ingest(samples: p.baseAddress!, frameCount: n, sampleRate: 48000)
     }
-    wait(for: [exp], timeout: 1.0)
+    wait(for: [exp], timeout: 5.0)
     XCTAssertEqual(capturedSampleRate, 48000, accuracy: 0.001)
   }
 
@@ -57,7 +57,7 @@ final class FFTProcessorTests: XCTestCase {
     rest.withUnsafeBufferPointer { p in
       proc.ingest(samples: p.baseAddress!, frameCount: 256, sampleRate: 44100)
     }
-    wait(for: [emitted], timeout: 1.0)
+    wait(for: [emitted], timeout: 5.0)
     XCTAssertEqual(calls, 1)
   }
 
@@ -74,7 +74,7 @@ final class FFTProcessorTests: XCTestCase {
     buffer.withUnsafeBufferPointer { p in
       proc.ingest(samples: p.baseAddress!, frameCount: 128, sampleRate: 44100)
     }
-    wait(for: [exp], timeout: 1.0)
+    wait(for: [exp], timeout: 5.0)
     let samples = try XCTUnwrap(capturedSamples)
     XCTAssertEqual(samples.size, 128 * MemoryLayout<Float>.size)
   }
@@ -94,7 +94,7 @@ final class FFTProcessorTests: XCTestCase {
     buffer.withUnsafeBufferPointer { p in
       proc.ingest(samples: p.baseAddress!, frameCount: 128, sampleRate: 44100)
     }
-    wait(for: [exp], timeout: 1.0)
+    wait(for: [exp], timeout: 5.0)
     XCTAssertTrue(captured)
     XCTAssertNil(capturedSamples)
   }
@@ -117,7 +117,7 @@ final class FFTProcessorTests: XCTestCase {
     samples.withUnsafeBufferPointer { p in
       proc.ingest(samples: p.baseAddress!, frameCount: n, sampleRate: 48000)
     }
-    wait(for: [exp], timeout: 1.0)
+    wait(for: [exp], timeout: 5.0)
     let fft = try XCTUnwrap(capturedFft)
     let mags = arrayBufferToFloats(fft)
     let peakBin = mags.indices.max(by: { mags[$0] < mags[$1] }) ?? -1
@@ -205,7 +205,7 @@ final class FFTProcessorTests: XCTestCase {
     closure(leftIn, leftOut, n, 1, 0, 2)
     closure(rightIn, rightOut, n, 1, 1, 2)
 
-    wait(for: [exp], timeout: 1.0)
+    wait(for: [exp], timeout: 5.0)
     let samples = try XCTUnwrap(capturedSamples)
     XCTAssertEqual(samples.size, n * MemoryLayout<Float>.size)
 
@@ -233,7 +233,9 @@ final class FFTProcessorTests: XCTestCase {
     }
     let exp = expectation(description: "drained")
     DispatchQueue.main.asyncAfter(deadline: .now() + 0.1) { exp.fulfill() }
-    wait(for: [exp], timeout: 1.0)
+    // Generous timeout: the 0.1s drain only needs to outlast the 1000ms
+    // throttle window; the ceiling is headroom for a loaded CI main queue.
+    wait(for: [exp], timeout: 10.0)
     XCTAssertEqual(calls, 1, "second back-to-back call must be throttled")
   }
 

package/ios/TrackPlayer.swift

@@ -587,6 +587,22 @@ class TrackPlayer: HybridTrackPlayerSpec {
           canSkipNext: self.cachedSkipCapability.canSkipNext,
           canSkipPrevious: self.cachedSkipCapability.canSkipPrevious
         )
+        // Route CarPlay Up Next row taps through the same steps the
+        // `skipToIndex` Hybrid runs — engine guard, index validation,
+        // and cast routing (a tap during an active cast session jumps
+        // the RECEIVER; the local engine stays paused, so a local index
+        // write would desync from it) — then the local index write.
+        // Set + invoked on main; the scene delegate calls it from the
+        // Up Next row handler.
+        CarPlayCoordinator.shared.skipToIndexHandler = { [weak self] index in
+          guard let self = self else { return }
+          guard self.engine != nil else { return }
+          guard let target = InputGuards.validQueueIndex(
+            Double(index), count: self.tracks.count
+          ) else { return }
+          if CastTransportRouter.routeSkipToIndex(index: target) { return }
+          self.applyNewCurrentIndex(newIndex: target, reason: .userSkipToIndex)
+        }
         // Refresh on every configure() so a header / UA update lands
         // on the next artwork resolve. Live config — read fresh on
         // each track-change resolve.
@@ -891,6 +907,8 @@ class TrackPlayer: HybridTrackPlayerSpec {
     // configure cycle.
     let coordinator = CarPlayCoordinator.shared
     coordinator.dataProvider.setSnapshot(nil)
+    coordinator.queueProvider.setSnapshot(nil)
+    coordinator.skipToIndexHandler = nil
     coordinator.pending.clear()
     coordinator.loader.clearCache()
     // engine.release() drains the underlying AVQueuePlayer's items +
@@ -2089,6 +2107,11 @@ class TrackPlayer: HybridTrackPlayerSpec {
   /// - `destroy` (resets to (false, false) so a final emit lets
   ///   subscribers know the player is gone)
   internal func recomputeCapabilities() {
+    // Every queue / current-index / repeat-mode change funnels through here,
+    // so it's the single point that keeps the CarPlay Up Next mirror current
+    // — done before the skip-capability dedup guard below so reorder/metadata
+    // changes (which don't flip skip capability) still refresh the mirror.
+    syncCarPlayQueueMirror()
     let mode = repeatModeAsSkipMode()
     let count = tracks.count
     let cur = currentTrackIndex
@@ -2109,6 +2132,30 @@ class TrackPlayer: HybridTrackPlayerSpec {
     )
   }
 
+  /// Mirror the live queue + current index into the process-wide
+  /// [CarPlayQueueProvider] so the CarPlay Up Next surface renders the
+  /// current playback queue without round-tripping through JS. Driven
+  /// from `recomputeCapabilities()`, which every queue / current-index /
+  /// repeat-mode change funnels through. An empty queue clears the
+  /// mirror to `nil` so the Up Next button hides. Main-thread only
+  /// (queue state is main-bound).
+  internal func syncCarPlayQueueMirror() {
+    guard !self.tracks.isEmpty else {
+      CarPlayCoordinator.shared.queueProvider.setSnapshot(nil)
+      return
+    }
+    let entries = self.tracks.map { track in
+      CarPlayQueueEntry(
+        title: track.title ?? "",
+        subtitle: track.artist ?? track.album,
+        artworkUrl: track.artworkUrl
+      )
+    }
+    CarPlayCoordinator.shared.queueProvider.setSnapshot(
+      CarPlayQueueSnapshot(entries: entries, currentIndex: self.currentTrackIndex)
+    )
+  }
+
   /// Apply a new `currentTrackIndex` and sync the AVQueuePlayer.
   ///
   /// **Forward skip** (newIndex > oldIndex) — surgical trim of items

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-queue-player",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "description": "Nitro Modules audio playback library for React Native — gapless, EQ, crossfade, automotive, voice, casting",
   "main": "./lib/module/index.js",
   "types": "./lib/typescript/index.d.ts",