react-native-queue-player 1.1.2 → 2.0.0

package/ios/Tests/AVQueueBuilderTests.swift

@@ -137,176 +137,129 @@ final class AVQueueBuilderTests: XCTestCase {
     XCTAssertEqual(item?.preferredForwardBufferDuration, 0.0)
   }
 
-  // MARK: - Cache integration
+  // MARK: - Read-through routing
 
-  func testMakeItemPrefersCachedURLWhenFullyCached() async throws {
-    // Build a LookaheadCache, drive a download through a URLProtocol-
-    // stubbed URLSession so the entry is fully cached, then call
-    // makeItem(for:config:cache:) and assert the AVPlayerItem is
-    // backed by the local file URL (not the remote one).
-    let tempDir = FileManager.default.temporaryDirectory
-      .appendingPathComponent("AVQueueBuilderTests-cache-\(UUID().uuidString)", isDirectory: true)
-    defer { try? FileManager.default.removeItem(at: tempDir) }
-
-    StubURLProtocol.reset()
-    defer { StubURLProtocol.reset() }
-    let sessionConfig = URLSessionConfiguration.ephemeral
-    sessionConfig.protocolClasses = [StubURLProtocol.self] + (sessionConfig.protocolClasses ?? [])
-    let session = URLSession(configuration: sessionConfig)
-    defer { session.invalidateAndCancel() }
+  private func routableConfig() -> PlayerConfig {
+    PlayerConfig(httpHeaders: nil, userAgent: nil, placeholderArtworkUri: nil, autoRetries: nil, retryBackoffMs: nil, networkTimeoutMs: nil, audioContentType: nil, audioCategoryOptions: nil, voiceVocabularyDonationEnabled: nil, visualizationEnabled: nil, clampSeekToBuffered: nil, skipToPreviousBehavior: nil, lookaheadCacheMaxSizeMb: nil, lookaheadCacheEvictionPolicy: nil, progressUpdateIntervalMs: nil, backgroundProgressUpdateIntervalMs: nil)
+  }
 
-    let cache = LookaheadCache(
-      directory: tempDir, maxSizeBytes: 1024 * 1024, urlSession: session
-    )
-    defer { cache.tearDown() }
+  private func startedServer() async -> ReadThroughServer {
+    let server = ReadThroughServer(cachedFileForOrigin: { _ in nil }, onFirstDiskHit: { _ in })
+    server.start()
+    XCTAssertTrue(server.waitUntilBound(), "the loopback listener binds within the wait")
+    return server
+  }
 
-    let remoteURL = URL(string: "https://example.com/cached.m4a")!
-    StubURLProtocol.stub(url: remoteURL, data: Data("payload".utf8), statusCode: 200)
+  /// The routing decision is stamped on the item at build time, which is what
+  /// source classification reads: a routed item carries the stamp and an
+  /// item built with no server does not.
+  func testTheItemCarriesWhetherItWasRouted() async throws {
+    let server = await startedServer()
+    defer { server.stop() }
+    let track = makeTrack(id: "remote-stamp", url: "https://example.com/stamp.mp3")
+
+    let routed = try XCTUnwrap(
+      AVQueueBuilder.makeItem(for: track, queueItemId: "q1", config: routableConfig(), server: server))
+    let direct = try XCTUnwrap(
+      AVQueueBuilder.makeItem(for: track, queueItemId: "q2", config: routableConfig(), server: nil))
+
+    XCTAssertTrue(routed.isRoutedThroughReadThroughServer)
+    XCTAssertFalse(direct.isRoutedThroughReadThroughServer)
+  }
 
-    let track = makeTrack(id: "cached-1", url: remoteURL.absoluteString)
-    try await cache.download(track: track, headers: nil)
+  /// A remote track binds the local server, not the origin — whether or not
+  /// the cache holds it yet. That is the point: the URL is chosen once and the
+  /// cache question is answered per request, later, when it can be answered.
+  func testARemoteTrackBindsTheReadThroughServer() async throws {
+    let server = await startedServer()
+    defer { server.stop() }
+    let track = makeTrack(id: "remote-1", url: "https://example.com/track.mp3")
 
     let item = AVQueueBuilder.makeItem(
-      for: track,
-      queueItemId: UUID().uuidString,
-      config: PlayerConfig(httpHeaders: nil, userAgent: nil, placeholderArtworkUri: nil, autoRetries: nil, retryBackoffMs: nil, networkTimeoutMs: nil, audioContentType: nil, audioCategoryOptions: nil, visualizationEnabled: nil, clampSeekToBuffered: nil, skipToPreviousBehavior: nil, lookaheadCacheMaxSizeMb: nil, lookaheadCacheEvictionPolicy: nil, progressUpdateIntervalMs: nil, backgroundProgressUpdateIntervalMs: nil),
-      cache: cache
-    )
-    XCTAssertNotNil(item)
-    let urlAsset = try XCTUnwrap(item?.asset as? AVURLAsset)
-    XCTAssertTrue(urlAsset.url.isFileURL,
-      "fully-cached track must resolve to a local file URL, got \(urlAsset.url)")
-    XCTAssertEqual(
-      urlAsset.url.deletingLastPathComponent().path,
-      cache.cacheDirectory.path,
-      "local file URL must point inside the cache directory"
-    )
-  }
+      for: track, queueItemId: UUID().uuidString, config: routableConfig(), server: server)
 
