react-native-queue-player 1.0.2 → 1.0.4

package/ios/ProgressEmissionGate.swift

@@ -1,6 +1,6 @@
 /// Throttles the JS `onProgress` fan-out to a configurable cadence, with an
 /// optional reduced rate while the app is backgrounded. Pure + deterministic
-/// (the caller supplies a monotonic timestamp), so it unit-tests directly.
+/// (the caller supplies a monotonic timestamp).
 ///
 /// This gates ONLY the JS emission — the native 2 Hz sampler keeps running, so
 /// milestone detection and buffer-state recomputation stay full-rate. A tick

package/ios/QueueMutationArithmetic.swift

@@ -1,10 +1,10 @@
 import Foundation
 
 /// Pure-Swift index-shift arithmetic for queue mutations. Extracted
-/// from `TrackPlayer.swift` so the shift semantics are unit-testable
+/// from `TrackPlayer.swift` so the shift semantics stand alone,
 /// without an AVQueuePlayer. Mirrors
 /// `android/.../QueueMutationArithmetic.kt` 1:1 — same function
-/// shapes, same input/output semantics, same test matrix.
+/// shapes, same input/output semantics.
 ///
 /// The helper only computes the new `currentTrackIndex` and (for
 /// `removeFromQueue`) which original indices apply after dedup /

package/ios/QueueSkipArithmetic.swift

@@ -1,23 +1,19 @@
 /// Pure-Swift skip-index arithmetic. Extracted from `TrackPlayer.swift`
-/// so the logic can be unit-tested without crossing the Swift ↔ C++
-/// interop boundary — Nitrogen-generated types (`TrackItem`, `RepeatMode`)
-/// don't export their members to importing modules under Swift's current
-/// `-cxx-interoperability-mode=default` settings, which makes `@testable
-/// import QueuePlayer` useless for touching anything that reads Nitro
-/// types. By taking primitive arguments, these helpers stay reachable
-/// from the XCTest bundle via plain `import QueuePlayer`.
+/// so the logic stays clear of the Swift ↔ C++ interop boundary —
+/// Nitrogen-generated types (`TrackItem`, `RepeatMode`) don't export
+/// their members to importing modules under Swift's current
+/// `-cxx-interoperability-mode=default` settings. These helpers take
+/// primitive arguments instead.
 ///
 /// `TrackPlayer.computeNextIndex` / `.computePreviousIndex` instance
 /// methods are thin adapters that map the Nitrogen `RepeatMode` enum
 /// onto `QueueSkipRepeatMode` and call through here.
 
 /// Repeat-mode enum expressed in plain Swift. Value order (0/1/2)
-/// matches `RepeatModeKind` in the nitro.ts spec, so a test that
-/// asserts the raw integer is robust against accidental reordering
-/// in the Nitrogen spec.
+/// matches `RepeatModeKind` in the nitro.ts spec.
 ///
