react-native-queue-player 1.0.0

package/ios/Tests/CarPlayBrowseBuilderTests.swift

@@ -0,0 +1,221 @@
+import CarPlay
+import XCTest
+@testable import QueuePlayer
+
+/// Coverage for [CarPlayBrowseBuilder] — snapshot → template
+/// conversion, item count + accessory mapping, pagination against
+/// `CPListTemplate.maximumItemCount`. Direct method calls on the
+/// builder; the scene delegate's full lifecycle is covered by the
+/// CarPlay Sim manual playbook.
+final class CarPlayBrowseBuilderTests: XCTestCase {
+
+  private func item(
+    _ id: String,
+    title: String? = nil,
+    playable: Bool = true,
+    hasChildren: Bool? = nil,
+    subtitle: String? = nil,
+    artworkUrl: String? = nil
+  ) -> BrowseItem {
+    BrowseItem(
+      id: id,
+      title: title ?? "T-\(id)",
+      subtitle: subtitle,
+      artworkUrl: artworkUrl,
+      playable: playable,
+      hasChildren: hasChildren
+    )
+  }
+
+  private func section(
+    _ id: String,
+    icon: SectionIcon? = nil,
+    items: [BrowseItem] = []
+  ) -> BrowseSection {
+    BrowseSection(id: id, title: "S-\(id)", icon: icon, artworkUrl: nil, items: items)
+  }
+
+  // MARK: - Root tab bar
+
+  func testBuildRootTemplateMapsSectionsToTabs() {
+    let builder = CarPlayBrowseBuilder()
+    let provider = CarPlayBrowseDataProvider()
+    let bridge = CarPlayBridge()
+    let pending = PendingBrowseRequests()
+    let loader = ArtworkLoader()
+    let snapshot = BrowseSnapshot(
+      rootId: "root",
+      sections: [section("a"), section("b"), section("c")]
+    )
+    provider.setSnapshot(snapshot)
+    let tabBar = builder.buildRootTemplate(
+      provider: provider,
+      bridge: bridge,
+      pending: pending,
+      loader: loader,
+      pushTemplate: { _ in }
+    )
+    XCTAssertNotNil(tabBar)
+    XCTAssertEqual(tabBar?.templates.count, 3)
+    let tabs = tabBar?.templates.compactMap { $0 as? CPListTemplate } ?? []
+    XCTAssertEqual(tabs[0].tabTitle, "S-a")
+    XCTAssertEqual(tabs[1].tabTitle, "S-b")
+    XCTAssertEqual(tabs[2].tabTitle, "S-c")
+  }
+
+  func testBuildRootTemplateReturnsNilWhenSnapshotMissing() {
+    let builder = CarPlayBrowseBuilder()
+    let provider = CarPlayBrowseDataProvider()
+    let bridge = CarPlayBridge()
+    let pending = PendingBrowseRequests()
+    let loader = ArtworkLoader()
+    let tabBar = builder.buildRootTemplate(
+      provider: provider,
+      bridge: bridge,
+      pending: pending,
+      loader: loader,
+      pushTemplate: { _ in }
+    )
+    XCTAssertNil(tabBar)
+  }
+
+  func testBuildRootTemplateCapsSectionsAtMaximumTabCount() {
+    let builder = CarPlayBrowseBuilder()
+    let provider = CarPlayBrowseDataProvider()
+    let bridge = CarPlayBridge()
+    let pending = PendingBrowseRequests()
+    let loader = ArtworkLoader()
+    let cap = CarPlayBrowseBuilder.maximumTabCount
+    let sections = (0..<cap + 3).map { section("s\($0)") }
+    let snapshot = BrowseSnapshot(rootId: "root", sections: sections)
+    provider.setSnapshot(snapshot)
+    let tabBar = builder.buildRootTemplate(
+      provider: provider,
+      bridge: bridge,
+      pending: pending,
+      loader: loader,
+      pushTemplate: { _ in }
+    )
+    XCTAssertEqual(tabBar?.templates.count, cap)
+  }
+
+  func testBuildRootTemplateAssignsTabImagesFromSectionIcons() {
+    let builder = CarPlayBrowseBuilder()
+    let provider = CarPlayBrowseDataProvider()
+    let bridge = CarPlayBridge()
+    let pending = PendingBrowseRequests()
+    let loader = ArtworkLoader()
+    let snapshot = BrowseSnapshot(
+      rootId: "root",
+      sections: [
+        section("a", icon: .albums),
+        section("p", icon: .playlists),
+        section("noicon"),
+      ]
+    )
+    provider.setSnapshot(snapshot)
+    let tabBar = builder.buildRootTemplate(
+      provider: provider,
+      bridge: bridge,
+      pending: pending,
+      loader: loader,
+      pushTemplate: { _ in }
+    )
+    let tabs = tabBar?.templates.compactMap { $0 as? CPListTemplate } ?? []
+    XCTAssertNotNil(tabs[0].tabImage)
+    XCTAssertNotNil(tabs[1].tabImage)
+    XCTAssertNil(tabs[2].tabImage)
+  }
+
+  func testBuildPlaceholderRootTabBarReturnsOneTab() {
+    let builder = CarPlayBrowseBuilder()
+    let tabBar = builder.buildPlaceholderRootTabBar()
+    XCTAssertEqual(tabBar.templates.count, 1)
+  }
+
+  // MARK: - Icon mapping
+
+  func testIconToSFSymbolMapsEveryCase() {
+    let allCases: [SectionIcon] = [
+      .home, .library, .playlists, .favourites,
+      .albums, .artists, .songs, .genres,
+      .recentlyPlayed, .radio, .search, .downloaded, .podcasts,
+    ]
+    for icon in allCases {
+      XCTAssertNotNil(
+        CarPlayBrowseBuilder.iconToSFSymbol(icon),
+        "Missing SF Symbol mapping for \(icon)"
+      )
+    }
+    XCTAssertNil(CarPlayBrowseBuilder.iconToSFSymbol(nil))
+  }
+
+  // MARK: - Section template
+
+  func testSectionTemplateMapsItemsWithCorrectAccessory() {
+    let builder = CarPlayBrowseBuilder()
+    let bridge = CarPlayBridge()
+    let loader = ArtworkLoader()
+    let sectionItems: [BrowseItem] = [
+      item("a-1", playable: true),
+      item("a-2", playable: false, hasChildren: true),
+      item("a-3", playable: false, hasChildren: false),
+    ]
+    let template = builder.buildSectionTemplate(
+      section: BrowseSection(id: "a", title: "A", icon: nil, artworkUrl: nil, items: sectionItems),
+      bridge: bridge,
+      loader: loader,
+      pushTemplate: { _ in }
+    )
+    let items = (template.sections.first?.items ?? []).compactMap { $0 as? CPListItem }
+    XCTAssertEqual(items.count, 3)
+    XCTAssertEqual(items[0].accessoryType, .none)
+    XCTAssertEqual(items[1].accessoryType, .disclosureIndicator)
+    XCTAssertEqual(items[2].accessoryType, .none)
+  }
+
+  func testSectionTemplateCapsItemsAtMaximumItemCount() {
+    let builder = CarPlayBrowseBuilder()
+    let bridge = CarPlayBridge()
+    let loader = ArtworkLoader()
+    let cap = CarPlayBrowseBuilder.maximumItemsPerSection
+    let sectionItems = (0..<cap + 10).map { item("i\($0)") }
+    let template = builder.buildSectionTemplate(
+      section: BrowseSection(id: "a", title: "A", icon: nil, artworkUrl: nil, items: sectionItems),
+      bridge: bridge,
+      loader: loader,
+      pushTemplate: { _ in }
+    )
+    let items = template.sections.first?.items ?? []
+    XCTAssertEqual(items.count, cap)
+  }
+
+  // MARK: - Per-item construction
+
+  func testMakeListItemPropagatesTitleAndSubtitle() {
+    let builder = CarPlayBrowseBuilder()
+    let bridge = CarPlayBridge()
+    let loader = ArtworkLoader()
+    let listItem = builder.makeListItem(
+      for: item("song", title: "Hold On", subtitle: "Wilco"),
+      bridge: bridge,
+      loader: loader,
+      pushTemplate: { _ in }
+    )
+    XCTAssertEqual(listItem.text, "Hold On")
+    XCTAssertEqual(listItem.detailText, "Wilco")
+  }
+
+  func testMakeListItemNonTappableForHeaderRow() {
+    let builder = CarPlayBrowseBuilder()
+    let bridge = CarPlayBridge()
+    let loader = ArtworkLoader()
+    let listItem = builder.makeListItem(
+      for: item("hdr", playable: false, hasChildren: false),
+      bridge: bridge,
+      loader: loader,
+      pushTemplate: { _ in }
+    )
+    XCTAssertEqual(listItem.accessoryType, .none)
+  }
+}

