react-native-queue-player 1.0.3 → 1.0.6

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

@@ -16,9 +16,7 @@ import org.robolectric.annotation.Config
 /**
  * Wiring coverage for the `Equalizer` HybridObject — engine
  * selection, JS-facing surface routing through the synchronous
- * `*Internal` core, listener registry behaviour. The audible
- * effect is verified at the integration layer via demo Maestro
- * once the engine is hooked to ExoPlayer's audio session.
+ * `*Internal` core, listener registry behaviour.
  */
 @RunWith(RobolectricTestRunner::class)
 @Config(sdk = [34])

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

@@ -13,9 +13,8 @@ import org.robolectric.annotation.Config
  * State-mirror coverage for [EqualizerLegacyEngine] on the API <28 path.
  * Robolectric's audio-effect shadow doesn't model the hardware-side
  * band centre frequencies + gain range; the band-mapping + dB↔mB
- * conversion are the test-reachable invariants. Real audible effect
- * verified at user-led API 26 emulator playbook (legacy API
- * behaviour varies per OEM).
+ * conversion are the invariants this covers. Legacy AudioEffect
+ * behaviour varies per OEM.
  */
 @RunWith(RobolectricTestRunner::class)
 @Config(sdk = [27])

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

@@ -19,8 +19,7 @@ import kotlin.math.sin
  * Unit coverage for [FFTProcessorTee] — buffer ingestion across PCM
  * encodings, intervalMs throttling, includeSamples flag, and
  * multi-channel mixdown. The Tee callback contract is mocked
- * directly; integration with Media3's audio chain is verified at the
- * Maestro layer (no Robolectric harness for ExoPlayer audio output).
+ * directly.
  */
 @RunWith(RobolectricTestRunner::class)
 @Config(sdk = [34])

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

@@ -15,8 +15,6 @@ import org.robolectric.annotation.Config
 /**
  * Lifecycle smoke coverage for [GaplessEngine] — empty-state
  * sentinels and the idempotent / delegate-clearing release contract.
- * Behavioural coverage of transport / queue mutation runs through
- * the existing TrackPlayer integration suites + Maestro flows.
  */
 @RunWith(RobolectricTestRunner::class)
 @Config(sdk = [34])

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

@@ -19,10 +19,8 @@ import org.robolectric.annotation.Config
  * Real Media3 metadata dispatch is not emulated by Robolectric
  * without playback, so the listener body composes its work through
  * the engine-internal `handleReplayGainParse` helper which these
- * tests drive directly with synthetic [ReplayGainData]. The
- * pure-math piece of the pipeline is covered in [ReplayGainGainTest];
- * end-to-end propagation lands in the demo app's `replaygain`
- * Maestro suite. This file covers the no-data baseline,
+ * tests drive directly with synthetic [ReplayGainData].
+ * This file covers the no-data baseline,
  * mode-change-without-data behaviour, and the
  * `handleReplayGainParse` cache + recompute contract.
  */
@@ -147,8 +145,5 @@ class GaplessEngineReplayGainTest {
 
   // The cache-clear-on-transition path lives inline in the
   // `Player.Listener.onMediaItemTransition` body. Robolectric does not
-  // drive that callback without real playback, so the contract is
-  // covered at the integration layer by `RNQP-Demo/src/tests/suites/
-  // replaygain.ts` (steps `cross-track-active-updates` +
-  // `skip-next-mid-playback-resets-from-stale-cache`).
+  // drive that callback without real playback.
 }

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

@@ -21,11 +21,9 @@ import org.robolectric.annotation.Config
  * surface: the default no-task `getTaskConfig` contract and the
  * process-wide wake-lock helper.
  *
