react-native-audio-browser 0.2.0-next.28 → 0.2.0-next.29

package/ios/Tests/{PlaybackCoordinatorTests.swift → PlayerTests.swift}

@@ -2,46 +2,43 @@
 import Foundation
 import Testing
 
-/// Helper to build a coordinator with mocks for testing.
+/// Helper to build a player with mocks for testing.
 @MainActor
 private func makeCoordinator() -> (
-  coordinator: PlaybackCoordinator,
-  effectHandler: MockPlaybackEffectHandler,
-  callbacks: MockPlaybackCoordinatorCallbacks,
-  sleepTimer: MockSleepTimerHandling,
+  player: Player,
+  engine: MockPlayerEngine,
+  callbacks: MockPlayerCallbacks,
+  sleepTimer: SleepTimerManager,
 ) {
-  let retryHandler = MockRetryHandling()
-  let errorHandler = PlaybackErrorHandler(retryHandler: retryHandler)
-  let sleepTimer = MockSleepTimerHandling()
-  let coordinator = PlaybackCoordinator(errorHandler: errorHandler, sleepTimerManager: sleepTimer)
-  let effectHandler = MockPlaybackEffectHandler()
-  let callbacks = MockPlaybackCoordinatorCallbacks()
-  coordinator.effectHandler = effectHandler
-  coordinator.callbacks = callbacks
-  return (coordinator, effectHandler, callbacks, sleepTimer)
+  let sleepTimer = SleepTimerManager(scheduler: ManualSleepTimerScheduler())
+  let engine = MockPlayerEngine()
+  let player = makePlayer(engine: engine, retries: false, sleepTimer: sleepTimer)
+  let callbacks = MockPlayerCallbacks()
+  player.callbacks = callbacks
+  return (player, engine, callbacks, sleepTimer)
 }
 
-/// Helper to load a track into the coordinator's queue so it has a currentTrack.
+/// Helper to load a track into the player's queue so it has a currentTrack.
 @MainActor
 private func loadTrack(
-  _ coordinator: PlaybackCoordinator,
+  _ player: Player,
   id: String = "t1",
   src: String? = "https://example.com/audio.mp3",
   title: String = "Test Track",
 ) {
   let track = Track(id: id, src: src, title: title)
-  coordinator.setQueue([track])
+  player.setQueue([track])
 }
 
 // MARK: - Transition + Side Effects
 