-  func testMakeItemFallsBackToRemoteWhenCacheMisses() {
-    // No cache provided → behaves identically to the no-cache path.
-    let track = makeTrack(id: "t1", url: "https://example.com/track.m4a")
-    let config = PlayerConfig(httpHeaders: nil, userAgent: nil, placeholderArtworkUri: nil, autoRetries: nil, retryBackoffMs: nil, networkTimeoutMs: nil, audioContentType: nil, audioCategoryOptions: nil, visualizationEnabled: nil, clampSeekToBuffered: nil, skipToPreviousBehavior: nil, lookaheadCacheMaxSizeMb: nil, lookaheadCacheEvictionPolicy: nil, progressUpdateIntervalMs: nil, backgroundProgressUpdateIntervalMs: nil)
-    let item = AVQueueBuilder.makeItem(
-      for: track, queueItemId: UUID().uuidString, config: config, cache: nil)
-    XCTAssertNotNil(item)
-    if let urlAsset = item?.asset as? AVURLAsset {
-      XCTAssertEqual(urlAsset.url.absoluteString, "https://example.com/track.m4a",
-        "no cache → remote URL")
-    } else {
-      XCTFail("expected AVURLAsset")
-    }
+    let asset = try XCTUnwrap(item?.asset as? AVURLAsset)
+    XCTAssertEqual(asset.url.host, "127.0.0.1", "a remote track must read through the server")
   }
 
-  func testMakeItemFallsBackToRemoteWhenTrackNotInCache() throws {
-    let tempDir = FileManager.default.temporaryDirectory
-      .appendingPathComponent("AVQueueBuilderTests-miss-\(UUID().uuidString)", isDirectory: true)
-    defer { try? FileManager.default.removeItem(at: tempDir) }
+  /// The media's own URL survives on the item. Everything that reads a
+  /// container, a codec or a track identity out of a URL reads this one — the
+  /// asset URL now names the transport.
+  func testTheSourceURLRemainsTheOriginAfterRouting() async throws {
+    let server = await startedServer()
+    defer { server.stop() }
+    let track = makeTrack(id: "remote-2", url: "https://example.com/track.flac")
 
-    let cache = LookaheadCache(
-      directory: tempDir,
-      maxSizeBytes: 1024 * 1024,
-      urlSession: URLSession(configuration: .ephemeral)
-    )
-    defer { cache.tearDown() }
-
-    let track = makeTrack(id: "uncached", url: "https://example.com/uncached.m4a")
     let item = AVQueueBuilder.makeItem(
-      for: track,
-      queueItemId: UUID().uuidString,
-      config: PlayerConfig(httpHeaders: nil, userAgent: nil, placeholderArtworkUri: nil, autoRetries: nil, retryBackoffMs: nil, networkTimeoutMs: nil, audioContentType: nil, audioCategoryOptions: nil, visualizationEnabled: nil, clampSeekToBuffered: nil, skipToPreviousBehavior: nil, lookaheadCacheMaxSizeMb: nil, lookaheadCacheEvictionPolicy: nil, progressUpdateIntervalMs: nil, backgroundProgressUpdateIntervalMs: nil),
-      cache: cache
-    )
-    XCTAssertNotNil(item)
-    if let urlAsset = item?.asset as? AVURLAsset {
-      XCTAssertEqual(urlAsset.url.absoluteString, "https://example.com/uncached.m4a",
-        "cache miss → remote URL")
-    } else {
-      XCTFail("expected AVURLAsset")
-    }
-  }
+      for: track, queueItemId: UUID().uuidString, config: routableConfig(), server: server)
 