-/// Gated behind `@_spi(QueuePlayerTests)` so the XCTest-only helper
-/// surface stays off the library's consumer-facing API.
+/// Gated behind `@_spi(QueuePlayerTests)` so the helper surface stays
+/// off the library's consumer-facing API.
 @_spi(QueuePlayerTests)
 public enum QueueSkipRepeatMode: Int {
   case off = 0

package/ios/Siri/PlayMediaIntentHandler.swift

@@ -189,11 +189,7 @@ internal final class PlayMediaIntentHandler: NSObject, INPlayMediaIntentHandling
   /// Map `INPlayMediaIntent.mediaSearch` into the lib's
   /// `MediaSearchRequest` shape so the consumer's JS resolver sees
   /// the same wire format regardless of voice surface (SiriKit on
-  /// iOS, Google Assistant on Android). Coverage lives at the
-  /// Maestro integration layer (`e2e/manual/siri-cold-start.md`
-  /// S1–S5) — the return type's cxx-interop bridging blocks
-  /// `@testable import` from constructing or comparing
-  /// `MediaSearchRequest` values in XCTest.
+  /// iOS, Google Assistant on Android).
   static func buildRequest(from intent: INPlayMediaIntent) -> MediaSearchRequest {
     let mediaSearch = intent.mediaSearch
     let mediaName = mediaSearch?.mediaName ?? ""

package/ios/SleepTimerCore.swift

@@ -1,7 +1,7 @@
 import Foundation
 
 /// Pure state machine for the sleep timer — no player, volume, or timer
-/// dependencies, so it is unit-testable in isolation. The owning `TrackPlayer`
+/// dependencies, so it stands alone. The owning `TrackPlayer`
 /// drives it from a repeating native timer and applies the returned decision
 /// (volume fade, pause) to the engine.
 ///
@@ -36,6 +36,11 @@ struct SleepTimerCore {
   // Guards the tail rule to a single track so a stalled/looping position can't
   // defer the pause forever.
   private var tailExtended = false
+  // True while an end-of-track timer is pending, and survives the conversion to
+  // a `.duration` fade so the real track-end signal (`fireAtTrackEnd`) knows to
+  // fire — the poll can't hit the boundary exactly and never fires at all when
+  // the duration is unknown (live/streaming).
+  private var originEndOfTrack = false
 
   let fadeSeconds: Double
   let tailGraceSeconds: Double
@@ -52,18 +57,31 @@ struct SleepTimerCore {
     mode = .duration
     deadlineEpochMs = nowMs + Int64(seconds * 1000)
     tailExtended = false
+    originEndOfTrack = false
   }
 
   mutating func armEndOfTrack() {
     mode = .endOfTrack
     deadlineEpochMs = nil
     tailExtended = false
+    originEndOfTrack = true
   }
 
   mutating func clear() {
     mode = .inactive
     deadlineEpochMs = nil
     tailExtended = false
+    originEndOfTrack = false
+  }
+
+  /// Fire the pending end-of-track timer at the current track's real end. The
+  /// owning player calls this from its track-end signal so the pause lands
+  /// exactly at the boundary (and fires even when the track duration was never
+  /// known). No-op unless an end-of-track timer is pending.
+  mutating func fireAtTrackEnd() -> Tick {
+    guard originEndOfTrack else { return .idle }
+    clear()
+    return Tick(fadeFraction: 1.0, pauseNow: true, stateChanged: true)
   }
 
   /// Whole seconds until the fixed deadline, or `nil` when inactive / awaiting
@@ -83,9 +101,13 @@ struct SleepTimerCore {
       // then let the duration branch ride it out + fire.
       if let tail = trackRemaining(trackDurationSec, trackPositionSec), tail <= tailGraceSeconds {
         mode = .duration
-        deadlineEpochMs = nowMs + Int64((tail + 1) * 1000)
+        // Deadline lands AT the track boundary (not 1s past it) so the fade
+        // completes at the end; on local playback the real track-end signal
+        // (fireAtTrackEnd) owns the actual pause, and this deadline is the
+        // fallback the cast path rides out on the receiver's clock.
+        deadlineEpochMs = nowMs + Int64(tail * 1000)
         tailExtended = true
-        return Tick(fadeFraction: fadeFraction(tail + 1), pauseNow: false, stateChanged: true)
+        return Tick(fadeFraction: fadeFraction(tail), pauseNow: false, stateChanged: true)
       }
       return .idle
 
@@ -106,9 +128,7 @@ struct SleepTimerCore {
         return Tick(fadeFraction: fadeFraction(tail + 1), pauseNow: false, stateChanged: true)
       }
       // Fire.
-      mode = .inactive
-      deadlineEpochMs = nil
-      tailExtended = false
+      clear()
       return Tick(fadeFraction: 1.0, pauseNow: true, stateChanged: true)
     }
   }

package/ios/Tests/AudioTapProviderReplayGainTests.swift

@@ -3,19 +3,15 @@ import XCTest
 @testable import QueuePlayer
 
 /// Unit tests for the ReplayGain mode + gain-math paths in
-/// `AudioTapProvider`. The metadata-extraction async path + per-item
-/// recompute walk are covered at the integration layer (auto-suite
-/// `replaygain.ts` step). These tests drive the pure
+/// `AudioTapProvider`. These tests drive the pure
 /// `computeLinearGain(data:mode:)` static helper plus the mode
 /// getter/setter round-trip.
 final class AudioTapProviderReplayGainTests: XCTestCase {
 
-  // Mode getter / setter round-trip is exercised at the integration
-  // layer (`replaygain.ts` auto-suite) — `getReplayGainMode`'s
-  // `ReplayGainMode` return type touches the Swift↔C++ interop
-  // graph, so direct equality from `@testable` XCTest can't observe
-  // it (NOTES.md §6). The pure gain-math matrix below is the unit
-  // surface; mode propagation lands in the integration tests.
+  // `getReplayGainMode`'s `ReplayGainMode` return type touches the
+  // Swift↔C++ interop graph, so direct equality from `@testable`
+  // XCTest can't observe it (NOTES.md §6). The pure gain-math matrix
+  // below is the unit surface.
 
   // MARK: - computeLinearGain — strict mode + selection
 

package/ios/Tests/CarPlayBridgeTests.swift

@@ -2,9 +2,7 @@ import XCTest
 @testable import QueuePlayer
 
 /// `CarPlayBridge` tests cover only the registration/dispose/clear
-/// state machine. Promise-await dispatch is exercised by the
-/// production scene delegate + browse builder via integration paths;
-/// the unit suite stays focused on the slot semantics. The
+/// state machine — the slot semantics. The
 /// Android-side `BrowseCallbackRegistry` exposes suspending
 /// `await*Callback()` helpers because its dispatch sites coroutine-
 /// poll for cold-start race recovery; iOS uses NotificationCenter
@@ -18,9 +16,7 @@ final class CarPlayBridgeTests: XCTestCase {
     // The browse / playFromId slot reads return a Promise of a
     // Nitrogen-bridged type, which Swift cxx-interop excludes from
     // `@testable import`. Their slots use the identical `Slot<>`
-    // machinery asserted here for connect/disconnect, and their
-    // dispatch is covered at the integration layer (scene delegate +
-    // browse builder).
+    // machinery asserted here for connect/disconnect.
     XCTAssertNil(bridge.carConnectCallback())
     XCTAssertNil(bridge.carDisconnectCallback())
   }

package/ios/Tests/CarPlayBrowseBuilderTests.swift

@@ -5,8 +5,7 @@ import XCTest
 /// 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.
+/// builder; the scene delegate's full lifecycle is out of scope here.
 final class CarPlayBrowseBuilderTests: XCTestCase {
 
   private func item(

package/ios/Tests/CarPlayCoordinatorTests.swift

@@ -0,0 +1,35 @@
+import XCTest
+@testable import QueuePlayer
+
+/// `CarPlayCoordinator` connection-flag tests. The flag is written by the
+/// CarPlay scene delegate at scene attach / detach; this suite locks the
+/// get/set contract the `isCarConnected()` getter reads back.
+final class CarPlayCoordinatorTests: XCTestCase {
+
+  override func setUp() {
+    super.setUp()
+    // Shared process-wide singleton — start from a known-disconnected state
+    // regardless of test order.
+    CarPlayCoordinator.shared.setCarConnected(false)
+  }
+
+  override func tearDown() {
+    // Shared process-wide singleton — leave it disconnected so it can't
+    // leak a connected state into another suite.
+    CarPlayCoordinator.shared.setCarConnected(false)
+    super.tearDown()
+  }
+
+  func testCarConnectedFlagReflectsSetter() {
+    let coordinator = CarPlayCoordinator.shared
+
+    coordinator.setCarConnected(false)
+    XCTAssertFalse(coordinator.isCarConnected, "disconnected after setCarConnected(false)")
+
+    coordinator.setCarConnected(true)
+    XCTAssertTrue(coordinator.isCarConnected, "connected after setCarConnected(true)")
+
+    coordinator.setCarConnected(false)
+    XCTAssertFalse(coordinator.isCarConnected, "disconnected again after setCarConnected(false)")
+  }
+}

package/ios/Tests/EQProcessorTests.swift

@@ -1,10 +1,7 @@
 import XCTest
 @testable import QueuePlayer
 
-/// Unit coverage for `EQProcessor` cascade. Audible response
-/// (sine-sweep magnitude per band) is verified at the integration
-/// layer via the demo Maestro EQ suite once the AVPlayerItem mix
-/// attach path is wired.
+/// Unit coverage for `EQProcessor` cascade.
 final class EQProcessorTests: XCTestCase {
 
   func testIsNotReadyBeforeChannelCountSet() {

package/ios/Tests/EQTapTests.swift

@@ -4,8 +4,7 @@ import XCTest
 
 /// Skeleton coverage for `EQTap` — tap creation, HLS detection,
 /// pass-through process body. The actual tap firing is on the
-/// audio render thread and verified at the integration layer via
-/// the demo Maestro EQ suite once the DSP body lands.
+/// audio render thread.
 final class EQTapTests: XCTestCase {
 
   func testPassThroughCopiesInputToOutput() {

package/ios/Tests/EqualizerAudioMixProviderTests.swift

@@ -2,10 +2,9 @@ import AVFoundation
 import XCTest
 @testable import QueuePlayer
 
-/// Provider-layer coverage for the shared `AudioTapProvider`. Real
-/// audio routing is verified at the integration layer via the demo
-/// Maestro EQ + visualizer suites; these tests cover the
-/// configuration + bypass + consumer-registration surface.
+/// Provider-layer coverage for the shared `AudioTapProvider`. These
+/// tests cover the configuration + bypass + consumer-registration
+/// surface.
 ///
 /// Filename note: kept at `EqualizerAudioMixProviderTests.swift`
 /// even though the class is `AudioTapProviderTests`. Renaming the

package/ios/Tests/EqualizerHybridTests.swift

@@ -3,9 +3,7 @@ import XCTest
 @testable import QueuePlayer
 
 /// Wiring coverage for the iOS `Equalizer` HybridObject.
-/// Targets the synchronous internal core; the async Promise-
-/// returning surface is exercised at integration via the demo
-/// Maestro EQ suite.
+/// Targets the synchronous internal core.
 final class EqualizerHybridTests: XCTestCase {
 
   private var defaults: UserDefaults!

package/ios/Tests/FFTProcessorTests.swift

@@ -39,9 +39,15 @@ final class FFTProcessorTests: XCTestCase {
 
   func testDoesNotEmitUntilFftSizeSamplesAccumulate() throws {
     var calls = 0
+    // Fulfilled by the emit itself so the wait tracks the actual main-queue
+    // callback rather than a fixed delay that can lose the race under load.
+    let emitted = expectation(description: "emit landed")
     let proc = try FFTProcessor(
       fftSize: 512, intervalMs: 1, includeSamples: false,
-    ) { _, _, _ in calls += 1 }
+    ) { _, _, _ in
+      calls += 1
+      emitted.fulfill()
+    }
     let half = [Float](repeating: 0, count: 256)
     half.withUnsafeBufferPointer { p in
       proc.ingest(samples: p.baseAddress!, frameCount: 256, sampleRate: 44100)
@@ -51,10 +57,7 @@ final class FFTProcessorTests: XCTestCase {
     rest.withUnsafeBufferPointer { p in
       proc.ingest(samples: p.baseAddress!, frameCount: 256, sampleRate: 44100)
     }
-    // The callback hops to main; spin the run loop to give it a chance.
-    let exp = expectation(description: "emit landed")
-    DispatchQueue.main.asyncAfter(deadline: .now() + 0.1) { exp.fulfill() }
-    wait(for: [exp], timeout: 1.0)
+    wait(for: [emitted], timeout: 1.0)
     XCTAssertEqual(calls, 1)
   }
 
@@ -240,9 +243,7 @@ final class FFTProcessorTests: XCTestCase {
     // `ingest` resumes, `onFrame` fires again at the documented
     // intervalMs cadence. Live audio chains express "pause" by
     // ceasing tap callbacks; the unit-test analogue is a sleep
-    // window. End-to-end pause/play coverage lives in the
-    // `visualizer:*` integration suite's `pause-stops-resume-restarts`
-    // step.
+    // window.
     let n = 256
     let intervalMs = 1
     let lock = NSLock()

package/ios/Tests/GaplessEngineLifecycleTests.swift

@@ -4,8 +4,6 @@ import XCTest
 
 /// Lifecycle smoke coverage for `GaplessEngine` — empty-queue
 /// sentinels + idempotent / delegate-clearing release contract.
-/// Behavioural coverage of transport + seek runs through the
-/// existing TrackPlayer integration suites + Maestro flows.
 final class GaplessEngineLifecycleTests: XCTestCase {
 
   func testEmptyQueueReturnsDocumentedSentinelState() {

package/ios/Tests/LookaheadCacheEvictionTests.swift

@@ -4,10 +4,7 @@ import XCTest
 
 /// `LookaheadCacheEviction.computeEvictions` unit tests.
 ///
-/// Pure-logic LRU policy. Plain JUnit-equivalent — no FS access, no
-/// URLSession. File + index mutation is tested through the
-/// LookaheadCacheTests integration path that drives `download` past
-/// the budget.
+/// Pure-logic LRU policy. No FS access, no URLSession.
 final class LookaheadCacheEvictionTests: XCTestCase {
 
   func testNoEvictionWhenUnderBudget() {

package/ios/Tests/MetadataReaderTests.swift

@@ -4,8 +4,6 @@ import XCTest
 /// Byte-level unit tests for `MetadataReader`'s container parsers.
 /// Builds synthetic ID3v2 / FLAC / MP4 byte sequences in-memory and
 /// verifies tag extraction surfaces the expected `[key: value]` map.
-/// End-to-end "extract from a real media file" coverage lives in
-/// the auto-suite `replaygain.ts`.
 final class MetadataReaderTests: XCTestCase {
 
   // MARK: - ID3v2 TXXX

package/ios/Tests/MilestoneTrackerTests.swift

@@ -2,9 +2,7 @@ import XCTest
 @testable import QueuePlayer
 
 /// Unit tests for `MilestoneTracker` — the pure 25/50/75/90% crossing
-/// logic behind `onPlaybackMilestone`. Native wiring (progress tick,
-/// seek, track-change reset) is covered by the `playback-milestones`
-/// demo suite.
+/// logic behind `onPlaybackMilestone`.
 final class MilestoneTrackerTests: XCTestCase {
 
   /// 200s track, ticks every ~10s of media time.

package/ios/Tests/NowPlayingFormatExtractorTests.swift

@@ -3,10 +3,9 @@ import CoreMedia
 import XCTest
 @testable import QueuePlayer
 
-/// Pure-mapping coverage for `NowPlayingFormatExtractor`. The async
-/// `extract(item:)` path is exercised end-to-end through the demo
-/// suites; these tests pin the codec / container / MIME tables so a
-/// future contributor can't drift the JS-visible enum without a test
+/// Pure-mapping coverage for `NowPlayingFormatExtractor`. These
+/// tests pin the codec / container / MIME tables so a future
+/// contributor can't drift the JS-visible enum without a test
 /// failure.
 final class NowPlayingFormatExtractorTests: XCTestCase {
 

package/ios/Tests/PlaybackErrorMappingTests.swift

@@ -5,9 +5,6 @@ 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

package/ios/Tests/PlaybackModeStateMachineTests.swift

@@ -3,15 +3,11 @@ import XCTest
 
 /// 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.
+/// validation (constructing `PlaybackMode` instances + driving
+/// `setRequested`) is out of scope here — `PlaybackMode` is bridged
+/// via Nitro `@_spi` and can't be constructed from a Swift XCTest
+/// target. Mirrors the cxx-interop carve-out already documented in
+/// AGENTS.md §2.
 final class PlaybackModeStateMachineTests: XCTestCase {
 
   func testCrossfadeBoundsHelperAcceptsEveryValueOnTheStep() {

package/ios/Tests/PlayerStateDerivationTests.swift

@@ -3,8 +3,7 @@ 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.
+/// shared by both engines.
 final class PlayerStateDerivationTests: XCTestCase {
 
   private func derive(

package/ios/Tests/ProgressEmissionGateTests.swift

@@ -2,9 +2,7 @@ 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.
+/// configurable / background-reduced `onProgress` cadence.
 ///
 /// Most tests pass `samplerPeriodMs: 0` to exercise exact interval semantics;
 /// the jitter + quantization tests pass the production `500` to verify the

package/ios/Tests/QueueMutationArithmeticTests.swift

@@ -3,9 +3,6 @@ import XCTest
 @_spi(QueuePlayerTests) import QueuePlayer
 
 /// Pure-Swift tests for the queue-mutation index-shift arithmetic.
-/// 1:1 mirror of `android/.../QueueMutationArithmeticTest.kt` —
-/// every Kotlin test name has a Swift twin so the cross-platform
-/// matrix stays in lock-step.
 final class QueueMutationArithmeticTests: XCTestCase {
 
   // MARK: - clampInsertBefore

package/ios/Tests/RemoteCommandsTests.swift

@@ -6,11 +6,8 @@ import XCTest
 /// registrations + the per-command `isEnabled` state. Tests pin the
 /// install / uninstall lifecycle and the `setSkipCapability` ->
 /// `nextTrackCommand.isEnabled` / `previousTrackCommand.isEnabled`
-/// mapping. Dispatch into the owner's `onCommand` closure is verified
-/// at the integration layer (Maestro suite + JS-visible reason
-/// classification); attempting to fire `MPRemoteCommandCenter`
-/// handlers from XCTest would require lib-side SPI we deliberately
-/// do not ship.
+/// mapping. Attempting to fire `MPRemoteCommandCenter` handlers from
+/// XCTest would require lib-side SPI we deliberately do not ship.
 ///
 /// The shared command center is process-global. `setUp` resets all
 /// seven commands the lib touches, `tearDown` calls `uninstall()` to

package/ios/Tests/ReplayGainExtractorTests.swift

@@ -4,11 +4,6 @@ import XCTest
 /// Unit tests for `ReplayGainExtractor`'s pure string parsers
 /// (`parseGainDb`, `parsePeak`) and the `selectGain(mode:)` matrix
 /// on `ReplayGainData`.
-///
-/// Container-level extraction (ID3v2 TXXX, FLAC Vorbis, MP4
-/// freeform) is covered by `MetadataReaderTests`. End-to-end
-/// extraction-on-load is covered by the auto-suite `replaygain.ts`
-/// step.
 final class ReplayGainExtractorTests: XCTestCase {
 
   // Helper: `XCTAssertEqual` with the `accuracy:` overload requires

package/ios/Tests/SkipCapabilityTests.swift

@@ -2,15 +2,12 @@ import XCTest
 @testable import QueuePlayer
 @_spi(QueuePlayerTests) import QueuePlayer
 
-/// Integration tests for the canSkip surface + `onSkipCapabilityChange`
-/// listener emission. Pairs with the pure-helper coverage in
-/// `SkipIndexTests` (`canSkipNext` / `canSkipPrevious`).
+/// Tests for the canSkip surface + `onSkipCapabilityChange`
+/// listener emission.
 ///
-/// XCTest can cover only the cases where `configure(...)` has not yet
+/// Covers the cases where `configure(...)` has not yet
 /// stood up an AVQueuePlayer — initial cached-getter state, listener
-/// registration + auto-fire, dispose closure correctness. Behavioural
-/// coverage of every `recomputeCapabilities()` hook point lives in
-/// the Robolectric sibling and the end-to-end demo suite.
+/// registration + auto-fire, dispose closure correctness.
 final class SkipCapabilityTests: XCTestCase {
 
   func testGetCanSkipNextReturnsFalseInitially() throws {

package/ios/Tests/SleepTimerCoreTests.swift

@@ -85,6 +85,8 @@ final class SleepTimerCoreTests: XCTestCase {
     XCTAssertTrue(converted.stateChanged)
     XCTAssertFalse(t.isEndOfTrack)
     XCTAssertTrue(t.isActive)
+    // Deadline lands AT the boundary (tail=50s), not 1s past it.
+    XCTAssertEqual(t.deadlineEpochMs, 2000 + 50_000)
   }
 
   func testClearResetsToInactive() {
@@ -95,4 +97,41 @@ final class SleepTimerCoreTests: XCTestCase {
     XCTAssertNil(t.deadlineEpochMs)
     XCTAssertNil(t.remainingSeconds(nowMs: 0))
   }
+
+  func testEndOfTrackFiresPauseAtTrackEndSignal() {
+    var t = SleepTimerCore()
+    t.armEndOfTrack()
+    // Fires at the real track-end signal, before any tail conversion and even
+    // when the duration was never known (never ticked).
+    let fired = t.fireAtTrackEnd()
+    XCTAssertTrue(fired.pauseNow)
+    XCTAssertTrue(fired.stateChanged)
+    XCTAssertFalse(t.isActive)
+  }
+
+  func testEndOfTrackSignalFiresAfterTailConversion() {
+    var t = SleepTimerCore()
+    t.armEndOfTrack()
+    _ = t.tick(nowMs: 1000, trackDurationSec: 200, trackPositionSec: 150) // converts to fade
+    // The end-of-track origin survives the conversion, so the boundary signal
+    // still owns the pause.
+    let fired = t.fireAtTrackEnd()
+    XCTAssertTrue(fired.pauseNow)
+    XCTAssertFalse(t.isActive)
+  }
+
+  func testFireAtTrackEndIsIdempotent() {
+    var t = SleepTimerCore()
+    t.armEndOfTrack()
+    _ = t.fireAtTrackEnd()
+    XCTAssertFalse(t.fireAtTrackEnd().pauseNow)
+  }
+
+  func testFireAtTrackEndIgnoresDurationTimer() {
+    var t = SleepTimerCore()
+    t.armDuration(seconds: 60, nowMs: 0)
+    let fired = t.fireAtTrackEnd()
+    XCTAssertFalse(fired.pauseNow)
+    XCTAssertTrue(t.isActive)
+  }
 }

package/ios/Tests/VoiceDonationTests.swift

@@ -4,10 +4,10 @@ import XCTest
 @_spi(QueuePlayerTests) import QueuePlayer
 
 /// Smoke coverage for `VoiceDonation.donateVoiceVocabulary`. Live
-/// `INVocabulary` delivery is verified via the manual siri-cold-start
-/// playbook; this test pins the in-process contract that the method
-/// early-returns when `NSSiriUsageDescription` is absent from the
-/// host bundle (the XCTest bundle's plist).
+/// `INVocabulary` delivery isn't exercised here; this test pins the
+/// in-process contract that the method early-returns when
+/// `NSSiriUsageDescription` is absent from the host bundle (the XCTest
+/// bundle's plist).
 @available(iOS 13.0, *)
 final class VoiceDonationTests: XCTestCase {
   func testDonateVoiceVocabularyEarlyReturnsWithoutUsageDescription() {