react-native-queue-player 1.0.7 → 1.0.9

package/ios/Tests/AVQueueBuilderTests.swift

@@ -15,6 +15,10 @@ import AVFoundation
 /// overloads are adapters that unpack the Nitro structs and delegate here,
 /// so exercising the raw entry points is sufficient coverage for the
 /// merge + routing behaviour.
+// Main-actor-isolated: several assertions read `AVPlayerItem.asset`, which
+// the SDK marks main-actor-isolated; running the cases on the main actor
+// keeps those reads warning-free.
+@MainActor
 final class AVQueueBuilderTests: XCTestCase {
 
   // MARK: - httpOptionsRaw merging
@@ -165,7 +169,7 @@ final class AVQueueBuilderTests: XCTestCase {
     let item = AVQueueBuilder.makeItem(
       for: track,
       queueItemId: UUID().uuidString,
-      config: PlayerConfig(httpHeaders: nil, userAgent: nil, autoRetries: nil, retryBackoffMs: nil, networkTimeoutMs: nil, audioContentType: nil, audioCategoryOptions: nil, visualizationEnabled: nil, clampSeekToBuffered: nil, lookaheadCacheMaxSizeMb: nil, lookaheadCacheEvictionPolicy: nil, progressUpdateIntervalMs: nil, backgroundProgressUpdateIntervalMs: nil),
+      config: PlayerConfig(httpHeaders: nil, userAgent: nil, placeholderArtworkUri: nil, autoRetries: nil, retryBackoffMs: nil, networkTimeoutMs: nil, audioContentType: nil, audioCategoryOptions: nil, visualizationEnabled: nil, clampSeekToBuffered: nil, lookaheadCacheMaxSizeMb: nil, lookaheadCacheEvictionPolicy: nil, progressUpdateIntervalMs: nil, backgroundProgressUpdateIntervalMs: nil),
       cache: cache
     )
     XCTAssertNotNil(item)
@@ -182,7 +186,7 @@ final class AVQueueBuilderTests: XCTestCase {
   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, autoRetries: nil, retryBackoffMs: nil, networkTimeoutMs: nil, audioContentType: nil, audioCategoryOptions: nil, visualizationEnabled: nil, clampSeekToBuffered: nil, lookaheadCacheMaxSizeMb: nil, lookaheadCacheEvictionPolicy: nil, progressUpdateIntervalMs: nil, backgroundProgressUpdateIntervalMs: nil)
+    let config = PlayerConfig(httpHeaders: nil, userAgent: nil, placeholderArtworkUri: nil, autoRetries: nil, retryBackoffMs: nil, networkTimeoutMs: nil, audioContentType: nil, audioCategoryOptions: nil, visualizationEnabled: nil, clampSeekToBuffered: nil, lookaheadCacheMaxSizeMb: nil, lookaheadCacheEvictionPolicy: nil, progressUpdateIntervalMs: nil, backgroundProgressUpdateIntervalMs: nil)
     let item = AVQueueBuilder.makeItem(
       for: track, queueItemId: UUID().uuidString, config: config, cache: nil)
     XCTAssertNotNil(item)
@@ -210,7 +214,7 @@ final class AVQueueBuilderTests: XCTestCase {
     let item = AVQueueBuilder.makeItem(
       for: track,
       queueItemId: UUID().uuidString,
-      config: PlayerConfig(httpHeaders: nil, userAgent: nil, autoRetries: nil, retryBackoffMs: nil, networkTimeoutMs: nil, audioContentType: nil, audioCategoryOptions: nil, visualizationEnabled: nil, clampSeekToBuffered: nil, lookaheadCacheMaxSizeMb: nil, lookaheadCacheEvictionPolicy: nil, progressUpdateIntervalMs: nil, backgroundProgressUpdateIntervalMs: nil),
+      config: PlayerConfig(httpHeaders: nil, userAgent: nil, placeholderArtworkUri: nil, autoRetries: nil, retryBackoffMs: nil, networkTimeoutMs: nil, audioContentType: nil, audioCategoryOptions: nil, visualizationEnabled: nil, clampSeekToBuffered: nil, lookaheadCacheMaxSizeMb: nil, lookaheadCacheEvictionPolicy: nil, progressUpdateIntervalMs: nil, backgroundProgressUpdateIntervalMs: nil),
       cache: cache
     )
     XCTAssertNotNil(item)
@@ -256,7 +260,7 @@ final class AVQueueBuilderTests: XCTestCase {
     let item = AVQueueBuilder.makeItem(
       for: track,
       queueItemId: UUID().uuidString,
-      config: PlayerConfig(httpHeaders: nil, userAgent: nil, autoRetries: nil, retryBackoffMs: nil, networkTimeoutMs: nil, audioContentType: nil, audioCategoryOptions: nil, visualizationEnabled: nil, clampSeekToBuffered: nil, lookaheadCacheMaxSizeMb: nil, lookaheadCacheEvictionPolicy: nil, progressUpdateIntervalMs: nil, backgroundProgressUpdateIntervalMs: nil),
+      config: PlayerConfig(httpHeaders: nil, userAgent: nil, placeholderArtworkUri: nil, autoRetries: nil, retryBackoffMs: nil, networkTimeoutMs: nil, audioContentType: nil, audioCategoryOptions: nil, visualizationEnabled: nil, clampSeekToBuffered: nil, lookaheadCacheMaxSizeMb: nil, lookaheadCacheEvictionPolicy: nil, progressUpdateIntervalMs: nil, backgroundProgressUpdateIntervalMs: nil),
       cache: cache
     )
     XCTAssertNotNil(item)
@@ -292,7 +296,7 @@ final class AVQueueBuilderTests: XCTestCase {
     let items = AVQueueBuilder.buildPlayerItems(
       tracks: [trackA, trackB],
       queueItemIds: [UUID().uuidString, UUID().uuidString],
-      config: PlayerConfig(httpHeaders: nil, userAgent: nil, autoRetries: nil, retryBackoffMs: nil, networkTimeoutMs: nil, audioContentType: nil, audioCategoryOptions: nil, visualizationEnabled: nil, clampSeekToBuffered: nil, lookaheadCacheMaxSizeMb: nil, lookaheadCacheEvictionPolicy: nil, progressUpdateIntervalMs: nil, backgroundProgressUpdateIntervalMs: nil),
+      config: PlayerConfig(httpHeaders: nil, userAgent: nil, placeholderArtworkUri: nil, autoRetries: nil, retryBackoffMs: nil, networkTimeoutMs: nil, audioContentType: nil, audioCategoryOptions: nil, visualizationEnabled: nil, clampSeekToBuffered: nil, lookaheadCacheMaxSizeMb: nil, lookaheadCacheEvictionPolicy: nil, progressUpdateIntervalMs: nil, backgroundProgressUpdateIntervalMs: nil),
       cache: cache
     )
     XCTAssertEqual(items.count, 2)
@@ -367,12 +371,12 @@ final class AVQueueBuilderTests: XCTestCase {
     let queueItemIdB = UUID().uuidString
     let itemA = AVQueueBuilder.makeItem(
       for: track, queueItemId: queueItemIdA,
-      config: PlayerConfig(httpHeaders: nil, userAgent: nil, autoRetries: nil, retryBackoffMs: nil, networkTimeoutMs: nil, audioContentType: nil, audioCategoryOptions: nil, visualizationEnabled: nil, clampSeekToBuffered: nil, lookaheadCacheMaxSizeMb: nil, lookaheadCacheEvictionPolicy: nil, progressUpdateIntervalMs: nil, backgroundProgressUpdateIntervalMs: nil),
+      config: PlayerConfig(httpHeaders: nil, userAgent: nil, placeholderArtworkUri: nil, autoRetries: nil, retryBackoffMs: nil, networkTimeoutMs: nil, audioContentType: nil, audioCategoryOptions: nil, visualizationEnabled: nil, clampSeekToBuffered: nil, lookaheadCacheMaxSizeMb: nil, lookaheadCacheEvictionPolicy: nil, progressUpdateIntervalMs: nil, backgroundProgressUpdateIntervalMs: nil),
       cache: nil
     )
     let itemB = AVQueueBuilder.makeItem(
       for: track, queueItemId: queueItemIdB,
-      config: PlayerConfig(httpHeaders: nil, userAgent: nil, autoRetries: nil, retryBackoffMs: nil, networkTimeoutMs: nil, audioContentType: nil, audioCategoryOptions: nil, visualizationEnabled: nil, clampSeekToBuffered: nil, lookaheadCacheMaxSizeMb: nil, lookaheadCacheEvictionPolicy: nil, progressUpdateIntervalMs: nil, backgroundProgressUpdateIntervalMs: nil),
+      config: PlayerConfig(httpHeaders: nil, userAgent: nil, placeholderArtworkUri: nil, autoRetries: nil, retryBackoffMs: nil, networkTimeoutMs: nil, audioContentType: nil, audioCategoryOptions: nil, visualizationEnabled: nil, clampSeekToBuffered: nil, lookaheadCacheMaxSizeMb: nil, lookaheadCacheEvictionPolicy: nil, progressUpdateIntervalMs: nil, backgroundProgressUpdateIntervalMs: nil),
       cache: nil
     )
     XCTAssertNotNil(itemA)
@@ -397,7 +401,7 @@ final class AVQueueBuilderTests: XCTestCase {
     let queueItemId = UUID().uuidString
     let item = AVQueueBuilder.makeItem(
       for: track, queueItemId: queueItemId,
-      config: PlayerConfig(httpHeaders: nil, userAgent: nil, autoRetries: nil, retryBackoffMs: nil, networkTimeoutMs: nil, audioContentType: nil, audioCategoryOptions: nil, visualizationEnabled: nil, clampSeekToBuffered: nil, lookaheadCacheMaxSizeMb: nil, lookaheadCacheEvictionPolicy: nil, progressUpdateIntervalMs: nil, backgroundProgressUpdateIntervalMs: nil),
+      config: PlayerConfig(httpHeaders: nil, userAgent: nil, placeholderArtworkUri: nil, autoRetries: nil, retryBackoffMs: nil, networkTimeoutMs: nil, audioContentType: nil, audioCategoryOptions: nil, visualizationEnabled: nil, clampSeekToBuffered: nil, lookaheadCacheMaxSizeMb: nil, lookaheadCacheEvictionPolicy: nil, progressUpdateIntervalMs: nil, backgroundProgressUpdateIntervalMs: nil),
       cache: nil
     )
     XCTAssertNotNil(item)
@@ -413,7 +417,7 @@ final class AVQueueBuilderTests: XCTestCase {
     let queueItemId = UUID().uuidString
     let item = AVQueueBuilder.makeItem(
       for: track, queueItemId: queueItemId,
-      config: PlayerConfig(httpHeaders: nil, userAgent: nil, autoRetries: nil, retryBackoffMs: nil, networkTimeoutMs: nil, audioContentType: nil, audioCategoryOptions: nil, visualizationEnabled: nil, clampSeekToBuffered: nil, lookaheadCacheMaxSizeMb: nil, lookaheadCacheEvictionPolicy: nil, progressUpdateIntervalMs: nil, backgroundProgressUpdateIntervalMs: nil),
+      config: PlayerConfig(httpHeaders: nil, userAgent: nil, placeholderArtworkUri: nil, autoRetries: nil, retryBackoffMs: nil, networkTimeoutMs: nil, audioContentType: nil, audioCategoryOptions: nil, visualizationEnabled: nil, clampSeekToBuffered: nil, lookaheadCacheMaxSizeMb: nil, lookaheadCacheEvictionPolicy: nil, progressUpdateIntervalMs: nil, backgroundProgressUpdateIntervalMs: nil),
       cache: nil
     )
     XCTAssertNotNil(item)
@@ -421,10 +425,80 @@ final class AVQueueBuilderTests: XCTestCase {
       "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))
+
+    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")
+  }
+
+  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")
+  }
+
   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
     )
   }
+
+  /// 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
+  }
 }

package/ios/Tests/CastNowPlayingControllerTests.swift

@@ -132,6 +132,39 @@ final class CastNowPlayingControllerTests: XCTestCase {
       "activation renders the most recent cached metadata"
     )
   }
+
+  func testSeededPlaceholderReflectsConfiguredCustomImage() throws {
+    let tmp = FileManager.default.temporaryDirectory
+      .appendingPathComponent("rnqp-cast-placeholder-\(UUID().uuidString).jpg")
+    try makeTinyJpeg().write(to: tmp)
+    defer {
+      try? FileManager.default.removeItem(at: tmp)
+      PlaceholderArtwork.setCustom(uri: nil)
+    }
+    let builtInSize = PlaceholderArtwork.image.size
+    PlaceholderArtwork.setCustom(uri: tmp.absoluteString)
+    let customSize = PlaceholderArtwork.image.size
+    // Precondition: the fixture is a different size from the built-in,
+    // else the size check below can't tell them apart.
+    XCTAssertNotEqual(customSize, builtInSize)
+
+    try router.setActive(ControllableRemoteSession())
+
+    let artwork = info?[MPMediaItemPropertyArtwork] as? MPMediaItemArtwork
+    XCTAssertEqual(
+      artwork?.image(at: customSize)?.size, customSize,
+      "the cast lockscreen seeds the live custom placeholder, not a frozen built-in"
+    )
+  }
+
+  private func makeTinyJpeg() -> Data {
+    let renderer = UIGraphicsImageRenderer(size: CGSize(width: 1, height: 1))
+    let image = renderer.image { ctx in
+      UIColor.green.setFill()
+      ctx.fill(CGRect(x: 0, y: 0, width: 1, height: 1))
+    }
+    return image.jpegData(compressionQuality: 1.0) ?? Data()
+  }
 }
 
 // MARK: - Listener-firing fake

package/ios/Tests/PlaceholderArtworkTests.swift

@@ -0,0 +1,81 @@
+import XCTest
+@testable import QueuePlayer
+import UIKit
+
+/// `PlaceholderArtwork` swaps in a consumer-supplied cover-art placeholder
+/// (`PlayerConfig.placeholderArtworkUri`) in place of the bundled RNQP
+/// image. Only a local `file://` image is honoured; a remote or unset URI,
+/// or an unloadable file, keeps the bundled placeholder.
+@MainActor
+final class PlaceholderArtworkTests: XCTestCase {
+
+  override func tearDown() {
+    // Process-wide singleton — reset so a set custom image does not leak
+    // into other suites that read the bundled placeholder.
+    PlaceholderArtwork.setCustom(uri: nil)
+    super.tearDown()
+  }
+
+  func testCustomFileUriReplacesTheBundledPlaceholder() throws {
+    let bundled = PlaceholderArtwork.image
+    let tmp = FileManager.default.temporaryDirectory
+      .appendingPathComponent("rnqp-placeholder-\(UUID().uuidString).jpg")
+    try makeJpegBytes().write(to: tmp)
+    defer { try? FileManager.default.removeItem(at: tmp) }
+
+    PlaceholderArtwork.setCustom(uri: tmp.absoluteString)
+
+    let image = PlaceholderArtwork.image
+    XCTAssertFalse(image === bundled,
+                   "a loadable file:// image replaces the bundled placeholder")
+    XCTAssertTrue(image === PlaceholderArtwork.image,
+                  "the custom image is stable across reads")
+  }
+
+  func testUnsetUriKeepsTheBundledPlaceholder() {
+    let bundled = PlaceholderArtwork.image
+    PlaceholderArtwork.setCustom(uri: nil)
+    XCTAssertTrue(PlaceholderArtwork.image === bundled)
+  }
+
+  func testNonFileUriIsRejectedAndKeepsTheBundledPlaceholder() {
+    let bundled = PlaceholderArtwork.image
+    PlaceholderArtwork.setCustom(uri: "https://example.com/logo.png")
+    XCTAssertTrue(PlaceholderArtwork.image === bundled,
+                  "a remote URI is rejected — offline-only file:// contract")
+  }
+
+  func testUnloadableFileUriFallsBackToTheBundledPlaceholder() {
+    let bundled = PlaceholderArtwork.image
+    PlaceholderArtwork.setCustom(uri: "file:///nonexistent/path/missing.jpg")
+    XCTAssertTrue(PlaceholderArtwork.image === bundled)
+  }
+
+  func testEmptyUriKeepsTheBundledPlaceholder() {
+    let bundled = PlaceholderArtwork.image
+    PlaceholderArtwork.setCustom(uri: "")
+    XCTAssertTrue(PlaceholderArtwork.image === bundled)
+  }
+
+  func testUppercaseFileSchemeIsHonoured() throws {
+    let bundled = PlaceholderArtwork.image
+    let tmp = FileManager.default.temporaryDirectory
+      .appendingPathComponent("rnqp-placeholder-\(UUID().uuidString).jpg")
+    try makeJpegBytes().write(to: tmp)
+    defer { try? FileManager.default.removeItem(at: tmp) }
+
+    PlaceholderArtwork.setCustom(uri: "FILE://" + tmp.path)
+
+    XCTAssertFalse(PlaceholderArtwork.image === bundled,
+                   "an uppercase FILE:// scheme is honoured (case-insensitive)")
+  }
+
+  private func makeJpegBytes() -> Data {
+    let renderer = UIGraphicsImageRenderer(size: CGSize(width: 1, height: 1))
+    let image = renderer.image { ctx in
+      UIColor.blue.setFill()
+      ctx.fill(CGRect(x: 0, y: 0, width: 1, height: 1))
+    }
+    return image.jpegData(compressionQuality: 1.0) ?? Data()
+  }
+}

package/ios/Tests/QueueStateTests.swift

@@ -0,0 +1,50 @@
+import XCTest
+@testable import QueuePlayer
+
+/// `QueueState` holds `tracks` and `queueItemIds` as parallel arrays. The
+/// id-supplying `insert` overload lets a caller reuse the lib-generated
+/// ids it stamped on pre-built AVPlayerItems (the immediate-next preload
+/// path) while preserving the 1:1 invariant.
+final class QueueStateTests: XCTestCase {
+
+  func testInsertWithSuppliedIdsPlacesThemParallelToTracks() {
+    var state = QueueState()
+    _ = state.replaceAll([track("a"), track("b"), track("c")])
+
+    state.insert([track("x"), track("y")], at: 1, ids: ["id-x", "id-y"])
+
+    XCTAssertEqual(state.tracks.map { $0.url }, ["a", "x", "y", "b", "c"])
+    XCTAssertEqual(state.queueItemIds.count, state.tracks.count)
+    XCTAssertEqual(state.queueItemIds[1], "id-x")
+    XCTAssertEqual(state.queueItemIds[2], "id-y")
+  }
+
+  func testInsertWithSuppliedIdsAppendsAtEnd() {
+    var state = QueueState()
+    _ = state.replaceAll([track("a")])
+
+    state.insert([track("z")], at: 1, ids: ["id-z"])
+
+    XCTAssertEqual(state.tracks.map { $0.url }, ["a", "z"])
+    XCTAssertEqual(state.queueItemIds.count, 2)
+    XCTAssertEqual(state.queueItemIds[1], "id-z")
+  }
+
+  func testGeneratingInsertStillReturnsFreshParallelIds() {
+    var state = QueueState()
+    _ = state.replaceAll([track("a"), track("b")])
+
+    let ids = state.insert([track("x")], at: 1)
+
+    XCTAssertEqual(ids.count, 1)
+    XCTAssertEqual(state.queueItemIds[1], ids[0])
+    XCTAssertEqual(state.queueItemIds.count, state.tracks.count)
+  }
+
+  private func track(_ url: String) -> TrackItem {
+    TrackItem(
+      id: nil, url: url, title: nil, artist: nil, album: nil,
+      duration: nil, artworkUrl: nil, extras: nil
+    )
+  }
+}

package/ios/TrackPlayer.swift

@@ -97,7 +97,7 @@ class TrackPlayer: HybridTrackPlayerSpec {
     PlayerConfig(
       httpHeaders: nil,
       userAgent: nil,
-      autoRetries: nil,
+      placeholderArtworkUri: nil, autoRetries: nil,
       retryBackoffMs: nil,
       networkTimeoutMs: nil,
       audioContentType: nil,
@@ -232,6 +232,7 @@ class TrackPlayer: HybridTrackPlayerSpec {
   // simultaneously without clobbering each other.
   private let stateChangeListeners = ListenerRegistry<(PlayerState, StateChangeReason) -> Void>()
   private let trackChangeListeners = ListenerRegistry<(TrackItem?, Double, TrackChangeReason, Double?) -> Void>()
+  private let queueChangeListeners = ListenerRegistry<([TrackItem], Double, QueueChangeReason) -> Void>()
   private let progressListeners = ListenerRegistry<(PlayerProgress) -> Void>()
   private let milestoneListeners = ListenerRegistry<(Double, Double) -> Void>()
   /// Per-playthrough 25/50/75/90% milestone state. Main-thread-confined
@@ -608,6 +609,10 @@ class TrackPlayer: HybridTrackPlayerSpec {
         // each track-change resolve.
         self.artworkResolver.configHeaders = config.httpHeaders
         self.artworkResolver.configUserAgent = config.userAgent
+        // Swap the cover-art placeholder to the consumer-supplied image
+        // (or back to the built-in when unset). Every placeholder site
+        // reads `PlaceholderArtwork.image`, so this is the only hook needed.
+        PlaceholderArtwork.setCustom(uri: config.placeholderArtworkUri)
         // Same live config for the cast lockscreen's own artwork
         // resolver so authenticated covers resolve during cast.
         CastNowPlayingController.shared.configureArtwork(
@@ -1372,6 +1377,7 @@ class TrackPlayer: HybridTrackPlayerSpec {
           self.castEventBridge.seedStartMetadata(startIndex: resolvedStart)
           self.rescheduleLookahead()
           self.recomputeCapabilities()
+          self.emitQueueChange(.setQueue)
         }
         return
       }
@@ -1415,6 +1421,7 @@ class TrackPlayer: HybridTrackPlayerSpec {
         }
         self.rescheduleLookahead()
         self.recomputeCapabilities()
+        self.emitQueueChange(.setQueue)
       }
     }
   }
@@ -1433,30 +1440,86 @@ class TrackPlayer: HybridTrackPlayerSpec {
       // resolved insert index against the pre-mutation queue, then mirror
       // the insert to the receiver. Index resolution to receiver itemIds
       // happens inside the cast session via GCKMediaQueue.
-      let insertAt: Int = self.onMainSync {
-        let at = QueueMutationArithmetic.clampInsertBefore(
-          insertBefore: insertBefore.flatMap { $0.isFinite ? Int($0) : nil },
-          trackCount: self.tracks.count
-        )
-        self.performingMutation {
-          self.addToQueueBody(newTracks: newTracks, insertBefore: insertBefore)
+      //
+      // When the insert lands in the immediate-next slot of a playing
+      // queue, `AVQueuePlayer` prerolls the new item on the shared render
+      // pipeline mid-playback, which briefly disturbs the current item.
+      // For that case only, build the items on main but preload the
+      // leading asset OFF the mutation, then commit state + engine insert
+      // atomically so the forced preroll is cheap. Every other insert
+      // keeps the synchronous path — the tail is inert (no preroll, no
+      // disturbance), so there's nothing to warm.
+      let plan: (insertAt: Int, prebuild: (ids: [String], items: [AVPlayerItem])?) =
+        self.onMainSync {
+          let at = QueueMutationArithmetic.clampInsertBefore(
+            insertBefore: insertBefore.flatMap { $0.isFinite ? Int($0) : nil },
+            trackCount: self.tracks.count
+          )
+          // Immediate-next slot = the only insert AVQueuePlayer prerolls
+          // while the current item plays (covers "play next" mid-queue and
+          // an append when the current track is the last one).
+          let oldCur = self.currentTrackIndex
+          guard oldCur >= 0, at == oldCur + 1 else {
+            self.performingMutation {
+              self.addToQueueBody(newTracks: newTracks, insertBefore: insertBefore)
+            }
+            self.rescheduleLookahead()
+            self.recomputeCapabilities()
+            return (at, nil)
+          }
+          let ids = newTracks.map { _ in UUID().uuidString }
+          let items = AVQueueBuilder.buildPlayerItems(
+            tracks: newTracks, queueItemIds: ids,
+            config: self.config, cache: self.lookaheadCache)
+          return (at, (ids: ids, items: items))
+        }
+
+      var insertAt = plan.insertAt
+      if let prebuild = plan.prebuild {
+        // Warm the leading buildable item's asset off the mutation so the
+        // immediate-next preroll is cheap. `.first` is the first item that
+        // survived `buildPlayerItems`' compactMap — the same item that lands
+        // in the engine's next slot even if an earlier track had an
+        // unbuildable URL.
+        if let leading = prebuild.items.first {
+          await AVQueueBuilder.preloadAssetForInsert(leading)
+        }
+        // Commit state + engine insert atomically after the preload, and
+        // route the cast mirror against the index the local queue actually
+        // used: a mutation during the preload can shift it, and `at` is
+        // resolved against the live queue inside the same hop.
+        insertAt = self.onMainSync {
+          let committedAt = QueueMutationArithmetic.clampInsertBefore(
+            insertBefore: insertBefore.flatMap { $0.isFinite ? Int($0) : nil },
+            trackCount: self.tracks.count
+          )
+          self.performingMutation {
+            self.addToQueueBody(
+              newTracks: newTracks, insertBefore: insertBefore, prebuilt: prebuild)
+          }
+          self.rescheduleLookahead()
+          self.recomputeCapabilities()
+          return committedAt
         }
-        self.rescheduleLookahead()
-        self.recomputeCapabilities()
-        return at
       }
+
       // Mirror only when every new track is castable. A dropped item would
       // shift the receiver queue out of alignment with the local index space
       // that later mutations (remove/move) resolve against, so a partial set
       // is not routed at all — the same all-or-nothing rule `setQueue` applies.
       let castItems = newTracks.compactMap { CastMediaItem.from(track: $0) }
       if !castItems.isEmpty, castItems.count == newTracks.count {
-        _ = await CastTransportRouter.routeAddToQueue(items: castItems, beforeIndex: insertAt)
+        _ = await CastTransportRouter.routeAddToQueue(
+          items: castItems, beforeIndex: insertAt)
       }
     }
   }
 
-  private func addToQueueBody(newTracks: [TrackItem], insertBefore: Double?) {
+  private func addToQueueBody(
+    newTracks: [TrackItem],
+    insertBefore: Double?,
+    prebuilt: (ids: [String], items: [AVPlayerItem])? = nil
+  ) {
     guard !newTracks.isEmpty, let engine = self.engine else { return }
 
     // Non-finite `insertBefore` is dropped (treated as append) so
@@ -1468,7 +1531,18 @@ class TrackPlayer: HybridTrackPlayerSpec {
       trackCount: self.tracks.count
     )
 
-    let newIds = self.queueState.insert(newTracks, at: at)
+    // When the caller pre-built the items (immediate-next preload path)
+    // reuse its lib-generated ids so each item's stamped `queueItemId`
+    // stays 1:1 with `queueItemIds`. `at` is resolved against the live
+    // queue here, so the reused items land at the position the current
+    // queue dictates.
+    let newIds: [String]
+    if let prebuilt = prebuilt {
+      self.queueState.insert(newTracks, at: at, ids: prebuilt.ids)
+      newIds = prebuilt.ids
+    } else {
+      newIds = self.queueState.insert(newTracks, at: at)
+    }
     // Initialise retry-budget entries for the new items so they have
     // an auto-retry budget when (if) they hit a transient error.
     let attempts = self.effectiveAutoRetries()
@@ -1483,6 +1557,10 @@ class TrackPlayer: HybridTrackPlayerSpec {
     self.currentTrackIndex = QueueMutationArithmetic.currentIndexAfterAdd(
       currentIndex: oldCur, insertAt: at, count: newTracks.count
     )
+    // Queue data model is final here (tracks + index committed); the
+    // engine insert below only touches the audio pipeline. Emit before
+    // the early returns so every non-empty add reports one snapshot.
+    self.emitQueueChange(.add)
 
     if oldCur < 0 {
       // Queue was empty — player stays empty until skipToIndex.
@@ -1510,7 +1588,7 @@ class TrackPlayer: HybridTrackPlayerSpec {
       existing.first { $0.queueItemId != nil && $0.queueItemId == anchorId }
         ?? existing.last
 
-    let newItems = AVQueueBuilder.buildPlayerItems(
+    let newItems = prebuilt?.items ?? AVQueueBuilder.buildPlayerItems(
       tracks: newTracks, queueItemIds: newIds,
       config: self.config, cache: self.lookaheadCache)
     let ok = engine.insertItems(newItems, after: afterItem)
@@ -1596,6 +1674,10 @@ class TrackPlayer: HybridTrackPlayerSpec {
       sanitisedIndices: sanitised,
       trackCountBefore: trackCountBefore
     )
+    // Reached only past the `sanitised.isEmpty` guard, so ≥1 track was
+    // removed. tracks + index are final; the engine.remove loop below
+    // only detaches the AVPlayerItems.
+    self.emitQueueChange(.remove)
 
     // The currentItem is untouched (never in `itemsToRemove`); removing
     // only later/earlier items leaves it playing in place.
@@ -1665,11 +1747,15 @@ class TrackPlayer: HybridTrackPlayerSpec {
     self.performingMutation {
       self.syncPlayerQueue(preserveCurrent: preserveCurrent)
     }
+    // Reached only past the invalid/`from == to` guard, so the order
+    // actually changed.
+    self.emitQueueChange(.move)
   }
 
   func clearQueue() throws -> Promise<Void> {
     return Promise<Void>.async {
       await self.onMain {
+        let queueWasNonEmpty = !self.tracks.isEmpty
         self.performingMutation {
           self.engine?.removeAllItems()
           self.queueState.clear()
@@ -1691,6 +1777,11 @@ class TrackPlayer: HybridTrackPlayerSpec {
         self.lastErrorQueueItemId = nil
         self.lastErrorCode = nil
         self.retryAttemptsRemaining.removeAll()
+        // Fire queue-change BEFORE the synthetic track-change so a
+        // `useQueue()` consumer sees the empty queue + index -1 together,
+        // not a one-frame (old queue, index -1) transient. Only when the
+        // queue was actually non-empty — clearing an empty queue is a no-op.
+        if queueWasNonEmpty { self.emitQueueChange(.clear) }
         self.trackChangeListeners.forEach { $0(nil, Double(-1), .queueReplaced, nil) }
         self.nowPlayingInfo.refreshAll()
         self.artworkResolver.cancelInFlight()
@@ -2823,6 +2914,8 @@ class TrackPlayer: HybridTrackPlayerSpec {
         }
         self.rescheduleLookahead()
         self.recomputeCapabilities()
+        // Skip a single-track shuffle — the order can't change.
+        if self.tracks.count > 1 { self.emitQueueChange(.shuffle) }
 
         // Resume playback if the user was playing before the shuffle.
         // Stays paused otherwise — consumer can call play() if they
@@ -2960,6 +3053,24 @@ class TrackPlayer: HybridTrackPlayerSpec {
     return { [weak self] in self?.trackChangeListeners.remove(id: id) }
   }
 
+  func onQueueChange(
+    callback: @escaping (_ queue: [TrackItem], _ currentIndex: Double, _ reason: QueueChangeReason) -> Void
+  ) throws -> () -> Void {
+    let id = queueChangeListeners.add(callback)
+    return { [weak self] in self?.queueChangeListeners.remove(id: id) }
+  }
+
+  /// Fire `onQueueChange` with an atomic snapshot of the post-mutation
+  /// queue + current index. Main-thread only — every queue mutation
+  /// commits on main, so `self.tracks` / `self.currentTrackIndex` are the
+  /// settled values here. Callers gate this on an actual content/order
+  /// change so a no-op mutation never emits.
+  private func emitQueueChange(_ reason: QueueChangeReason) {
+    let snapshot = self.tracks
+    let index = Double(self.currentTrackIndex)
+    queueChangeListeners.forEach { $0(snapshot, index, reason) }
+  }
+
   func onProgress(
     callback: @escaping (_ progress: PlayerProgress) -> Void
   ) throws -> () -> Void {

package/lib/module/hooks/index.js

@@ -3,6 +3,7 @@
 export { useProgress } from "./useProgress.js";
 export { usePlaybackState } from "./usePlaybackState.js";
 export { useActiveTrack } from "./useActiveTrack.js";
+export { useQueue } from "./useQueue.js";
 export { useCanSkip } from "./useCanSkip.js";
 export { useSleepTimer } from "./useSleepTimer.js";
 export { useBufferState } from "./useBufferState.js";

package/lib/module/hooks/index.js.map

@@ -1 +1 @@
-{"version":3,"names":["useProgress","usePlaybackState","useActiveTrack","useCanSkip","useSleepTimer","useBufferState","useFullyBuffered","useEqualizer","useVisualizerState","useLookaheadCache","useNowPlayingFormat","useCast","useAudioRoute"],"sourceRoot":"../../../src","sources":["hooks/index.ts"],"mappings":";;AAAA,SAASA,WAAW,QAAQ,kBAAe;AAG3C,SAASC,gBAAgB,QAAQ,uBAAoB;AAGrD,SAASC,cAAc,QAAQ,qBAAkB;AAGjD,SAASC,UAAU,QAAQ,iBAAc;AAGzC,SAASC,aAAa,QAAQ,oBAAiB;AAE/C,SAASC,cAAc,QAAQ,qBAAkB;AAEjD,SAASC,gBAAgB,QAAQ,uBAAoB;AAErD,SAASC,YAAY,QAAQ,mBAAgB;AAG7C,SAASC,kBAAkB,QAAQ,yBAAsB;AAGzD,SAASC,iBAAiB,QAAQ,wBAAqB;AAGvD,SAASC,mBAAmB,QAAQ,0BAAuB;AAE3D,SAASC,OAAO,QAAQ,cAAW;AAGnC,SAASC,aAAa,QAAQ,oBAAiB","ignoreList":[]}
+{"version":3,"names":["useProgress","usePlaybackState","useActiveTrack","useQueue","useCanSkip","useSleepTimer","useBufferState","useFullyBuffered","useEqualizer","useVisualizerState","useLookaheadCache","useNowPlayingFormat","useCast","useAudioRoute"],"sourceRoot":"../../../src","sources":["hooks/index.ts"],"mappings":";;AAAA,SAASA,WAAW,QAAQ,kBAAe;AAG3C,SAASC,gBAAgB,QAAQ,uBAAoB;AAGrD,SAASC,cAAc,QAAQ,qBAAkB;AAGjD,SAASC,QAAQ,QAAQ,eAAY;AAGrC,SAASC,UAAU,QAAQ,iBAAc;AAGzC,SAASC,aAAa,QAAQ,oBAAiB;AAE/C,SAASC,cAAc,QAAQ,qBAAkB;AAEjD,SAASC,gBAAgB,QAAQ,uBAAoB;AAErD,SAASC,YAAY,QAAQ,mBAAgB;AAG7C,SAASC,kBAAkB,QAAQ,yBAAsB;AAGzD,SAASC,iBAAiB,QAAQ,wBAAqB;AAGvD,SAASC,mBAAmB,QAAQ,0BAAuB;AAE3D,SAASC,OAAO,QAAQ,cAAW;AAGnC,SAASC,aAAa,QAAQ,oBAAiB","ignoreList":[]}