-  // MARK: - Cache integration edge cases
+    XCTAssertEqual(item?.sourceURL, "https://example.com/track.flac")
+  }
 
-  func testMakeItemFallsBackToRemoteWhenCachedFileDeletedExternally() async throws {
-    // An external `rm` of the cache file falls through to the remote
-    // URL via `cachedURL`'s defensive stale-entry-prune branch.
-    let tempDir = FileManager.default.temporaryDirectory
-      .appendingPathComponent("AVQueueBuilderTests-stale-\(UUID().uuidString)", isDirectory: true)
-    defer { try? FileManager.default.removeItem(at: tempDir) }
+  /// One URL per track for the session, so a window rebuild does not re-point
+  /// an asset the player is already reading.
+  func testRebuildingTheSameTrackBindsTheSameURL() async throws {
+    let server = await startedServer()
+    defer { server.stop() }
+    let track = makeTrack(id: "remote-3", url: "https://example.com/stable.mp3")
+    let config = routableConfig()
+
+    let first = AVQueueBuilder.makeItem(
+      for: track, queueItemId: UUID().uuidString, config: config, server: server)
+    let second = AVQueueBuilder.makeItem(
+      for: track, queueItemId: UUID().uuidString, config: config, server: server)
+
+    let a = try XCTUnwrap(first?.asset as? AVURLAsset).url
+    let b = try XCTUnwrap(second?.asset as? AVURLAsset).url
+    XCTAssertEqual(a, b)
+  }
 
-    StubURLProtocol.reset()
-    defer { StubURLProtocol.reset() }
-    let sessionConfig = URLSessionConfiguration.ephemeral
-    sessionConfig.protocolClasses = [StubURLProtocol.self] + (sessionConfig.protocolClasses ?? [])
-    let session = URLSession(configuration: sessionConfig)
-    defer { session.invalidateAndCancel() }
+  func testAFileTrackIsNeverRouted() async throws {
+    let server = await startedServer()
+    defer { server.stop() }
+    let track = makeTrack(id: "local-1", url: "file:///tmp/song.mp3")
 
-    let cache = LookaheadCache(
-      directory: tempDir, maxSizeBytes: 1024 * 1024, urlSession: session
-    )
-    defer { cache.tearDown() }
+    let item = AVQueueBuilder.makeItem(
+      for: track, queueItemId: UUID().uuidString, config: routableConfig(), server: server)
 
-    let remoteURL = URL(string: "https://example.com/stale.m4a")!
-    StubURLProtocol.stub(url: remoteURL, data: Data("payload".utf8), statusCode: 200)
-    let track = makeTrack(id: "stale-1", url: remoteURL.absoluteString)
-    try await cache.download(track: track, headers: nil)
+    let asset = try XCTUnwrap(item?.asset as? AVURLAsset)
+    XCTAssertTrue(asset.url.isFileURL, "a local file has nothing to read through")
+  }
 
-    // External actor (consumer rm, OS reclaim, …) deletes the file
-    // out from under the cache index.
-    let fileURL = cache.cachedURL(forUrl: track.url)!
-    try FileManager.default.removeItem(at: fileURL)
+  /// AVFoundation resolves a playlist's relative segment paths against the URL
+  /// it fetched the playlist from, so a proxied playlist would point every
+  /// segment at a token that names none of them.
+  func testAnHLSPlaylistIsNeverRouted() async throws {
+    let server = await startedServer()
+    defer { server.stop() }
+    let track = makeTrack(id: "hls-1", url: "https://example.com/stream.m3u8")
 
     let item = AVQueueBuilder.makeItem(
-      for: track,
-      queueItemId: UUID().uuidString,
-      config: PlayerConfig(httpHeaders: nil, userAgent: nil, placeholderArtworkUri: nil, autoRetries: nil, retryBackoffMs: nil, networkTimeoutMs: nil, audioContentType: nil, audioCategoryOptions: nil, visualizationEnabled: nil, clampSeekToBuffered: nil, skipToPreviousBehavior: nil, lookaheadCacheMaxSizeMb: nil, lookaheadCacheEvictionPolicy: nil, progressUpdateIntervalMs: nil, backgroundProgressUpdateIntervalMs: nil),
-      cache: cache
-    )
-    XCTAssertNotNil(item)
-    let urlAsset = try XCTUnwrap(item?.asset as? AVURLAsset)
-    XCTAssertEqual(urlAsset.url.absoluteString, remoteURL.absoluteString,
-      "deleted-file path must fall back to remote URL via cachedURL's stale-entry prune")
+      for: track, queueItemId: UUID().uuidString, config: routableConfig(), server: server)
+
+    let asset = try XCTUnwrap(item?.asset as? AVURLAsset)
+    XCTAssertEqual(asset.url.absoluteString, "https://example.com/stream.m3u8")
   }
 