package/ios/Tests/CarPlayBrowseDataProviderTests.swift

@@ -0,0 +1,218 @@
+import XCTest
+@testable import QueuePlayer
+
+/// Coverage for [CarPlayBrowseDataProvider]. Mirrors the Android
+/// `BrowseDataProviderTest` cases — atomic snapshot replacement,
+/// root + section + item lookup, paginated children, change-set
+/// computation across snapshot transitions, and the
+/// `didUpdateNotification` dispatch contract.
+final class CarPlayBrowseDataProviderTests: XCTestCase {
+
+  private func item(
+    _ id: String,
+    title: String? = nil,
+    playable: Bool = true,
+    hasChildren: Bool? = nil
+  ) -> BrowseItem {
+    BrowseItem(
+      id: id,
+      title: title ?? "T-\(id)",
+      subtitle: nil,
+      artworkUrl: nil,
+      playable: playable,
+      hasChildren: hasChildren
+    )
+  }
+
+  private func section(_ id: String, items: [BrowseItem] = []) -> BrowseSection {
+    BrowseSection(id: id, title: "S-\(id)", icon: nil, artworkUrl: nil, items: items)
+  }
+
+  // MARK: - Snapshot lifecycle
+
+  func testInitiallyEmpty() {
+    let p = CarPlayBrowseDataProvider()
+    XCTAssertNil(p.getSnapshot())
+    XCTAssertFalse(p.isRoot("root"))
+    XCTAssertNil(p.getSection("a"))
+    XCTAssertNil(p.getItem("a-1"))
+    XCTAssertTrue(p.getChildren(parentId: "root", page: 0, pageSize: 50).isEmpty)
+  }
+
+  func testSetSnapshotMakesSnapshotReadable() {
+    let p = CarPlayBrowseDataProvider()
+    let snap = BrowseSnapshot(
+      rootId: "root",
+      sections: [section("a", items: [item("a-1")])]
+    )
+    p.setSnapshot(snap)
+    XCTAssertEqual(p.getSnapshot()?.rootId, "root")
+    XCTAssertTrue(p.isRoot("root"))
+  }
+
+  func testSetSnapshotNilClearsTheCache() {
+    let p = CarPlayBrowseDataProvider()
+    p.setSnapshot(BrowseSnapshot(rootId: "root", sections: []))
+    p.setSnapshot(nil)
+    XCTAssertNil(p.getSnapshot())
+    XCTAssertFalse(p.isRoot("root"))
+  }
+
+  // MARK: - Section + item lookup
+
+  func testGetSectionResolvesById() {
+    let p = CarPlayBrowseDataProvider()
+    p.setSnapshot(
+      BrowseSnapshot(
+        rootId: "root",
+        sections: [
+          section("recents", items: [item("r-1")]),
+          section("favourites", items: [item("f-1")])
+        ]
+      )
+    )
+    XCTAssertEqual(p.getSection("favourites")?.id, "favourites")
+    XCTAssertNil(p.getSection("missing"))
+  }
+
+  func testGetItemWalksEverySection() {
+    let p = CarPlayBrowseDataProvider()
+    p.setSnapshot(
+      BrowseSnapshot(
+        rootId: "root",
+        sections: [
+          section("a", items: [item("a-1"), item("a-2")]),
+          section("b", items: [item("b-1")])
+        ]
+      )
+    )
+    XCTAssertEqual(p.getItem("b-1")?.id, "b-1")
+    XCTAssertNil(p.getItem("missing"))
+  }
+
+  // MARK: - Children + pagination
+
+  func testGetChildrenOfRootReturnsOneRowPerSection() {
+    let p = CarPlayBrowseDataProvider()
+    p.setSnapshot(
+      BrowseSnapshot(
+        rootId: "root",
+        sections: [
+          section("recents", items: [item("r-1")]),
+          section("favourites", items: [item("f-1")])
+        ]
+      )
+    )
+    let children = p.getChildren(parentId: "root", page: 0, pageSize: 50)
+    XCTAssertEqual(children.map { $0.id }, ["recents", "favourites"])
+    XCTAssertTrue(children.allSatisfy { $0.playable == false })
+    XCTAssertTrue(children.allSatisfy { $0.hasChildren == true })
+  }
+
+  func testGetChildrenOfSectionReturnsItsItems() {
+    let p = CarPlayBrowseDataProvider()
+    p.setSnapshot(
+      BrowseSnapshot(
+        rootId: "root",
+        sections: [
+          section("a", items: [item("a-1"), item("a-2"), item("a-3")])
+        ]
+      )
+    )
+    let children = p.getChildren(parentId: "a", page: 0, pageSize: 50)
+    XCTAssertEqual(children.map { $0.id }, ["a-1", "a-2", "a-3"])
+  }
+
+  func testGetChildrenOfUnknownParentReturnsEmpty() {
+    let p = CarPlayBrowseDataProvider()
+    p.setSnapshot(
+      BrowseSnapshot(rootId: "root", sections: [section("a", items: [item("a-1")])])
+    )
+    XCTAssertTrue(p.getChildren(parentId: "missing", page: 0, pageSize: 50).isEmpty)
+  }
+
+  func testGetChildrenPaginates() {
+    let p = CarPlayBrowseDataProvider()
+    let items = (0..<20).map { item("i-\($0)") }
+    p.setSnapshot(BrowseSnapshot(rootId: "root", sections: [section("a", items: items)]))
+
+    let page0 = p.getChildren(parentId: "a", page: 0, pageSize: 5)
+    XCTAssertEqual(page0.map { $0.id }, ["i-0", "i-1", "i-2", "i-3", "i-4"])
+
+    let page2 = p.getChildren(parentId: "a", page: 2, pageSize: 5)
+    XCTAssertEqual(page2.map { $0.id }, ["i-10", "i-11", "i-12", "i-13", "i-14"])
+  }
+
+  func testGetChildrenPageBeyondEndReturnsEmpty() {
+    let p = CarPlayBrowseDataProvider()
+    p.setSnapshot(
+      BrowseSnapshot(rootId: "root",
+                     sections: [section("a", items: [item("a-1"), item("a-2")])])
+    )
+    XCTAssertTrue(p.getChildren(parentId: "a", page: 5, pageSize: 5).isEmpty)
+  }
+
+  func testGetChildrenPageSizeZeroIsUnbounded() {
+    let p = CarPlayBrowseDataProvider()
+    let items = (0..<3).map { item("i-\($0)") }
+    p.setSnapshot(BrowseSnapshot(rootId: "root", sections: [section("a", items: items)]))
+    XCTAssertEqual(
+      p.getChildren(parentId: "a", page: 0, pageSize: 0).map { $0.id },
+      ["i-0", "i-1", "i-2"]
+    )
+  }
+
+  func testGetChildrenNegativePageReturnsEmpty() {
+    let p = CarPlayBrowseDataProvider()
+    p.setSnapshot(
+      BrowseSnapshot(rootId: "root",
+                     sections: [section("a", items: [item("a-1")])])
+    )
+    XCTAssertTrue(p.getChildren(parentId: "a", page: -1, pageSize: 5).isEmpty)
+  }
+
+  // MARK: - Changed-parent computation
+
+  func testSetSnapshotReturnsAffectedParents() {
+    let p = CarPlayBrowseDataProvider()
+    let initial = BrowseSnapshot(
+      rootId: "root",
+      sections: [section("a"), section("b")]
+    )
+    let firstChanged = p.setSnapshot(initial)
+    XCTAssertEqual(firstChanged, ["root", "a", "b"])
+
+    // Replace one section + add a new one. Returns root + a (gone) +
+    // b (still present in old + new) + c (new) — every parentId
+    // touched by either snapshot.
+    let next = BrowseSnapshot(
+      rootId: "root",
+      sections: [section("b"), section("c")]
+    )
+    let secondChanged = p.setSnapshot(next)
+    XCTAssertEqual(secondChanged, ["root", "a", "b", "c"])
+  }
+
+  func testSetSnapshotNilOnNilReturnsEmpty() {
+    let p = CarPlayBrowseDataProvider()
+    let changed = p.setSnapshot(nil)
+    XCTAssertTrue(changed.isEmpty)
+  }
+
+  // MARK: - Notification dispatch
+
+  func testSetSnapshotPostsDidUpdateNotification() {
+    let p = CarPlayBrowseDataProvider()
+    let exp = expectation(forNotification: CarPlayBrowseDataProvider.didUpdateNotification,
+                          object: p,
+                          handler: { note in
+      let payload = note.userInfo?[CarPlayBrowseDataProvider.changedParentsKey]
+        as? Set<String>
+      return payload == ["root", "a"]
+    })
+    DispatchQueue.global().async {
+      p.setSnapshot(BrowseSnapshot(rootId: "root", sections: [self.section("a")]))
+    }
+    wait(for: [exp], timeout: 2)
+  }
+}

