react-native-queue-player 1.0.0

package/ios/Tests/PlaybackEngineProtocolTests.swift

@@ -0,0 +1,92 @@
+import AVFoundation
+import XCTest
+@testable import QueuePlayer
+
+/// Type-check coverage for `PlaybackEngine` + `PlaybackEngineDelegate`
+/// + `AudioMixProvider`. The protocols have no runtime; this suite
+/// exercises the type surface so a regression that drops a method
+/// or rotates a parameter shape surfaces immediately. Goes away once
+/// the real `GaplessEngine` impl pins the type surface from a
+/// runtime perspective.
+final class PlaybackEngineProtocolTests: XCTestCase {
+
+  func testProtocolSurfaceCompiles() {
+    let stub = NoopPlaybackEngine()
+    XCTAssertEqual(stub.currentMediaItemIndex, -1)
+    XCTAssertEqual(stub.currentPositionSeconds, 0)
+    XCTAssertEqual(stub.currentDurationSeconds, 0)
+    XCTAssertEqual(stub.bufferedPositionSeconds, 0)
+    XCTAssertFalse(stub.isPlaying)
+    XCTAssertNil(stub.currentMediaItem)
+    XCTAssertEqual(stub.allMediaItems.count, 0)
+  }
+
+  func testDelegateSurfaceCompiles() {
+    let delegate = NoopDelegate()
+    let stub = NoopPlaybackEngine()
+    stub.delegate = delegate
+    XCTAssertTrue(stub.delegate === delegate)
+  }
+
+  func testAudioMixProviderRegistration() {
+    let stub = NoopPlaybackEngine()
+    let provider = NoopMixProvider()
+    stub.setAudioMixProvider(provider)
+    stub.refreshAllItemMixes()
+    stub.setAudioMixProvider(nil)
+  }
+}
+
+private final class NoopPlaybackEngine: PlaybackEngine {
+  func prepare(items: [AVPlayerItem], startIndex: Int, startPositionSeconds: TimeInterval) async {}
+  func release() {}
+  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() {}
+  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) {}
+
+  var currentMediaItemIndex: Int { -1 }
+  var currentPositionSeconds: TimeInterval { 0 }
+  var currentDurationSeconds: TimeInterval { 0 }
+  var bufferedPositionSeconds: TimeInterval { 0 }
+  var isPlaying: Bool { false }
+  var timeControlStatus: AVPlayer.TimeControlStatus { .paused }
+  var currentMediaItem: AVPlayerItem? { nil }
+  var allMediaItems: [AVPlayerItem] { [] }
+
+  func setAudioMixProvider(_ provider: AudioMixProvider?) {}
+  func refreshAllItemMixes() {}
+
+  func handoff(to nextEngine: PlaybackEngine, atTrackBoundary: Bool) async {}
+
+  var delegate: PlaybackEngineDelegate?
+}
+
+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) {}
+}
+
+private final class NoopMixProvider: AudioMixProvider {
+  func audioMix(for item: AVPlayerItem) -> AVAudioMix? { nil }
+}

package/ios/Tests/PlaybackErrorMappingTests.swift