-  func testBuildPlayerItemsMixesCachedAndUncachedTracks() async throws {
-    let tempDir = FileManager.default.temporaryDirectory
-      .appendingPathComponent("AVQueueBuilderTests-mixed-\(UUID().uuidString)", isDirectory: true)
-    defer { try? FileManager.default.removeItem(at: tempDir) }
+  /// A consumer running without the lookahead cache has no server, and gets
+  /// exactly today's behaviour rather than a local hop that could never hit.
+  func testWithNoServerTheOriginIsBoundDirectly() throws {
+    let track = makeTrack(id: "remote-4", url: "https://example.com/direct.mp3")
 
-    StubURLProtocol.reset()
-    defer { StubURLProtocol.reset() }
-    let sessionConfig = URLSessionConfiguration.ephemeral
-    sessionConfig.protocolClasses = [StubURLProtocol.self] + (sessionConfig.protocolClasses ?? [])
-    let session = URLSession(configuration: sessionConfig)
-    defer { session.invalidateAndCancel() }
+    let item = AVQueueBuilder.makeItem(
+      for: track, queueItemId: UUID().uuidString, config: routableConfig(), server: nil)
 
-    let cache = LookaheadCache(
-      directory: tempDir, maxSizeBytes: 1024 * 1024, urlSession: session
-    )
-    defer { cache.tearDown() }
+    let asset = try XCTUnwrap(item?.asset as? AVURLAsset)
+    XCTAssertEqual(asset.url.absoluteString, "https://example.com/direct.mp3")
+  }
 
-    // Download A only; B stays uncached.
-    let urlA = URL(string: "https://example.com/a.m4a")!
-    StubURLProtocol.stub(url: urlA, data: Data("a".utf8), statusCode: 200)
-    let trackA = makeTrack(id: "a", url: urlA.absoluteString)
-    let trackB = makeTrack(id: "b", url: "https://example.com/b.m4a")
-    try await cache.download(track: trackA, headers: nil)
-
-    let items = AVQueueBuilder.buildPlayerItems(
-      tracks: [trackA, trackB],
-      queueItemIds: [UUID().uuidString, UUID().uuidString],
-      config: PlayerConfig(httpHeaders: nil, userAgent: nil, placeholderArtworkUri: nil, autoRetries: nil, retryBackoffMs: nil, networkTimeoutMs: nil, audioContentType: nil, audioCategoryOptions: nil, visualizationEnabled: nil, clampSeekToBuffered: nil, skipToPreviousBehavior: nil, lookaheadCacheMaxSizeMb: nil, lookaheadCacheEvictionPolicy: nil, progressUpdateIntervalMs: nil, backgroundProgressUpdateIntervalMs: nil),
-      cache: cache
-    )
-    XCTAssertEqual(items.count, 2)
-    let assetA = try XCTUnwrap(items[0].asset as? AVURLAsset)
-    let assetB = try XCTUnwrap(items[1].asset as? AVURLAsset)
-    XCTAssertTrue(assetA.url.isFileURL,
-      "A is cached → file URL")
-    XCTAssertFalse(assetB.url.isFileURL,
-      "B is uncached → remote URL")
-    XCTAssertEqual(assetB.url.absoluteString, "https://example.com/b.m4a")
+  func testRoutabilityIsSchemeAndManifestAware() {
+    XCTAssertTrue(AVQueueBuilder.isRoutable("https://example.com/a.mp3"))
+    XCTAssertTrue(AVQueueBuilder.isRoutable("http://example.com/a.mp3"))
+    XCTAssertTrue(AVQueueBuilder.isRoutable("https://example.com/no-extension"))
+    XCTAssertFalse(AVQueueBuilder.isRoutable("file:///tmp/a.mp3"))
+    XCTAssertFalse(AVQueueBuilder.isRoutable("https://example.com/stream.m3u8"))
+    XCTAssertFalse(AVQueueBuilder.isRoutable("HTTPS://example.com/stream.M3U8"))
   }
 
   func testSetMaxSizeBytesShrinkProtectsCurrentlyPlayingTrack() async throws {
@@ -371,13 +324,13 @@ final class AVQueueBuilderTests: XCTestCase {
     let queueItemIdB = UUID().uuidString
     let itemA = AVQueueBuilder.makeItem(
       for: track, queueItemId: queueItemIdA,
-      config: PlayerConfig(httpHeaders: nil, userAgent: nil, placeholderArtworkUri: nil, autoRetries: nil, retryBackoffMs: nil, networkTimeoutMs: nil, audioContentType: nil, audioCategoryOptions: nil, visualizationEnabled: nil, clampSeekToBuffered: nil, skipToPreviousBehavior: nil, lookaheadCacheMaxSizeMb: nil, lookaheadCacheEvictionPolicy: nil, progressUpdateIntervalMs: nil, backgroundProgressUpdateIntervalMs: nil),
-      cache: nil
+      config: PlayerConfig(httpHeaders: nil, userAgent: nil, placeholderArtworkUri: nil, autoRetries: nil, retryBackoffMs: nil, networkTimeoutMs: nil, audioContentType: nil, audioCategoryOptions: nil, voiceVocabularyDonationEnabled: nil, visualizationEnabled: nil, clampSeekToBuffered: nil, skipToPreviousBehavior: nil, lookaheadCacheMaxSizeMb: nil, lookaheadCacheEvictionPolicy: nil, progressUpdateIntervalMs: nil, backgroundProgressUpdateIntervalMs: nil),
+      server: nil
     )
     let itemB = AVQueueBuilder.makeItem(
       for: track, queueItemId: queueItemIdB,
-      config: PlayerConfig(httpHeaders: nil, userAgent: nil, placeholderArtworkUri: nil, autoRetries: nil, retryBackoffMs: nil, networkTimeoutMs: nil, audioContentType: nil, audioCategoryOptions: nil, visualizationEnabled: nil, clampSeekToBuffered: nil, skipToPreviousBehavior: nil, lookaheadCacheMaxSizeMb: nil, lookaheadCacheEvictionPolicy: nil, progressUpdateIntervalMs: nil, backgroundProgressUpdateIntervalMs: nil),
-      cache: nil
+      config: PlayerConfig(httpHeaders: nil, userAgent: nil, placeholderArtworkUri: nil, autoRetries: nil, retryBackoffMs: nil, networkTimeoutMs: nil, audioContentType: nil, audioCategoryOptions: nil, voiceVocabularyDonationEnabled: nil, visualizationEnabled: nil, clampSeekToBuffered: nil, skipToPreviousBehavior: nil, lookaheadCacheMaxSizeMb: nil, lookaheadCacheEvictionPolicy: nil, progressUpdateIntervalMs: nil, backgroundProgressUpdateIntervalMs: nil),
+      server: nil
     )
     XCTAssertNotNil(itemA)
     XCTAssertNotNil(itemB)
@@ -396,13 +349,15 @@ final class AVQueueBuilderTests: XCTestCase {
     let track = TrackItem(
       id: nil, url: "https://example.com/nil-id.m4a",
       title: nil, artist: nil, album: nil,
-      duration: nil, artworkUrl: nil, extras: nil
+      duration: nil, artworkUrl: nil, extras: nil,
+      replayGainTrackGain: nil, replayGainTrackPeak: nil,
+      replayGainAlbumGain: nil, replayGainAlbumPeak: nil
     )
     let queueItemId = UUID().uuidString
     let item = AVQueueBuilder.makeItem(
       for: track, queueItemId: queueItemId,
-      config: PlayerConfig(httpHeaders: nil, userAgent: nil, placeholderArtworkUri: nil, autoRetries: nil, retryBackoffMs: nil, networkTimeoutMs: nil, audioContentType: nil, audioCategoryOptions: nil, visualizationEnabled: nil, clampSeekToBuffered: nil, skipToPreviousBehavior: nil, lookaheadCacheMaxSizeMb: nil, lookaheadCacheEvictionPolicy: nil, progressUpdateIntervalMs: nil, backgroundProgressUpdateIntervalMs: nil),
-      cache: nil
+      config: PlayerConfig(httpHeaders: nil, userAgent: nil, placeholderArtworkUri: nil, autoRetries: nil, retryBackoffMs: nil, networkTimeoutMs: nil, audioContentType: nil, audioCategoryOptions: nil, voiceVocabularyDonationEnabled: nil, visualizationEnabled: nil, clampSeekToBuffered: nil, skipToPreviousBehavior: nil, lookaheadCacheMaxSizeMb: nil, lookaheadCacheEvictionPolicy: nil, progressUpdateIntervalMs: nil, backgroundProgressUpdateIntervalMs: nil),
+      server: nil
     )
     XCTAssertNotNil(item)
     XCTAssertEqual(item?.queueItemId, queueItemId,
@@ -417,88 +372,70 @@ final class AVQueueBuilderTests: XCTestCase {
     let queueItemId = UUID().uuidString
     let item = AVQueueBuilder.makeItem(
       for: track, queueItemId: queueItemId,
-      config: PlayerConfig(httpHeaders: nil, userAgent: nil, placeholderArtworkUri: nil, autoRetries: nil, retryBackoffMs: nil, networkTimeoutMs: nil, audioContentType: nil, audioCategoryOptions: nil, visualizationEnabled: nil, clampSeekToBuffered: nil, skipToPreviousBehavior: nil, lookaheadCacheMaxSizeMb: nil, lookaheadCacheEvictionPolicy: nil, progressUpdateIntervalMs: nil, backgroundProgressUpdateIntervalMs: nil),
-      cache: nil
+      config: PlayerConfig(httpHeaders: nil, userAgent: nil, placeholderArtworkUri: nil, autoRetries: nil, retryBackoffMs: nil, networkTimeoutMs: nil, audioContentType: nil, audioCategoryOptions: nil, voiceVocabularyDonationEnabled: nil, visualizationEnabled: nil, clampSeekToBuffered: nil, skipToPreviousBehavior: nil, lookaheadCacheMaxSizeMb: nil, lookaheadCacheEvictionPolicy: nil, progressUpdateIntervalMs: nil, backgroundProgressUpdateIntervalMs: nil),
+      server: nil
     )
     XCTAssertNotNil(item)
     XCTAssertEqual(item?.queueItemId, queueItemId,
       "queueItemId must be set even when track.id is empty string")
   }
 
-  // MARK: - preloadAssetForInsert
 
-  func testPreloadAssetForInsertLoadsTracksForLocalFile() async throws {
-    let url = try Self.writeTinyWav()
-    defer { try? FileManager.default.removeItem(at: url) }
-    let item = try XCTUnwrap(
-      AVQueueBuilder.makeItemRaw(urlString: url.absoluteString, headers: nil, userAgent: nil))
+  private func makeTrack(id: String, url: String) -> TrackItem {
+    return TrackItem(
+      id: id, url: url, title: nil, artist: nil, album: nil,
+      duration: nil, artworkUrl: nil, extras: nil,
+      replayGainTrackGain: nil, replayGainTrackPeak: nil,
+      replayGainAlbumGain: nil, replayGainAlbumPeak: nil
+    )
+  }
 
-    await AVQueueBuilder.preloadAssetForInsert(item)
 
-    // The load resolved the tracks key on the same asset instance the
-    // enqueue will insert, so the audio track is present without a second
-    // fault — the preroll after insert has nothing left to load.
-    let tracks = try await item.asset.load(.tracks)
-    XCTAssertFalse(tracks.isEmpty,
-      "preload must resolve the local asset's tracks so the enqueue preroll is cheap")
+  // MARK: - Cancelling loads on discarded items
+
+  /// A cancelled asset can never become playable, so cancellation may only
+  /// touch assets that no surviving item reuses.
+  func testEveryOutgoingItemIsDroppedWhenNothingSurvives() {
+    let outgoing = [makeItem("a"), makeItem("b")]
+    let dropped = AVQueueBuilder.itemsBeingDropped(outgoing: outgoing, keeping: [])
+    XCTAssertEqual(dropped.count, 2)
   }
 
-  func testPreloadAssetForInsertLeavesUnreadableAssetInsertable() async throws {
-    // Best-effort contract: a missing file's load fails but the item stays
-    // intact + insertable, so the enqueue proceeds unwarmed rather than
-    // being blocked or corrupted.
-    let missing = FileManager.default.temporaryDirectory
-      .appendingPathComponent("does-not-exist-\(UUID().uuidString).m4a")
-    let item = try XCTUnwrap(
-      AVQueueBuilder.makeItemRaw(urlString: missing.absoluteString, headers: nil, userAgent: nil))
-
-    let start = Date()
-    await AVQueueBuilder.preloadAssetForInsert(item, timeout: 0.5)
-    let elapsed = Date().timeIntervalSince(start)
-
-    XCTAssertLessThan(elapsed, 2.0,
-      "a best-effort preload of an unreadable asset must return promptly, not hang")
-    let urlAsset = try XCTUnwrap(item.asset as? AVURLAsset)
-    XCTAssertEqual(urlAsset.url, missing,
-      "a failed preload must leave the item's asset unchanged and insertable")
+  func testAnItemWhoseAssetIsReusedIsNotDropped() {
+    let shared = AVURLAsset(url: URL(string: "https://example.com/shared.m4a")!)
+    let outgoing = [AVPlayerItem(asset: shared), makeItem("other")]
+    let rebuiltOnTheSameAsset = AVPlayerItem(asset: shared)
+
+    let dropped = AVQueueBuilder.itemsBeingDropped(
+      outgoing: outgoing, keeping: [rebuiltOnTheSameAsset])
+
+    XCTAssertEqual(
+      dropped.count, 1,
+      "an asset a surviving item rebuilt on must keep its loads — cancelling it "
+        + "leaves that item permanently unplayable")
+    XCTAssertFalse(
+      dropped.contains { $0.asset === shared },
+      "the reused asset must not be handed to cancellation")
   }
 
-  private func makeTrack(id: String, url: String) -> TrackItem {
-    return TrackItem(
-      id: id, url: url, title: nil, artist: nil, album: nil,
-      duration: nil, artworkUrl: nil, extras: nil
-    )
+  func testKeepingIsComparedByAssetIdentityNotByItem() {
+    let shared = AVURLAsset(url: URL(string: "https://example.com/shared.m4a")!)
+    let outgoing = [AVPlayerItem(asset: shared)]
+    // A different item object wrapping the same asset still protects it.
+    let dropped = AVQueueBuilder.itemsBeingDropped(
+      outgoing: outgoing, keeping: [AVPlayerItem(asset: shared)])
+    XCTAssertTrue(dropped.isEmpty)
   }
 
-  /// Writes a minimal valid 16-bit PCM mono WAV (silent samples) so
-  /// AVFoundation resolves exactly one audio track from the file.
-  private static func writeTinyWav() throws -> URL {
-    let sampleRate: UInt32 = 44100
-    let channels: UInt16 = 1
-    let bitsPerSample: UInt16 = 16
-    let frameCount = 1024
-    let dataSize = UInt32(frameCount) * UInt32(channels) * UInt32(bitsPerSample / 8)
-    var data = Data()
-    func appendLE<T: FixedWidthInteger>(_ value: T) {
-      withUnsafeBytes(of: value.littleEndian) { data.append(contentsOf: $0) }
-    }
-    data.append(contentsOf: Array("RIFF".utf8))
-    appendLE(UInt32(36) + dataSize)
-    data.append(contentsOf: Array("WAVE".utf8))
-    data.append(contentsOf: Array("fmt ".utf8))
-    appendLE(UInt32(16))
-    appendLE(UInt16(1))
-    appendLE(channels)
-    appendLE(sampleRate)
-    appendLE(sampleRate * UInt32(channels) * UInt32(bitsPerSample / 8))
-    appendLE(UInt16(channels * bitsPerSample / 8))
-    appendLE(bitsPerSample)
-    data.append(contentsOf: Array("data".utf8))
-    appendLE(dataSize)
-    data.append(Data(count: Int(dataSize)))
-    let url = FileManager.default.temporaryDirectory
-      .appendingPathComponent("preload-\(UUID().uuidString).wav")
-    try data.write(to: url)
-    return url
+  func testAnUnrelatedSurvivorDoesNotProtectOtherAssets() {
+    let outgoing = [makeItem("a"), makeItem("b")]
+    let dropped = AVQueueBuilder.itemsBeingDropped(
+      outgoing: outgoing, keeping: [makeItem("c")])
+    XCTAssertEqual(dropped.count, 2)
   }
+
+  private func makeItem(_ name: String) -> AVPlayerItem {
+    AVPlayerItem(asset: AVURLAsset(url: URL(string: "https://example.com/\(name).m4a")!))
+  }
+
 }

package/ios/Tests/ActiveItemEngineStub.swift

@@ -0,0 +1,44 @@
+import AVFoundation
+@testable import QueuePlayer
+
+/// A `PlaybackEngine` that reports one active item and nothing else; for
+/// tests whose subject reads `activeMediaItem` and needs a real
+/// `AVPlayerItem` identity behind it.
+final class ActiveItemEngineStub: PlaybackEngine {
+  var item: AVPlayerItem?
+  private(set) var released = false
+  private(set) var playCalls = 0
+
+  var currentMediaItem: AVPlayerItem? { item }
+  var allMediaItems: [AVPlayerItem] { item.map { [$0] } ?? [] }
+  var attachedQueueItemIds: [String] { [] }
+  var isFadePendingOrActive: Bool { false }
+  var currentMediaItemIndex: Int { item == nil ? -1 : 0 }
+  var currentPositionSeconds: TimeInterval { 0 }
+  var currentDurationSeconds: TimeInterval { 0 }
+  var bufferedPositionSeconds: TimeInterval { 0 }
+  var isPlaying: Bool { false }
+  var timeControlStatus: AVPlayer.TimeControlStatus { .paused }
+  var delegate: PlaybackEngineDelegate?
+
+  func release() { released = true }
+  func setItems(_ items: [AVPlayerItem], startIndex: Int, startPositionSeconds: TimeInterval) {}
+  @discardableResult
+  func insertItems(_ items: [AVPlayerItem], after: AVPlayerItem?) -> Bool { true }
+  func remove(_ item: AVPlayerItem) {}
+  func removeAllItems() {}
+  func canInsert(_ item: AVPlayerItem, after: AVPlayerItem?) -> Bool { true }
+  func play() { playCalls += 1 }
+  func pause() {}
+  func stop() {}
+  func seek(toIndex index: Int, position: TimeInterval) {}
+  func skipToNext() {}
+  func skipToPrevious() {}
+  func setVolume(_ volume: Float) {}
+  func setPlaybackSpeed(_ speed: Float) {}
+  func seedPlaybackSpeed(_ speed: Float) {}
+  func setRepeatMode(_ mode: RepeatMode) {}
+  func setPitchCorrectionMode(_ mode: PitchCorrectionMode) {}
+  func setAudioMixProvider(_ provider: AudioMixProvider?) {}
+  func refreshAllItemMixes() {}
+}