react-native-queue-player 1.2.0 → 2.0.0

package/ios/LookaheadCache.swift

@@ -86,6 +86,9 @@ public final class LookaheadCache: @unchecked Sendable {
   /// scheduling immediately. Guarded by `queue`. The URLSession is
   /// only invalidated by `tearDown()` at full destroy.
   private var isEnabled: Bool = true
+  /// Downloads admitted and not yet finished; `tearDown` waits on it before
+  /// invalidating the session.
+  private let inFlightDownloads = DispatchGroup()
 
   // MARK: - Init / lifecycle
 
@@ -115,7 +118,8 @@ public final class LookaheadCache: @unchecked Sendable {
   internal convenience init(
     directory: URL = LookaheadCache.defaultDirectory(),
     maxSizeBytes: UInt64 = LookaheadCache.DEFAULT_MAX_SIZE_BYTES,
-    evictionPolicy: EvictionPolicy = .lru
+    evictionPolicy: EvictionPolicy = .lru,
+    allowsCellularAccess: Bool = true
   ) {
     // `.ephemeral` rather than `.default` so the OS shared URL
     // response cache doesn't double-cache our prefetch bytes (we
@@ -136,10 +140,25 @@ public final class LookaheadCache: @unchecked Sendable {
       directory: directory,
       maxSizeBytes: maxSizeBytes,
       evictionPolicy: evictionPolicy,
-      urlSession: URLSession(configuration: cfg)
+      urlSession: URLSession(configuration: cfg),
+      allowsCellularAccess: allowsCellularAccess
     )
   }
 
+  /// Whether prefetch downloads may use cellular. Set on each request rather
+  /// than baked into the session, so a change applies from the next request
+  /// without disturbing anything in flight — that one keeps the value it was
+  /// issued with. `URLRequest.allowsCellularAccess = false` is an
+  /// unconditional refusal, where the session's own value is only a
+  /// permissive default.
+  internal var allowsCellularAccess: Bool {
+    get { queue.sync { cellularAllowed } }
+    set { queue.sync { cellularAllowed = newValue } }
+  }
+
+  /// Guarded by `queue`, like the rest of the mutable cache state.
+  private var cellularAllowed: Bool = true
+
   /// Test-only init — tests inject a `URLSession` wired to a
   /// `URLProtocol` stub here. `internal` (not `@_spi public`)
   /// because `public` symbols still emit C++ interop bindings even
@@ -150,12 +169,14 @@ public final class LookaheadCache: @unchecked Sendable {
     directory: URL,
     maxSizeBytes: UInt64,
     evictionPolicy: EvictionPolicy = .lru,
-    urlSession: URLSession
+    urlSession: URLSession,
+    allowsCellularAccess: Bool = true
   ) {
     self.cacheDirectory = directory
     self.maxBytes = maxSizeBytes
     self.evictionPolicy = evictionPolicy
     self.urlSession = urlSession
+    self.cellularAllowed = allowsCellularAccess
     Self.ensureDirectoryExists(at: directory)
     self.index = Self.loadOrCreateIndex(at: directory)
   }
@@ -165,12 +186,30 @@ public final class LookaheadCache: @unchecked Sendable {
   /// Must be called from `TrackPlayer.destroy` BEFORE any consumer
   /// drops their reference to the cache instance.
   ///
+  /// Clears `isEnabled` before invalidating, so a prefetcher Task
+  /// that reaches `download` after the teardown returns at the
+  /// quiescence gate instead of asking an invalidated session for a
+  /// task — which raises the Obj-C exception `Task created in a
+  /// session that has been invalidated`, uncatchable in Swift's
+  /// `do-catch`. Unlike `disable()` the session is not reusable
+  /// afterwards; a teardown ends the instance's life.
+  ///
   /// Named `tearDown` (not `release`) to avoid the Obj-C
   /// `NSObject.release` selector collision; pure Swift class so
   /// there is no actual NSObject to inherit, but staying clear
   /// of the name keeps things friendly if a future @objc bridge
   /// gets added.
   public func tearDown() {
+    queue.sync {
+      self.isEnabled = false
+      self.pendingDownloads.removeAll()
+    }
+    // A download admitted before the flag flipped may not have reached the
+    // session yet; asking an invalidated session for a task raises an
+    // Objective-C exception Swift cannot catch. The prefetcher is cancelled
+    // before this is called, so admitted downloads leave the group as their
+    // cancellation lands — the wait is a bound, not a normal cost.
+    _ = inFlightDownloads.wait(timeout: .now() + .seconds(2))
     urlSession.invalidateAndCancel()
   }
 
@@ -182,7 +221,8 @@ public final class LookaheadCache: @unchecked Sendable {
   /// `Task created in a session that has been invalidated`,
   /// uncatchable in Swift's `do-catch`).
   ///
-  /// Effects: clears the `isEnabled` flag so `download` no-ops + the
+  /// Effects: clears the `isEnabled` flag so `download` no-ops, `cachedURL`
+  /// answers nil (the read-through server then serves from the origin) + the
   /// in-flight dedup set so a re-enable starts clean, and cancels
   /// any URLSession tasks already mid-flight via `getAllTasks`. The
   /// session itself stays alive — a later `enable()` reuses it.
@@ -205,19 +245,38 @@ public final class LookaheadCache: @unchecked Sendable {
     }
   }
 
+  /// URLs that must survive eviction: the playing track and the window
+  /// around it. Every eviction path consults this, not just a shrink —
+  /// `commitDownloadedFile` evicts after each prefetch commit, so without a
+  /// live set the entry backing the playing item can be deleted underneath
+  /// it and playback stops with a file that no longer exists.
+  ///
+  /// Written by `TrackPlayer` on track change and on prefetch reschedule.
+  /// Bounded by the caller: protecting the whole remaining queue would leave
+  /// nothing evictable and turn every commit into a full cache wipe.
+  private var liveProtectedUrls: Set<String> = []
+
+  /// Replace the set of URLs eviction must not touch.
+  ///
+  /// Asynchronous by design. The caller is `rescheduleLookahead`, which runs on
+  /// the queue serialising player state from every queue and skip path, and the
+  /// cache queue also serves download commits — a synchronous hop would park
+  /// that queue behind disk work on a hot path. The set is advisory for the next eviction, and
+  /// evictions run on this same serial queue, so a write enqueued here is
+  /// visible to every eviction that follows it.
+  public func setProtectedUrls(_ urls: Set<String>) {
+    queue.async { self.liveProtectedUrls = urls }
+  }
+
   /// Update the cache budget at runtime. On shrink, runs
-  /// `evictUnderBudgetLocked` immediately so the new ceiling is
-  /// enforced before the call returns. On grow, the new budget
-  /// takes effect on the next download — no immediate eviction.
+  /// `evictUnderBudgetLocked` immediately so the new ceiling is enforced
+  /// before the call returns. On grow, the new budget takes effect on the next
+  /// download — no immediate eviction.
   ///
-  /// `protectedUrls`: caller passes the source URLs whose
-  /// `AVPlayerItem`s are currently held by AVQueuePlayer. Without
-  /// this, a shrink could evict the file backing a live
-  /// AVPlayerItem + manifest as `AVPlayerItemFailedToPlayToEndTime`
-  /// mid-playback. TrackPlayer passes
-  /// `tracks[currentTrackIndex...].map { $0.url }` so the entire
-  /// active tail (current + buffered-ahead) is safe. Always keyed
-  /// on URL — `track.id` is consumer-supplied + unreliable.
+  /// `protectedUrls` names the source URLs whose items the engine currently
+  /// holds. Without it a shrink can evict the file backing a live item and
+  /// surface as `AVPlayerItemFailedToPlayToEndTime` mid-playback. Always keyed
+  /// on URL: `track.id` is consumer-supplied and unreliable.
   public func setMaxSizeBytes(_ newSize: UInt64, protectedUrls: Set<String> = []) {
     let urlsToDeleteAfterUnlock: [URL] = queue.sync {
       let shrinking = newSize < self.maxBytes
@@ -254,30 +313,35 @@ public final class LookaheadCache: @unchecked Sendable {
     }
   }
 
-  /// Number of cache index entries whose file is still on disk
-  /// (queue-agnostic). Mirrors the semantics of `currentSizeBytes()`
-  /// (cache state, independent of any current queue). Used by
-  /// `TrackPlayer.buildCacheStatusSnapshot` for the
-  /// `tracksFullyCached` field — the count reflects the cache itself,
-  /// not the intersection with `self.tracks`.
+  /// Number of entries the cache index holds (queue-agnostic). Mirrors the
+  /// semantics of `currentSizeBytes()` — cache state, independent of any
+  /// current queue. Used by `TrackPlayer.buildCacheStatusSnapshot` for the
+  /// `tracksFullyCached` field, so the count reflects the cache itself, not
+  /// the intersection with `self.tracks`.
+  ///
+  /// The index is the source of truth, exactly as it is for
+  /// `currentSizeBytes()`, so this is O(1) and holds the lock briefly: a
+  /// cache-status subscriber has it fire after every prefetch iteration, and
+  /// stating the disk per entry would park the caller on the queue committing
+  /// those downloads. It therefore over-reports a file removed out from under
+  /// the index. Where the answer has to be exact about a single file — deciding
+  /// whether to play from cache — `isFullyCached(url:)` stats it.
+  ///
+  /// Android's counterpart verifies bytes on disk per key, because Media3
+  /// caches partial chunks and counting keys there would over-report a
+  /// half-downloaded track rather than a deleted one.
   public func fullyCachedCount() -> Int {
-    return queue.sync {
-      self.index.entries.reduce(into: 0) { acc, entry in
-        let fileURL = cacheDirectory.appendingPathComponent(entry.fileName)
-        if FileManager.default.fileExists(atPath: fileURL.path) {
-          acc += 1
-        }
-      }
-    }
+    return queue.sync { self.index.entries.count }
   }
 
   /// Wipe every cached file + reset the index.
   ///
-  /// **Mid-playback caveat:** if a currently-playing `AVPlayerItem`
-  /// was constructed from a cached file URL, deleting that file
-  /// mid-playback surfaces as an `AVPlayerItemFailedToPlayToEndTime`
-  /// error. Contract is "do not call during active playback";
-  /// consumers should `pause()` first or accept the mid-track error.
+  /// Safe during playback. A playing item is bound to the read-through server
+  /// rather than to a cache file, so a track whose file is deleted underneath
+  /// it reads through to the origin on its next request instead of failing —
+  /// the cost is re-fetching the remainder, not an
+  /// `AVPlayerItemFailedToPlayToEndTime`. A response already in flight
+  /// completes, because the open handle holds the unlinked inode.
   public func clear() {
     let urlsToDelete: [URL] = queue.sync {
       let urls = self.index.entries.map {
@@ -299,14 +363,14 @@ public final class LookaheadCache: @unchecked Sendable {
 
   // MARK: - Lookup
 
-  /// Return the local file URL for `url` (the source URL — see
-  /// "Key shape" on `isFullyCached(url:)`) if a fully-downloaded
-  /// cache entry exists, otherwise nil. Pure read — does NOT touch
-  /// the LRU access tick. Callers that want LRU bookkeeping (the
-  /// `AVQueueBuilder.makeItem` cache-hit branch is the production
-  /// caller) call `touch(url:)` separately. Splitting these
-  /// out avoids the prior pattern's two-FS-writes-per-read penalty
-  /// on the playback hot path.
+  /// Return the local file URL for `url` (the source URL — the same
+  /// string `isFullyCached(url:)` keys on) if the cache is enabled and a
+  /// fully-downloaded entry exists, otherwise nil. Pure read — does NOT touch the LRU
+  /// access tick. The external production caller is the read-through server's
+  /// per-request `cachedFileForOrigin` lookup (built in
+  /// `TrackPlayer.startReadThroughServer`), which calls `touch(url:)`
+  /// once per token on its first disk hit, so a track's many range
+  /// requests cost one index write rather than one per read.
   ///
   /// Defensive: if the file got pruned out from under us (consumer
   /// ran `rm -rf tmp`, or eviction then crashed before
@@ -319,6 +383,9 @@ public final class LookaheadCache: @unchecked Sendable {
   /// for the lifetime of this process.
   public func cachedURL(forUrl url: String) -> URL? {
     return queue.sync {
+      // A disabled cache serves nothing: every request goes to the origin,
+      // whatever is on disk. The files stay for the next enable.
+      guard self.isEnabled else { return nil }
       guard let entryIdx = self.index.entries.firstIndex(where: { $0.trackId == url }) else {
         return nil
       }
@@ -379,7 +446,12 @@ public final class LookaheadCache: @unchecked Sendable {
     // that survived `disable()` + tried to download against the
     // (intentionally NOT invalidated) session still skips the
     // request rather than competing with a re-enable cycle.
-    let enabled = queue.sync { self.isEnabled }
+    //
+    // The cellular policy is read here too, so one download cannot straddle a
+    // change: it is issued wholly under the policy in force when it started.
+    let (enabled, cellularAllowed) = queue.sync {
+      (self.isEnabled, self.cellularAllowed)
+    }
     guard enabled else { return }
 
     // Cache key = source URL. The `Entry` struct's `trackId` field
@@ -407,18 +479,34 @@ public final class LookaheadCache: @unchecked Sendable {
     // contract in `LookaheadCachePrefetcher` (failed tracks retry
     // on the next reschedule).
     let dedupeKey = track.url
-    let alreadyPending: Bool = queue.sync {
-      if self.pendingDownloads.contains(dedupeKey) { return true }
+    // Re-read `isEnabled` in the same hop that claims the dedup slot. The read
+    // above is separated from here by two more hops, and `tearDown` takes this
+    // same queue to invalidate the session — asking an invalidated session for
+    // a task raises an Objective-C exception Swift cannot catch. Admission and
+    // the enabled check have to be one decision, not two.
+    let admitted: Bool = queue.sync {
+      guard self.isEnabled, !self.pendingDownloads.contains(dedupeKey) else {
+        return false
+      }
       self.pendingDownloads.insert(dedupeKey)
-      return false
+      // Entered under the same decision, so `tearDown` sees this download as
+      // in flight from the moment it is admitted.
+      self.inFlightDownloads.enter()
+      return true
     }
-    if alreadyPending { return }
+    guard admitted else { return }
     defer {
+      inFlightDownloads.leave()
       queue.async { _ = self.pendingDownloads.remove(dedupeKey) }
     }
 
+    // Teardown cancels the prefetcher before invalidating the session, and
+    // cancellation is cooperative — this is the checkpoint that honours it, so
+    // a task admitted a moment before teardown does not reach the session.
+    try Task.checkCancellation()
+
     let (tempLocation, sizeBytes, contentType) = try await performDownload(
-      url: url, headers: headers
+      url: url, headers: headers, allowsCellularAccess: cellularAllowed
     )
     try Task.checkCancellation()
 
@@ -431,16 +519,35 @@ public final class LookaheadCache: @unchecked Sendable {
     )
   }
 
-  /// Run the URLSession download + HTTP-status validation. Returns
-  /// the temp location URLSession wrote to + the measured size in
-  /// bytes (so the commit step doesn't re-stat the file). Throws
-  /// `LookaheadCacheError.httpError` for non-2xx responses (and
-  /// cleans up the temp file before throwing).
+  /// Remove a rejected download's temp file. Cleanup failures are logged
+  /// rather than thrown — the caller is already failing the download, and a
+  /// leaked temp file should be diagnosable without masking that reason.
+  private func discardTemp(at location: URL, reason: String) {
+    do {
+      try FileManager.default.removeItem(at: location)
+    } catch {
+      NSLog(
+        "[LookaheadCache] temp-file cleanup failed (%@) at %@: %@",
+        reason, location.path, String(describing: error)
+      )
+    }
+  }
+
+  /// Run the URLSession download and HTTP-status validation. Returns the temp
+  /// location URLSession wrote to plus the measured size in bytes, so the
+  /// commit step does not re-stat the file. Throws
+  /// `LookaheadCacheError.httpError` for non-2xx responses, cleaning up the
+  /// temp file before throwing.
   private func performDownload(
-    url: URL, headers: [String: String]?
+    url: URL, headers: [String: String]?, allowsCellularAccess: Bool
   ) async throws -> (tempLocation: URL, sizeBytes: UInt64, contentType: String?) {
     var request = URLRequest(url: url)
     headers?.forEach { request.addValue($1, forHTTPHeaderField: $0) }
+    // Prefetch downloads whole upcoming tracks, so on a metered connection it
+    // can spend a lot of data on tracks the listener skips past. `false` here
+    // is an unconditional refusal — the request fails with
+    // `NSURLErrorDataNotAllowed` rather than falling back to cellular.
+    request.allowsCellularAccess = allowsCellularAccess
 
     let (tempLocation, response) = try await urlSession.download(for: request)
 
@@ -462,8 +569,35 @@ public final class LookaheadCache: @unchecked Sendable {
       )
     }
 
-    let attrs = try? FileManager.default.attributesOfItem(atPath: tempLocation.path)
-    let sizeBytes: UInt64 = (attrs?[.size] as? NSNumber)?.uint64Value ?? 0
+    // A 206 to a request that carried no `Range` is a partial body nobody
+    // asked for — short by construction.
+    if httpResponse.statusCode == 206,
+       request.value(forHTTPHeaderField: "Range") == nil {
+      discardTemp(at: tempLocation, reason: "unexpected 206")
+      throw LookaheadCacheError.unexpectedPartialContent
+    }
+
+    // Read the size explicitly rather than defaulting a failure to zero: a
+    // `?? 0` turns an unreadable attribute on a perfectly good download into
+    // a rejection once the size is checked below.
+    guard let attrs = try? FileManager.default.attributesOfItem(atPath: tempLocation.path),
+          let sizeNumber = attrs[.size] as? NSNumber else {
+      discardTemp(at: tempLocation, reason: "size unreadable")
+      throw LookaheadCacheError.sizeUnreadable
+    }
+    let sizeBytes = sizeNumber.uint64Value
+
+    // Reject only when the body is SHORTER than declared. Stated this way the
+    // check is immune to Content-Encoding: a decoded body longer than the
+    // declared compressed length is not a truncation. `expectedContentLength`
+    // is -1 when the server chunked the response, which carries no length to
+    // compare against.
+    let expected = httpResponse.expectedContentLength
+    if expected > 0, sizeBytes < UInt64(expected) {
+      discardTemp(at: tempLocation, reason: "short body")
+      throw LookaheadCacheError.truncatedBody(expected: expected, received: sizeBytes)
+    }
+
     let contentType = httpResponse.value(forHTTPHeaderField: "Content-Type")
     return (tempLocation, sizeBytes, contentType)
   }
@@ -546,7 +680,7 @@ public final class LookaheadCache: @unchecked Sendable {
       entries: self.index.entries,
       maxBytes: self.maxBytes,
       useFifoOrder: self.evictionPolicy == .fifo,
-      protectedUrls: protectedUrls
+      protectedUrls: protectedUrls.union(self.liveProtectedUrls)
     )
     if evicted.isEmpty { return [] }
     let evictedIds = Set(evicted.map { $0.trackId })
@@ -682,7 +816,7 @@ public final class LookaheadCache: @unchecked Sendable {
   /// Map an HTTP `Content-Type` value to a file-extension hint that
   /// AVFoundation recognises. Returns `nil` for unknown / missing
   /// types so the caller can fall through to URL-derived hints.
-  /// `application/octet-stream` (default for some Subsonic configs)
+  /// `application/octet-stream` (the default on some media servers)
   /// is treated as unknown — caller falls back to URL hints.
   @_spi(QueuePlayerTests)
   public static func extensionFromMimeType(_ contentType: String?) -> String? {
@@ -807,6 +941,16 @@ public enum LookaheadCacheError: Error {
   /// `cachedURL` lookups return nil and the cache-status snapshot
   /// lies. See `download(track:headers:)` for the throw site.
   case moveFailed(underlying: Error)
+  /// Body was shorter than the response declared. Committing it would put a
+  /// truncated file behind a "fully cached" entry, and the item built from
+  /// it fails to decode on every play and every retry.
+  case truncatedBody(expected: Int64, received: UInt64)
+  /// Server answered a partial body to a request that asked for the whole
+  /// file, so the download is short by construction.
+  case unexpectedPartialContent
+  /// The downloaded file's size could not be read, so the truncation check
+  /// cannot run; the file is discarded rather than committed unchecked.
+  case sizeUnreadable
 }
 
 /// Abstraction over `LookaheadCache.download` so the prefetcher

package/ios/LookaheadCachePrefetcher.swift

@@ -55,21 +55,25 @@ public final class LookaheadCachePrefetcher {
 
   /// Headers + UA snapshot used for prefetch downloads. Read on
   /// every download call so a runtime-config update can swap
-  /// the snapshot atomically. Swift's `var` is property-observer
-  /// safe because writes happen only on main (TrackPlayer.configure
-  /// hops to main first).
+  /// the snapshot atomically. Written from `configure`, which runs on the
+  /// same queue this prefetcher is confined to.
   internal var configHeaders: [String: String]?
   internal var configUserAgent: String?
 
-  /// Source URL of the in-flight download, or `nil` when no
-  /// download is mid-flight. Used by the orchestrator to decide
-  /// whether to cancel + by `reschedule` to know which URL is
-  /// already covered. Updated on main inside the orchestrator
-  /// loop body.
+  /// The queue every access to this prefetcher's state runs on. Nothing here
+  /// touches UI — the work is URLSession downloads and file IO through a cache
+  /// that serialises itself — so it is confined to whichever queue owns player
+  /// state rather than to main. That keeps it on the same queue as the callers
+  /// which cancel and tear it down, whose ordering against the cache's
+  /// URLSession invalidation has to hold.
+  private let queue: DispatchQueue
+
+  /// Source URL of the in-flight download, or `nil` when nothing is
+  /// mid-flight. The orchestrator reads it to decide whether to cancel, and
+  /// `reschedule` to know which URL is already covered.
   ///
-  /// **Threading contract:** all reads + writes happen on main.
-  /// Documented-only; `@MainActor` would cascade through the call
-  /// chain.
+  /// Guarded by `queue`, not by an isolation annotation: a `@MainActor` or
+  /// actor declaration here would cascade through every caller.
   private var inFlightUrl: String?
 
   /// The Task running the in-flight download. Held so a `reschedule`
@@ -139,10 +143,12 @@ public final class LookaheadCachePrefetcher {
   ///     each download.
   public init(
     cache: LookaheadCache,
+    confinedTo queue: DispatchQueue,
     configHeaders: [String: String]? = nil,
     configUserAgent: String? = nil
   ) {
     self.cache = cache
+    self.queue = queue
     self.configHeaders = configHeaders
     self.configUserAgent = configUserAgent
   }
@@ -154,10 +160,12 @@ public final class LookaheadCachePrefetcher {
   @_spi(QueuePlayerTests)
   public init(
     downloader: LookaheadCacheDownloader,
+    confinedTo queue: DispatchQueue,
     configHeaders: [String: String]? = nil,
     configUserAgent: String? = nil
   ) {
     self.cache = downloader
+    self.queue = queue
     self.configHeaders = configHeaders
     self.configUserAgent = configUserAgent
   }
@@ -177,7 +185,7 @@ public final class LookaheadCachePrefetcher {
   ///   2. `cache.tearDown()` — URLSession invalidated; any bytes
   ///      still on the wire abort.
   public func cancel() {
-    dispatchPrecondition(condition: .onQueue(.main))
+    dispatchPrecondition(condition: .onQueue(queue))
     pendingTargets.removeAll()
     inFlightTask?.cancel()
     inFlightTask = nil
@@ -195,7 +203,7 @@ public final class LookaheadCachePrefetcher {
   /// `LookaheadCache.tearDown` so the prefetch loop can observe
   /// cancellation cleanly before its underlying URLSession goes away.
   public func tearDown() {
-    dispatchPrecondition(condition: .onQueue(.main))
+    dispatchPrecondition(condition: .onQueue(queue))
     cancel()
   }
 
@@ -215,7 +223,7 @@ public final class LookaheadCachePrefetcher {
     currentIndex: Int,
     lookaheadCount: Int? = nil
   ) {
-    dispatchPrecondition(condition: .onQueue(.main))
+    dispatchPrecondition(condition: .onQueue(queue))
     let count = lookaheadCount ?? defaultLookaheadCount
     var desired = computeTargets(
       tracks: tracks, currentIndex: currentIndex, lookaheadCount: count
@@ -307,13 +315,6 @@ public final class LookaheadCachePrefetcher {
     return orchestrator != nil || inFlightTask != nil
   }
 
-  /// Test introspection — count of URLs queued behind the in-flight
-  /// download.
-  @_spi(QueuePlayerTests)
-  public var pendingCount: Int {
-    return pendingTargets.count
-  }
-
   /// Test introspection — await the orchestrator so test
   /// assertions can fire after the prefetch chain drains.
   @_spi(QueuePlayerTests)
@@ -323,6 +324,15 @@ public final class LookaheadCachePrefetcher {
 
   // MARK: - Orchestrator
 
+  /// Run `body` on the confinement queue and await its result. The orchestrator
+  /// itself runs on the cooperative pool, so every touch of this object's state
+  /// comes back through here. Bodies keep their own `[weak self]` capture.
+  private func onQueue<T>(_ body: @escaping () -> T) async -> T {
+    await withCheckedContinuation { (cont: CheckedContinuation<T, Never>) in
+      queue.async { cont.resume(returning: body()) }
+    }
+  }
+
   /// Launch a fresh orchestrator if none is running. Capturing
   /// `self` weakly keeps the prefetcher releaseable mid-loop —
   /// tearDown nils the orchestrator reference and the loop body
@@ -336,7 +346,7 @@ public final class LookaheadCachePrefetcher {
     isOrchestratorRunning = true
     orchestrator = Task { [weak self] in
       await self?.runOrchestrator()
-      await MainActor.run { [weak self] in
+      await self?.onQueue { [weak self] in
         guard let self else { return }
         // Identity check: only clear ownership if this trailing hook
         // belongs to the still-current orchestrator. If a `cancel()`
@@ -362,11 +372,11 @@ public final class LookaheadCachePrefetcher {
   }
 
   /// Drain `pendingTargets` one URL at a time. Pops the next track
-  /// on main, downloads it on the cooperative pool, then loops.
+  /// on its owner queue, downloads it on the cooperative pool, then loops.
   /// Exits when `pendingTargets` is empty or the Task is cancelled.
   private func runOrchestrator() async {
     while !Task.isCancelled {
-      let next: TrackItem? = await MainActor.run { [weak self] () -> TrackItem? in
+      let next: TrackItem? = await onQueue { [weak self] () -> TrackItem? in
         guard let self = self else { return nil }
         if self.pendingTargets.isEmpty { return nil }
         return self.pendingTargets.removeFirst()
@@ -378,11 +388,11 @@ public final class LookaheadCachePrefetcher {
       // `reschedule` enqueued the URL just before a download via a
       // different path completed.
       if cache.isFullyCached(url: track.url) {
-        await MainActor.run { [weak self] in self?.onTrackProcessed?() }
+        await onQueue { [weak self] in self?.onTrackProcessed?() }
         continue
       }
 
-      let headers = await MainActor.run { [weak self] () -> [String: String] in
+      let headers = await onQueue { [weak self] () -> [String: String] in
         guard let self = self else { return [:] }
         return Self.merge(
           headers: self.configHeaders, userAgent: self.configUserAgent
@@ -392,7 +402,7 @@ public final class LookaheadCachePrefetcher {
       // Build the Task suspended via an explicit start barrier so
       // `inFlightUrl` / `inFlightTask` publish before the download
       // body executes. Without the barrier the eager-start Task can
-      // race the MainActor.run setter — observers polling the
+      // race the queue-hop setter — observers polling the
       // currently-downloading URL after the gated downloader fires
       // its onStart can otherwise see a stale `nil`.
       let startBarrier = AsyncBarrier()
@@ -400,7 +410,7 @@ public final class LookaheadCachePrefetcher {
         await startBarrier.wait()
         try await cache.download(track: track, headers: headers)
       }
-      await MainActor.run { [weak self] in
+      await onQueue { [weak self] in
         self?.inFlightUrl = track.url
         self?.inFlightTask = downloadTask
       }
@@ -415,7 +425,7 @@ public final class LookaheadCachePrefetcher {
         logSwallowed(track: track, error: error)
       }
 
-      await MainActor.run { [weak self] in
+      await onQueue { [weak self] in
         self?.inFlightUrl = nil
         self?.inFlightTask = nil
         self?.onTrackProcessed?()
@@ -434,14 +444,16 @@ public final class LookaheadCachePrefetcher {
   private static func merge(
     headers: [String: String]?, userAgent: String?
   ) -> [String: String] {
-    var merged = headers ?? [:]
-    if let ua = userAgent, !ua.isEmpty {
-      merged["User-Agent"] = ua
-    }
-    return merged
+    AVQueueBuilder.mergedHeaders(headers: headers, userAgent: userAgent)
   }
 
   private func logSwallowed(track: TrackItem, error: Error) {
+    // A consumer who turned `allowsCellularAccess` off gets this on every
+    // reschedule made while the device is on cellular. It is the policy
+    // working, not a fault, so it does not go to the log.
+    let nsError = error as NSError
+    if nsError.domain == NSURLErrorDomain,
+       nsError.code == NSURLErrorDataNotAllowed { return }
     // Log by source URL (the trustworthy field). `track.id` is
     // optional consumer data — a missing or empty value would
     // produce an unhelpful log line.
@@ -460,7 +472,7 @@ public final class LookaheadCachePrefetcher {
 }
 
 /// Internal one-shot barrier used by the orchestrator so the
-/// in-flight URL publishes on main BEFORE the download body
+/// in-flight URL publishes on the owner queue BEFORE the download body
 /// executes. `release()` is idempotent + non-blocking; `wait()`
 /// suspends until the first `release()` and resumes immediately
 /// for any subsequent `wait()` (no producer needed).
@@ -469,7 +481,7 @@ public final class LookaheadCachePrefetcher {
 /// the download Deferred to achieve the same publish-before-body
 /// semantics. Swift Tasks have no equivalent lazy-start option, so
 /// the orchestrator constructs the Task suspended on this barrier,
-/// publishes `inFlightUrl` / `inFlightTask` on main, then releases.
+/// publishes `inFlightUrl` / `inFlightTask` on the owner queue, then releases.
 private final class AsyncBarrier: @unchecked Sendable {
   private let lock = NSLock()
   private var continuation: CheckedContinuation<Void, Never>?