-@Suite("PlaybackCoordinator - transition + side effects")
+@Suite("Player - transition + side effects")
 struct TransitionTests {
   @Test @MainActor
   func toReady_startsPlayback_whenPlayWhenReady() {
     let (c, eh, _, _) = makeCoordinator()
     loadTrack(c)
-    c.playWhenReady = true
+    c.setPlayWhenReady(true)
     eh.startPlaybackCallCount = 0 // reset from playWhenReady setter
 
     c.transition(.bufferingSufficient)
@@ -77,19 +74,19 @@ struct TransitionTests {
     c.transition(.errorOccurred(.playbackFailed))
 
     #expect(c.state == .error)
-    #expect(c.playbackError == .playbackFailed)
+    #expect(c.errorStatus.error == .playbackFailed)
   }
 
   @Test @MainActor
   func leavingError_clearsPlaybackError() {
     let (c, _, _, _) = makeCoordinator()
     c.transition(.errorOccurred(.playbackFailed))
-    #expect(c.playbackError == .playbackFailed)
+    #expect(c.errorStatus.error == .playbackFailed)
 
     c.transition(.trackLoading)
 
     #expect(c.state == .loading)
-    #expect(c.playbackError == nil)
+    #expect(c.errorStatus.error == nil)
   }
 
   @Test @MainActor
@@ -103,7 +100,7 @@ struct TransitionTests {
 
     // State stays .error but error is updated
     #expect(c.state == .error)
-    #expect(c.playbackError == .notConnectedToInternet)
+    #expect(c.errorStatus.error == .notConnectedToInternet)
     #expect(cb.playbackChanges.count == 1)
     #expect(cb.errorEvents.count == 1)
   }
@@ -114,29 +111,21 @@ struct TransitionTests {
 /// Advisory errors from the retry loop: attached to the current non-terminal
 /// state via `playerDidChangePlayback`, never a state transition and never a
 /// `playerDidError`.
-/// Builds a coordinator whose retry handler will accept the error and
-/// pretend the (instant) retry succeeded, so only the advisory path runs.
-/// The effect handler is returned solely to keep the weak reference alive.
+/// Builds a player whose retries reload at once, so the advisory path is what shows.
 @MainActor
 private func makeRetrying() -> (
-  PlaybackCoordinator, MockRetryHandling, MockPlaybackCoordinatorCallbacks,
-  MockPlaybackEffectHandler,
+  Player, RetryLoop, MockPlayerCallbacks,
+  MockPlayerEngine,
 ) {
-  let retryHandler = MockRetryHandling()
-  retryHandler.isRetryableResult = true
-  retryHandler.attemptRetryResult = true
-  let errorHandler = PlaybackErrorHandler(retryHandler: retryHandler)
-  let coordinator = PlaybackCoordinator(
-    errorHandler: errorHandler, sleepTimerManager: MockSleepTimerHandling(),
-  )
-  let effectHandler = MockPlaybackEffectHandler()
-  coordinator.effectHandler = effectHandler
-  let callbacks = MockPlaybackCoordinatorCallbacks()
-  coordinator.callbacks = callbacks
-  return (coordinator, retryHandler, callbacks, effectHandler)
+  let retryHandler = makeRetryLoop()
+  let engine = MockPlayerEngine()
+  let player = makePlayer(engine: engine, retry: retryHandler)
+  let callbacks = MockPlayerCallbacks()
+  player.callbacks = callbacks
+  return (player, retryHandler, callbacks, engine)
 }
 
-@Suite("PlaybackCoordinator - retrying errors")
+@Suite("Player - retrying errors")
 struct RetryingErrorTests {
   @Test @MainActor
   func retryingError_attachesToCurrentState() async {
@@ -144,16 +133,16 @@ struct RetryingErrorTests {
     c.transition(.trackLoading)
     cb.playbackChanges.removeAll()
 
-    c.errorHandler.handleError(URLError(.cannotConnectToHost), context: .mediaLoad)
+    c.retry.handleError(URLError(.cannotConnectToHost), context: .mediaLoad)
 
     #expect(c.state == .loading)
-    #expect(c.playbackError == .hostUnreachable)
+    #expect(c.errorStatus.error == .hostUnreachable)
     #expect(cb.playbackChanges.count == 1)
     #expect(cb.playbackChanges.last?.state == .loading)
     #expect(cb.playbackChanges.last?.error?.retrying == true)
     // Advisory, not terminal: the error event is reserved for .error.
     #expect(cb.errorEvents.isEmpty)
-    await c.errorHandler.pendingRetryTask?.value
+    await c.retry.pendingTask?.value
   }
 
   /// Every failed attempt re-reports through `handleError`; identical repeats
@@ -164,10 +153,10 @@ struct RetryingErrorTests {
     c.transition(.trackLoading)
     cb.playbackChanges.removeAll()
 
-    c.errorHandler.handleError(URLError(.cannotConnectToHost), context: .mediaLoad)
-    await c.errorHandler.pendingRetryTask?.value
-    c.errorHandler.handleError(URLError(.cannotConnectToHost), context: .mediaLoad)
-    await c.errorHandler.pendingRetryTask?.value
+    c.retry.handleError(URLError(.cannotConnectToHost), context: .mediaLoad)
+    await c.retry.pendingTask?.value
+    c.retry.handleError(URLError(.cannotConnectToHost), context: .mediaLoad)
+    await c.retry.pendingTask?.value
 
     #expect(cb.playbackChanges.count == 1)
   }
@@ -180,11 +169,11 @@ struct RetryingErrorTests {
     c.transition(.avPlayerPlaying)
     cb.playbackChanges.removeAll()
 
-    c.errorHandler.handleError(URLError(.cannotConnectToHost), context: .playback)
+    c.retry.handleError(URLError(.cannotConnectToHost), context: .playback)
 
-    #expect(c.playbackError == nil)
+    #expect(c.errorStatus.error == nil)
     #expect(cb.playbackChanges.isEmpty)
-    await c.errorHandler.pendingRetryTask?.value
+    await c.retry.pendingTask?.value
   }
 
   /// Reaching .ready proves the retry recovered: the advisory error must not
@@ -193,13 +182,13 @@ struct RetryingErrorTests {
   func recovery_clearsTheRetryingError() async {
     let (c, _, cb, _) = makeRetrying()
     c.transition(.trackLoading)
-    c.errorHandler.handleError(URLError(.cannotConnectToHost), context: .mediaLoad)
-    await c.errorHandler.pendingRetryTask?.value
+    c.retry.handleError(URLError(.cannotConnectToHost), context: .mediaLoad)
+    await c.retry.pendingTask?.value
 
     c.transition(.loadSeekCompleted)
 
     #expect(c.state == .ready)
-    #expect(c.playbackError == nil)
+    #expect(c.errorStatus.error == nil)
     #expect(cb.playbackChanges.last?.error == nil)
   }
 
@@ -209,12 +198,12 @@ struct RetryingErrorTests {
   func exhaustion_hardensIntoTerminalError() async {
     let (c, retryHandler, cb, _) = makeRetrying()
     c.transition(.trackLoading)
-    c.errorHandler.handleError(URLError(.cannotConnectToHost), context: .mediaLoad)
-    await c.errorHandler.pendingRetryTask?.value
+    c.retry.handleError(URLError(.cannotConnectToHost), context: .mediaLoad)
+    await c.retry.pendingTask?.value
 
-    retryHandler.attemptRetryResult = false
-    c.errorHandler.handleError(URLError(.cannotConnectToHost), context: .mediaLoad)
-    await c.errorHandler.pendingRetryTask?.value
+    retryHandler.shouldRetry = { false }
+    c.retry.handleError(URLError(.cannotConnectToHost), context: .mediaLoad)
+    await c.retry.pendingTask?.value
 
     #expect(c.state == .error)
     #expect(cb.playbackChanges.last?.state == .error)
@@ -225,7 +214,7 @@ struct RetryingErrorTests {
 
 // MARK: - emitStateChange
 
-@Suite("PlaybackCoordinator - emitStateChange")
+@Suite("Player - emitStateChange")
 struct EmitStateChangeTests {
   @Test @MainActor
   func alwaysEmits_playerDidChangePlayback() {
@@ -275,7 +264,7 @@ struct EmitStateChangeTests {
 
 // MARK: - Observer Guards
 
-@Suite("PlaybackCoordinator - observer guards")
+@Suite("Player - observer guards")
 struct ObserverGuardTests {
   @Test @MainActor
   func timeControlStatus_paused_nearTrackEnd_ignored() {
@@ -312,7 +301,7 @@ struct ObserverGuardTests {
     eh.hasLoadedAsset = true
     eh.currentTime = 10
     eh.duration = 100
-    c.playWhenReady = false
+    c.setPlayWhenReady(false)
 
     c.avPlayerDidChangeTimeControlStatus(.paused)
 
@@ -326,7 +315,7 @@ struct ObserverGuardTests {
     eh.hasLoadedAsset = true
     eh.currentTime = 10
     eh.duration = 100
-    c.playWhenReady = true
+    c.setPlayWhenReady(true)
 
     c.avPlayerDidChangeTimeControlStatus(.paused)
 
@@ -414,28 +403,37 @@ struct ObserverGuardTests {
 
 // MARK: - playWhenReady
 
-@Suite("PlaybackCoordinator - playWhenReady")
+@Suite("Player - playWhenReady")
 struct PlayWhenReadyTests {
   @Test @MainActor
   func true_fromError_triggersReload() {
     let (c, eh, _, _) = makeCoordinator()
+    loadTrack(c)
+    eh.emit(.itemPrepared(likelyToKeepUp: false))
     c.transition(.errorOccurred(.playbackFailed))
+    eh.resumePosition = 42
+    let resolvesBefore = eh.resolveAndLoadCalls.count
 
-    c.playWhenReady = true
+    c.setPlayWhenReady(true)
 
-    #expect(eh.reloadTrackCalls.count == 1)
-    #expect(eh.reloadTrackCalls.first == true) // startFromCurrentTime for error
+    // A restart from .error is a new Load on a new AVPlayer, resuming where it failed.
+    #expect(eh.recreateCount == 1)
+    #expect(eh.resolveAndLoadCalls.count == resolvesBefore + 1)
+    #expect(c.state == .loading)
+    #expect(c.deferredSeek.target == 42)
   }
 
   @Test @MainActor
   func true_fromStopped_triggersReload() {
     let (c, eh, _, _) = makeCoordinator()
     c.transition(.stopped)
+    eh.resumePosition = 42
 
-    c.playWhenReady = true
+    c.setPlayWhenReady(true)
 
-    #expect(eh.reloadTrackCalls.count == 1)
-    #expect(eh.reloadTrackCalls.first == false) // startFromCurrentTime for stopped
+    #expect(eh.recreateCount == 0)
+    #expect(eh.loadResolvedCount == 1)
+    #expect(c.deferredSeek.target == nil) // a stop restarts from the start
   }
 
   @Test @MainActor
@@ -443,7 +441,7 @@ struct PlayWhenReadyTests {
     let (c, eh, _, _) = makeCoordinator()
     c.transition(.bufferingSufficient) // .ready state
 
-    c.playWhenReady = true
+    c.setPlayWhenReady(true)
 
     #expect(eh.startPlaybackCallCount >= 1)
   }
@@ -452,10 +450,10 @@ struct PlayWhenReadyTests {
   func false_notLoading_pausesPlayback() {
     let (c, eh, _, _) = makeCoordinator()
     c.transition(.avPlayerPlaying)
-    c.playWhenReady = true
+    c.setPlayWhenReady(true)
     eh.pausePlaybackCallCount = 0
 
-    c.playWhenReady = false
+    c.setPlayWhenReady(false)
 
     #expect(eh.pausePlaybackCallCount == 1)
   }
@@ -467,7 +465,7 @@ struct PlayWhenReadyTests {
     eh.startPlaybackCallCount = 0
     eh.pausePlaybackCallCount = 0
 
-    c.playWhenReady = true
+    c.setPlayWhenReady(true)
 
     // During loading, should NOT call start/pause
     #expect(eh.startPlaybackCallCount == 0)
@@ -478,7 +476,7 @@ struct PlayWhenReadyTests {
   func emitsCallback_onChange() {
     let (c, _, cb, _) = makeCoordinator()
 
-    c.playWhenReady = true
+    c.setPlayWhenReady(true)
 
     #expect(cb.playWhenReadyChanges.count == 1)
     #expect(cb.playWhenReadyChanges.first == true)
@@ -487,7 +485,7 @@ struct PlayWhenReadyTests {
 
 // MARK: - Skip availability (next/previous greying)
 
-@Suite("PlaybackCoordinator - skip availability")
+@Suite("Player - skip availability")
 struct SkipAvailabilityCoordinatorTests {
   private static func multiTrack() -> [Track] {
     [
@@ -541,25 +539,25 @@ struct SkipAvailabilityCoordinatorTests {
 
 // MARK: - handleCurrentTrackChanged
 
-@Suite("PlaybackCoordinator - handleCurrentTrackChanged")
+@Suite("Player - handleCurrentTrackChanged")
 struct HandleCurrentTrackChangedTests {
   @Test @MainActor
   func clearsError_beforeTransition() {
     let (c, eh, _, _) = makeCoordinator()
     eh.hasLoadedAsset = true
     c.transition(.errorOccurred(.playbackFailed))
-    #expect(c.playbackError != nil)
+    #expect(c.errorStatus.error != nil)
 
     loadTrack(c)
 
     // After loading a track, the error should be cleared
-    #expect(c.playbackError == nil)
+    #expect(c.errorStatus.error == nil)
   }
 
   @Test @MainActor
   func preservesPlayWhenReady_acrossLoading() {
     let (c, _, _, _) = makeCoordinator()
-    c.playWhenReady = true
+    c.setPlayWhenReady(true)
 
     loadTrack(c)
 
@@ -575,7 +573,7 @@ struct HandleCurrentTrackChangedTests {
     c.setQueue([track])
 
     #expect(c.state == .error)
-    #expect(c.playbackError == .invalidSourceUrl("nil"))
+    #expect(c.errorStatus.error == .invalidSourceUrl("nil"))
     #expect(cb.errorEvents.count >= 1)
   }
 
@@ -595,19 +593,19 @@ struct HandleCurrentTrackChangedTests {
 
 // MARK: - handleTrackDidPlayToEndTime
 
-@Suite("PlaybackCoordinator - handleTrackDidPlayToEndTime")
+@Suite("Player - handleTrackDidPlayToEndTime")
 struct HandleTrackDidPlayToEndTimeTests {
   @Test @MainActor
   func repeatTrack_replays() {
     let (c, eh, _, _) = makeCoordinator()
-    loadTrack(c)
+    startPlaying(c, eh)
     c.repeatMode = .track
-    c.playWhenReady = true
+    eh.startPlaybackCallCount = 0
 
     c.handleTrackDidPlayToEndTime()
 
-    // replay delegates to effectHandler.replayCurrentTrack (seek to 0 + play)
-    #expect(eh.replayCurrentTrackCallCount == 1)
+    #expect(eh.seekCalls == [0])
+    #expect(eh.startPlaybackCallCount == 1)
   }
 
   /// The end-of-track sleep timer pauses (clears intent) just before this
@@ -620,19 +618,18 @@ struct HandleTrackDidPlayToEndTimeTests {
     let (c, eh, cb, _) = makeCoordinator()
     loadTrack(c)
     c.repeatMode = .track
-    c.playWhenReady = false
+    c.setPlayWhenReady(false)
 
     c.handleTrackDidPlayToEndTime()
 
     #expect(cb.queueEndedEvents.isEmpty)
-    #expect(eh.replayCurrentTrackCallCount == 0)
+    #expect(eh.seekCalls.isEmpty)
     #expect(c.state == .ended)
   }
 
   @Test @MainActor
   func lastTrack_noRepeat_transitionsToEnded() {
     let (c, eh, cb, _) = makeCoordinator()
-    _ = eh // retain weak effectHandler
     loadTrack(c)
     c.repeatMode = .off
 
@@ -666,7 +663,7 @@ struct HandleTrackDidPlayToEndTimeTests {
 /// `playWhenReady` must not stay true. Keeping it inverted the play/pause
 /// toggle, held the audio session forever, armed interruption auto-resume into
 /// silence, and made play-from-ended a silent no-op.
-@Suite("PlaybackCoordinator - natural end drops play intent")
+@Suite("Player - natural end drops play intent")
 struct NaturalEndPlayIntentTests {
   @Test @MainActor
   func naturalEnd_clearsPlayWhenReady() {
@@ -697,11 +694,13 @@ struct NaturalEndPlayIntentTests {
     let (c, eh, _, _) = makeCoordinator()
     startPlaying(c, eh)
     c.handleTrackDidPlayToEndTime()
-    eh.reloadTrackCalls.removeAll()
+    eh.resumePosition = 300
+    let resolvesBefore = eh.resolveAndLoadCalls.count
 
     c.play()
 
-    #expect(eh.reloadTrackCalls == [false])
+    #expect(eh.resolveAndLoadCalls.count == resolvesBefore + 1)
+    #expect(c.deferredSeek.target == nil)
   }
 
   /// The cleared intent opens the call-site `!playWhenReady` gate, so a stray
@@ -724,13 +723,13 @@ struct NaturalEndPlayIntentTests {
     let (c, eh, _, _) = makeCoordinator()
     startPlaying(c, eh)
     c.handleTrackDidPlayToEndTime()
-    eh.reloadTrackCalls.removeAll()
+    let resolvesBefore = eh.resolveAndLoadCalls.count
 
     c.handleInterruptionBegan()
     c.handleInterruptionEnded(shouldResume: true)
 
     #expect(c.playWhenReady == false) // nothing was playing — never resume
-    #expect(eh.reloadTrackCalls.isEmpty)
+    #expect(eh.resolveAndLoadCalls.count == resolvesBefore)
   }
 }
 
@@ -740,153 +739,69 @@ struct NaturalEndPlayIntentTests {
 /// window/attempt counters must refill (mirrors Android's healthy-playback
 /// refill) — otherwise a long-lived stream permanently loses retry after its
 /// first recovered blip.
-@Suite("PlaybackCoordinator - healthy playback resets retry budget")
+@Suite("Player - healthy playback resets retry budget")
 struct HealthyPlaybackRetryResetTests {
+  /// A player whose retry loop has already executed one retry, so a reset shows.
+  @MainActor
+  private func makeAfterOneRetry(delay: TimeInterval = 0) async -> (Player, RetryLoop, MockPlayerEngine) {
+    let retry = makeRetryLoop(delay: delay)
+    let engine = MockPlayerEngine()
+    let player = makePlayer(engine: engine, retry: retry)
+    if delay == 0 {
+      retry.handleError(URLError(.timedOut), context: .playback)
+      await retry.pendingTask?.value
+    }
+    return (player, retry, engine)
+  }
+
   @Test @MainActor
   func sustainedPlayback_resetsRetryBudget() async {
-    let retryHandler = MockRetryHandling()
-    let errorHandler = PlaybackErrorHandler(retryHandler: retryHandler)
-    let coordinator = PlaybackCoordinator(
-      errorHandler: errorHandler, sleepTimerManager: MockSleepTimerHandling(),
-    )
-    let effectHandler = MockPlaybackEffectHandler()
-    coordinator.effectHandler = effectHandler
-    coordinator.healthyPlaybackDuration = 0.01
+    let (player, retry, _) = await makeAfterOneRetry()
+    #expect(retry.attempts == 1)
+    player.healthyPlaybackDuration = 0.01
 
-    coordinator.transition(.avPlayerPlaying)
-    await coordinator.healthyPlaybackTask?.value
+    player.transition(.avPlayerPlaying)
+    await player.healthyPlaybackTask?.value
 
-    #expect(retryHandler.resetCallCount == 1)
+    #expect(retry.attempts == 0)
   }
 
-  /// resetRetry() cancels a pending retry — firing the refill mid-episode
+  /// reset() cancels a pending retry — firing the refill mid-episode
   /// would kill an in-flight reconnect silently (stuck .playing forever).
   @Test @MainActor
   func refill_skipsWhileRetryIsPending() async {
-    let retryHandler = MockRetryHandling()
-    retryHandler.isRetryableResult = true
-    retryHandler.attemptRetryDelayNs = 1_000_000_000
-    let errorHandler = PlaybackErrorHandler(retryHandler: retryHandler)
-    let coordinator = PlaybackCoordinator(
-      errorHandler: errorHandler, sleepTimerManager: MockSleepTimerHandling(),
-    )
-    let effectHandler = MockPlaybackEffectHandler()
-    coordinator.effectHandler = effectHandler
-    coordinator.healthyPlaybackDuration = 0.01
+    let (player, retry, _) = await makeAfterOneRetry(delay: 1)
+    player.healthyPlaybackDuration = 0.01
 
-    coordinator.transition(.avPlayerPlaying)
-    errorHandler.handleError(URLError(.timedOut), context: .playback)
-    await coordinator.healthyPlaybackTask?.value
+    player.transition(.avPlayerPlaying)
+    retry.handleError(URLError(.timedOut), context: .playback)
+    await player.healthyPlaybackTask?.value
 
-    #expect(retryHandler.resetCallCount == 0)
-    #expect(errorHandler.pendingRetryTask != nil)
+    #expect(retry.pendingTask != nil)
+    retry.cancel()
   }
 
   @Test @MainActor
   func playbackInterruptedBeforeThreshold_doesNotReset() async {
-    let retryHandler = MockRetryHandling()
-    let errorHandler = PlaybackErrorHandler(retryHandler: retryHandler)
-    let coordinator = PlaybackCoordinator(
-      errorHandler: errorHandler, sleepTimerManager: MockSleepTimerHandling(),
-    )
-    let effectHandler = MockPlaybackEffectHandler()
-    coordinator.effectHandler = effectHandler
-    effectHandler.hasLoadedAsset = true
-    coordinator.healthyPlaybackDuration = 0.5
+    let (player, retry, engine) = await makeAfterOneRetry()
+    engine.hasLoadedAsset = true
+    player.healthyPlaybackDuration = 0.5
 
-    coordinator.transition(.avPlayerPlaying)
-    let refill = coordinator.healthyPlaybackTask
-    coordinator.transition(.avPlayerWaiting) // stalls before the threshold
+    player.transition(.avPlayerPlaying)
+    let refill = player.healthyPlaybackTask
+    player.transition(.avPlayerWaiting) // stalls before the threshold
 
     // Leaving .playing cancels the refill; awaiting the cancelled task is the
     // deterministic way to reach the point where it would have fired.
     await refill?.value
 
-    #expect(retryHandler.resetCallCount == 0)
-  }
-}
-
-@Suite("PlaybackCoordinator - now playing state")
-struct PlaybackCoordinatorNowPlayingStateTests {
-  @Test @MainActor
-  func change_updatesNowPlayingState_evenDuringLoading() {
-    let (c, eh, _, _) = makeCoordinator()
-    c.transition(.trackLoading) // mid track-load; start/pause is deferred
-    eh.updateNowPlayingStateCalls.removeAll()
-
-    c.playWhenReady = true
-
-    // The lock-screen / CarPlay play-pause button reflects the user's play
-    // *intent* immediately, even while the new item is still loading — otherwise
-    // it stays stuck showing "paused" until a later state transition repairs it.
-    #expect(eh.updateNowPlayingStateCalls.last == true)
-  }
-
-  @Test @MainActor
-  func staysPlaying_whenBufferRunsDry() {
-    let (c, eh, _, _) = makeCoordinator()
-    c.playWhenReady = true
-    c.transition(.avPlayerPlaying)
-    eh.updateNowPlayingStateCalls.removeAll()
-
-    c.transition(.avPlayerWaiting) // buffer ran dry → .buffering
-
-    // A buffer underrun doesn't change play intent, so the button stays "playing"
-    // (the system shows buffering) — it must NOT flip to paused like a user pause.
-    #expect(eh.updateNowPlayingStateCalls.last == true)
-  }
-
-  @Test @MainActor
-  func fallsBackToPaused_onError() {
-    let (c, eh, _, _) = makeCoordinator()
-    c.playWhenReady = true
-    c.transition(.trackLoading) // active + intent → playing
-    eh.updateNowPlayingStateCalls.removeAll()
-
-    c.transition(.errorOccurred(.playbackFailed))
-
-    // On a terminal error the button must fall back to paused — never stick on
-    // "playing" — even though playWhenReady is still true.
-    #expect(eh.updateNowPlayingStateCalls.last == false)
-  }
-
-  @Test @MainActor
-  func change_doesNotStampNowPlayingState_fromTerminalState() {
-    let (c, eh, _, _) = makeCoordinator()
-    c.transition(.errorOccurred(.playbackFailed)) // terminal, not playbackActive
-    eh.updateNowPlayingStateCalls.removeAll()
-
-    c.playWhenReady = true
-
-    // Must NOT stamp .playing from a terminal state: the reload may fail and no
-    // active transition would repair a premature "playing", leaving a phantom
-    // playing button. The reload's own .loading/.ready transition stamps it.
-    #expect(eh.updateNowPlayingStateCalls.isEmpty)
-  }
-
-  @Test @MainActor
-  func selectingNewTrack_whileStopped_showsPlayingInNowPlaying() {
-    let (c, eh, _, _) = makeCoordinator()
-    let tracks = [
-      Track(id: "t1", src: "https://example.com/1.mp3", title: "Track 1"),
-      Track(id: "t2", src: "https://example.com/2.mp3", title: "Track 2"),
-    ]
-    c.setQueue(tracks) // loads t1 (playWhenReady defaults to false)
-    c.transition(.stopped) // user had paused/stopped
-    eh.updateNowPlayingStateCalls.removeAll()
-
-    // User selects another track, intending to play it.
-    try? c.skipTo(1, playWhenReady: true)
-
-    // Audio will play, so the now-playing button must end up "playing" — not the
-    // stale "paused" captured before playWhenReady flipped true during loading.
-    #expect(eh.updateNowPlayingStateCalls.last == true)
+    #expect(retry.attempts == 1)
   }
 }
 
 // MARK: - Sleep Timer Fade
 
-@Suite("PlaybackCoordinator - sleep timer fade")
+@Suite("Player - sleep timer fade")
 struct SleepTimerFadeTests {
   @Test @MainActor
   func fadeStart_capturesPreFadeVolume() {
@@ -903,7 +818,7 @@ struct SleepTimerFadeTests {
   func completion_pausesThenRestoresPreFadeVolume() {
     let (c, eh, _, st) = makeCoordinator()
     loadTrack(c)
-    c.playWhenReady = true
+    c.setPlayWhenReady(true)
     c.transition(.bufferingSufficient) // leave .loading so pause reaches the player
     eh.pausePlaybackCallCount = 0
 
@@ -922,7 +837,7 @@ struct SleepTimerFadeTests {
   func completion_withoutFade_justPauses() {
     let (c, eh, _, st) = makeCoordinator()
     loadTrack(c)
-    c.playWhenReady = true
+    c.setPlayWhenReady(true)
     eh.volume = 0.8
 
     st.onComplete?()
@@ -949,38 +864,41 @@ struct SleepTimerFadeTests {
   func pauseDuringFade_clearsSleepTimer() {
     let (c, _, _, st) = makeCoordinator()
     loadTrack(c)
-    c.playWhenReady = true
+    c.setPlayWhenReady(true)
+    st.set(seconds: 60, fadeDuration: 10)
 
     st.onFadeStart?(10)
     c.pause()
 
-    #expect(st.clearCallCount == 1)
+    #expect(st.get() == nil)
   }
 
   @Test @MainActor
   func pauseWithoutFade_leavesSleepTimerAlone() {
     let (c, _, _, st) = makeCoordinator()
     loadTrack(c)
-    c.playWhenReady = true
+    c.setPlayWhenReady(true)
+    st.set(seconds: 60, fadeDuration: 10)
 
     c.pause()
 
-    #expect(st.clearCallCount == 0)
+    #expect(st.get() != nil)
   }
 }
 
 // MARK: - Audio Session Interruptions
 
-/// Helper to drive the coordinator into an actively-playing state.
+/// Helper to drive the player into an actively-playing state.
 @MainActor
-private func startPlaying(_ c: PlaybackCoordinator, _ eh: MockPlaybackEffectHandler) {
+private func startPlaying(_ c: Player, _ eh: MockPlayerEngine) {
   loadTrack(c)
   eh.hasLoadedAsset = true
-  c.playWhenReady = true
+  eh.hasItem = true
+  c.setPlayWhenReady(true)
   c.transition(.avPlayerPlaying)
 }
 
-@Suite("PlaybackCoordinator - audio session interruptions")
+@Suite("Player - audio session interruptions")
 struct InterruptionTests {
   @Test @MainActor
   func began_whilePlaying_pauses() {
@@ -1090,13 +1008,14 @@ struct InterruptionTests {
     let (c, eh, _, _) = makeCoordinator()
     startPlaying(c, eh)
     c.handleInterruptionBegan()
+    let resolvesBefore = eh.resolveAndLoadCalls.count
 
     c.stop()
     c.handleInterruptionEnded(shouldResume: true)
 
     #expect(c.state == .stopped)
     #expect(c.playWhenReady == false)
-    #expect(eh.reloadTrackCalls.isEmpty)
+    #expect(eh.resolveAndLoadCalls.count == resolvesBefore)
   }
 
   /// A user who plays then pauses during the interruption has taken ownership
@@ -1119,7 +1038,7 @@ struct InterruptionTests {
     let (c, eh, _, _) = makeCoordinator()
     startPlaying(c, eh)
     // Pause before the interruption (e.g. user already paused).
-    c.playWhenReady = false
+    c.setPlayWhenReady(false)
     c.avPlayerDidChangeTimeControlStatus(.paused)
     #expect(c.state == .paused)
 
@@ -1132,10 +1051,9 @@ struct InterruptionTests {
 
 // MARK: - Skip availability freshness
 
-/// tracks.didSet pushes availability mid-mutation, while currentIndex and the
-/// shuffle order are still stale — the coordinator must re-push after the
-/// mutation settles or the lock-screen buttons keep the wrong state.
-@Suite("PlaybackCoordinator - skip availability after mutations")
+/// A mutation pushes next/previous availability once, after currentIndex and the
+/// shuffle order have settled; an earlier push leaves the lock-screen buttons wrong.
+@Suite("Player - skip availability after mutations")
 struct MutationSkipAvailabilityTests {
   @Test @MainActor
   func move_pushesPostMutationAvailability() throws {
@@ -1149,6 +1067,7 @@ struct MutationSkipAvailabilityTests {
     try c.move(fromIndex: 0, toIndex: 1)
 
     // Current track is now last: nothing to skip to.
+    #expect(eh.updateSkipAvailabilityCalls.count == 1)
     #expect(eh.updateSkipAvailabilityCalls.last?.canNext == false)
   }
 
@@ -1167,49 +1086,180 @@ struct MutationSkipAvailabilityTests {
     try c.remove(0)
 
     // Current settled at index 1 of 2: previous available, next not.
+    #expect(eh.updateSkipAvailabilityCalls.count == 1)
     #expect(eh.updateSkipAvailabilityCalls.last?.canNext == false)
     #expect(eh.updateSkipAvailabilityCalls.last?.canPrevious == true)
   }
 }
 
+// MARK: - Publishing
+
+@Suite("Player - publishing")
+struct PublishingTests {
+  /// The order JS has always seen: the intent, then the playing state, then the playback. A
+  /// natural end clears the intent on the way in; each change still goes out once.
+  @Test @MainActor
+  func endingPublishesTheIntentThenThePlayingStateThenThePlayback() {
+    let (c, _, cb, _) = makeCoordinator()
+    c.setPlayWhenReady(true)
+    c.transition(.avPlayerPlaying)
+    cb.publishOrder.removeAll()
+
+    c.transition(.trackEndedNaturally)
+
+    #expect(cb.publishOrder == ["playWhenReady", "playingState", "playback"])
+  }
+
+  @Test @MainActor
+  func aTransitionPublishesThePlayingStateBeforeThePlayback() {
+    let (c, _, cb, _) = makeCoordinator()
+    c.setPlayWhenReady(true)
+    cb.publishOrder.removeAll()
+
+    c.transition(.avPlayerPlaying)
+
+    #expect(cb.publishOrder == ["playingState", "playback"])
+  }
+
+  @Test @MainActor
+  func aRepeatedTerminalErrorIsReportedAgain() {
+    let (c, _, cb, _) = makeCoordinator()
+    c.transition(.errorOccurred(.playbackFailed))
+    c.transition(.errorOccurred(.playbackFailed))
+
+    #expect(cb.errorEvents.count == 2)
+  }
+}
+
+// MARK: - Load
+
+@Suite("Player - Load")
+struct LoadTests {
+  @MainActor
+  private func track(_ id: String) -> Track {
+    Track(id: id, src: "https://example.com/\(id).mp3", title: id)
+  }
+
+  @Test @MainActor
+  func aNewTrackStartsAnUnprovenLoad() {
+    let (c, _, _, _) = makeCoordinator()
+    c.setQueue([track("a"), track("b")])
+    let first = c.load
+    c.audioDidStart()
+    #expect(c.load?.hasPlayed == true)
+
+    c.next()
+
+    #expect(c.load != nil && c.load?.id != first?.id)
+    #expect(c.load?.hasPlayed == false)
+  }
+
+  /// The healthy-playback refill resets the retry budgets mid-play; the load, and with it the
+  /// recovery budget, must survive it.
+  @Test @MainActor
+  func aRetryResetKeepsTheLoad() {
+    let (c, _, _, _) = makeCoordinator()
+    c.setQueue([track("a")])
+    c.audioDidStart()
+    let load = c.load
+
+    c.retry.reset()
+
+    #expect(c.load == load)
+    #expect(c.load?.hasPlayed == true)
+  }
+
+  @Test @MainActor
+  func theNowPlayingPrimeRunsOncePerLoad() {
+    let (c, _, _, _) = makeCoordinator()
+    c.setQueue([track("a")])
+    #expect(c.claimNowPlayingPrime())
+    #expect(!c.claimNowPlayingPrime())
+
+    c.beginLoad()
+
+    #expect(c.claimNowPlayingPrime())
+  }
+}
+
+// MARK: - Queue publication
+
+@Suite("Player - queue publication")
+struct QueuePublicationTests {
+  @MainActor
+  private func threeTracks() -> [Track] {
+    ["a", "b", "c"].map { Track(id: $0, src: "https://example.com/\($0).mp3", title: $0) }
+  }
+
+  @Test @MainActor
+  func setQueue_publishesTheQueueBeforeTheActiveTrack() {
+    let (c, _, cb, _) = makeCoordinator()
+    c.setQueue(threeTracks())
+    #expect(cb.queueChanges.map { $0.map(\.id) } == [["a", "b", "c"]])
+    #expect(cb.queueAndTrackOrder == ["queue", "activeTrack"])
+  }
+
+  @Test @MainActor
+  func move_publishesTheSettledQueueOnce() throws {
+    let (c, _, cb, _) = makeCoordinator()
+    c.setQueue(threeTracks())
+    cb.queueChanges.removeAll()
+    try c.move(fromIndex: 0, toIndex: 2)
+    #expect(cb.queueChanges.map { $0.map(\.id) } == [["b", "c", "a"]])
+  }
+
+  @Test @MainActor
+  func clear_publishesAnEmptyQueue() {
+    let (c, _, cb, _) = makeCoordinator()
+    c.setQueue(threeTracks())
+    cb.queueChanges.removeAll()
+    c.clear()
+    #expect(cb.queueChanges.map(\.count) == [0])
+  }
+
+  @Test @MainActor
+  func navigation_publishesNoQueue() throws {
+    let (c, _, cb, _) = makeCoordinator()
+    c.setQueue(threeTracks())
+    cb.queueChanges.removeAll()
+    c.next()
+    c.previous()
+    try c.skipTo(2)
+    #expect(cb.queueChanges.isEmpty)
+  }
+}
+
 // MARK: - Stop cancels pending retry
 
-@Suite("PlaybackCoordinator - stop cancels pending retry")
+@Suite("Player - stop cancels pending retry")
 struct StopCancelsRetryTests {
   /// A retry surviving stop() gives up later (intent dropped) and surfaced
   /// .errorOccurred over the deliberate stop — the UI showed an error seconds
   /// after the user stopped.
   @Test @MainActor
   func stop_cancelsPendingRetry_andStaysSilent() async {
-    let retryHandler = MockRetryHandling()
-    retryHandler.isRetryableResult = true
-    retryHandler.attemptRetryResult = false
-    retryHandler.attemptRetryDelayNs = 50_000_000
-    let errorHandler = PlaybackErrorHandler(retryHandler: retryHandler)
-    let coordinator = PlaybackCoordinator(
-      errorHandler: errorHandler, sleepTimerManager: MockSleepTimerHandling(),
-    )
-    let effectHandler = MockPlaybackEffectHandler()
-    let callbacks = MockPlaybackCoordinatorCallbacks()
-    coordinator.effectHandler = effectHandler
-    coordinator.callbacks = callbacks
+    let errorHandler = makeRetryLoop(delay: 0.05)
+    let engine = MockPlayerEngine()
+    let player = makePlayer(engine: engine, retry: errorHandler)
+    let callbacks = MockPlayerCallbacks()
+    player.callbacks = callbacks
 
     errorHandler.handleError(URLError(.timedOut), context: .playback)
-    let task = errorHandler.pendingRetryTask
+    let task = errorHandler.pendingTask
     #expect(task != nil)
 
-    coordinator.stop()
-    #expect(errorHandler.pendingRetryTask == nil)
+    player.stop()
+    #expect(errorHandler.pendingTask == nil)
 
     await task?.value
-    #expect(coordinator.state == .stopped)
+    #expect(player.state == .stopped)
     #expect(callbacks.errorEvents.isEmpty)
   }
 }
 
 // MARK: - Audio session release (#60)
 
-@Suite("PlaybackCoordinator - audio session release")
+@Suite("Player - audio session release")
 struct SessionReleaseTests {
   @Test @MainActor
   func deliberatePause_requestsRelease() {