@@ -0,0 +1,179 @@
+import XCTest
+@testable import QueuePlayer
+@_spi(QueuePlayerTests) import QueuePlayer
+import AVFoundation
+
+/// Unit tests for the iOS half of the cross-platform error-code
+/// mapping in `PlaybackErrorMapping.swift`.
+/// Mirrors the Android-side coverage in
+/// `TrackPlayerEventsTest.kt#error mapping classifies Media3 codes`
+/// + `error mapping strips query strings`.
+///
+/// **Why string-keyed assertions?** NOTES.md §6 — Swift's
+/// `-cxx-interoperability-mode=default` hides members of functions
+/// whose signatures touch Nitrogen-generated C++-backed types
+/// (PlaybackErrorCode is one) when viewed from a separate test
+/// module. The lib exposes a `*Raw` surface returning Strings as a
+/// workaround; tests assert on the SCREAMING_SNAKE_CASE string
+/// values from `PlaybackErrorCode.stringValue`.
+final class PlaybackErrorMappingTests: XCTestCase {
+
+  // MARK: - classifyRaw(NSError?)
+
+  func testClassifyNilUnderlyingReturnsCannotOpen() {
+    // When `item.error` is nil (e.g. AVPlayerItem reached `.failed`
+    // without a downstream NSError), classify falls back to the
+    // user-visible "Cannot Open" code. Treated as transient because
+    // the overwhelmingly common cause in the wild is a slow-spin-up
+    // server, not corruption.
+    XCTAssertEqual(PlaybackErrorMapping.classifyRaw(nil), "CANNOT_OPEN")
+  }
+
+  func testClassifyNSURLErrorTimedOutMapsToTimeout() {
+    let err = NSError(domain: NSURLErrorDomain, code: NSURLErrorTimedOut)
+    XCTAssertEqual(PlaybackErrorMapping.classifyRaw(err), "TIMEOUT")
+  }
+
+  func testClassifyNSURLErrorNotConnectedMapsToNetworkUnreachable() {
+    let err = NSError(domain: NSURLErrorDomain, code: NSURLErrorNotConnectedToInternet)
+    XCTAssertEqual(PlaybackErrorMapping.classifyRaw(err), "NETWORK_UNREACHABLE")
+  }
+
+  func testClassifyNSURLErrorConnectionLostMapsToConnectionLost() {
+    let err = NSError(domain: NSURLErrorDomain, code: NSURLErrorNetworkConnectionLost)
+    XCTAssertEqual(PlaybackErrorMapping.classifyRaw(err), "CONNECTION_LOST")
+  }
+
+  func testClassifyNSURLErrorBadURLMapsToSourceUnreachable() {
+    let err = NSError(domain: NSURLErrorDomain, code: NSURLErrorBadURL)
+    XCTAssertEqual(PlaybackErrorMapping.classifyRaw(err), "SOURCE_UNREACHABLE")
+  }
+
+  func testClassifyNSURLErrorATSMapsToCleartextNotPermitted() {
+    let err = NSError(
+      domain: NSURLErrorDomain,
+      code: NSURLErrorAppTransportSecurityRequiresSecureConnection
+    )
+    XCTAssertEqual(PlaybackErrorMapping.classifyRaw(err), "CLEARTEXT_NOT_PERMITTED")
+  }
+
+  func testClassifyNSURLErrorAuthMapsToAuthError() {
+    let err = NSError(domain: NSURLErrorDomain, code: NSURLErrorUserAuthenticationRequired)
+    XCTAssertEqual(PlaybackErrorMapping.classifyRaw(err), "AUTH_ERROR")
+  }
+
+  func testClassifyAVErrorFileFormatNotRecognized() {
+    let err = NSError(domain: AVFoundationErrorDomain, code: -11828)
+    XCTAssertEqual(PlaybackErrorMapping.classifyRaw(err), "FILE_FORMAT_NOT_RECOGNIZED")
+  }
+
+  func testClassifyAVErrorDecoderNotFound() {
+    let err = NSError(domain: AVFoundationErrorDomain, code: -11833)
+    XCTAssertEqual(PlaybackErrorMapping.classifyRaw(err), "DECODER_NOT_FOUND")
+  }
+
+  func testClassifyAVErrorMediaServicesWereResetMapsToCannotOpen() {
+    let err = NSError(domain: AVFoundationErrorDomain, code: -11819)
+    XCTAssertEqual(PlaybackErrorMapping.classifyRaw(err), "CANNOT_OPEN")
+  }
+
+  func testClassifyAVErrorWithNSURLUnderlyingMapsToCannotOpenTransient() {
+    // Two-tier classifier: bare unknown AVError IS fatal (.unknown);
+    // wrapped network underlying is transient (.cannotOpen).
+    let inner = NSError(domain: NSURLErrorDomain, code: NSURLErrorTimedOut)
+    let outer = NSError(
+      domain: AVFoundationErrorDomain,
+      code: -99999,  // unknown AVError code
+      userInfo: [NSUnderlyingErrorKey: inner]
+    )
+    XCTAssertEqual(
+      PlaybackErrorMapping.classifyRaw(outer), "CANNOT_OPEN",
+      "AVError with NSURL underlying must map to transient CANNOT_OPEN"
+    )
+    XCTAssertTrue(
+      PlaybackErrorMapping.isTransientRaw("CANNOT_OPEN"),
+      "CANNOT_OPEN must be classified transient so auto-retry kicks in"
+    )
+  }
+
+  func testClassifyBareUnknownAVErrorIsUnknown() {
+    let err = NSError(domain: AVFoundationErrorDomain, code: -99999)
+    XCTAssertEqual(PlaybackErrorMapping.classifyRaw(err), "UNKNOWN")
+  }
+
+  func testClassifyOtherDomainReturnsUnknown() {
+    let err = NSError(domain: "CoreMediaErrorDomain", code: 12345)
+    XCTAssertEqual(PlaybackErrorMapping.classifyRaw(err), "UNKNOWN")
+  }
+
+  // MARK: - isTransientRaw — drives auto-retry eligibility
+
+  func testIsTransientFlagsNetworkClass() {
+    XCTAssertTrue(PlaybackErrorMapping.isTransientRaw("TIMEOUT"))
+    XCTAssertTrue(PlaybackErrorMapping.isTransientRaw("CONNECTION_LOST"))
+    XCTAssertTrue(PlaybackErrorMapping.isTransientRaw("NETWORK_UNREACHABLE"))
+    XCTAssertTrue(PlaybackErrorMapping.isTransientRaw("SOURCE_UNREACHABLE"))
+    XCTAssertTrue(PlaybackErrorMapping.isTransientRaw("CANNOT_OPEN"))
+    XCTAssertTrue(PlaybackErrorMapping.isTransientRaw("UNKNOWN"))
+  }
+
+  func testIsTransientFlagsCodecClassFatal() {
+    XCTAssertFalse(PlaybackErrorMapping.isTransientRaw("FILE_FORMAT_NOT_RECOGNIZED"))
+    XCTAssertFalse(PlaybackErrorMapping.isTransientRaw("DECODER_NOT_FOUND"))
+    XCTAssertFalse(PlaybackErrorMapping.isTransientRaw("DECODING_FAILED"))
+  }
+
+  func testIsTransientFlagsAuthAndCleartextFatal() {
+    XCTAssertFalse(PlaybackErrorMapping.isTransientRaw("HTTP_ERROR"))
+    XCTAssertFalse(PlaybackErrorMapping.isTransientRaw("AUTH_ERROR"))
+    XCTAssertFalse(PlaybackErrorMapping.isTransientRaw("CLEARTEXT_NOT_PERMITTED"))
+  }
+
+  // MARK: - stripQuery — PII safe
+
+  func testStripQueryRemovesQueryString() {
+    let raw = "Source error at https://server.example/stream?u=user&t=token rejected"
+    let stripped = PlaybackErrorMapping.stripQuery(raw)
+    XCTAssertFalse(stripped.contains("u=user"))
+    XCTAssertFalse(stripped.contains("t=token"))
+    XCTAssertTrue(stripped.contains("https://server.example/stream"))
+    XCTAssertTrue(stripped.contains("rejected"))
+  }
+
+  func testStripQueryNoOpWhenNoQueryString() {
+    let raw = "decoder failed: codec MP3 not available"
+    XCTAssertEqual(PlaybackErrorMapping.stripQuery(raw), raw)
+  }
+
+  func testStripQueryHandlesQueryAtEnd() {
+    let raw = "https://example.com/x?a=1&b=2"
+    let stripped = PlaybackErrorMapping.stripQuery(raw)
+    XCTAssertEqual(stripped, "https://example.com/x")
+  }
+
+  // MARK: - messageForRaw — lib-mapped human-readable
+
+  func testMessageForReturnsConsistentStrings() {
+    // Spot-check that every code maps to a non-empty, sentence-case
+    // message ending with a period. Cross-platform consumers compare
+    // these against localized strings; empty / capitalisation drift
+    // would surface as inconsistent UX.
+    for codeString in [
+      "TIMEOUT", "CONNECTION_LOST", "NETWORK_UNREACHABLE",
+      "HTTP_ERROR", "AUTH_ERROR", "CLEARTEXT_NOT_PERMITTED",
+      "FILE_FORMAT_NOT_RECOGNIZED", "DECODER_NOT_FOUND", "DECODING_FAILED",
+      "SOURCE_UNREACHABLE", "CANNOT_OPEN", "UNKNOWN"
+    ] {
+      let message = PlaybackErrorMapping.messageForRaw(codeString)
+      XCTAssertFalse(message.isEmpty, "messageForRaw(\(codeString)) must not be empty")
+      XCTAssertTrue(
+        message.first?.isUppercase ?? false,
+        "messageForRaw(\(codeString)) should be sentence-case"
+      )
+      XCTAssertTrue(
+        message.hasSuffix("."),
+        "messageForRaw(\(codeString)) should end with a period"
+      )
+    }
+  }
+}