package/ios/Tests/CastNowPlayingControllerTests.swift

@@ -0,0 +1,204 @@
+import MediaPlayer
+import XCTest
+@testable import QueuePlayer
+
+/// `CastNowPlayingController` drives `MPNowPlayingInfoCenter` while a
+/// Chromecast `CastSessionRemotePlayer` is active. Tests activate the
+/// shared controller through the real `PlaybackStateRouter`, drive a
+/// listener-firing fake session, and assert the lockscreen dictionary.
+///
+/// `MPNowPlayingInfoCenter.default()` + both singletons are process-
+/// global, so each test resets the router, stops the controller, and
+/// nils the dictionary in setUp + tearDown.
+final class CastNowPlayingControllerTests: XCTestCase {
+
+  private let router = PlaybackStateRouter.shared
+  private let controller = CastNowPlayingController.shared
+
+  override func setUp() {
+    super.setUp()
+    router._resetForTesting()
+    MPNowPlayingInfoCenter.default().nowPlayingInfo = nil
+    controller.start()
+  }
+
+  override func tearDown() {
+    controller.stop()
+    router._resetForTesting()
+    MPNowPlayingInfoCenter.default().nowPlayingInfo = nil
+    super.tearDown()
+  }
+
+  private var info: [String: Any]? {
+    MPNowPlayingInfoCenter.default().nowPlayingInfo
+  }
+
+  func testActivationSeedsAudioTypeAndPlaceholderArtwork() throws {
+    try router.setActive(ControllableRemoteSession())
+    XCTAssertEqual(
+      info?[MPNowPlayingInfoPropertyMediaType] as? UInt,
+      MPNowPlayingInfoMediaType.audio.rawValue
+    )
+    XCTAssertNotNil(
+      info?[MPMediaItemPropertyArtwork],
+      "the lockscreen seeds a placeholder so it is never artwork-less"
+    )
+  }
+
+  func testUpdateTrackMetadataWritesTitleArtistAlbum() throws {
+    try router.setActive(ControllableRemoteSession())
+    controller.updateTrackMetadata(
+      title: "Song", artist: "Artist", album: "Album",
+      durationSec: 180, artworkUrl: nil
+    )
+    XCTAssertEqual(info?[MPMediaItemPropertyTitle] as? String, "Song")
+    XCTAssertEqual(info?[MPMediaItemPropertyArtist] as? String, "Artist")
+    XCTAssertEqual(info?[MPMediaItemPropertyAlbumTitle] as? String, "Album")
+  }
+
+  func testDurationPrefersReceiverStreamDuration() throws {
+    let session = ControllableRemoteSession()
+    session.lastDurationMs = 200_000
+    try router.setActive(session)
+    // Consumer-supplied duration (5s) is untrusted; the receiver's live
+    // 200s stream duration wins.
+    controller.updateTrackMetadata(
+      title: "S", artist: nil, album: nil,
+      durationSec: 5, artworkUrl: nil
+    )
+    XCTAssertEqual(
+      info?[MPMediaItemPropertyPlaybackDuration] as? Double, 200.0
+    )
+  }
+
+  func testStateListenerDrivesPlaybackRate() throws {
+    let session = ControllableRemoteSession()
+    try router.setActive(session)
+    session.fireState(.playing)
+    XCTAssertEqual(info?[MPNowPlayingInfoPropertyPlaybackRate] as? Double, 1.0)
+    session.fireState(.paused)
+    XCTAssertEqual(info?[MPNowPlayingInfoPropertyPlaybackRate] as? Double, 0.0)
+  }
+
+  func testPositionListenerDrivesElapsed() throws {
+    let session = ControllableRemoteSession()
+    try router.setActive(session)
+    session.firePosition(positionMs: 30_000)
+    XCTAssertEqual(
+      info?[MPNowPlayingInfoPropertyElapsedPlaybackTime] as? Double, 30.0
+    )
+  }
+
+  func testPositionListenerRepublishesDuration() throws {
+    let session = ControllableRemoteSession()
+    try router.setActive(session)
+    // Duration arrives on a later position tick, after the initial
+    // refresh saw 0 — it must reach the scrubber.
+    session.firePosition(positionMs: 1_000, durationMs: 240_000)
+    XCTAssertEqual(
+      info?[MPMediaItemPropertyPlaybackDuration] as? Double, 240.0
+    )
+  }
+
+  func testDeactivateClearsNowPlayingInfo() throws {
+    try router.setActive(ControllableRemoteSession())
+    controller.updateTrackMetadata(
+      title: "S", artist: nil, album: nil, durationSec: 0, artworkUrl: nil
+    )
+    XCTAssertNotNil(info)
+    try router.setActive(nil)
+    XCTAssertNil(info, "the lockscreen surface is released on disconnect")
+  }
+
+  func testPushSinkSessionDoesNotTakeLockscreen() throws {
+    let airplay = ControllableRemoteSession()
+    airplay.pushSink = true
+    try router.setActive(airplay)
+    XCTAssertNil(
+      info,
+      "AirPlay keeps the local AVAudioSession alive; the cast controller stays out"
+    )
+  }
+
+  func testMetadataPushedBeforeActivationAppearsOnActivate() throws {
+    // No active session yet — the push is cached, not written.
+    controller.updateTrackMetadata(
+      title: "Cached", artist: nil, album: nil, durationSec: 0, artworkUrl: nil
+    )
+    XCTAssertNil(info)
+    try router.setActive(ControllableRemoteSession())
+    XCTAssertEqual(
+      info?[MPMediaItemPropertyTitle] as? String, "Cached",
+      "activation renders the most recent cached metadata"
+    )
+  }
+}
+
+// MARK: - Listener-firing fake
+
+/// `CastSessionRemotePlayer` whose state / position / currentItemId
+/// listeners can be fired on demand, so controller behaviour can be
+/// driven deterministically. Transport calls are no-ops.
+final class ControllableRemoteSession: CastSessionRemotePlayer {
+  var pushSink = false
+  var isPushSink: Bool { pushSink }
+
+  var lastState: RemotePlaybackStateKind = .idle
+  var lastPositionMs: Int64 = 0
+  var lastDurationMs: Int64 = 0
+  var lastBufferedMs: Int64 = 0
+  var lastCurrentTrackIndex: Int = -1
+  var lastVolume: Float = .nan
+
+  private var stateCb: ((RemotePlaybackStateKind) -> Void)?
+  private var positionCb: ((Int64, Int64, Int64) -> Void)?
+
+  func fireState(_ state: RemotePlaybackStateKind) {
+    lastState = state
+    stateCb?(state)
+  }
+
+  func firePosition(positionMs: Int64, durationMs: Int64 = 0, bufferedMs: Int64 = 0) {
+    lastPositionMs = positionMs
+    lastDurationMs = durationMs
+    positionCb?(positionMs, durationMs, bufferedMs)
+  }
+
+  func addStateListener(_ cb: @escaping (RemotePlaybackStateKind) -> Void) -> () -> Void {
+    stateCb = cb
+    return { [weak self] in self?.stateCb = nil }
+  }
+
+  func addPositionListener(_ cb: @escaping (Int64, Int64, Int64) -> Void) -> () -> Void {
+    positionCb = cb
+    return { [weak self] in self?.positionCb = nil }
+  }
+
+  func addCurrentTrackIndexListener(_ cb: @escaping (Int) -> Void) -> () -> Void { {} }
+  func addEndedReasonListener(_ cb: @escaping (RemoteEndReasonKind) -> Void) -> () -> Void { {} }
+  func addMediaErrorListener(_ cb: @escaping (RemoteMediaErrorPayload) -> Void) -> () -> Void { {} }
+  func addSeekCompletedListener(_ cb: @escaping (Int64) -> Void) -> () -> Void { {} }
+  func addVolumeListener(_ cb: @escaping (Float) -> Void) -> () -> Void { {} }
+
+  func setVolume(_ value: Float) {}
+  func close() {}
+  func play() {}
+  func pause() {}
+  func stop() {}
+  func seekTo(positionMs: Int64) {}
+  func seekBy(deltaMs: Int64) {}
+  func queueNext() {}
+  func queuePrev() {}
+  func skipToQueueIndex(index: Int) {}
+  func setPlaybackRate(_ rate: Float) {}
+  func setRepeatMode(_ mode: RemoteRepeatMode) {}
+
+  func load(items: [CastMediaItem], startIndex: Int, startPositionMs: Int64, playWhenReady: Bool) async throws -> [Int] {
+    (0..<items.count).map { $0 + 1 }
+  }
+
+  func queueInsert(items: [CastMediaItem], beforeIndex: Int?) async throws {}
+  func queueRemove(indices: [Int]) async throws {}
+  func queueMove(fromIndex: Int, toIndex: Int) async throws {}
+  func queueClear() async throws {}
+}