- * The full `onStartCommand` chain (which routes through Media3's
+ * The full `onStartCommand` chain routes through Media3's
  * `MediaLibraryService.onStartCommand` and into native code that
- * Robolectric can't satisfy) is exercised end-to-end by
- * [PlaybackServiceLifecycleTest] (which subclasses into the new
- * `HeadlessJsMediaService` base) plus the Maestro demo cycle.
+ * Robolectric can't satisfy, so it is out of scope here.
  */
 @RunWith(RobolectricTestRunner::class)
 @Config(sdk = [34])

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

@@ -26,11 +26,10 @@ import org.robolectric.annotation.Config
  *   both produce items — the file/remote routing difference is a
  *   DataSource.Factory concern, not a MediaItem concern).
  *
- * Factory-building is exercised by type only (the internal
+ * Factory-building is checked by type only (the internal
  * `DefaultHttpDataSource.Factory` is configured via a builder chain
  * whose effective state is hard to read back without reflection —
- * the factory is wired into ExoPlayer at construction time and
- * exercised implicitly through the TrackPlayer lifecycle tests).
+ * the factory is wired into ExoPlayer at construction time).
  *
  * @Config sdk=34 — Robolectric 4.11.1's max supported SDK.
  */

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

@@ -5,9 +5,7 @@ import org.junit.Test
 
 /**
  * Unit tests for [MilestoneTracker] — the pure 25/50/75/90% crossing
- * logic behind `onPlaybackMilestone`. Native wiring (progress tick,
- * seek, track-change reset) is covered by the `playback-milestones`
- * demo suite.
+ * logic behind `onPlaybackMilestone`.
  */
 class MilestoneTrackerTest {
 

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

@@ -7,8 +7,7 @@ import org.junit.Assert.assertEquals
 import org.junit.Test
 
 /**
- * Pure-mapping coverage for [NowPlayingFormatExtractor]. The full
- * `extract(player:)` path is exercised through demo suites; these
+ * Pure-mapping coverage for [NowPlayingFormatExtractor]. These
  * tests pin the codec / container tables so the JS-visible enum can't
  * drift without a test failure.
  */

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

@@ -17,7 +17,7 @@ import org.robolectric.annotation.Config
 /**
  * Routing coverage for [PitchAwareAudioProcessorChain]: which stretcher is
  * actually stretching for each [PitchCorrectionMode] and speed. The native
- * stretch itself is covered on-device; these assert only the mode gate, which
+ * stretch itself runs on-device; these assert only the mode gate, which
  * runs without the native library.
  *
  * Note Signalsmith is intentionally ALWAYS active on the float path (so Media3's

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

@@ -10,8 +10,8 @@ import org.robolectric.annotation.Config
  * Unit coverage for [PitchCorrection.playbackParameters], the pure mapping
  * from a [PitchCorrectionMode] + speed to Media3 [androidx.media3.common.PlaybackParameters].
  *
- * Engine wiring (which player the params land on) is covered by the
- * auto-suite `pitch-correction.ts` step.
+ * Engine wiring (which player the params land on) is out of scope for
+ * this pure test.
  */
 @RunWith(RobolectricTestRunner::class)
 @Config(sdk = [34])

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

@@ -70,6 +70,9 @@ class PlaybackServiceCallbackTest {
     controllerInfo = MediaSession.ControllerInfo.createTestOnlyControllerInfo(
       "test-controller", 0, 0, 0, 0, false, android.os.Bundle.EMPTY, false
     )
+    // Process-wide count; reset so headless connect/disconnect assertions
+    // start from a known-disconnected state regardless of test order.
+    CarConnectionState.reset()
   }
 
   @After
@@ -87,8 +90,7 @@ class PlaybackServiceCallbackTest {
 
   // Controller-driven `Player.Command` interception (skip-next /
   // skip-previous veto, transport `system`-reason stamping) now lives
-  // on [SessionCommandForwardingPlayer]; its routing is covered in
-  // SessionCommandForwardingPlayerTest. This suite keeps the
+  // on [SessionCommandForwardingPlayer]. This suite keeps the
   // callback's connect / resumption / available-commands surface.
 
   @Test
@@ -270,9 +272,7 @@ class PlaybackServiceCallbackTest {
     // The per-controller iteration body (session.setAvailableCommands)
     // requires a live MediaController that has completed handshake,
     // which is not reachable from Robolectric without standing up a
-    // full MediaController.Builder.buildAsync() flow. End-to-end
-    // coverage of the lock-screen-greying behaviour lives in the
-    // Maestro suites for repeat-mode + queue-boundary scenarios.
+    // full MediaController.Builder.buildAsync() flow.
   }
 
   // --- TrackPlayer-side handler implementation
@@ -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
@@ -615,6 +685,76 @@ class PlaybackServiceCallbackTest {
     assertEquals(0, fakeEnv.headlessConnectPackages.size)
   }
 
+  // --- isCarConnected: the process-wide flag TrackPlayer.isCarConnected() reads
+
+  @Test
+  fun `CarConnectionState is disconnected with no controller attached`() {
+    assertFalse(CarConnectionState.isConnected())
+  }
+
+  @Test
+  fun `headless connect marks connected, last disconnect marks disconnected`() {
+    val cb = PlaybackServiceCallback(RecordingEnvironment(service))
+    val gearhead = controllerFor("com.google.android.projection.gearhead")
+    cb.onConnect(session, gearhead)
+    assertTrue("connected after the first headless controller", CarConnectionState.isConnected())
+    cb.onDisconnected(session, gearhead)
+    assertFalse("disconnected after the last controller drops", CarConnectionState.isConnected())
+  }
+
+  @Test
+  fun `stays connected while any headless controller remains`() {
+    val cb = PlaybackServiceCallback(RecordingEnvironment(service))
+    val gearhead = controllerFor("com.google.android.projection.gearhead")
+    val wear = controllerFor("com.google.android.wearable.app")
+    cb.onConnect(session, gearhead)
+    cb.onConnect(session, wear)
+    cb.onDisconnected(session, gearhead)
+    assertTrue("still connected with one controller remaining", CarConnectionState.isConnected())
+    cb.onDisconnected(session, wear)
+    assertFalse("disconnected once the last controller drops", CarConnectionState.isConnected())
+  }
+
+  @Test
+  fun `non-headless controller leaves the flag disconnected`() {
+    val cb = PlaybackServiceCallback(RecordingEnvironment(service))
+    val phone = controllerFor("com.example.regular.app")
+    cb.onConnect(session, phone)
+    assertFalse(CarConnectionState.isConnected())
+    cb.onDisconnected(session, phone)
+    assertFalse(CarConnectionState.isConnected())
+  }
+
+  @Test
+  fun `untracked headless disconnect does not mark connected`() {
+    val cb = PlaybackServiceCallback(RecordingEnvironment(service))
+    val gearhead = controllerFor("com.google.android.projection.gearhead")
+    // A stray disconnect for a controller that never connected (service-
+    // restart edge) must not mark connected; the count floors at zero.
+    cb.onDisconnected(session, gearhead)
+    assertFalse(CarConnectionState.isConnected())
+  }
+
+  @Test
+  fun `a stray disconnect floors the count so a later connect still reads connected`() {
+    val cb = PlaybackServiceCallback(RecordingEnvironment(service))
+    val gearhead = controllerFor("com.google.android.projection.gearhead")
+    cb.onConnect(session, gearhead)
+    cb.onDisconnected(session, gearhead)
+    // Extra (stray) disconnect: the count must floor at zero, not go negative.
+    cb.onDisconnected(session, gearhead)
+    assertFalse("disconnected after the real drop", CarConnectionState.isConnected())
+    // If the stray disconnect had driven the count to -1, this connect would
+    // land it back at 0 and read disconnected.
+    cb.onConnect(session, gearhead)
+    assertTrue("connected again after a fresh attach", CarConnectionState.isConnected())
+  }
+
+  private fun controllerFor(packageName: String): MediaSession.ControllerInfo =
+    MediaSession.ControllerInfo.createTestOnlyControllerInfo(
+      packageName, 0, 0, 0, 0, false, android.os.Bundle.EMPTY, false
+    )
+
   @Test
   fun `becoming-noisy receiver unregisters in onDestroy`() {
     val handler = RecordingHandler()
@@ -689,10 +829,11 @@ class PlaybackServiceCallbackTest {
       return skipPreviousHandled
     }
 
+    override fun onSeekToMediaItemCommand(mediaItemIndex: Int): Boolean = false
+
     override fun getCachedSkipCapability(): SkipCapability = capability
 
-    // Raw-key paths are exercised in MediaButtonDispatchTest; this
-    // suite covers the controller-driven callback routing only.
+    // This suite covers the controller-driven callback routing only.
     override fun onMediaPlay() {}
     override fun onMediaPause() {}
     override fun onMediaTogglePlayPause() {}

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

@@ -6,9 +6,7 @@ import org.junit.Test
 
 /**
  * Unit tests for [ProgressEmissionGate] — the pure throttle behind the
- * configurable / background-reduced `onProgress` cadence. Native wiring (the
- * progress tick + the ProcessLifecycleOwner observer) is covered by
- * [TrackPlayerProgressThrottleTest] and the progress demo suites.
+ * configurable / background-reduced `onProgress` cadence.
  *
  * Most tests pass `samplerPeriodMs = 0.0` to exercise exact interval semantics;
  * the jitter + quantization tests pass the production `500` to verify the

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

@@ -348,8 +348,7 @@ class TrackPlayerEventsTest {
   //
   // The measured silence gap rides on onTrackChange's 4th arg only for a
   // natural gapless auto-advance. Every other transition carries `null`.
-  // The positive numeric value (a nanoTime delta) is a native measurement
-  // verified on-device by the `gapless-album` demo suite.
+  // The positive numeric value is a native nanoTime delta.
 
   @Test
   fun `handleMediaItemTransition PLAYLIST_CHANGED reports null transitionGapMs`() {

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

@@ -20,10 +20,8 @@ import org.robolectric.annotation.Config
  * ExoPlayer timeline synchronisation (`mediaItemCount`,
  * `currentMediaItemIndex` where applicable).
  *
- * Arithmetic edge cases are covered more exhaustively in
- * [QueueMutationArithmeticTest]; these tests focus on wiring
- * correctness — that the arithmetic result is actually applied
- * to both state structures in concert.
+ * These tests focus on wiring correctness — that the arithmetic
+ * result is actually applied to both state structures in concert.
  */
 @RunWith(RobolectricTestRunner::class)
 @Config(sdk = [34])

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

@@ -19,8 +19,7 @@ import org.robolectric.annotation.Config
  * `initHybrid()` → JNI which the Robolectric runtime doesn't load. This
  * file pins the default and the synchronous read path
  * ([TrackPlayer.getPitchCorrectionMode]) against the canonical state
- * field; end-to-end Promise dispatch + engine wiring is exercised through
- * the demo `pitch-correction` suite.
+ * field.
  */
 @RunWith(RobolectricTestRunner::class)
 @Config(sdk = [34])

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

@@ -9,9 +9,8 @@ import org.robolectric.annotation.Config
 
 /**
  * `setPlaybackMode` / `getPlaybackMode` imperative spec coverage —
- * the engine-swap path is exercised at the integration layer
- * (Maestro 1+1 cycle) since Robolectric can't fully bind the
- * service + ExoPlayer to verify a real swap.
+ * the engine-swap path can't be fully bound under Robolectric, which
+ * can't stand up the service + ExoPlayer to verify a real swap.
  */
 @RunWith(RobolectricTestRunner::class)
 @Config(sdk = [34])

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

@@ -20,9 +20,7 @@ import org.robolectric.annotation.Config
  * [ReplayGainConfig.setMode] then asks the active engine to
  * recompute; this file pins the synchronous read path
  * ([TrackPlayer.getReplayGainMode]) round-trips with
- * [ReplayGainConfig], and the mode write is itself covered by
- * [ReplayGainConfigTest]. End-to-end Promise dispatch is exercised
- * through the demo `replaygain` Maestro suite.
+ * [ReplayGainConfig].
  */
 @RunWith(RobolectricTestRunner::class)
 @Config(sdk = [34])