react-native-queue-player 1.0.4 → 1.0.7

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

@@ -68,10 +68,9 @@ class PlaybackServiceCallbackSearchTest {
       override fun commandHandler() = null
       override fun mediaButtonDispatch() = null
       override fun playerCommandsFor(
-        capability: SkipCapability,
-        hasMediaItems: Boolean
+        capability: SkipCapability
       ): Player.Commands =
-        service.playerCommandsFor(capability, hasMediaItems)
+        service.playerCommandsFor(capability)
       override fun onSearchQueryReceived(query: String) {
         received.add(query)
       }

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

@@ -227,8 +227,7 @@ class PlaybackServiceCallbackTest {
   @Test
   fun `playerCommandsFor strips both skips when capability disallows both`() {
     val commands = service.playerCommandsFor(
-      SkipCapability(canSkipPrevious = false, canSkipNext = false),
-      hasMediaItems = true
+      SkipCapability(canSkipPrevious = false, canSkipNext = false)
     )
     assertFalse(commands.contains(Player.COMMAND_SEEK_TO_NEXT))
     assertFalse(commands.contains(Player.COMMAND_SEEK_TO_NEXT_MEDIA_ITEM))
@@ -243,23 +242,21 @@ class PlaybackServiceCallbackTest {
   }
 
   @Test
-  fun `playerCommandsFor strips PLAY-related commands when queue is empty`() {
-    // Empty queue → action mask must carry no ACTION_PLAY bits so
-    // AA's dashboard tap routes to Library rather than Now Playing.
+  fun `playerCommandsFor keeps transport commands when queue is empty`() {
+    // Transport commands stay available so the API 33+ System UI keeps the
+    // play/pause button + the draggable seek scrubber; only the skip pair
+    // greys out with the queue boundary.
     val commands = service.playerCommandsFor(
-      SkipCapability(canSkipPrevious = false, canSkipNext = false),
-      hasMediaItems = false
+      SkipCapability(canSkipPrevious = false, canSkipNext = false)
     )
-    assertFalse(
-      "PLAY_PAUSE drives the legacy ACTION_PLAY bit; must be absent on empty queue",
+    assertTrue(
+      "play/pause is retained for the System UI play/pause button",
       commands.contains(Player.COMMAND_PLAY_PAUSE)
     )
-    assertFalse(commands.contains(Player.COMMAND_PREPARE))
-    assertFalse(commands.contains(Player.COMMAND_STOP))
-    assertFalse(commands.contains(Player.COMMAND_SEEK_TO_DEFAULT_POSITION))
-    assertFalse(commands.contains(Player.COMMAND_SET_SPEED_AND_PITCH))
-    assertFalse(commands.contains(Player.COMMAND_SET_REPEAT_MODE))
-    assertFalse(commands.contains(Player.COMMAND_SET_SHUFFLE_MODE))
+    assertTrue(commands.contains(Player.COMMAND_PREPARE))
+    assertTrue(commands.contains(Player.COMMAND_SEEK_TO_DEFAULT_POSITION))
+    assertTrue(commands.contains(Player.COMMAND_SEEK_IN_CURRENT_MEDIA_ITEM))
+    assertTrue(commands.contains(Player.COMMAND_SET_SPEED_AND_PITCH))
   }
 
   @Test
@@ -342,7 +339,7 @@ class PlaybackServiceCallbackTest {
       // The handler's value is what `PlaybackCallback.onConnect` reads,
       // so a fresh `onConnect` against any session sharing this handler
       // sees the post-flip command set.
-      val playerCommands = service.playerCommandsFor(mid, hasMediaItems = true)
+      val playerCommands = service.playerCommandsFor(mid)
       assertTrue(playerCommands.contains(Player.COMMAND_SEEK_TO_NEXT_MEDIA_ITEM))
       assertFalse(playerCommands.contains(Player.COMMAND_SEEK_TO_PREVIOUS_MEDIA_ITEM))
     } finally {
@@ -375,6 +372,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 +826,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.
@@ -804,10 +873,9 @@ class PlaybackServiceCallbackTest {
     override fun mediaButtonDispatch(): MediaButtonDispatch? = null
 
     override fun playerCommandsFor(
-      capability: SkipCapability,
-      hasMediaItems: Boolean
+      capability: SkipCapability
     ): Player.Commands =
-      service.playerCommandsFor(capability, hasMediaItems)
+      service.playerCommandsFor(capability)
 
     override fun onPlayFromSearchRequest(
       request: MediaSearchRequest

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

@@ -65,7 +65,6 @@ class PlayerCommandsForTest {
   fun `commands include every skip pair when capability allows both`() {
     val commands = service.playerCommandsFor(
       SkipCapability(canSkipPrevious = true, canSkipNext = true),
-      hasMediaItems = true,
     )
     assertTrue(commands.contains(Player.COMMAND_SEEK_TO_NEXT))
     assertTrue(commands.contains(Player.COMMAND_SEEK_TO_NEXT_MEDIA_ITEM))
@@ -78,7 +77,6 @@ class PlayerCommandsForTest {
   fun `commands omit only the next pair when capability disallows skip-next`() {
     val commands = service.playerCommandsFor(
       SkipCapability(canSkipPrevious = true, canSkipNext = false),
-      hasMediaItems = true,
     )
     assertFalse(commands.contains(Player.COMMAND_SEEK_TO_NEXT))
     assertFalse(commands.contains(Player.COMMAND_SEEK_TO_NEXT_MEDIA_ITEM))
@@ -91,7 +89,6 @@ class PlayerCommandsForTest {
   fun `commands omit only the previous pair when capability disallows skip-previous`() {
     val commands = service.playerCommandsFor(
       SkipCapability(canSkipPrevious = false, canSkipNext = true),
-      hasMediaItems = true,
     )
     assertTrue(commands.contains(Player.COMMAND_SEEK_TO_NEXT))
     assertTrue(commands.contains(Player.COMMAND_SEEK_TO_NEXT_MEDIA_ITEM))
@@ -104,7 +101,6 @@ class PlayerCommandsForTest {
   fun `commands omit both skip pairs when capability disallows both`() {
     val commands = service.playerCommandsFor(
       SkipCapability(canSkipPrevious = false, canSkipNext = false),
-      hasMediaItems = true,
     )
     assertFalse(commands.contains(Player.COMMAND_SEEK_TO_NEXT))
     assertFalse(commands.contains(Player.COMMAND_SEEK_TO_NEXT_MEDIA_ITEM))
@@ -119,7 +115,6 @@ class PlayerCommandsForTest {
   fun `repeat OFF at index 0 of a two-track queue exposes only skip-next`() {
     val commands = service.playerCommandsFor(
       capabilityFor(repeat = QueueSkipRepeatMode.OFF, count = 2, current = 0),
-      hasMediaItems = true,
     )
     assertTrue(commands.contains(Player.COMMAND_SEEK_TO_NEXT_MEDIA_ITEM))
     assertFalse(commands.contains(Player.COMMAND_SEEK_TO_PREVIOUS_MEDIA_ITEM))
@@ -129,7 +124,6 @@ class PlayerCommandsForTest {
   fun `repeat OFF at the last index of a two-track queue exposes only skip-previous`() {
     val commands = service.playerCommandsFor(
       capabilityFor(repeat = QueueSkipRepeatMode.OFF, count = 2, current = 1),
-      hasMediaItems = true,
     )
     assertFalse(commands.contains(Player.COMMAND_SEEK_TO_NEXT_MEDIA_ITEM))
     assertTrue(commands.contains(Player.COMMAND_SEEK_TO_PREVIOUS_MEDIA_ITEM))
@@ -139,7 +133,6 @@ class PlayerCommandsForTest {
   fun `repeat OFF on a single-track queue exposes neither skip command`() {
     val commands = service.playerCommandsFor(
       capabilityFor(repeat = QueueSkipRepeatMode.OFF, count = 1, current = 0),
-      hasMediaItems = true,
     )
     assertFalse(commands.contains(Player.COMMAND_SEEK_TO_NEXT_MEDIA_ITEM))
     assertFalse(commands.contains(Player.COMMAND_SEEK_TO_PREVIOUS_MEDIA_ITEM))
@@ -149,15 +142,12 @@ class PlayerCommandsForTest {
   fun `repeat QUEUE wraps so both skip commands stay enabled at every queue position`() {
     val first = service.playerCommandsFor(
       capabilityFor(repeat = QueueSkipRepeatMode.QUEUE, count = 3, current = 0),
-      hasMediaItems = true,
     )
     val mid = service.playerCommandsFor(
       capabilityFor(repeat = QueueSkipRepeatMode.QUEUE, count = 3, current = 1),
-      hasMediaItems = true,
     )
     val last = service.playerCommandsFor(
       capabilityFor(repeat = QueueSkipRepeatMode.QUEUE, count = 3, current = 2),
-      hasMediaItems = true,
     )
     for (commands in listOf(first, mid, last)) {
       assertTrue(commands.contains(Player.COMMAND_SEEK_TO_NEXT_MEDIA_ITEM))
@@ -170,7 +160,6 @@ class PlayerCommandsForTest {
     // First track of 2: next available, no previous (no wrap).
     val atFirst = service.playerCommandsFor(
       capabilityFor(repeat = QueueSkipRepeatMode.TRACK, count = 2, current = 0),
-      hasMediaItems = true,
     )
     assertTrue(atFirst.contains(Player.COMMAND_SEEK_TO_NEXT_MEDIA_ITEM))
     assertFalse(atFirst.contains(Player.COMMAND_SEEK_TO_PREVIOUS_MEDIA_ITEM))
@@ -178,31 +167,33 @@ class PlayerCommandsForTest {
     // Last track of 2: previous available, no next (no wrap).
     val atLast = service.playerCommandsFor(
       capabilityFor(repeat = QueueSkipRepeatMode.TRACK, count = 2, current = 1),
-      hasMediaItems = true,
     )
     assertFalse(atLast.contains(Player.COMMAND_SEEK_TO_NEXT_MEDIA_ITEM))
     assertTrue(atLast.contains(Player.COMMAND_SEEK_TO_PREVIOUS_MEDIA_ITEM))
   }
 
   @Test
-  fun `empty queue exposes neither skip command regardless of repeat mode`() {
+  fun `empty queue disables skip but keeps transport commands for the System UI`() {
     for (mode in QueueSkipRepeatMode.entries) {
       val commands = service.playerCommandsFor(
         capabilityFor(repeat = mode, count = 0, current = -1),
-        hasMediaItems = false,
       )
       assertFalse(
-        "skip-next is always disabled with no tracks (repeat=$mode)",
+        "skip-next is disabled with no tracks (repeat=$mode)",
         commands.contains(Player.COMMAND_SEEK_TO_NEXT_MEDIA_ITEM),
       )
       assertFalse(
-        "skip-previous is always disabled with no tracks (repeat=$mode)",
+        "skip-previous is disabled with no tracks (repeat=$mode)",
         commands.contains(Player.COMMAND_SEEK_TO_PREVIOUS_MEDIA_ITEM),
       )
-      assertFalse(
-        "PLAY_PAUSE is stripped on empty queue so AA lands on Library (repeat=$mode)",
+      assertTrue(
+        "play/pause is retained so the API 33+ System UI keeps the button (repeat=$mode)",
         commands.contains(Player.COMMAND_PLAY_PAUSE),
       )
+      assertTrue(
+        "in-item seek is retained so the seek scrubber stays draggable (repeat=$mode)",
+        commands.contains(Player.COMMAND_SEEK_IN_CURRENT_MEDIA_ITEM),
+      )
     }
   }
 

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/android/src/test/java/com/margelo/nitro/queueplayer/VisualizerKtTest.kt

@@ -187,6 +187,7 @@ private class FakePlaybackEngineWithSinks : PlaybackEngine {
   override val bufferedPositionMs: Long get() = error("not used in test")
   override val isPlaying: Boolean get() = error("not used in test")
   override val currentMediaItem: androidx.media3.common.MediaItem? get() = error("not used in test")
+  override val isCrossfadeActive: Boolean get() = false
   override val allMediaItems: List<androidx.media3.common.MediaItem> get() = error("not used in test")
   override fun currentAudioSessionIds(): IntArray = IntArray(0)
   override fun addAudioSessionIdListener(listener: (IntArray) -> Unit): () -> Unit = { /* noop */ }

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