package/ios/Tests/CrossfadeEngineStubTests.swift

@@ -0,0 +1,43 @@
+import AVFoundation
+import XCTest
+@testable import QueuePlayer
+
+/// Stub coverage for `CrossfadeEngine`. Constructor non-crash and
+/// delegate wirability are the only assertable surfaces — every
+/// runtime method crashes via `preconditionFailure`, which is
+/// non-recoverable from XCTest. The Kotlin counterpart asserts
+/// `NotImplementedError` on every method via `assertThrows`; on
+/// Swift the equivalent would require a crash-runner test
+/// harness, which adds infra for low value here.
+///
+/// Negative-duration constructor guard at
+/// `CrossfadeEngine.init(crossfadeDurationSeconds:)` is also
+/// non-testable for the same reason. The load-bearing guard for
+/// runtime callers is the clamp inside `PlaybackModeStateMachine`;
+/// the constructor `precondition` is a defensive belt.
+final class CrossfadeEngineStubTests: XCTestCase {
+
+  func testConstructorAcceptsNonNegativeCrossfadeDuration() {
+    let engine = CrossfadeEngine(crossfadeDurationSeconds: 5.0)
+    XCTAssertNotNil(engine)
+  }
+
+  func testDelegateIsWirableOnTheStub() {
+    let engine = CrossfadeEngine(crossfadeDurationSeconds: 5.0)
+    let delegate = NoopDelegate()
+    engine.delegate = delegate
+    XCTAssertTrue(engine.delegate === delegate)
+  }
+}
+
+private final class NoopDelegate: PlaybackEngineDelegate {
+  func engineStateMaybeChanged(_ engine: PlaybackEngine, reason: StateChangeReason?) {}
+  func engineIsPlayingChanged(_ engine: PlaybackEngine, isPlaying: Bool) {}
+  func engineDidTransitionTrack(_ engine: PlaybackEngine) {}
+  func engineActiveItemFormatChanged(_ engine: PlaybackEngine) {}
+  func engineDidFailWithError(_ engine: PlaybackEngine, error: Error) {}
+  func engineDidPlayItemToEnd(_ engine: PlaybackEngine) {}
+  func enginePlaybackEnded(_ engine: PlaybackEngine) {}
+  func engineCrossfadeDidBegin(_ engine: PlaybackEngine, incomingIndex: Int) {}
+  func engineCrossfadeDidCancel(_ engine: PlaybackEngine, revertedIndex: Int) {}
+}