react-native-queue-player 1.2.0 → 2.0.1

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

@@ -45,7 +45,9 @@ class TrackPlayerQueueTest {
   private fun track(id: String) = TrackItem(
     id = id, url = "https://example.com/$id.m4a",
     title = null, artist = null, album = null,
-    duration = null, artworkUrl = null, extras = null
+    duration = null, artworkUrl = null, extras = null,
+    replayGainTrackGain = null, replayGainTrackPeak = null,
+    replayGainAlbumGain = null, replayGainAlbumPeak = null
   )
 
   private lateinit var serviceHandle: PlaybackServiceTestHandle
@@ -55,7 +57,7 @@ class TrackPlayerQueueTest {
     player = TrackPlayer()
     serviceHandle = bindPlaybackServiceForTest(player, context())
     player.configureInternal(
-      PlayerConfig(httpHeaders = null, userAgent = null, autoRetries = null, retryBackoffMs = null, networkTimeoutMs = null, audioContentType = null, audioCategoryOptions = null, visualizationEnabled = null, clampSeekToBuffered = null, lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null, progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null, skipToPreviousBehavior = null), context()
+      PlayerConfig(httpHeaders = null, userAgent = null, autoRetries = null, retryBackoffMs = null, networkTimeoutMs = null, audioContentType = null, audioCategoryOptions = null, voiceVocabularyDonationEnabled = null, visualizationEnabled = null, clampSeekToBuffered = null, lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null, progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null, skipToPreviousBehavior = null), context()
     )
   }
 
@@ -128,13 +130,15 @@ class TrackPlayerQueueTest {
   // --- getQueue / getCurrentTrackIndex
 
   @Test
-  fun `getQueue returns the track list as an array`() {
+  fun `setQueueInternal stores the tracks in order`() {
+    // `getQueue()` itself returns a Nitro Promise, which cannot be resolved
+    // from Robolectric; it reads this list on main, and the demo cycle covers
+    // the bridged call.
     val tracks = (1..3).map { track("t$it") }
     player.setQueueInternal(tracks)
 
-    val result = player.getQueue()
-    assertEquals(3, result.size)
-    assertEquals("t1", result[0].id)
+    assertEquals(3, player.tracks.size)
+    assertEquals("t1", player.tracks[0].id)
   }
 
   @Test
@@ -275,7 +279,7 @@ class TrackPlayerQueueTest {
   fun `skipToIndex after setQueue issues the ExoPlayer seek`() {
     // After setQueue the MediaItem timeline has 3 entries, so the
     // `target < mediaItemCount` guard in skipToIndexInternal no
-    // longer short-circuits — confirms the skip → seek plumbing
+    // longer short-circuits — confirms the skip → seek path
     // survives once the timeline is populated.
     player.setQueueInternal((1..3).map { track("t$it") })
 

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

@@ -41,7 +41,8 @@ class TrackPlayerReadersTest {
       PlayerConfig(
         httpHeaders = null, userAgent = null, autoRetries = null, retryBackoffMs = null,
         networkTimeoutMs = null, audioContentType = null, audioCategoryOptions = null,
-        visualizationEnabled = null, clampSeekToBuffered = null,
+        voiceVocabularyDonationEnabled = null,
+      visualizationEnabled = null, clampSeekToBuffered = null,
         lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null, progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null, skipToPreviousBehavior = null
       ),
       context()

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

@@ -40,7 +40,9 @@ class TrackPlayerSkipCapabilityTest {
   private fun track(id: String) = TrackItem(
     id = id, url = "https://example.com/$id.m4a",
     title = null, artist = null, album = null,
-    duration = null, artworkUrl = null, extras = null
+    duration = null, artworkUrl = null, extras = null,
+    replayGainTrackGain = null, replayGainTrackPeak = null,
+    replayGainAlbumGain = null, replayGainAlbumPeak = null
   )
 
   /** Drain main-looper posts so the auto-fire-on-subscribe lands. */
@@ -53,7 +55,7 @@ class TrackPlayerSkipCapabilityTest {
     player = TrackPlayer()
     serviceHandle = bindPlaybackServiceForTest(player, context())
     player.configureInternal(
-      PlayerConfig(httpHeaders = null, userAgent = null, autoRetries = null, retryBackoffMs = null, networkTimeoutMs = null, audioContentType = null, audioCategoryOptions = null, visualizationEnabled = null, clampSeekToBuffered = null, lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null, progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null, skipToPreviousBehavior = null), context()
+      PlayerConfig(httpHeaders = null, userAgent = null, autoRetries = null, retryBackoffMs = null, networkTimeoutMs = null, audioContentType = null, audioCategoryOptions = null, voiceVocabularyDonationEnabled = null, visualizationEnabled = null, clampSeekToBuffered = null, lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null, progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null, skipToPreviousBehavior = null), context()
     )
   }
 
@@ -318,7 +320,7 @@ class TrackPlayerSkipCapabilityTest {
     player = TrackPlayer()
     serviceHandle = bindPlaybackServiceForTest(player, context())
     player.configureInternal(
-      PlayerConfig(httpHeaders = null, userAgent = null, autoRetries = null, retryBackoffMs = null, networkTimeoutMs = null, audioContentType = null, audioCategoryOptions = null, visualizationEnabled = null, clampSeekToBuffered = null, lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null, progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null, skipToPreviousBehavior = null), context()
+      PlayerConfig(httpHeaders = null, userAgent = null, autoRetries = null, retryBackoffMs = null, networkTimeoutMs = null, audioContentType = null, audioCategoryOptions = null, voiceVocabularyDonationEnabled = null, visualizationEnabled = null, clampSeekToBuffered = null, lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null, progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null, skipToPreviousBehavior = null), context()
     )
   }
 
@@ -326,10 +328,25 @@ class TrackPlayerSkipCapabilityTest {
 
   private fun configureRestart() {
     player.configureInternal(
-      PlayerConfig(httpHeaders = null, userAgent = null, autoRetries = null, retryBackoffMs = null, networkTimeoutMs = null, audioContentType = null, audioCategoryOptions = null, visualizationEnabled = null, clampSeekToBuffered = null, lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null, progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null, skipToPreviousBehavior = SkipToPreviousBehavior.RESTART_OR_PREVIOUS), context()
+      PlayerConfig(httpHeaders = null, userAgent = null, autoRetries = null, retryBackoffMs = null, networkTimeoutMs = null, audioContentType = null, audioCategoryOptions = null, voiceVocabularyDonationEnabled = null, visualizationEnabled = null, clampSeekToBuffered = null, lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null, progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null, skipToPreviousBehavior = SkipToPreviousBehavior.RESTART_OR_PREVIOUS), context()
     )
   }
 
+  @Test
+  fun `restart mode — addToQueueInternal into empty queue keeps Previous false (cur stays -1)`() {
+    configureRestart()
+    val emissions = mutableListOf<SkipCapability>()
+    player.onSkipCapabilityChange { cap -> emissions.add(cap) }
+    flushMain()
+    emissions.clear()
+
+    player.addToQueueInternal((1..3).map { track("t$it") }, insertBefore = null)
+    // No loaded track: nothing to restart and nothing before it, so the
+    // lock-screen Previous control stays disabled until skipToIndex.
+    assertEquals(false, player.getCanSkipPrevious())
+    assertEquals(emptyList<SkipCapability>(), emissions)
+  }
+
   @Test
   fun `restart mode forces canSkipPrevious true at index 0`() {
     configureRestart()
@@ -360,4 +377,73 @@ class TrackPlayerSkipCapabilityTest {
       emissions.last().canSkipPrevious
     )
   }
+
+  // --- cast index writes keep the capability current
+
+  @Test
+  fun `emitRemoteTrackChange to the last index disables Next`() {
+    player.setQueueInternal((1..3).map { track("t$it") })
+    assertEquals(true, player.getCanSkipNext())
+
+    // The receiver advanced to the last track; the lock-screen Next
+    // control must grey out exactly as it does for a local advance.
+    player.emitRemoteTrackChange(2)
+    assertEquals(2, player.currentTrackIndex)
+    assertEquals(false, player.getCanSkipNext())
+    assertEquals(true, player.getCanSkipPrevious())
+  }
+
+  @Test
+  fun `emitRemoteTrackChange emits the capability change`() {
+    player.setQueueInternal((1..3).map { track("t$it") })
+    val emissions = mutableListOf<SkipCapability>()
+    player.onSkipCapabilityChange { cap -> emissions.add(cap) }
+    flushMain()
+    emissions.clear()
+
+    player.emitRemoteTrackChange(2)
+    flushMain()
+    assertEquals(
+      listOf(SkipCapability(canSkipPrevious = true, canSkipNext = false)),
+      emissions
+    )
+  }
+
+  @Test
+  fun `emitRemoteTrackChange classifies the new track's source`() {
+    // A local file at index 2, streaming tracks elsewhere: the source the
+    // JS side reads must follow the index the receiver moved to.
+    val local = TrackItem(
+      id = "local", url = "file:///tmp/local.m4a",
+      title = null, artist = null, album = null,
+      duration = null, artworkUrl = null, extras = null,
+      replayGainTrackGain = null, replayGainTrackPeak = null,
+      replayGainAlbumGain = null, replayGainAlbumPeak = null
+    )
+    player.setQueueInternal(listOf(track("t1"), track("t2"), local))
+    assertEquals(TrackSource.STREAMING, player.getCurrentTrackSource())
+
+    player.emitRemoteTrackChange(2)
+    assertEquals(TrackSource.LOCAL, player.getCurrentTrackSource())
+  }
+
+  @Test
+  fun `resumeLocalAfterCast lands on the handback index with its capability and source`() {
+    val local = TrackItem(
+      id = "local", url = "file:///tmp/local.m4a",
+      title = null, artist = null, album = null,
+      duration = null, artworkUrl = null, extras = null,
+      replayGainTrackGain = null, replayGainTrackPeak = null,
+      replayGainAlbumGain = null, replayGainAlbumPeak = null
+    )
+    player.setQueueInternal(listOf(track("t1"), track("t2"), local))
+    assertEquals(true, player.getCanSkipNext())
+    assertEquals(TrackSource.STREAMING, player.getCurrentTrackSource())
+
+    player.resumeLocalAfterCast(trackIndex = 2, positionMs = 0L)
+    flushMain()
+    assertEquals(2, player.currentTrackIndex)
+    assertEquals(false, player.getCanSkipNext())
+    assertEquals(TrackSource.LOCAL, player.getCurrentTrackSource())
+  }
 }

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

@@ -15,9 +15,8 @@ import org.robolectric.annotation.Config
  * [TrackPlayer]. `QueueSkipArithmeticTest` covers the raw
  * arithmetic; these tests cover the adapter layer:
  *
- * - `computeNextIndex` / `computePreviousIndex` — read
- *   `repeatModeState` + `currentTrackIndex` + `tracks.size` and
- *   delegate to [QueueSkipArithmetic].
+ * - `computeNextIndex` — reads `repeatModeState` + `currentTrackIndex`
+ *   + `tracks.size` and delegates to [QueueSkipArithmetic].
  * - `skipToNextInternal` / `skipToPreviousInternal` /
  *   `skipToIndexInternal` — advance `currentTrackIndex` when the
  *   arithmetic returns a target, no-op when it returns null. Under
@@ -41,7 +40,9 @@ class TrackPlayerSkipTest {
   private fun track(id: String) = TrackItem(
     id = id, url = "https://example.com/$id.m4a",
     title = null, artist = null, album = null,
-    duration = null, artworkUrl = null, extras = null
+    duration = null, artworkUrl = null, extras = null,
+    replayGainTrackGain = null, replayGainTrackPeak = null,
+    replayGainAlbumGain = null, replayGainAlbumPeak = null
   )
 
   private lateinit var serviceHandle: PlaybackServiceTestHandle
@@ -51,7 +52,7 @@ class TrackPlayerSkipTest {
     player = TrackPlayer()
     serviceHandle = bindPlaybackServiceForTest(player, context())
     player.configureInternal(
-      PlayerConfig(httpHeaders = null, userAgent = null, autoRetries = null, retryBackoffMs = null, networkTimeoutMs = null, audioContentType = null, audioCategoryOptions = null, visualizationEnabled = null, clampSeekToBuffered = null, lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null, progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null, skipToPreviousBehavior = null), context()
+      PlayerConfig(httpHeaders = null, userAgent = null, autoRetries = null, retryBackoffMs = null, networkTimeoutMs = null, audioContentType = null, audioCategoryOptions = null, voiceVocabularyDonationEnabled = null, visualizationEnabled = null, clampSeekToBuffered = null, lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null, progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null, skipToPreviousBehavior = null), context()
     )
     player.tracks = (1..5).map { track("t$it") }
     player.currentTrackIndex = 2 // mid-queue default for most cases
@@ -63,7 +64,7 @@ class TrackPlayerSkipTest {
     serviceHandle.destroy()
   }
 
-  // --- computeNextIndex / computePreviousIndex (adapter)
+  // --- computeNextIndex (adapter)
 
   @Test
   fun `computeNextIndex reads repeatModeState`() {
@@ -77,18 +78,6 @@ class TrackPlayerSkipTest {
     assertEquals(3, player.computeNextIndex())
   }
 
-  @Test
-  fun `computePreviousIndex reads repeatModeState`() {
-    player.repeatModeState = RepeatMode.OFF
-    assertEquals(1, player.computePreviousIndex())
-
-    player.repeatModeState = RepeatMode.TRACK
-    assertEquals(1, player.computePreviousIndex())
-
-    player.repeatModeState = RepeatMode.QUEUE
-    assertEquals(1, player.computePreviousIndex())
-  }
-
   @Test
   fun `computeNextIndex returns null at end under REPEAT OFF`() {
     player.repeatModeState = RepeatMode.OFF
@@ -103,13 +92,6 @@ class TrackPlayerSkipTest {
     assertEquals(0, player.computeNextIndex())
   }
 
-  @Test
-  fun `computePreviousIndex wraps to last under REPEAT QUEUE at index 0`() {
-    player.repeatModeState = RepeatMode.QUEUE
-    player.currentTrackIndex = 0
-    assertEquals(4, player.computePreviousIndex())
-  }
-
   // --- skipToNextInternal / skipToPreviousInternal
 
   @Test
@@ -293,7 +275,7 @@ class TrackPlayerSkipTest {
 
   private fun configureSkipBehavior(behavior: SkipToPreviousBehavior?) {
     player.configureInternal(
-      PlayerConfig(httpHeaders = null, userAgent = null, autoRetries = null, retryBackoffMs = null, networkTimeoutMs = null, audioContentType = null, audioCategoryOptions = null, visualizationEnabled = null, clampSeekToBuffered = null, lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null, progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null, skipToPreviousBehavior = behavior), context()
+      PlayerConfig(httpHeaders = null, userAgent = null, autoRetries = null, retryBackoffMs = null, networkTimeoutMs = null, audioContentType = null, audioCategoryOptions = null, voiceVocabularyDonationEnabled = null, visualizationEnabled = null, clampSeekToBuffered = null, lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null, progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null, skipToPreviousBehavior = behavior), context()
     )
     player.tracks = (1..5).map { track("t$it") }
   }

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

@@ -50,7 +50,7 @@ class TrackPlayerTransportTest {
     player = TrackPlayer()
     serviceHandle = bindPlaybackServiceForTest(player, context())
     player.configureInternal(
-      PlayerConfig(httpHeaders = null, userAgent = null, autoRetries = null, retryBackoffMs = null, networkTimeoutMs = null, audioContentType = null, audioCategoryOptions = null, visualizationEnabled = null, clampSeekToBuffered = null, lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null, progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null, skipToPreviousBehavior = null), context()
+      PlayerConfig(httpHeaders = null, userAgent = null, autoRetries = null, retryBackoffMs = null, networkTimeoutMs = null, audioContentType = null, audioCategoryOptions = null, voiceVocabularyDonationEnabled = null, visualizationEnabled = null, clampSeekToBuffered = null, lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null, progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null, placeholderArtworkUri = null, skipToPreviousBehavior = null), context()
     )
   }
 
@@ -80,7 +80,7 @@ class TrackPlayerTransportTest {
     // currentTrackIndex while the ExoPlayer is still IDLE.
     // iOS parity: paused-with-queue returns PAUSED, not NONE.
     player.tracks = listOf(
-      TrackItem("t1", "https://example.com/1.m4a", null, null, null, null, null, null)
+      TrackItem("t1", "https://example.com/1.m4a", null, null, null, null, null, null, null, null, null, null)
     )
     player.currentTrackIndex = 0
 
@@ -104,7 +104,7 @@ class TrackPlayerTransportTest {
     // on eventually-seekable content still lands. The reset-to-start protection
     // applies once the item is loaded (STATE_READY) and confirmed unseekable.
     player.setQueueInternal(
-      (1..3).map { TrackItem("t$it", "https://example.com/$it.m4a", null, null, null, null, null, null) }
+      (1..3).map { TrackItem("t$it", "https://example.com/$it.m4a", null, null, null, null, null, null, null, null, null, null) }
     )
     player.currentTrackIndex = 0
 

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

@@ -162,9 +162,6 @@ private class FakePlaybackEngineWithSinks : PlaybackEngine {
 
   override val mediaSessionPlayer: androidx.media3.exoplayer.ExoPlayer
     get() = error("not used in test")
-  override suspend fun prepare(
-    mediaItems: List<androidx.media3.common.MediaItem>, startIndex: Int, startPositionMs: Long,
-  ) = error("not used in test")
   override fun release() = error("not used in test")
   override fun setMediaItems(items: List<androidx.media3.common.MediaItem>, startIndex: Int, startPositionMs: Long) = error("not used in test")
   override fun addMediaItems(items: List<androidx.media3.common.MediaItem>, insertBefore: Int) = error("not used in test")
@@ -197,6 +194,5 @@ private class FakePlaybackEngineWithSinks : PlaybackEngine {
   override fun detachAudioBufferSink(sink: TeeAudioProcessor.AudioBufferSink) {
     if (attachedSinks.remove(sink)) detachCount++
   }
-  override suspend fun handoff(to: PlaybackEngine, atTrackBoundary: Boolean) = error("not used in test")
   override var delegate: PlaybackEngineDelegate? = null
 }

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

@@ -12,7 +12,7 @@ import kotlinx.coroutines.flow.asStateFlow
  * Test double for [CastSession.RemotePlayer]. Transport calls record their
  * name in [transportCalls]; the StateFlows are driveable via the public
  * backing fields, or via [reportState] to mirror the real session's
- * [hasReportedState] latch; [mediaSessionPlayer] is injectable so bind tests
+ * [hasReportedState] flag; [mediaSessionPlayer] is injectable so bind tests
  * can assert the MediaSession swaps to it.
  */
 internal class FakeRemotePlayer(
@@ -44,7 +44,7 @@ internal class FakeRemotePlayer(
 
   /**
    * Drive the receiver state the way a live session does: a non-idle report
-   * latches [hasReportedState]. Set [backingState] directly to stage a state
+   * sets [hasReportedState]. Set [backingState] directly to stage a state
    * the receiver has not reported yet.
    */
   fun reportState(state: RemotePlaybackState) {

package/android/src/test/java/com/margelo/nitro/queueplayer/cast/net/LocalAddressMonitorTest.kt

@@ -0,0 +1,173 @@
+package com.margelo.nitro.queueplayer.cast.net
+
+import android.content.Context
+import android.net.ConnectivityManager
+import android.net.LinkAddress
+import android.net.LinkProperties
+import android.net.Network
+import android.net.NetworkCapabilities
+import androidx.test.core.app.ApplicationProvider
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertNull
+import org.junit.Assert.assertTrue
+import org.junit.Test
+import org.junit.runner.RunWith
+import org.robolectric.RobolectricTestRunner
+import org.robolectric.Shadows.shadowOf
+import org.robolectric.annotation.Config
+import org.robolectric.shadow.api.Shadow
+import org.robolectric.shadows.ShadowNetwork
+import org.robolectric.shadows.ShadowNetworkCapabilities
+import org.robolectric.util.ReflectionHelpers
+import org.robolectric.util.ReflectionHelpers.ClassParameter
+import java.net.InetAddress
+
+/**
+ * `currentAddress` is the Wi-Fi network's IPv4 address: the callback is
+ * registered for Wi-Fi networks only, the `start()` seed uses the active
+ * network only when it is Wi-Fi and not a VPN, and the address follows
+ * that network's link properties until it is lost.
+ */
+@RunWith(RobolectricTestRunner::class)
+@Config(sdk = [34], shadows = [ShadowConnectivityManagerRecordingRequests::class])
+class LocalAddressMonitorTest {
+
+  private val context: Context = ApplicationProvider.getApplicationContext()
+  private val cm = context.getSystemService(Context.CONNECTIVITY_SERVICE) as ConnectivityManager
+  private val shadowCm: ShadowConnectivityManagerRecordingRequests = Shadow.extract(cm)
+
+  // The shadow's default active network has netId 0; its transport is
+  // whatever capabilities the test puts on it. Any other netId is a
+  // network that exists but is not the active one.
+  private val activeNetwork: Network = ShadowNetwork.newInstance(0)
+  private val otherNetwork: Network = ShadowNetwork.newInstance(1)
+
+  private fun describe(network: Network, transports: List<Int>, ipv4: String, vpn: Boolean = false) {
+    val capabilities = ShadowNetworkCapabilities.newInstance()
+    transports.forEach { shadowOf(capabilities).addTransportType(it) }
+    if (vpn) shadowOf(capabilities).removeCapability(NetworkCapabilities.NET_CAPABILITY_NOT_VPN)
+    shadowCm.setNetworkCapabilities(network, capabilities)
+    shadowCm.setLinkProperties(network, linkProperties(ipv4))
+  }
+
+  private fun linkProperties(vararg addresses: String): LinkProperties {
+    val linkAddresses = addresses.map { literal ->
+      val inet = InetAddress.getByName(literal)
+      ReflectionHelpers.callConstructor(
+        LinkAddress::class.java,
+        ClassParameter.from(InetAddress::class.java, inet),
+        ClassParameter.from(Int::class.javaPrimitiveType, if (inet.address.size == 4) 24 else 64),
+      )
+    }
+    return LinkProperties().apply { setLinkAddresses(linkAddresses) }
+  }
+
+  @Test
+  fun `the callback is registered for Wi-Fi networks only`() {
+    LocalAddressMonitor(context).start()
+
+    val request = shadowCm.requests.single()
+    assertTrue(request.hasTransport(NetworkCapabilities.TRANSPORT_WIFI))
+    assertFalse(request.hasTransport(NetworkCapabilities.TRANSPORT_CELLULAR))
+    assertTrue(request.hasCapability(NetworkCapabilities.NET_CAPABILITY_NOT_VPN))
+  }
+
+  @Test
+  fun `start seeds the address from a Wi-Fi active network`() {
+    describe(activeNetwork, listOf(NetworkCapabilities.TRANSPORT_WIFI), "192.168.1.10")
+
+    val monitor = LocalAddressMonitor(context).also { it.start() }
+
+    assertEquals("192.168.1.10", monitor.currentAddress)
+  }
+
+  @Test
+  fun `start does not seed the address from a cellular active network`() {
+    describe(otherNetwork, listOf(NetworkCapabilities.TRANSPORT_WIFI), "192.168.1.10")
+    describe(activeNetwork, listOf(NetworkCapabilities.TRANSPORT_CELLULAR), "10.0.0.5")
+
+    val monitor = LocalAddressMonitor(context).also { it.start() }
+
+    assertNull("a cellular address is unreachable from a LAN receiver", monitor.currentAddress)
+  }
+
+  @Test
+  fun `start does not seed the address from a VPN over Wi-Fi`() {
+    describe(
+      activeNetwork,
+      listOf(NetworkCapabilities.TRANSPORT_VPN, NetworkCapabilities.TRANSPORT_WIFI),
+      "10.8.0.2",
+      vpn = true,
+    )
+
+    val monitor = LocalAddressMonitor(context).also { it.start() }
+
+    assertNull("a tunnel address is unreachable from a LAN receiver", monitor.currentAddress)
+  }
+
+  @Test
+  fun `start registers the callback and seeds nothing when there is no active network`() {
+    shadowCm.setDefaultNetworkActive(false)
+
+    val monitor = LocalAddressMonitor(context).also { it.start() }
+
+    assertEquals(1, shadowCm.networkCallbacks.size)
+    assertNull(monitor.currentAddress)
+  }
+
+  @Test
+  fun `a matched network's link properties set the address and its loss clears it`() {
+    shadowCm.setDefaultNetworkActive(false)
+    val monitor = LocalAddressMonitor(context).also { it.start() }
+    val callback = shadowCm.networkCallbacks.single()
+
+    callback.onLinkPropertiesChanged(otherNetwork, linkProperties("192.168.1.20"))
+    assertEquals("192.168.1.20", monitor.currentAddress)
+
+    callback.onLost(otherNetwork)
+    assertNull(monitor.currentAddress)
+  }
+
+  /** A Wi-Fi handover reports the new network's link before the old network
+   *  is lost; the loss of the old one must not clear the new address. */
+  @Test
+  fun `losing a network other than the one that supplied the address keeps it`() {
+    shadowCm.setDefaultNetworkActive(false)
+    val monitor = LocalAddressMonitor(context).also { it.start() }
+    val callback = shadowCm.networkCallbacks.single()
+    val oldWifi = otherNetwork
+    val newWifi = ShadowNetwork.newInstance(2)
+
+    callback.onLinkPropertiesChanged(oldWifi, linkProperties("192.168.1.20"))
+    callback.onLinkPropertiesChanged(newWifi, linkProperties("192.168.2.30"))
+    callback.onLost(oldWifi)
+    assertEquals("192.168.2.30", monitor.currentAddress)
+
+    callback.onLost(newWifi)
+    assertNull(monitor.currentAddress)
+  }
+
+  @Test
+  fun `the address is the first non-loopback IPv4 among the link addresses`() {
+    shadowCm.setDefaultNetworkActive(false)
+    val monitor = LocalAddressMonitor(context).also { it.start() }
+    val callback = shadowCm.networkCallbacks.single()
+
+    callback.onLinkPropertiesChanged(otherNetwork, linkProperties("fe80::1", "127.0.0.1", "192.168.1.20", "192.168.1.21"))
+    assertEquals("192.168.1.20", monitor.currentAddress)
+
+    callback.onLinkPropertiesChanged(otherNetwork, linkProperties("fe80::1"))
+    assertNull(monitor.currentAddress)
+  }
+
+  @Test
+  fun `stop unregisters the callback`() {
+    val monitor = LocalAddressMonitor(context).also { it.start() }
+    assertEquals(1, shadowCm.networkCallbacks.size)
+
+    monitor.stop()
+
+    assertTrue(shadowCm.networkCallbacks.isEmpty())
+  }
+}

package/android/src/test/java/com/margelo/nitro/queueplayer/cast/net/ShadowConnectivityManagerRecordingRequests.kt

@@ -0,0 +1,27 @@
+package com.margelo.nitro.queueplayer.cast.net
+
+import android.net.ConnectivityManager
+import android.net.NetworkRequest
+import android.os.Handler
+import org.robolectric.annotation.Implements
+import org.robolectric.shadows.ShadowConnectivityManager
+
+/**
+ * A [ShadowConnectivityManager] that keeps the [NetworkRequest] passed to
+ * `registerNetworkCallback`; the stock shadow discards it and stores only
+ * the callback.
+ */
+@Implements(ConnectivityManager::class)
+class ShadowConnectivityManagerRecordingRequests : ShadowConnectivityManager() {
+
+  val requests = mutableListOf<NetworkRequest>()
+
+  override fun registerNetworkCallback(
+    request: NetworkRequest,
+    networkCallback: ConnectivityManager.NetworkCallback,
+    handler: Handler?,
+  ) {
+    requests.add(request)
+    super.registerNetworkCallback(request, networkCallback, handler)
+  }
+}

package/app.plugin.js

@@ -331,6 +331,13 @@ const withChromecastSubspecPodfile = (config) =>
     },
   ]);
 
+/**
+ * Bonjour type the local-network permission probe advertises and browses.
+ * Mirrors `LocalNetworkPermissionProbe.serviceType`; the two must agree or the
+ * probe is blocked with nothing to indicate why.
+ */
+const LOCAL_NETWORK_PROBE_SERVICE_TYPE = '_rnqp-lnp._tcp';
+
 const withChromecastInfoPlist = (config, receiverAppId) =>
   withInfoPlist(config, (cfg) => {
     const appId = (receiverAppId || 'CC1AD845').toUpperCase();
@@ -344,7 +351,16 @@ const withChromecastInfoPlist = (config, receiverAppId) =>
     const existingBonjour = Array.isArray(cfg.modResults.NSBonjourServices)
       ? cfg.modResults.NSBonjourServices
       : [];
-    const additions = ['_googlecast._tcp', `_${appId}._googlecast._tcp`];
+    // The permission probe browses its own service type. iOS refuses to browse
+    // a type that is not declared here, so without this entry the probe can
+    // never succeed and every consumer reads `undetermined` forever.
+    // Must match `LocalNetworkPermissionProbe.serviceType` in
+    // ios/Cast/Core/LocalNetworkPermissionProbe.swift.
+    const additions = [
+      '_googlecast._tcp',
+      `_${appId}._googlecast._tcp`,
+      LOCAL_NETWORK_PROBE_SERVICE_TYPE,
+    ];
     for (const s of additions) {
       if (!existingBonjour.includes(s)) existingBonjour.push(s);
     }

package/ios/AVPlayerItemQueueItemId.swift

@@ -26,14 +26,18 @@ import AVFoundation
 /// standard idiom — no `.m` / `.h` source files introduced.
 private var queueItemIdKey: UInt8 = 0
 private var sourceURLKey: UInt8 = 0
+private var routedThroughReadThroughServerKey: UInt8 = 0
 
+/// `nonisolated` throughout: the SDK marks `AVPlayerItem` main-actor isolated
+/// because `asset` is not Sendable, but these stamps are written once at
+/// construction and read on the player queue.
 extension AVPlayerItem {
   /// Lib-internal identity for this AVPlayerItem. Set once at
   /// construction by `AVQueueBuilder.makeItem`; never mutated
   /// after. nil only for AVPlayerItems that did not flow through
   /// the lib's queue construction path (e.g. built directly via
   /// `makeItemRaw`).
-  var queueItemId: String? {
+  nonisolated var queueItemId: String? {
     get { objc_getAssociatedObject(self, &queueItemIdKey) as? String }
     set {
       objc_setAssociatedObject(
@@ -41,21 +45,31 @@ extension AVPlayerItem {
     }
   }
 
-  /// The exact `track.url` string this item was built from. Stored
-  /// verbatim — `LookaheadCache` keys entries by raw URL-string
-  /// equality, so a re-resolution against the cache must use the same
-  /// string the cache was keyed with, NOT the item's `AVURLAsset.url`
-  /// (which is already a `file://` path once an item is built from a
-  /// cached local file, and is a parse/re-serialize round-trip of the
-  /// original for a remote item). Lets a later attach (crossfade
-  /// skip / fade-arm) look the track up in the cache and swap a
-  /// remote-built item for its local cache file once it finishes
-  /// downloading.
-  var sourceURL: String? {
+  /// The exact `track.url` string this item was built from, stored
+  /// verbatim. A routed item's `AVURLAsset.url` is the read-through
+  /// server's `127.0.0.1` address and an unrouted one is a
+  /// parse/re-serialize round-trip of the original, so anything that
+  /// reads a container, codec or track identity out of a URL reads this:
+  /// `NowPlayingFormatExtractor`, `AssetReplayGainReader`, the error
+  /// `url` field, and the source diagnostic log.
+  nonisolated var sourceURL: String? {
     get { objc_getAssociatedObject(self, &sourceURLKey) as? String }
     set {
       objc_setAssociatedObject(
         self, &sourceURLKey, newValue, .OBJC_ASSOCIATION_RETAIN_NONATOMIC)
     }
   }
+
+  /// Whether this item's asset URL is the read-through server's loopback
+  /// address rather than `sourceURL` itself. Set once by
+  /// `AVQueueBuilder.makeItem`; the routing decision is made at build time
+  /// and an item is never re-pointed, so the stamp is what source
+  /// classification reads instead of guessing from the server's presence.
+  nonisolated var isRoutedThroughReadThroughServer: Bool {
+    get { (objc_getAssociatedObject(self, &routedThroughReadThroughServerKey) as? Bool) ?? false }
+    set {
+      objc_setAssociatedObject(
+        self, &routedThroughReadThroughServerKey, newValue, .OBJC_ASSOCIATION_RETAIN_NONATOMIC)
+    }
+  }
 }