react-native-queue-player 1.2.0 → 2.0.0

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

@@ -0,0 +1,85 @@
+package com.margelo.nitro.queueplayer
+
+import androidx.media3.common.util.UnstableApi
+import androidx.test.core.app.ApplicationProvider
+import org.junit.Assert.assertTrue
+import org.junit.Test
+import org.junit.runner.RunWith
+import org.robolectric.RobolectricTestRunner
+import org.robolectric.annotation.Config
+import java.util.concurrent.CountDownLatch
+import java.util.concurrent.TimeUnit
+
+/**
+ * Cancelling a prefetch stops the write that is running, not only the
+ * coroutine around it.
+ */
+@RunWith(RobolectricTestRunner::class)
+@Config(sdk = [34])
+@UnstableApi
+class LookaheadCacheWriterCancelTest {
+
+  private fun httpTrack(id: String) = TrackItem(
+    id = id, url = "https://example.com/$id.m4a", title = null, artist = null, album = null,
+    duration = null, artworkUrl = null, extras = null,
+    replayGainTrackGain = null, replayGainTrackPeak = null,
+    replayGainAlbumGain = null, replayGainAlbumPeak = null)
+
+  /**
+   * `CacheWriter.cache()` blocks and polls only its own cancelled flag, so a
+   * cancelled coroutine alone would leave it writing. The download body
+   * relays the cancellation onto the writer; `CacheWriter` then closes its
+   * source, which is what this observes.
+   */
+  @Test
+  fun `cancel stops the running download, not just its coroutine`() {
+    val cache = LookaheadCache(
+      context = ApplicationProvider.getApplicationContext(),
+      maxSizeBytes = 4L * 1024L * 1024L,
+      cacheDirName = "writer-cancel-${System.nanoTime()}"
+    )
+    val source = TricklingDataSource()
+    val writer = LookaheadCacheWriter.create(
+      cache = cache,
+      httpFactory = androidx.media3.datasource.DataSource.Factory { source },
+      isOnCellular = { false }
+    )
+    try {
+      // The window is the tracks ahead of the current one.
+      writer.reschedule(listOf(httpTrack("current"), httpTrack("slow")), currentIndex = 0, lookaheadCount = 1)
+      assertTrue("the download must have opened its source", source.opened.await(5, TimeUnit.SECONDS))
+
+      writer.cancel()
+
+      assertTrue("a cancelled write closes its source", source.closed.await(5, TimeUnit.SECONDS))
+    } finally {
+      writer.release()
+      cache.release()
+    }
+  }
+
+  /** A source that hands out one byte at a time, forever, until closed. */
+  private class TricklingDataSource : androidx.media3.datasource.DataSource {
+    val opened = CountDownLatch(1)
+    val closed = CountDownLatch(1)
+    private var uri: android.net.Uri? = null
+
+    override fun addTransferListener(transferListener: androidx.media3.datasource.TransferListener) {}
+    override fun open(dataSpec: androidx.media3.datasource.DataSpec): Long {
+      uri = dataSpec.uri
+      opened.countDown()
+      return androidx.media3.common.C.LENGTH_UNSET.toLong()
+    }
+    override fun read(buffer: ByteArray, offset: Int, length: Int): Int {
+      if (length == 0) return 0
+      Thread.sleep(2)
+      buffer[offset] = 0
+      return 1
+    }
+    override fun getUri(): android.net.Uri? = uri
+    override fun close() {
+      closed.countDown()
+    }
+  }
+
+}

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

@@ -57,6 +57,18 @@ class LookaheadCacheWriterTest {
     assertTrue(w.computeTargets(emptyList(), currentIndex = 0, lookaheadCount = 3).isEmpty())
   }
 
