react-native-queue-player 1.1.2 → 2.0.0

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

package/ios/AVQueueBuilder.swift

@@ -12,11 +12,11 @@ import AVFoundation
 /// Constructs AVPlayerItem instances from TrackItem descriptors,
 /// applying the PlayerConfig's custom HTTP headers + user agent.
 ///
-/// Headers are the load-bearing feature for Subsonic-behind-reverse-
-/// proxy deployments — every remote fetch (asset read, lookahead-
-/// cache download, artwork fetch) has to carry the consumer app's
-/// auth. `AVURLAssetHTTPHeaderFieldsKey` on the AVURLAsset options
-/// dictionary does this on iOS.
+/// Headers carry the consumer app's auth on every remote fetch —
+/// asset read, lookahead-cache download, artwork fetch. An unrouted
+/// asset gets them through `AVURLAssetHTTPHeaderFieldsKey` on its
+/// options dictionary; a routed one is built with no asset options,
+/// and the read-through server sends them on its origin leg instead.
 ///
 /// User-Agent handling: AVURLAsset has no dedicated UA option. The
 /// standard workaround is to include `User-Agent: <ua>` inside the
@@ -28,19 +28,20 @@ public enum AVQueueBuilder {
 
   /// Build AVPlayerItems for every track in `tracks`, applying config
   /// headers + UA on remote URLs. Returns an empty array for an empty
-  /// input. Never throws — invalid URLs silently produce a nil asset
-  /// which AVQueuePlayer surfaces as a playback error at runtime.
+  /// input. Never throws — a track whose URL does not parse is dropped
+  /// from the result (`makeItem` returns nil), so the engine never sees
+  /// it.
   ///
-  /// When `cache` is non-nil + a track is fully cached, the
-  /// AVPlayerItem is built from the local file URL instead of the
-  /// remote one. Bytes never hit the network on playback. Partial
-  /// caches fall through to the remote URL — `cache.cachedURL`
-  /// returns nil for entries that haven't fully downloaded.
+  /// With a non-nil `server`, every routable remote track (`isRoutable`)
+  /// is built on the read-through server's local URL, and the server
+  /// decides per request whether bytes come from the lookahead cache or
+  /// the origin. `file://` tracks, `.m3u8` manifests, and every track when
+  /// `server` is nil bind `track.url` directly — see `makeItem`.
   static func buildPlayerItems(
     tracks: [TrackItem],
     queueItemIds: [String],
     config: PlayerConfig,
-    cache: LookaheadCache? = nil
+    server: ReadThroughServer? = nil
   ) -> [AVPlayerItem] {
     // Parallel-array invariant: a violation is a programming error
     // we own (QueueState uphold-able at construction). `precondition`
@@ -51,41 +52,43 @@ public enum AVQueueBuilder {
       "AVQueueBuilder.buildPlayerItems requires queueItemIds parallel to tracks (1:1)"
     )
     return zip(tracks, queueItemIds).compactMap { track, id in
-      makeItem(for: track, queueItemId: id, config: config, cache: cache)
+      makeItem(for: track, queueItemId: id, config: config, server: server)
     }
   }
 
-  /// Best-effort warm-up of a freshly-built item's asset BEFORE it is
-  /// inserted into a live `AVQueuePlayer`. When the insert lands in the
-  /// immediate-next slot of a playing queue, `AVQueuePlayer` prerolls the
-  /// new item on the shared decode/render pipeline while the current item
-  /// is still rendering; faulting the asset's `tracks` / `duration` /
-  /// `playable` keys in synchronously at that moment briefly disturbs the
-  /// currently-playing item. Loading them here first makes that preroll
-  /// cheap.
+  /// Cancel outstanding key loads on the assets of items being discarded.
   ///
-  /// Best-effort: the load races a [timeout] deadline and the caller
-  /// proceeds as soon as either wins. `AVAsset`'s async loader honours
-  /// task cancellation, so `cancelAll` caps a slow / unreachable remote
-  /// asset at [timeout] and the item is inserted unwarmed rather than
-  /// deferring the enqueue. Load errors are ignored for the same reason.
-  @MainActor
-  static func preloadAssetForInsert(_ item: AVPlayerItem, timeout: TimeInterval = 2.0) async {
-    let asset = item.asset
-    await withTaskGroup(of: Void.self) { group in
-      group.addTask { @MainActor in
-        _ = try? await asset.load(.tracks, .duration, .isPlayable)
-      }
-      group.addTask {
-        try? await Task.sleep(nanoseconds: UInt64(timeout * 1_000_000_000))
-      }
-      _ = await group.next()
-      group.cancelAll()
+  /// `AVURLAsset.dealloc` cancels them implicitly and **blocks the deallocating
+  /// thread while it does** — a dispatch-group wait on the asset inspector,
+  /// measured at tens of seconds for a queue of 200 with loads in flight.
+  /// Cancelling first makes that wait a no-op. That thread is
+  /// `playerQueue`, so the block stalls every queue operation behind it.
+  ///
+  /// Only assets that are genuinely being dropped may be cancelled: a
+  /// cancelled asset can never become playable, so an item rebuilt on a reused
+  /// asset would stall silently. `keeping` is the set that survives, compared
+  /// by identity.
+  static func cancelLoading(dropping outgoing: [AVPlayerItem], keeping: [AVPlayerItem] = []) {
+    for item in itemsBeingDropped(outgoing: outgoing, keeping: keeping) {
+      item.asset.cancelLoading()
     }
   }
 
-  /// Single-item builder. Used by addToQueue. Honours the cache
-  /// lookup when a cache instance is supplied.
+  /// The items in `outgoing` that no entry of `keeping` reuses. Identity, not
+  /// equality: two items can wrap the same asset, and it is the asset's
+  /// survival that decides whether cancelling it is safe.
+  @_spi(QueuePlayerTests)
+  public static func itemsBeingDropped(
+    outgoing: [AVPlayerItem], keeping: [AVPlayerItem]
+  ) -> [AVPlayerItem] {
+    guard !keeping.isEmpty else { return outgoing }
+    let survivingAssets = keeping.map { ObjectIdentifier($0.asset) }
+    let surviving = Set(survivingAssets)
+    return outgoing.filter { !surviving.contains(ObjectIdentifier($0.asset)) }
+  }
+
+  /// Single-item builder behind `buildPlayerItems`. Routes a routable
+  /// remote track through `server` when one is supplied.
   ///
   /// `queueItemId` is the lib-generated identity for this AVPlayerItem
   /// instance — set on the constructed item via the
@@ -95,53 +98,68 @@ public enum AVQueueBuilder {
   /// position; the value passed here is the corresponding entry.
   /// Never derived from any consumer-supplied TrackItem field —
   /// only `track.url` is required + reliable on consumer data.
+  ///
+  /// The consumer's ReplayGain claim over [track] is resolved and
+  /// validated here, once, and stamped on the item alongside those two.
+  /// The item is the only thing the audio path holds, and this is the
+  /// one place that has both it and the `TrackItem` it came from.
   static func makeItem(
     for track: TrackItem,
     queueItemId: String,
     config: PlayerConfig,
-    cache: LookaheadCache? = nil
+    server: ReadThroughServer? = nil
   ) -> AVPlayerItem? {
-    if let cachedURL = cache?.cachedURL(forUrl: track.url) {
-      // Local file URL — no headers needed. `cachedURL` is a pure
-      // read; LRU bookkeeping is opt-in via `touch` so a read-heavy
-      // playback path doesn't trigger a plist write per resolution.
-      cache?.touch(url: track.url)
-      // `automaticallyLoadedAssetKeys` pre-loads the listed keys
-      // asynchronously while the AVPlayerItem itself becomes
-      // addressable — Apple's documented iOS 16+ preferred
-      // construction pattern, shaving first-frame latency vs a
-      // bare `AVPlayerItem(asset:)` that loads keys lazily on first
-      // access.
-      //
-      // `"tracks"` is included here (file:// branch only — the
-      // HTTP path in `makeItemRaw` keeps the original two-key set
-      // so HLS / streaming items don't pay the variant-playlist +
-      // segment-header round-trip at insert time). The local
-      // tracks-key load is free; once it's loaded, the engine's
-      // per-item `audioMix(for:)` install (called BEFORE
-      // `player.insert`) gets a tap-bearing mix synchronously,
-      // which is the only window AVPlayer honours per Apple's
-      // contract (`audioMix` changes after the item starts
-      // rendering are silently dropped).
-      let asset = AVURLAsset(url: cachedURL)
-      let item = AVPlayerItem(
+    // Remote tracks bind the read-through server's URL, which is stable for
+    // the session and never re-pointed. Whether the bytes come from the cache
+    // or the origin is the server's decision, made per request — the only
+    // moment it can be answered, because the cache fills long after the queue
+    // is built. Headers move to the origin leg with it.
+    //
+    // HLS is excluded: proxying a playlist would re-base its relative segment
+    // paths against the local URL. No server means no routing, which is what a
+    // consumer running without the lookahead cache gets.
+    let routed: URL? = Self.isRoutable(track.url) ? server.flatMap { srv in
+      URL(string: track.url).flatMap { srv.localURL(for: $0, sourceURL: track.url) }
+    } : nil
+
+    let item: AVPlayerItem?
+    if let routed {
+      let asset = AVURLAsset(url: routed)
+      let built = AVPlayerItem(
         asset: asset,
-        automaticallyLoadedAssetKeys: ["playable", "duration", "tracks"]
+        automaticallyLoadedAssetKeys: ["playable", "duration"]
       )
-      pinForwardBufferDuration(on: item)
-      item.queueItemId = queueItemId
-      item.sourceURL = track.url
-      return item
+      pinForwardBufferDuration(on: built)
+      built.isRoutedThroughReadThroughServer = true
+      item = built
+    } else {
+      item = makeItemRaw(
+        urlString: track.url,
+        headers: config.httpHeaders,
+        userAgent: config.userAgent)
     }
-    let item = makeItemRaw(
-      urlString: track.url,
-      headers: config.httpHeaders,
-      userAgent: config.userAgent)
     item?.queueItemId = queueItemId
+    // The media's own URL, always — never the transport's. Everything that
+    // reads a container, a codec or a track identity out of a URL reads this.
     item?.sourceURL = track.url
+    item?.suppliedReplayGain = SuppliedReplayGain.from(track: track)
     return item
   }
 
+  /// Whether a URL is one the read-through server can carry.
+  ///
+  /// `http(s)` only, and not a manifest: AVFoundation resolves an HLS
+  /// playlist's relative segment paths against the URL it fetched the playlist
+  /// from, so a proxied playlist would point every segment at the local server
+  /// under a token that names none of them.
+  static func isRoutable(_ urlString: String) -> Bool {
+    guard let url = URL(string: urlString), let scheme = url.scheme?.lowercased(),
+          scheme == "http" || scheme == "https"
+    else { return false }
+    return url.pathExtension.lowercased() != "m3u8"
+  }
+
+
   /// Apple-acknowledged AVPlayer mitigation: explicitly setting
   /// `preferredForwardBufferDuration = 0.0` on every item closes a
   /// long-standing AVQueuePlayer bug where items can be dropped
@@ -198,9 +216,24 @@ public enum AVQueueBuilder {
     return item
   }
 
-  /// Plain-Swift merging core — takes primitive arguments so it stays
-  /// clear of the Swift↔C++ interop boundary.
-  /// `makeItemRaw(urlString:headers:userAgent:)` below
+  /// The consumer's headers with `userAgent` folded in, which is the request
+  /// shape every outbound leg uses: asset loads, cache prefetches, and the
+  /// read-through server's origin requests.
+  @_spi(QueuePlayerTests)
+  public static func mergedHeaders(
+    headers: [String: String]?,
+    userAgent: String?
+  ) -> [String: String] {
+    var merged: [String: String] = headers ?? [:]
+    if let ua = userAgent, !ua.isEmpty {
+      merged["User-Agent"] = ua
+    }
+    return merged
+  }
+
+  /// Plain-Swift options-dictionary builder — takes primitive arguments so
+  /// it stays clear of the Swift↔C++ interop boundary.
+  /// `makeItemRaw(urlString:headers:userAgent:)`
   /// calls this, and `makeItem(for:, config:)` unpacks its `PlayerConfig`
   /// argument into the same primitive pair and calls `makeItemRaw`.
   ///
@@ -209,18 +242,20 @@ public enum AVQueueBuilder {
   ///
   /// Key spelling: `AVURLAssetHTTPHeaderFieldsKey` is not a public
   /// Swift API. The raw Obj-C string still works at runtime. See
-  /// NOTES.md §7. We do not implement an
-  /// `AVAssetResourceLoaderDelegate` replacement — see
-  /// `plan/blocked.md`.
+  /// NOTES.md §7.
+  ///
+  /// No `AVAssetResourceLoaderDelegate` is installed, and none will be: an
+  /// asset routed through a loader takes a custom URL scheme, and Apple states
+  /// AirPlay is unsupported for one. Remote tracks reach the lookahead cache
+  /// through a local HTTP server instead, which keeps AVFoundation's own HTTP
+  /// stack — including the redirect following a loader would have to
+  /// reimplement.
   @_spi(QueuePlayerTests)
   public static func httpOptionsRaw(
     headers: [String: String]?,
     userAgent: String?
   ) -> [String: Any] {
-    var merged: [String: String] = headers ?? [:]
-    if let ua = userAgent, !ua.isEmpty {
-      merged["User-Agent"] = ua
-    }
+    let merged = mergedHeaders(headers: headers, userAgent: userAgent)
     guard !merged.isEmpty else { return [:] }
     return ["AVURLAssetHTTPHeaderFieldsKey": merged]
   }

package/ios/ArtworkLoader.swift

@@ -127,10 +127,3 @@ final class ArtworkLoader {
   private var _configHeaders: [String: String]?
   private var _configUserAgent: String?
 }
-
-private extension NSLock {
-  func withLock<T>(_ body: () throws -> T) rethrows -> T {
-    lock(); defer { unlock() }
-    return try body()
-  }
-}

package/ios/ArtworkResolver.swift

@@ -53,11 +53,10 @@ final class ArtworkResolver {
   /// only one the consumer cares about. Threading: completion fires
   /// on main.
   func resolve(url: String?, completion: @escaping (UIImage) -> Void) {
-    self.currentSeq &+= 1
-    let seq = self.currentSeq
+    let seq = bumpSeq()
 
     loader.load(uri: url) { [weak self] image in
-      guard let self = self, self.currentSeq == seq else { return }
+      guard let self = self, self.isCurrent(seq) else { return }
       completion(image ?? PlaceholderArtwork.image)
     }
   }
@@ -68,7 +67,7 @@ final class ArtworkResolver {
   /// already in transit will populate the loader's cache for a
   /// future `resolve(...)` that hits the same URL.
   func cancelInFlight() {
-    currentSeq &+= 1
+    _ = bumpSeq()
   }
 
   /// Clear the underlying loader's cache + drop the in-flight
@@ -83,5 +82,24 @@ final class ArtworkResolver {
   /// Monotonic resolve-call counter. Captured into completion closures
   /// to drop responses for superseded requests, including same-URL
   /// re-resolves that the URL-string compare cannot distinguish.
+  /// Callers bump this on the queue that owns playback while the loader
+  /// reports completions on main, so the counter is the one piece of state
+  /// crossing between them and it carries its own lock.
+  private let seqLock = NSLock()
   private var currentSeq: UInt64 = 0
+
+  /// Advance the sequence and return the new value.
+  private func bumpSeq() -> UInt64 {
+    seqLock.lock()
+    defer { seqLock.unlock() }
+    currentSeq &+= 1
+    return currentSeq
+  }
+
+  /// Whether `seq` is still the newest request.
+  private func isCurrent(_ seq: UInt64) -> Bool {
+    seqLock.lock()
+    defer { seqLock.unlock() }
+    return currentSeq == seq
+  }
 }