package/ios/Tests/PlaybackModeStateMachineTests.swift

@@ -0,0 +1,40 @@
+import XCTest
+@testable import QueuePlayer
+
+/// Coverage for the pure-Swift `CrossfadeDurationBounds` helper that
+/// powers `PlaybackModeStateMachine.requireValid`. Full state-machine
+/// validation coverage (constructing `PlaybackMode` instances + driving
+/// `setRequested`) lives in the Android Robolectric suite — `PlaybackMode`
+/// is bridged via Nitro `@_spi` and can't be constructed from a Swift
+/// XCTest target, so the throws path is exercised end-to-end via the
+/// in-app TS test runner's `playback-mode` suite (the
+/// `crossfade-duration-out-of-range-rejected` and
+/// `crossfade-duration-non-quantised-rejected` steps in
+/// `RNQP-Demo/src/tests/suites/playback-mode.ts`). Mirrors the
+/// cxx-interop carve-out already documented in AGENTS.md §2.
+final class PlaybackModeStateMachineTests: XCTestCase {
+
+  func testCrossfadeBoundsHelperAcceptsEveryValueOnTheStep() {
+    var ms = CrossfadeDurationBounds.minMs
+    while ms <= CrossfadeDurationBounds.maxMs {
+      XCTAssertTrue(
+        CrossfadeDurationBounds.isQuantised(ms),
+        "expected \(ms) to be on a \(CrossfadeDurationBounds.stepMs)ms boundary")
+      ms += CrossfadeDurationBounds.stepMs
+    }
+  }
+
+  func testCrossfadeBoundsHelperRejectsNonQuantisedValues() {
+    for ms in [1_001.0, 1_234.0, 5_500.5, 7_777.0, 11_999.0] {
+      XCTAssertFalse(
+        CrossfadeDurationBounds.isQuantised(ms),
+        "expected \(ms) to be rejected as off-step")
+    }
+  }
+
+  func testCrossfadeBoundsHelperConstants() {
+    XCTAssertEqual(CrossfadeDurationBounds.minMs, 1_000)
+    XCTAssertEqual(CrossfadeDurationBounds.maxMs, 12_000)
+    XCTAssertEqual(CrossfadeDurationBounds.stepMs, 500)
+  }
+}

