react-native-audio-browser 0.2.0-next.3 → 0.2.0-next.31

package/ios/Player/{PlaybackCoordinatorCallbacks.swift → PlayerCallbacks.swift}

@@ -2,10 +2,8 @@
   import NitroModules
 #endif
 
-/// Subset of TrackPlayerCallbacks containing only the callbacks the coordinator fires.
-/// Uses Nitro types (no AVFoundation). TrackPlayerCallbacks extends this protocol
-/// so HybridAudioBrowser implements both automatically.
-@MainActor protocol PlaybackCoordinatorCallbacks: AnyObject {
+/// What the Player reports, in Nitro types. HybridAudioBrowser implements it.
+@MainActor protocol PlayerCallbacks: AnyObject {
   func playerDidChangePlayback(_ playback: Playback)
   func playerDidChangeActiveTrack(_ event: PlaybackActiveTrackChangedEvent)
   func playerDidUpdateProgress(_ event: PlaybackProgressUpdatedEvent)
@@ -21,4 +19,5 @@
   /// (those resume), and no retry is pending (a live-stream reconnect must keep the session). The
   /// host may release the audio session (debounced) so other apps' audio can resume.
   func playerShouldReleaseSession()
+  func playerDidChangeSleepTimer(_ state: SleepTimerState?)
 }

package/ios/Player/PlayerEngine.swift

@@ -0,0 +1,87 @@
+import Foundation
+
+#if canImport(NitroModules)
+  import NitroModules
+#endif
+
+/// What the media stack reports to the Player.
+enum EngineEvent {
+  /// The loaded item is now current and observed.
+  case itemPrepared(likelyToKeepUp: Bool)
+  /// Loading the asset failed; the retry loop classifies the error.
+  case loadFailed(Error)
+  /// The asset loaded but cannot play.
+  case unplayable
+  /// The source is not a URL.
+  case invalidSource(String)
+  /// The player or its item failed, with the HTTP status the server last answered, if any.
+  case failed(Error?, httpStatusCode: Int?)
+  case likelyToKeepUp(Bool)
+  /// `waitingForNoItem`: the player waits because it has no item to play.
+  case timeControlStatus(PlayerTimeControlStatus, waitingForNoItem: Bool)
+  /// Playback crossed the first millisecond.
+  case audioDidStart
+  case playedToEnd
+  /// The buffer emptied mid-playback.
+  case stalled
+}
+
+/// The media stack under the Player: the AVPlayer and its items, media loading, now playing and
+/// the remote commands. It carries out what the Player decides and reports what it observes
+/// through `onEvent`; it holds no playback policy. AVPlayerEngine is the one implementation;
+/// tests use a mock.
+@MainActor protocol PlayerEngine: AnyObject {
+  var onEvent: (@MainActor (EngineEvent) -> Void)? { get set }
+
+  // MARK: The current item
+
+  var hasItem: Bool { get }
+  var hasLoadedAsset: Bool { get }
+  var currentTime: Double { get }
+  var duration: Double { get }
+  var bufferedPosition: Double { get }
+  /// The position a reload resumes from: nil without an item, or for an indefinite duration.
+  var resumePosition: Double? { get }
+  /// The end of a live stream's seekable window, when it has one.
+  var liveEdge: Double? { get }
+  var isPlaybackLikelyToKeepUp: Bool { get }
+  var isAirPlayRoute: Bool { get }
+  /// 0–1; ramped by the sleep-timer fade.
+  var volume: Float { get set }
+
+  // MARK: Loading
+
+  /// Runs the media-URL resolver for `track`, so a short-lived URL is minted afresh, and loads
+  /// the result.
+  func resolveAndLoad(src: String, track: Track)
+  func cancelLoading()
+  /// Drops the asset and stops observing the item, leaving it in place for the reload.
+  func dropAsset()
+  /// Drops the asset and removes the item.
+  func clearItem()
+  func stopObservingItem()
+  /// Replaces the AVPlayer: every handle to the old one is invalid.
+  func recreate()
+
+  // MARK: Transport
+
+  func play()
+  func pause()
+  /// Stages `rate` for the next play; applies it now only when `playing`, since a nonzero
+  /// AVPlayer rate is a play.
+  func setRate(_ rate: Float, playing: Bool)
+  /// Seeks the current item exactly; `completion` runs on the main actor.
+  func seek(to seconds: Double, completion: @escaping @MainActor (Bool) -> Void)
+  func applyTimePitchAlgorithm()
+
+  // MARK: Now playing and remote commands
+
+  /// Renders silence so iOS elects the app onto the now-playing surfaces (ADR 0005).
+  func primeNowPlaying()
+  func loadNowPlayingMetadata(for track: Track)
+  func clearNowPlaying()
+  func updateRemoteRepeatMode(_ mode: RepeatMode)
+  func updateRemoteShuffleMode(_ enabled: Bool)
+  /// Greys out next/previous on the remote surfaces when the queue has nowhere to skip.
+  func updateSkipAvailability(canNext: Bool, canPrevious: Bool)
+}

package/ios/Player/PlayerStatusTypes.swift

@@ -1,9 +1,5 @@
-/// Decouples PlaybackCoordinator from AVFoundation enum types.
-/// TrackPlayer maps from AVPlayer.TimeControlStatus → PlayerTimeControlStatus at the call boundary.
+/// Decouples Player from AVFoundation enum types.
+/// AVPlayerEngine maps from AVPlayer.TimeControlStatus → PlayerTimeControlStatus at the call boundary.
 enum PlayerTimeControlStatus {
   case paused, waitingToPlayAtSpecifiedRate, playing
 }
-
-enum PlayerItemStatus {
-  case unknown, readyToPlay, failed
-}

package/ios/Player/QueueManager.swift

@@ -3,9 +3,16 @@ import Foundation
   import NitroModules
 #endif
 
-/// Notifies the owner when the track list changes.
-@MainActor protocol QueueManagerDelegate: AnyObject {
-  func queueDidChangeTracks(_ tracks: [Track])
+/// What a queue mutation changed, reported once the queue has settled.
+struct QueueChange: Equatable {
+  /// The track list changed.
+  var tracks = false
+  /// A different track became current, or the current track was cleared.
+  var currentTrack = false
+
+  static let none = QueueChange()
+  static let tracksOnly = QueueChange(tracks: true)
+  static let tracksAndCurrent = QueueChange(tracks: true, currentTrack: true)
 }
 
 /// Result of a navigation action (next/previous/skipTo).
@@ -19,11 +26,9 @@ enum QueueNavigationResult {
 }
 
 /// Pure queue logic: tracks, indices, shuffle, repeat.
-/// Has no knowledge of AVPlayer or playback — TrackPlayer owns that.
+/// Has no knowledge of AVPlayer or playback — Player and its engine own that.
 @MainActor
 class QueueManager {
-  weak var delegate: QueueManagerDelegate?
-
   // MARK: - Stored Properties
 
   /// The index of the current track. `-1` when there is no current track.
@@ -33,11 +38,7 @@ class QueueManager {
   private(set) var queueSourcePath: String?
 
   /// All tracks held by the queue.
-  private(set) var tracks: [Track] = [] {
-    didSet {
-      delegate?.queueDidChangeTracks(tracks)
-    }
-  }
+  private(set) var tracks: [Track] = []
 
   /// The shuffle order for randomized playback.
   private(set) var shuffleOrder = ShuffleOrder()
@@ -45,8 +46,15 @@ class QueueManager {
   /// The repeat mode for the queue. Plain property — no side effects.
   var repeatMode: RepeatMode = .off
 
-  /// Whether shuffle mode is enabled. Plain property — no side effects.
-  var shuffleEnabled: Bool = false
+  /// Whether shuffle mode is enabled.
+  var shuffleEnabled: Bool = false {
+    didSet {
+      // Re-pin on enable: the existing order has the current track wherever it happened to land,
+      // so without this, turning shuffle on near the end of the queue ends it right away.
+      guard shuffleEnabled, shuffleEnabled != oldValue else { return }
+      shuffleOrder.reshuffle(keepingFirst: currentIndex)
+    }
+  }
 
   // MARK: - Computed Properties
 
@@ -196,41 +204,36 @@ class QueueManager {
     return .trackChanged
   }
 
-  // MARK: - Mutations (returns Bool: whether current track changed)
+  // MARK: - Mutations
 
-  /// Replace the entire queue with new tracks.
-  /// Returns `true` (current track always changes).
+  /// Replace the entire queue with new tracks. The current track always changes.
   @discardableResult
-  func setQueue(_ newTracks: [Track], initialIndex: Int = 0, sourcePath: String? = nil) -> Bool {
+  func setQueue(_ newTracks: [Track], initialIndex: Int = 0, sourcePath: String? = nil) -> QueueChange {
     let clampedIndex = max(0, min(initialIndex, newTracks.count - 1))
     currentIndex = clampedIndex
     queueSourcePath = sourcePath
     tracks = newTracks
-    shuffleOrder = ShuffleOrder(length: newTracks.count)
-    return true
+    shuffleOrder = ShuffleOrder(length: newTracks.count, firstIndex: clampedIndex)
+    return .tracksAndCurrent
   }
 
-  /// Add tracks to the end of the queue.
-  /// Returns `true` if the queue was empty (a new current track was set).
+  /// Add tracks to the end of the queue. The current track changes only when the queue was empty.
   @discardableResult
-  func add(_ newTracks: [Track], initialIndex: Int = 0) -> Bool {
-    guard !newTracks.isEmpty else { return false }
+  func add(_ newTracks: [Track], initialIndex: Int = 0) -> QueueChange {
+    guard !newTracks.isEmpty else { return .none }
     let wasEmpty = tracks.isEmpty
     let insertIndex = tracks.count
     tracks.append(contentsOf: newTracks)
+    if wasEmpty { return adoptInitialCurrent(initialIndex) }
     shuffleOrder.insert(at: insertIndex, count: newTracks.count)
-    if wasEmpty {
-      currentIndex = max(0, min(initialIndex, tracks.count - 1))
-      return true
-    }
-    return false
+    return .tracksOnly
   }
 
-  /// Add tracks at a specific index in the queue.
-  /// Returns `true` if the queue was empty (a new current track was set).
+  /// Add tracks at a specific index in the queue. The current track changes only when the queue
+  /// was empty.
   @discardableResult
-  func addAt(_ newTracks: [Track], at index: Int) throws -> Bool {
-    guard !newTracks.isEmpty else { return false }
+  func addAt(_ newTracks: [Track], at index: Int) throws -> QueueChange {
+    guard !newTracks.isEmpty else { return .none }
     guard index >= 0, tracks.count >= index else {
       throw TrackPlayerError.QueueError.invalidIndex(
         index: index,
@@ -243,48 +246,68 @@ class QueueManager {
       currentIndex += newTracks.count
     }
     tracks.insert(contentsOf: newTracks, at: index)
+    if wasEmpty { return adoptInitialCurrent(0) }
     shuffleOrder.insert(at: index, count: newTracks.count)
-    if wasEmpty {
-      currentIndex = 0
-      return true
-    }
-    return false
+    return .tracksOnly
+  }
+
+  /// The queue was empty: `index` becomes the current track AND leads the
+  /// shuffle order. One operation because the two must not be separable —
+  /// forgetting the second half is the bug this exists to prevent.
+  ///
+  /// `insert(at:count:)` drops new indices at *random* shuffle positions, so
+  /// without the pin the starting track can land last in the order, which reads
+  /// as `isLastInPlaybackOrder`: the queue "ends" (and fires
+  /// `playerDidEndQueue`) the moment the first track finishes. Pins
+  /// unconditionally, like `setQueue` — the order has to be sane whether or not
+  /// shuffle is on right now, since `shuffleEnabled`'s didSet only re-pins on
+  /// the off→on edge.
+  ///
+  /// Returns the change, so callers can `return adoptInitialCurrent(…)`.
+  private func adoptInitialCurrent(_ index: Int) -> QueueChange {
+    currentIndex = max(0, min(index, tracks.count - 1))
+    shuffleOrder = ShuffleOrder(length: tracks.count, firstIndex: currentIndex)
+    return .tracksAndCurrent
   }
 
-  /// Remove a track from the queue.
-  /// Returns `true` if the current track changed.
+  /// Remove a track from the queue. The current track changes when it is the one removed.
   @discardableResult
-  func remove(_ index: Int) throws -> Bool {
+  func remove(_ index: Int) throws -> QueueChange {
     try throwIfQueueEmpty()
     try throwIfIndexInvalid(index: index)
     tracks.remove(at: index)
     shuffleOrder.remove(from: index, to: index + 1)
     if index == currentIndex {
       currentIndex = tracks.count > 0 ? currentIndex % tracks.count : -1
-      return true
+      return .tracksAndCurrent
     } else if index < currentIndex {
       currentIndex -= 1
     }
-    return false
+    return .tracksOnly
   }
 
-  /// Move a track in the queue from one position to another.
-  /// Returns `true` if the current track changed (fromIndex was currentIndex).
+  /// Move a track in the queue from one position to another. The current track never changes:
+  /// the pointer follows the playing track.
   @discardableResult
-  func move(fromIndex: Int, toIndex: Int) throws -> Bool {
+  func move(fromIndex: Int, toIndex: Int) throws -> QueueChange {
     try throwIfQueueEmpty()
     try throwIfIndexInvalid(index: fromIndex, name: "fromIndex")
     try throwIfIndexInvalid(index: toIndex, name: "toIndex", max: Int.max)
-    // Mutate a copy and assign once to trigger didSet only once
-    var newTracks = tracks
-    let track = newTracks.remove(at: fromIndex)
-    let insertion = min(newTracks.count, toIndex)
-    newTracks.insert(track, at: insertion)
-    tracks = newTracks
+    let track = tracks.remove(at: fromIndex)
+    let insertion = min(tracks.count, toIndex)
+    tracks.insert(track, at: insertion)
+    // Carry the moved track's shuffle position across the move. `insert(at:count:)`
+    // would drop it at a RANDOM position instead — reordering the queue would then
+    // silently reorder shuffled playback, and moving the playing track could land it
+    // last in the order, ending the queue at the next track boundary with tracks
+    // still unplayed (the failure `adoptInitialCurrent` guards against elsewhere).
+    // `remove` shifts every later position down by one, so re-inserting at the
+    // captured position restores the exact prior order.
+    let shufflePosition = shuffleOrder.shufflePosition(of: fromIndex)
     shuffleOrder.remove(from: fromIndex, to: fromIndex + 1)
-    shuffleOrder.insert(at: insertion, count: 1)
-    // The pointer follows the playing track; its identity never changes on a
-    // move, so no caller needs to reload (returning true reloads).
+    shuffleOrder.insert(
+      at: insertion, atShufflePosition: shufflePosition ?? shuffleOrder.count,
+    )
     if currentIndex == fromIndex {
       currentIndex = insertion
     } else if fromIndex < currentIndex, insertion >= currentIndex {
@@ -292,35 +315,38 @@ class QueueManager {
     } else if fromIndex > currentIndex, insertion <= currentIndex {
       currentIndex += 1
     }
-    return false
+    return .tracksOnly
   }
 
-  /// Remove all tracks and reset state.
-  /// Returns `true` if there was a current track to clear.
+  /// Remove all tracks and reset state. Does nothing when there is no current track.
   @discardableResult
-  func clear() -> Bool {
-    guard currentIndex != -1 else { return false }
+  func clear() -> QueueChange {
+    guard currentIndex != -1 else { return .none }
     currentIndex = -1
     tracks.removeAll()
     shuffleOrder.clear()
     queueSourcePath = nil
-    return true
+    return .tracksAndCurrent
   }
 
-  // MARK: - Other Mutations
-
-  /// Replace the track at a specific index.
-  func replace(_ index: Int, _ track: Track) {
+  /// Replace the track at a specific index; which index is current does not change.
+  /// Throws like every other index-taking mutation here, rather than trapping.
+  @discardableResult
+  func replace(_ index: Int, _ track: Track) throws -> QueueChange {
+    try throwIfIndexInvalid(index: index)
     tracks[index] = track
+    return .tracksOnly
   }
 
   /// Remove all upcoming tracks (those after currentIndex).
-  func removeUpcomingTracks() {
-    guard !tracks.isEmpty else { return }
+  @discardableResult
+  func removeUpcomingTracks() -> QueueChange {
+    guard !tracks.isEmpty else { return .none }
     let nextIndex = currentIndex + 1
-    guard nextIndex < tracks.count else { return }
+    guard nextIndex < tracks.count else { return .none }
     let end = tracks.count
     tracks.removeSubrange(nextIndex ..< end)
     shuffleOrder.remove(from: nextIndex, to: end)
+    return .tracksOnly
   }
 }

package/ios/Player/RetryLoop.swift

@@ -0,0 +1,261 @@
+import AVFoundation
+import Foundation
+#if canImport(NitroModules)
+  import NitroModules
+#endif
+import os.log
+
+/// Abstracts `NetworkMonitor` so tests can fake connectivity. Sendable because
+/// the network-restore race reads it from a task-group child.
+protocol NetworkStatusProviding: AnyObject, Sendable {
+  var isOnline: Bool { get }
+}
+
+/// Distinguishes playback failures from media-load failures.
+/// Each context carries the retry strategy and the fallback error classification.
+public enum PlaybackErrorContext {
+  /// AVPlayer/AVPlayerItem status failure — retry from current time, fallback `.playbackFailed`.
+  case playback
+  /// MediaLoader key-value load failure — retry from start, fallback `.failedToLoadKeyValue`.
+  case mediaLoad
+
+  var startFromCurrentTime: Bool {
+    switch self {
+    case .playback: true
+    case .mediaLoad: false
+    }
+  }
+
+  var fallbackError: TrackPlayerError.PlaybackError {
+    switch self {
+    case .playback: .playbackFailed
+    case .mediaLoad: .failedToLoadKeyValue
+    }
+  }
+}
+
+/// Retries failed loads: classifies each failure (`PlaybackFailure`), reports the ones it is
+/// working on as advisory, and reloads after an exponential backoff until a budget runs out,
+/// when it reports the error as terminal. Similar to Android's RetryLoadErrorHandlingPolicy.
+///
+/// Two duration budgets apply, chosen by whether the current Load has produced audio
+/// (`hasPlayed`, ADR 0004): a short first-connect budget, since a stream that fails before ever
+/// playing is usually dead and the listener is waiting for a verdict, and the full recovery
+/// budget for a stream that played and dropped. The short budget counts only online time, and
+/// while offline a scheduled retry fires as soon as connectivity returns.
+@MainActor
+final class RetryLoop {
+  private let logger = Logger(subsystem: "com.audiobrowser", category: "RetryLoop")
+
+  enum Policy {
+    case disabled
+    case infinite
+    case limited(maxRetries: Int)
+  }
+
+  private static let defaultMaxRetryDurationMs: Double = 120_000
+  private static let defaultFirstConnectMaxRetryDurationMs: Double = 12_000
+
+  /// Prevents surprising playback resumption after long periods offline.
+  private var maxRetryDuration: TimeInterval = defaultMaxRetryDurationMs / 1000
+  /// Bounds retries of a load that has never produced audio, while online.
+  private var firstConnectMaxRetryDuration: TimeInterval = defaultFirstConnectMaxRetryDurationMs / 1000
+
+  /// Whether the current Load has produced audio. Read from the Load, which a mid-play `reset()`
+  /// (the healthy-playback refill) leaves alone.
+  var hasPlayed: () -> Bool = { false }
+  /// Whether a retry is still wanted (the play intent); checked before and after the backoff.
+  var shouldRetry: () -> Bool = { true }
+  /// Reloads, from the current time or from the start.
+  var onRetry: ((Bool) -> Void)?
+  /// The retries gave up, or the failure cannot be retried.
+  var onError: ((TrackPlayerError.PlaybackError) -> Void)?
+  /// A failure a retry is now scheduled for, reported before the backoff so UIs can show the
+  /// cause while the state stays non-terminal.
+  var onRetryingError: ((TrackPlayerError.PlaybackError) -> Void)?
+
+  weak var networkMonitor: (any NetworkStatusProviding)?
+
+  /// The retry in flight; session release waits while there is one.
+  private(set) var pendingTask: Task<Void, Never>?
+  /// True only while a scheduled retry waits for connectivity to return, so a stall-driven
+  /// reconnect can defer to it rather than load twice.
+  private(set) var isWaitingForNetwork = false
+  /// Retries executed since the budgets last reset.
+  private(set) var attempts = 0
+
+  private var policy: Policy = .disabled
+  private var firstRetryTime: Date?
+  /// First failure observed while online for the current load: the first-connect budget's
+  /// clock. Never set while offline, and wiped by any offline observation, so an offline stretch
+  /// cannot burn the short budget.
+  private var firstOnlineRetryTime: Date?
+
+  private let sleep: @Sendable (TimeInterval) async throws -> Void
+
+  /// - Parameter sleep: Waits out a backoff or a connectivity poll; tests make it instant.
+  init(sleep: @escaping @Sendable (TimeInterval) async throws -> Void = { try await Task.sleep(for: .seconds($0)) }) {
+    self.sleep = sleep
+  }
+
+  var isEnabled: Bool {
+    if case .disabled = policy { return false }
+    return true
+  }
+
+  // MARK: - Configuration
+
+  func updatePolicy(from config: Variant_Bool_RetryConfig?) {
+    maxRetryDuration = Self.defaultMaxRetryDurationMs / 1000
+    firstConnectMaxRetryDuration = Self.defaultFirstConnectMaxRetryDurationMs / 1000
+    switch config {
+    case nil:
+      policy = .disabled
+    case let .first(enabled):
+      policy = enabled ? .infinite : .disabled
+    case let .second(retryConfig):
+      maxRetryDuration = (retryConfig.maxRetryDurationMs ?? Self.defaultMaxRetryDurationMs) / 1000
+      firstConnectMaxRetryDuration =
+        (retryConfig.firstConnectMaxRetryDurationMs ?? Self.defaultFirstConnectMaxRetryDurationMs) / 1000
+      // No attempt cap: retry indefinitely, bounded only by the duration.
+      policy = retryConfig.maxRetries.map { .limited(maxRetries: Int($0)) } ?? .infinite
+    }
+    logger.debug("Retry policy: \(String(describing: self.policy)), max duration \(self.maxRetryDuration)s")
+  }
+
+  // MARK: - Failures
+
+  func handleError(_ error: Error?, context: PlaybackErrorContext, httpStatusCode: Int? = nil) {
+    if let error {
+      let nsError = error as NSError
+      logger.error("[\(String(describing: context))] failure: domain=\(nsError.domain), code=\(nsError.code), localizedDescription=\(error.localizedDescription)")
+    } else {
+      logger.error("[\(String(describing: context))] failure with nil error")
+    }
+
+    let failure = PlaybackFailure.classify(error, httpStatusCode: httpStatusCode, fallback: context.fallbackError)
+    guard isEnabled, failure.retryable else {
+      logger.warning("Error not retryable, surfacing \(String(describing: failure.error))")
+      onError?(failure.error)
+      return
+    }
+    onRetryingError?(failure.error)
+    pendingTask?.cancel()
+    pendingTask = Task { [weak self] in
+      guard let self else { return }
+      let retried = await attemptRetry(startFromCurrentTime: context.startFromCurrentTime)
+      // Cancelled (track change, stop): stay silent, or the new track or a deliberate stop
+      // would flip to .error. The canceller owns the handle.
+      if Task.isCancelled { return }
+      if !retried { onError?(failure.error) }
+      pendingTask = nil
+    }
+  }
+
+  /// Drops the retry in flight without touching the budgets.
+  func cancel() {
+    pendingTask?.cancel()
+    pendingTask = nil
+  }
+
+  /// Drops the retry in flight and restarts the budgets.
+  func reset() {
+    cancel()
+    attempts = 0
+    firstRetryTime = nil
+    firstOnlineRetryTime = nil
+    isWaitingForNetwork = false
+  }
+
+  // MARK: - Budgets
+
+  private var isOnline: Bool { networkMonitor?.isOnline ?? true }
+
+  /// The exhausted budget, or nil while budget remains. The recovery duration bounds everything,
+  /// offline waits included; the first-connect duration also bounds never-played loads, online
+  /// only.
+  private func exhaustedBudget() -> String? {
+    let now = Date()
+    if let start = firstRetryTime, now.timeIntervalSince(start) >= maxRetryDuration {
+      return "max retry duration (\(maxRetryDuration)s)"
+    }
+    if !hasPlayed(), isOnline, let start = firstOnlineRetryTime,
+       now.timeIntervalSince(start) >= firstConnectMaxRetryDuration
+    {
+      return "first-connect retry duration (\(firstConnectMaxRetryDuration)s)"
+    }
+    return nil
+  }
+
+  /// 1 s, 1.5 s, 2.3 s, 3.4 s, then 5 s.
+  private var backoff: TimeInterval {
+    min(1.0 * pow(1.5, Double(attempts)), 5.0)
+  }
+
+  /// Waits out the backoff, or connectivity's return, then reloads. False when the policy, the
+  /// play intent or a budget says stop, or the wait was cancelled.
+  func attemptRetry(startFromCurrentTime: Bool) async -> Bool {
+    guard isEnabled, shouldRetry() else { return false }
+    if case let .limited(maxRetries) = policy, attempts >= maxRetries {
+      logger.info("Max retries (\(maxRetries)) exceeded, giving up")
+      return false
+    }
+
+    if firstRetryTime == nil { firstRetryTime = Date() }
+    if isOnline {
+      if firstOnlineRetryTime == nil { firstOnlineRetryTime = Date() }
+    } else {
+      // Offline restarts the first-connect clock: the station gets its full online seconds
+      // again once connectivity returns.
+      firstOnlineRetryTime = nil
+    }
+    if let budget = exhaustedBudget() {
+      logger.info("\(budget) exceeded, giving up")
+      return false
+    }
+
+    logger.info("Scheduling retry after \(self.backoff)s")
+    guard await waitForDelayOrNetworkRestored(delaySeconds: backoff), !Task.isCancelled, shouldRetry() else {
+      return false
+    }
+    // Re-checked: the wait for connectivity may have been long.
+    if let budget = exhaustedBudget() {
+      logger.info("\(budget) exceeded after waiting, giving up")
+      return false
+    }
+
+    attempts += 1
+    logger.info("Executing retry #\(self.attempts)")
+    onRetry?(startFromCurrentTime)
+    return true
+  }
+
+  // MARK: - Network-Aware Waiting
+
+  /// True when it is time to retry, false when the wait was cancelled.
+  private func waitForDelayOrNetworkRestored(delaySeconds: TimeInterval) async -> Bool {
+    guard let monitor = networkMonitor, !monitor.isOnline else {
+      return await (try? sleep(delaySeconds)) != nil
+    }
+    logger.debug("Device is offline, will retry immediately when connectivity is restored")
+    let sleep = sleep
+    return await withTaskGroup(of: Bool.self, returning: Bool.self) { group in
+      group.addTask { await (try? sleep(delaySeconds)) != nil }
+      group.addTask { [weak self] in await self?.waitForNetworkRestored(monitor: monitor) ?? false }
+      let result = await group.next() ?? false
+      group.cancelAll()
+      return result
+    }
+  }
+
+  /// True when connectivity returned, false when cancelled.
+  private func waitForNetworkRestored(monitor: any NetworkStatusProviding) async -> Bool {
+    isWaitingForNetwork = true
+    defer { isWaitingForNetwork = false }
+    while !monitor.isOnline {
+      guard await (try? sleep(0.5)) != nil else { return false }
+    }
+    logger.info("Network restored, accelerating retry")
+    return true
+  }
+}