+  @Test
+  fun `computeTargets clamps a lookaheadCount that would overflow the range`() {
+    // The count arrives as a JS Double, so Infinity reaches Int.MAX_VALUE here
+    // and `start + count` wraps negative — a range subList rejects outright.
+    val w = newWriter()
+    val tracks = (1..3).map { httpTrack("t$it") }
+    assertEquals(
+      2,
+      w.computeTargets(tracks, currentIndex = 0, lookaheadCount = Int.MAX_VALUE).size
+    )
+  }
+
   @Test
   fun `computeTargets returns empty for non-positive lookaheadCount`() {
     val w = newWriter()
@@ -632,6 +644,103 @@ class LookaheadCacheWriterTest {
 
   // --- Helpers
 
+  // --- allowsCellularAccess
+
+  @Test
+  fun `prefetch is skipped while cellular is not permitted and the network is cellular`() = runTest {
+    val downloads = mutableListOf<String>()
+    val writer = LookaheadCacheWriter(
+      downloader = { track -> downloads.add(track.id ?: "") },
+      scope = CoroutineScope(StandardTestDispatcher(testScheduler) + SupervisorJob()),
+      isOnCellular = { true }
+    )
+    writer.allowsCellularAccess = false
+
+    writer.reschedule((0..4).map { httpTrack("t$it") }, currentIndex = 0, lookaheadCount = 3)
+    advanceUntilIdle()
+
+    assertTrue(downloads.isEmpty())
+    assertNull(writer.orchestratorJob)
+  }
+
+  @Test
+  fun `prefetch runs on a non-cellular network even when cellular is not permitted`() = runTest {
+    val downloads = mutableListOf<String>()
+    val writer = LookaheadCacheWriter(
+      downloader = { track -> downloads.add(track.id ?: "") },
+      scope = CoroutineScope(StandardTestDispatcher(testScheduler) + SupervisorJob()),
+      isOnCellular = { false }
+    )
+    writer.allowsCellularAccess = false
+
+    writer.reschedule((0..4).map { httpTrack("t$it") }, currentIndex = 0, lookaheadCount = 3)
+    advanceUntilIdle()
+
+    assertEquals(listOf("t1", "t2", "t3"), downloads)
+  }
+
+  @Test
+  fun `prefetch runs on cellular while it is permitted`() = runTest {
+    val downloads = mutableListOf<String>()
+    val writer = LookaheadCacheWriter(
+      downloader = { track -> downloads.add(track.id ?: "") },
+      scope = CoroutineScope(StandardTestDispatcher(testScheduler) + SupervisorJob()),
+      isOnCellular = { true }
+    )
+
+    writer.reschedule((0..4).map { httpTrack("t$it") }, currentIndex = 0, lookaheadCount = 3)
+    advanceUntilIdle()
+
+    assertEquals(listOf("t1", "t2", "t3"), downloads)
+  }
+
+  @Test
+  fun `handing off to cellular cancels the download in flight`() = runBlocking<Unit> {
+    val started = CompletableDeferred<Unit>()
+    val release = CompletableDeferred<Unit>()
+    var onCellular = false
+    val writer = LookaheadCacheWriter(
+      downloader = { started.complete(Unit); release.await() },
+      scope = CoroutineScope(SupervisorJob()),
+      isOnCellular = { onCellular }
+    )
+    writer.allowsCellularAccess = false
+    val queue = (0..4).map { httpTrack("t$it") }
+    writer.reschedule(queue, currentIndex = 0, lookaheadCount = 3)
+    started.await()
+    // Captured before the handoff: the orchestrator clears `inFlightJob` on its
+    // own thread once the cancelled download resumes it, so reading the slot
+    // afterwards races that clear.
+    val inFlightBefore = writer.inFlightJob
+
+    onCellular = true
+    writer.reschedule(queue, currentIndex = 0, lookaheadCount = 3)
+
+    assertTrue("the download in flight must be cancelled", inFlightBefore?.isCancelled == true)
+    release.complete(Unit)
+  }
+
+  @Test
+  fun `turning cellular back on refills the window on the next reschedule`() = runTest {
+    val downloads = mutableListOf<String>()
+    val writer = LookaheadCacheWriter(
+      downloader = { track -> downloads.add(track.id ?: "") },
+      scope = CoroutineScope(StandardTestDispatcher(testScheduler) + SupervisorJob()),
+      isOnCellular = { true }
+    )
+    val queue = (0..4).map { httpTrack("t$it") }
+    writer.allowsCellularAccess = false
+    writer.reschedule(queue, currentIndex = 0, lookaheadCount = 3)
+    advanceUntilIdle()
+    assertTrue(downloads.isEmpty())
+
+    writer.allowsCellularAccess = true
+    writer.reschedule(queue, currentIndex = 0, lookaheadCount = 3)
+    advanceUntilIdle()
+
+    assertEquals(listOf("t1", "t2", "t3"), downloads)
+  }
+
   private fun httpTrack(id: String): TrackItem =
     makeTrack(id, "https://example.com/$id.m4a")
 
@@ -644,6 +753,8 @@ class LookaheadCacheWriterTest {
       album = null,
       duration = null,
       artworkUrl = null,
-      extras = null
+      extras = null,
+      replayGainTrackGain = null, replayGainTrackPeak = null,
+      replayGainAlbumGain = null, replayGainAlbumPeak = null
     )
 }

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

@@ -171,7 +171,7 @@ class MediaItemBuilderTest {
     // Parity with iOS `AVQueueBuilderTests.testMakeItemForFileURL
     // SkipsHeaderDictionary`: the test asserts the URI scheme is
     // preserved, but does NOT assert the file/remote routing
-    // downstream. The factory plumbing is opaque post-build on
+    // downstream. What the factory built is unreadable post-build on
     // both platforms (AVURLAsset options can't be read back on
     // iOS; DefaultDataSource.Factory wiring is internal on
     // Android), so the documented contract is the test.
@@ -184,7 +184,7 @@ class MediaItemBuilderTest {
     assertEquals("file", uri?.scheme)
   }
 
-  // --- buildMediaItems MIME plumbing
+  // --- buildMediaItems MIME handling
 
   @Test
   fun `buildMediaItems sets MIME from URL extension for http urls`() {
@@ -474,6 +474,8 @@ class MediaItemBuilderTest {
       album = album,
       duration = duration,
       artworkUrl = artworkUrl,
-      extras = null
+      extras = null,
+      replayGainTrackGain = null, replayGainTrackPeak = null,
+      replayGainAlbumGain = null, replayGainAlbumPeak = null
     )
 }

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

@@ -4,7 +4,10 @@ import androidx.media3.common.Format
 import androidx.media3.common.MimeTypes
 import androidx.media3.common.util.UnstableApi
 import org.junit.Assert.assertEquals
+import org.junit.Assert.assertNull
+import org.junit.Rule
 import org.junit.Test
+import org.junit.rules.TemporaryFolder
 
 /**
  * Pure-mapping coverage for [NowPlayingFormatExtractor]. These
@@ -14,6 +17,48 @@ import org.junit.Test
 @UnstableApi
 class NowPlayingFormatExtractorTest {
 
+  @get:Rule
+  val tempFolder = TemporaryFolder()
+
+  /**
+   * FLAC declares no bitrate, so Media3 reports NO_VALUE for it on local files
+   * as well as remote. For a file on disk the average is arithmetic — encoded
+   * bytes over playing time — which is the same derivation iOS uses.
+   */
+  @Test
+  fun averageBitrateIsBytesOverPlayingTime() {
+    val file = tempFolder.newFile("track.flac")
+    file.writeBytes(ByteArray(1_000_000))
+
+    // 1,000,000 bytes over 40 s = 8,000,000 bits / 40 = 200 kbps.
+    assertEquals(
+      200_000.0,
+      NowPlayingFormatExtractor.averageBitrateOf(file.absolutePath, 40.0)!!,
+      0.001
+    )
+  }
+
+  /**
+   * Every input that would make the answer invented rather than measured
+   * yields null: the player has not resolved a duration yet, the duration is
+   * nonsense, the path is absent, or the file has no bytes.
+   */
+  @Test
+  fun averageBitrateIsNullWhenItCannotBeMeasured() {
+    val file = tempFolder.newFile("track.flac")
+    file.writeBytes(ByteArray(1_000))
+
+    assertNull(NowPlayingFormatExtractor.averageBitrateOf(file.absolutePath, null))
+    assertNull(NowPlayingFormatExtractor.averageBitrateOf(file.absolutePath, 0.0))
+    assertNull(NowPlayingFormatExtractor.averageBitrateOf(file.absolutePath, -5.0))
+    assertNull(NowPlayingFormatExtractor.averageBitrateOf(null, 40.0))
+    assertNull(
+      NowPlayingFormatExtractor.averageBitrateOf(
+        tempFolder.newFile("empty.flac").absolutePath, 40.0))
+    assertNull(
+      NowPlayingFormatExtractor.averageBitrateOf("/nonexistent/nope.flac", 40.0))
+  }
+
   @Test
   fun mapCodecCoversAACAliases() {
     assertEquals(AudioCodec.AAC, NowPlayingFormatExtractor.mapCodec(MimeTypes.AUDIO_AAC))

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

@@ -60,7 +60,7 @@ class PitchAwareAudioProcessorChainTest {
 
   @Test
   fun `signalsmith stays active on the float path even when not stretching`() {
-    // The fix for Media3's static pipeline: Signalsmith must remain in the
+    // Media3's pipeline is static: Signalsmith must remain in the
     // active set regardless of mode/speed so it can stretch when music kicks in.
     val chain = newConfiguredChain()
     chain.setMode(PitchCorrectionMode.VOICE)

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

@@ -7,8 +7,16 @@ import androidx.media3.session.LibraryResult
 import androidx.media3.session.MediaLibraryService
 import androidx.media3.session.MediaSession
 import androidx.test.core.app.ApplicationProvider
+import java.util.concurrent.CountDownLatch
+import java.util.concurrent.TimeUnit
+import java.util.concurrent.atomic.AtomicInteger
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.ExperimentalCoroutinesApi
+import kotlinx.coroutines.test.resetMain
+import kotlinx.coroutines.test.setMain
 import org.junit.After
 import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
 import org.junit.Assert.assertNull
 import org.junit.Assert.assertTrue
 import org.junit.Before
@@ -167,4 +175,43 @@ class PlaybackServiceCallbackSearchTest {
       result.params
     )
   }
+
+  // --- dispatchSearchToJs
+
+  // `Dispatchers.setMain` is the only way to see which dispatcher the notify
+  // lands on; `notifySearchResultChanged` has no other observable effect with
+  // no controller connected.
+  @OptIn(ExperimentalCoroutinesApi::class)
+  @Test
+  fun `dispatchSearchToJs caches the answer then notifies on main`() {
+    // A Nitro Promise is JNI-constructed and cannot exist on the JVM, so
+    // the only JS answer reachable here is a throwing handler; that path
+    // still writes the cache and still notifies, which is the contract a
+    // connected controller depends on to stop waiting.
+    val mainDispatches = AtomicInteger(0)
+    val dispatched = CountDownLatch(1)
+    val recording = object : kotlinx.coroutines.CoroutineDispatcher() {
+      override fun dispatch(context: kotlin.coroutines.CoroutineContext, block: Runnable) {
+        mainDispatches.incrementAndGet()
+        dispatched.countDown()
+        android.os.Handler(android.os.Looper.getMainLooper()).post(block)
+      }
+    }
+    Dispatchers.setMain(recording)
+    try {
+      service.browseCallbacks.registerOnSearchRequest { _ ->
+        throw IllegalStateException("no Nitro runtime under Robolectric")
+      }
+      assertFalse(service.searchResultCache.hasResults("rock"))
+
+      service.dispatchSearchToJs("rock")
+
+      assertTrue("the notify reached a dispatcher", dispatched.await(2, TimeUnit.SECONDS))
+      org.robolectric.Shadows.shadowOf(android.os.Looper.getMainLooper()).idle()
+      assertEquals("notify is dispatched to main", 1, mainDispatches.get())
+      assertEquals(emptyList<BrowseItem>(), service.searchResultCache.getResults("rock"))
+    } finally {
+      Dispatchers.resetMain()
+    }
+  }
 }

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

@@ -259,19 +259,6 @@ class PlaybackServiceCallbackTest {
     assertTrue(commands.contains(Player.COMMAND_SET_SPEED_AND_PITCH))
   }
 
-  @Test
-  fun `refreshAvailableCommands is a no-op when no handler is registered`() {
-    // No handler, no controllers — exercising the early return.
-    binder.refreshAvailableCommands()
-    // Re-issue with a handler but no connected controllers — also a no-op.
-    binder.setCommandHandler(RecordingHandler())
-    binder.refreshAvailableCommands()
-    // 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.
-  }
-
   // --- TrackPlayer-side handler implementation
 
   @Test
@@ -291,8 +278,8 @@ class PlaybackServiceCallbackTest {
     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("a", "https://example.com/a.m4a", null, null, null, null, null, null, null, null, null, null),
+        TrackItem("b", "https://example.com/b.m4a", null, null, null, null, null, null, null, null, null, null),
       )
       player.currentTrackIndex = 0
 
@@ -326,8 +313,8 @@ class PlaybackServiceCallbackTest {
 
       // Two-track queue at index 0 — skip-next now allowed.
       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("a", "https://example.com/a.m4a", null, null, null, null, null, null, null, null, null, null),
+        TrackItem("b", "https://example.com/b.m4a", null, null, null, null, null, null, null, null, null, null),
       )
       player.currentTrackIndex = 0
       player.recomputeCapabilities()
@@ -352,8 +339,8 @@ class PlaybackServiceCallbackTest {
     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("a", "https://example.com/a.m4a", null, null, null, null, null, null, null, null, null, null),
+        TrackItem("b", "https://example.com/b.m4a", null, null, null, null, null, null, null, null, null, null),
       )
       player.currentTrackIndex = 1
 
@@ -377,9 +364,9 @@ class PlaybackServiceCallbackTest {
     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),
+        TrackItem("a", "https://example.com/a.m4a", null, null, null, null, null, null, null, null, null, null),
+        TrackItem("b", "https://example.com/b.m4a", null, null, null, null, null, null, null, null, null, null),
+        TrackItem("c", "https://example.com/c.m4a", null, null, null, null, null, null, null, null, null, null),
       )
       player.currentTrackIndex = 0
 
@@ -404,8 +391,8 @@ class PlaybackServiceCallbackTest {
     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("a", "https://example.com/a.m4a", null, null, null, null, null, null, null, null, null, null),
+        TrackItem("b", "https://example.com/b.m4a", null, null, null, null, null, null, null, null, null, null),
       )
       player.currentTrackIndex = 1
 
@@ -426,8 +413,8 @@ class PlaybackServiceCallbackTest {
     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("a", "https://example.com/a.m4a", null, null, null, null, null, null, null, null, null, null),
+        TrackItem("b", "https://example.com/b.m4a", null, null, null, null, null, null, null, null, null, null),
       )
       player.currentTrackIndex = 1
 
@@ -444,6 +431,35 @@ class PlaybackServiceCallbackTest {
 
   // --- Voice / browse-leaf routing through onAddMediaItems / onSetMediaItems
 
+  @Test
+  fun `onAddMediaItems asks for append and onSetMediaItems does not`() {
+    val fakeEnv = RecordingEnvironment(service)
+    val routingCallback = PlaybackServiceCallback(fakeEnv)
+    fakeEnv.idResolution = listOf(
+      MediaItem.Builder().setMediaId("resolved")
+        .setUri("https://example.com/resolved.m4a".toUri()).build()
+    )
+    fun idOnlyItem() = MediaItem.Builder().setMediaId("album:1").build()
+
+    routingCallback.onAddMediaItems(
+      session, controllerInfo, mutableListOf(idOnlyItem())
+    ).get()
+    // "Queue up X" grows the queue; Media3 appends what the resolution
+    // returns, so the lib's own queue has to grow by the same amount rather
+    // than being replaced by the new tracks alone.
+    assertEquals(listOf(true), fakeEnv.idAppendFlags)
+
+    fakeEnv.idAppendFlags.clear()
+    routingCallback.onSetMediaItems(
+      session, controllerInfo, mutableListOf(idOnlyItem()), 0, 0L
+    ).get()
+    // A browse-leaf tap is a genuine replace: it takes the no-sync route,
+    // where the JS handler's own `setQueue` is the only writer, so no
+    // append-flagged request reaches the environment at all.
+    assertEquals(listOf("album:1"), fakeEnv.idRequestsNoSync)
+    assertEquals(emptyList<Boolean>(), fakeEnv.idAppendFlags)
+  }
+
   @Test
   fun `onAddMediaItems with searchQuery dispatches to onPlayFromSearchRequest`() {
     val fakeEnv = RecordingEnvironment(service)
@@ -783,7 +799,8 @@ class PlaybackServiceCallbackTest {
         networkTimeoutMs = null,
         audioContentType = null,
         audioCategoryOptions = null,
-        visualizationEnabled = null,
+        voiceVocabularyDonationEnabled = null,
+      visualizationEnabled = null,
         clampSeekToBuffered = null,
       lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null, progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null, skipToPreviousBehavior = null,
       ),
@@ -878,19 +895,26 @@ class PlaybackServiceCallbackTest {
       service.playerCommandsFor(capability)
 
     override fun onPlayFromSearchRequest(
-      request: MediaSearchRequest
+      request: MediaSearchRequest,
+      append: Boolean
     ): ListenableFuture<List<MediaItem>> {
       searchRequests += request
+      searchAppendFlags += append
       return Futures.immediateFuture(searchResolution)
     }
 
     override fun onPlayFromIdRequest(
-      mediaId: String
+      mediaId: String,
+      append: Boolean
     ): ListenableFuture<List<MediaItem>> {
       idRequests += mediaId
+      idAppendFlags += append
       return Futures.immediateFuture(idResolution)
     }
 
+    val searchAppendFlags = mutableListOf<Boolean>()
+    val idAppendFlags = mutableListOf<Boolean>()
+
     override fun onPlayFromIdRequestNoSync(mediaId: String) {
       idRequestsNoSync += mediaId
     }

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

@@ -49,19 +49,19 @@ class PlaybackServiceLifecycleTest {
     val controller = Robolectric.buildService(PlaybackService::class.java).create()
     try {
       val binder = bindLocal(controller.get())
-      assertNotNull("binder.player is initialised in onCreate", binder.player)
+      assertNotNull("the engine's player is initialised in onCreate", binder.engine.mediaSessionPlayer)
       assertNotNull("binder.session is initialised in onCreate", binder.session)
       // The session binds to the stable SessionCommandForwardingPlayer
       // wrapper for its lifetime; the wrapper forwards to the engine's
-      // ExoPlayer the binder exposes.
+      // own ExoPlayer.
       val sessionPlayer = binder.session.player
       assertTrue(
         "binder.session.player is the stable forwarding wrapper",
         sessionPlayer is SessionCommandForwardingPlayer,
       )
       assertSame(
-        "the wrapper forwards to the ExoPlayer instance the binder exposes",
-        binder.player,
+        "the wrapper forwards to the engine's ExoPlayer instance",
+        binder.engine.mediaSessionPlayer,
         (sessionPlayer as SessionCommandForwardingPlayer).wrappedPlayer,
       )
       assertEquals(
@@ -173,8 +173,8 @@ class PlaybackServiceLifecycleTest {
       val binder = bindLocal(service)
       // A loaded + play-ready session: the previous behaviour kept the service
       // alive here. Swipe-away is now an unconditional kill.
-      binder.player.addMediaItem(MediaItem.fromUri("http://example.com/a.mp3"))
-      binder.player.playWhenReady = true
+      binder.engine.mediaSessionPlayer.addMediaItem(MediaItem.fromUri("http://example.com/a.mp3"))
+      binder.engine.mediaSessionPlayer.playWhenReady = true
       shadowOf(Looper.getMainLooper()).idle()
 
       service.onTaskRemoved(null)
@@ -183,7 +183,7 @@ class PlaybackServiceLifecycleTest {
       assertEquals(
         "the player is stopped (idle) on swipe-away",
         Player.STATE_IDLE,
-        binder.player.playbackState,
+        binder.engine.mediaSessionPlayer.playbackState,
       )
       assertTrue(
         "the service stops even with a queued, play-ready session",
@@ -198,7 +198,7 @@ class PlaybackServiceLifecycleTest {
   fun `onDestroy releases the player and clears the session`() {
     val controller = Robolectric.buildService(PlaybackService::class.java).create()
     val binder = bindLocal(controller.get())
-    val player = binder.player
+    val player = binder.engine.mediaSessionPlayer
     val session: MediaSession = binder.session
     assertFalse("player is live before destroy", player.isReleased)
 

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

@@ -134,7 +134,7 @@ class QueueSkipArithmeticTest {
   @Test
   fun `computePrevious OFF — at index 0 returns null (no wrap)`() {
     // The "tap Previous at track 0 restarts current" UX behaviour
-    // is applied by the skipToPrevious glue, not here.
+    // is applied by `skipToPrevious`, not here.
     assertNull(
       QueueSkipArithmetic.computePrevious(5, 0, QueueSkipRepeatMode.OFF)
     )
@@ -443,4 +443,36 @@ class QueueSkipArithmeticTest {
     assertFalse(QueueSkipArithmetic.canSkipPrevious(3, 0, QueueSkipRepeatMode.OFF, restartEnabled = false))
     assertTrue(QueueSkipArithmetic.canSkipPrevious(3, 1, QueueSkipRepeatMode.OFF, restartEnabled = false))
   }
+
+  @Test
+  fun `canSkipPrevious restartEnabled — nothing playing is false in any mode`() {
+    // Nothing is loaded, so there is no track to restart and no previous
+    // track to reach: resolveSkipToPrevious returns NoOp for this state.
+    for (mode in QueueSkipRepeatMode.entries) {
+      assertFalse(QueueSkipArithmetic.canSkipPrevious(5, -1, mode, restartEnabled = true))
+    }
+  }
+
+  @Test
+  fun `canSkipPrevious agrees with resolveSkipToPrevious`() {
+    // canSkipPrevious is the enabled-state of the same decision
+    // resolveSkipToPrevious makes; the two must never disagree.
+    for (count in listOf(0, 1, 3)) {
+      for (index in listOf(-1, 0, 1, 2)) {
+        for (mode in QueueSkipRepeatMode.entries) {
+          for (restart in listOf(false, true)) {
+            val can = QueueSkipArithmetic.canSkipPrevious(count, index, mode, restart)
+            val resolved = QueueSkipArithmetic.resolveSkipToPrevious(
+              count, index, mode, restart, positionMs = 0
+            )
+            assertEquals(
+              "count=$count index=$index mode=$mode restart=$restart",
+              can,
+              resolved != QueueSkipArithmetic.SkipToPreviousAction.NoOp
+            )
+          }
+        }
+      }
+    }
+  }
 }