package/ios/Tests/PlaybackStateRouterTests.swift

@@ -0,0 +1,178 @@
+import XCTest
+@testable import QueuePlayer
+
+final class PlaybackStateRouterTests: XCTestCase {
+
+  private let router = PlaybackStateRouter.shared
+
+  override func setUp() {
+    super.setUp()
+    router._resetForTesting()
+  }
+
+  override func tearDown() {
+    router._resetForTesting()
+    super.tearDown()
+  }
+
+  func testActiveRemoteStartsNil() {
+    XCTAssertNil(router.activeRemote())
+  }
+
+  func testSetActiveStoresSessionThenClearGoesNil() throws {
+    let session = FakeRemoteSession()
+    try router.setActive(session)
+    XCTAssertTrue(router.activeRemote() === session)
+    try router.setActive(nil)
+    XCTAssertNil(router.activeRemote())
+  }
+
+  func testSetActiveWithSecondSessionThrowsAlreadyActive() throws {
+    let first = FakeRemoteSession()
+    let second = FakeRemoteSession()
+    try router.setActive(first)
+    XCTAssertThrowsError(try router.setActive(second)) { err in
+      XCTAssertEqual(
+        err as? PlaybackStateRouter.CastRouterError,
+        .alreadyActive
+      )
+    }
+    XCTAssertTrue(router.activeRemote() === first)
+  }
+
+  func testReRegisterSameSessionIsNoOp() throws {
+    let session = FakeRemoteSession()
+    try router.setActive(session)
+    try router.setActive(session)  // no throw, no listener fire
+    XCTAssertTrue(router.activeRemote() === session)
+  }
+
+  func testClearActiveOnlyClearsExpectedSession() throws {
+    let first = FakeRemoteSession()
+    let unrelated = FakeRemoteSession()
+    try router.setActive(first)
+    router.clearActive(expected: unrelated)
+    XCTAssertTrue(
+      router.activeRemote() === first,
+      "clearActive(expected:) is a compare-and-clear; mismatched expected is a no-op"
+    )
+    router.clearActive(expected: first)
+    XCTAssertNil(router.activeRemote())
+  }
+
+  func testListenerFiresOnEveryTransition() throws {
+    var seen: [ObjectIdentifier?] = []
+    _ = router.addActiveChangeListener { session in
+      seen.append(session.map { ObjectIdentifier($0) })
+    }
+    let session = FakeRemoteSession()
+    try router.setActive(session)
+    try router.setActive(nil)
+
+    XCTAssertEqual(seen.count, 2)
+    XCTAssertEqual(seen[0], ObjectIdentifier(session))
+    XCTAssertNil(seen[1])
+  }
+
+  func testListenerDoesNotFireOnReRegisterSameSession() throws {
+    var fireCount = 0
+    _ = router.addActiveChangeListener { _ in fireCount += 1 }
+    let session = FakeRemoteSession()
+    try router.setActive(session)
+    try router.setActive(session)
+    XCTAssertEqual(fireCount, 1)
+  }
+
+  func testListenerDoesNotFireOnRedundantClear() throws {
+    var fireCount = 0
+    _ = router.addActiveChangeListener { _ in fireCount += 1 }
+    try router.setActive(nil)
+    try router.setActive(nil)
+    XCTAssertEqual(fireCount, 0)
+  }
+
+  func testDisposerRemovesListener() throws {
+    var fireCount = 0
+    let dispose = router.addActiveChangeListener { _ in fireCount += 1 }
+    let session = FakeRemoteSession()
+    try router.setActive(session)
+    XCTAssertEqual(fireCount, 1)
+    dispose()
+    try router.setActive(nil)
+    XCTAssertEqual(fireCount, 1, "disposed listener does not fire")
+  }
+
+  func testListenerNotInvokedOnSubscribe() throws {
+    let session = FakeRemoteSession()
+    try router.setActive(session)
+    var fireCount = 0
+    _ = router.addActiveChangeListener { _ in fireCount += 1 }
+    XCTAssertEqual(
+      fireCount, 0,
+      "subscribe does not replay the current value; callers read activeRemote() for the snapshot"
+    )
+  }
+
+}
+
+// MARK: - Fake session
+
+/// Minimal `CastSessionRemotePlayer` conformance for routing tests.
+/// All transport calls record into invocation arrays; state getters
+/// return deterministic seed values.
+final class FakeRemoteSession: CastSessionRemotePlayer {
+  var isPushSink: Bool { false }
+
+  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(set) var playCalls = 0
+  private(set) var pauseCalls = 0
+  private(set) var stopCalls = 0
+  private(set) var seekCalls: [Int64] = []
+  private(set) var seekByCalls: [Int64] = []
+  private(set) var queueNextCalls = 0
+  private(set) var queuePrevCalls = 0
+  private(set) var queueJumpCalls: [Int] = []
+  private(set) var volumeCalls: [Float] = []
+  private(set) var playbackRateCalls: [Float] = []
+  private(set) var repeatModeCalls: [RemoteRepeatMode] = []
+  private(set) var loadCalls: [(items: [CastMediaItem], startIndex: Int, startPositionMs: Int64)] = []
+  private(set) var closeCalls = 0
+
+  func setVolume(_ value: Float) { volumeCalls.append(value) }
+  func close() { closeCalls += 1 }
+
+  func addStateListener(_ cb: @escaping (RemotePlaybackStateKind) -> Void) -> () -> Void { {} }
+  func addPositionListener(_ cb: @escaping (Int64, Int64, Int64) -> Void) -> () -> Void { {} }
+  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 play() { playCalls += 1 }
+  func pause() { pauseCalls += 1 }
+  func stop() { stopCalls += 1 }
+  func seekTo(positionMs: Int64) { seekCalls.append(positionMs) }
+  func seekBy(deltaMs: Int64) { seekByCalls.append(deltaMs) }
+  func queueNext() { queueNextCalls += 1 }
+  func queuePrev() { queuePrevCalls += 1 }
+  func skipToQueueIndex(index: Int) { queueJumpCalls.append(index) }
+  func setPlaybackRate(_ rate: Float) { playbackRateCalls.append(rate) }
+  func setRepeatMode(_ mode: RemoteRepeatMode) { repeatModeCalls.append(mode) }
+
+  func load(items: [CastMediaItem], startIndex: Int, startPositionMs: Int64, playWhenReady: Bool) async throws -> [Int] {
+    loadCalls.append((items, startIndex, startPositionMs))
+    return (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/PlayerStateDerivationTests.swift

@@ -0,0 +1,69 @@
+import AVFoundation
+import XCTest
+@testable import QueuePlayer
+
+/// Unit tests for `PlayerStateDerivation` — the pure `PlayerState` mapping
+/// shared by both engines. Native wiring (getState + the two emit paths + the
+/// end-of-queue latch) is covered by the queue-end / crossfade demo suites.
+final class PlayerStateDerivationTests: XCTestCase {
+
+  private func derive(
+    _ status: AVPlayer.TimeControlStatus,
+    index: Int = 0,
+    hasItem: Bool = true,
+    ended: Bool = false
+  ) -> PlayerState {
+    PlayerStateDerivation.translate(
+      status: status, currentIndex: index, hasCurrentItem: hasItem, reachedQueueEnd: ended)
+  }
+
+  // MARK: baseline (no end-of-queue latch)
+
+  func testPlayingIsPlaying() {
+    XCTAssertEqual(derive(.playing), .playing)
+  }
+
+  func testPausedWithTrackIsPaused() {
+    XCTAssertEqual(derive(.paused, index: 3), .paused)
+  }
+
+  func testPausedEmptyQueueIsNone() {
+    XCTAssertEqual(derive(.paused, index: -1), .none)
+  }
+
+  func testWaitingWithItemIsBuffering() {
+    // Waiting to play with a current item = initial load / rebuffer.
+    XCTAssertEqual(derive(.waitingToPlayAtSpecifiedRate, hasItem: true), .buffering)
+  }
+
+  func testWaitingWithoutItemEmptyQueueIsNone() {
+    XCTAssertEqual(derive(.waitingToPlayAtSpecifiedRate, index: -1, hasItem: false), .none)
+  }
+
+  func testWaitingWithoutItemNonEmptyQueueIsEndedFallback() {
+    // A drained AVQueuePlayer parks at .waitingToPlay with no item before the
+    // latch flips — the end-of-queue fallback covers the timing race.
+    XCTAssertEqual(derive(.waitingToPlayAtSpecifiedRate, index: 5, hasItem: false), .ended)
+  }
+
+  // MARK: reachedQueueEnd latch
+
+  func testLatchWithTrackNotPlayingIsEnded() {
+    // Any non-playing status at end-of-queue is terminal — the same result for
+    // both engines (crossfade keeps its finished item, so hasItem is true).
+    XCTAssertEqual(derive(.paused, index: 5, ended: true), .ended)
+    XCTAssertEqual(
+      derive(.waitingToPlayAtSpecifiedRate, index: 5, hasItem: true, ended: true), .ended)
+  }
+
+  func testLatchYieldsToPlaying() {
+    // Playing takes precedence over the latch, so a resume reads correctly even
+    // before the latch clears.
+    XCTAssertEqual(derive(.playing, index: 5, ended: true), .playing)
+  }
+
+  func testLatchIgnoredWhenQueueEmpty() {
+    // A cleared queue (index < 0) skips the latch and derives normally.
+    XCTAssertEqual(derive(.paused, index: -1, ended: true), .none)
+  }
+}

package/ios/Tests/ProgressEmissionGateTests.swift

@@ -0,0 +1,113 @@
+import XCTest
+@testable import QueuePlayer
+
+/// Unit tests for `ProgressEmissionGate` — the pure throttle behind the
+/// configurable / background-reduced `onProgress` cadence. Native wiring
+/// (the periodic tick, the cast push, and the UIApplication background /
+/// foreground observers) is covered by the progress demo suites.
+///
+/// Most tests pass `samplerPeriodMs: 0` to exercise exact interval semantics;
+/// the jitter + quantization tests pass the production `500` to verify the
+/// half-sampler tolerance that keeps a periodic sampler from dropping ticks.
+final class ProgressEmissionGateTests: XCTestCase {
+
+  func testFirstTickAlwaysEmits() {
+    var gate = ProgressEmissionGate()
+    gate.setIntervals(foregroundMs: 500, backgroundMs: 500, samplerPeriodMs: 0)
+    // lastEmittedMs starts at -infinity, so any first observation emits.
+    XCTAssertTrue(gate.shouldEmit(nowMs: 0))
+  }
+
+  func testForegroundCadenceSuppressesWithinTheInterval() {
+    var gate = ProgressEmissionGate()
+    gate.setIntervals(foregroundMs: 1000, backgroundMs: 1000, samplerPeriodMs: 0)
+    XCTAssertTrue(gate.shouldEmit(nowMs: 0)) // first
+    XCTAssertFalse(gate.shouldEmit(nowMs: 500)) // 500 < 1000
+    XCTAssertFalse(gate.shouldEmit(nowMs: 999))
+    XCTAssertTrue(gate.shouldEmit(nowMs: 1000)) // exactly the interval emits (>=)
+    XCTAssertFalse(gate.shouldEmit(nowMs: 1499))
+    XCTAssertTrue(gate.shouldEmit(nowMs: 2000))
+  }
+
+  func testBackgroundUsesTheSlowerInterval() {
+    var gate = ProgressEmissionGate()
+    gate.setIntervals(foregroundMs: 500, backgroundMs: 2000, samplerPeriodMs: 0)
+    XCTAssertTrue(gate.shouldEmit(nowMs: 0)) // first
+    gate.setBackgrounded(true)
+    // Now gated on 2000ms, so a 500ms and 1000ms tick both suppress.
+    XCTAssertFalse(gate.shouldEmit(nowMs: 500))
+    XCTAssertFalse(gate.shouldEmit(nowMs: 1000))
+    XCTAssertTrue(gate.shouldEmit(nowMs: 2000))
+  }
+
+  func testForegroundReturnFlushesImmediately() {
+    var gate = ProgressEmissionGate()
+    gate.setIntervals(foregroundMs: 500, backgroundMs: 10_000, samplerPeriodMs: 0)
+    XCTAssertTrue(gate.shouldEmit(nowMs: 0))
+    gate.setBackgrounded(true)
+    XCTAssertFalse(gate.shouldEmit(nowMs: 5000)) // still within the 10s bg interval
+    // Returning to the foreground forces the next tick to emit, even though
+    // only 5001ms have elapsed since the last background emit at t=0.
+    gate.setBackgrounded(false)
+    XCTAssertTrue(gate.shouldEmit(nowMs: 5001))
+    // Then the normal foreground cadence resumes.
+    XCTAssertFalse(gate.shouldEmit(nowMs: 5100))
+    XCTAssertTrue(gate.shouldEmit(nowMs: 5601))
+  }
+
+  func testBackgroundToBackgroundDoesNotFlush() {
+    var gate = ProgressEmissionGate()
+    gate.setIntervals(foregroundMs: 500, backgroundMs: 2000, samplerPeriodMs: 0)
+    XCTAssertTrue(gate.shouldEmit(nowMs: 0))
+    gate.setBackgrounded(true)
+    // A redundant setBackgrounded(true) must NOT reset the throttle position.
+    gate.setBackgrounded(true)
+    XCTAssertFalse(gate.shouldEmit(nowMs: 500))
+  }
+
+  func testForegroundToForegroundDoesNotFlush() {
+    var gate = ProgressEmissionGate()
+    gate.setIntervals(foregroundMs: 1000, backgroundMs: 1000, samplerPeriodMs: 0)
+    XCTAssertTrue(gate.shouldEmit(nowMs: 0))
+    // A no-op foreground→foreground transition must not reset the position.
+    gate.setBackgrounded(false)
+    XCTAssertFalse(gate.shouldEmit(nowMs: 500))
+  }
+
+  func testSetIntervalsTakesEffectPreservingPosition() {
+    var gate = ProgressEmissionGate()
+    gate.setIntervals(foregroundMs: 2000, backgroundMs: 2000, samplerPeriodMs: 0)
+    XCTAssertTrue(gate.shouldEmit(nowMs: 0))
+    XCTAssertFalse(gate.shouldEmit(nowMs: 1000)) // 1000 < 2000
+    // Tighten the cadence mid-stream; the last-emitted position is preserved,
+    // so a tick 600ms past the last emit now clears the new 500ms interval.
+    gate.setIntervals(foregroundMs: 500, backgroundMs: 500, samplerPeriodMs: 0)
+    XCTAssertTrue(gate.shouldEmit(nowMs: 600))
+  }
+
+  func testDefaultIntervalEmitsEveryTickDespiteJitter() {
+    // The production case: interval == the 500ms sampler period. With the
+    // half-sampler tolerance, ticks landing a hair under 500ms apart (timer
+    // jitter) still emit — otherwise ~half would drop and the rate would sag
+    // toward 1Hz.
+    var gate = ProgressEmissionGate()
+    gate.setIntervals(foregroundMs: 500, backgroundMs: 500, samplerPeriodMs: 500)
+    XCTAssertTrue(gate.shouldEmit(nowMs: 0))
+    XCTAssertTrue(gate.shouldEmit(nowMs: 480)) // 480 >= 500 - 250
+    XCTAssertTrue(gate.shouldEmit(nowMs: 955))
+    XCTAssertTrue(gate.shouldEmit(nowMs: 1440))
+  }
+
+  func testLargerIntervalQuantizesToEveryNthTick() {
+    // interval == 2× the sampler period ⇒ emit every other tick. The tolerance
+    // snaps the emit to the on-target tick (1000, 2000) without letting the
+    // intermediate ticks (500, 1500) through.
+    var gate = ProgressEmissionGate()
+    gate.setIntervals(foregroundMs: 1000, backgroundMs: 1000, samplerPeriodMs: 500)
+    XCTAssertTrue(gate.shouldEmit(nowMs: 0))
+    XCTAssertFalse(gate.shouldEmit(nowMs: 500)) // 500 < 1000 - 250
+    XCTAssertTrue(gate.shouldEmit(nowMs: 1000))
+    XCTAssertFalse(gate.shouldEmit(nowMs: 1500))
+    XCTAssertTrue(gate.shouldEmit(nowMs: 2000))
+  }
+}