react-native-queue-player 1.0.0

package/ios/Cast/Core/CastNowPlayingController.swift

@@ -0,0 +1,310 @@
+import AVFoundation
+import Foundation
+import MediaPlayer
+import UIKit
+
+/// Drives `MPNowPlayingInfoCenter` (lockscreen + Control Center)
+/// metadata while a Chromecast session is active. Without this, iOS
+/// reclaims the Now Playing slot as soon as the local `AVPlayer`
+/// stops, leaving the lockscreen blank during cast.
+///
+/// A silent `AVPlayer` loop (`silence.m4a`) runs for the duration of
+/// the cast session so `AVAudioSession` stays active and iOS keeps
+/// treating this app as the Now Playing app — without audible output,
+/// the system hands the lockscreen slot to whatever plays next.
+///
+/// Subscribes to `PlaybackStateRouter.shared` so it observes
+/// `CastSessionRemotePlayer` activation flips without needing a
+/// `CastManager` reference. `isPushSink == true` sessions (AirPlay)
+/// are skipped — push-PCM keeps the local AVAudioSession active
+/// already, so the lockscreen continues to mirror the local player.
+final class CastNowPlayingController {
+
+  static let shared = CastNowPlayingController()
+
+  private var activeChangeDisposer: (() -> Void)?
+  private var sessionListenerDisposers: [() -> Void] = []
+  private var silentPlayer: AVQueuePlayer?
+  private var silentLooper: Any?
+  private weak var currentSession: CastSessionRemotePlayer?
+
+  /// Resolves the receiver track's artwork URL to a `UIImage` for the
+  /// lockscreen. A private instance (own sequence counter) so a
+  /// cast↔local surface handoff can't cross-cancel the other surface's
+  /// in-flight fetch. Auth config is forwarded from
+  /// `TrackPlayer.configure` via `configureArtwork`.
+  private let artworkResolver = ArtworkResolver()
+
+  /// Bundled placeholder shown until the real cover resolves, so the
+  /// lockscreen never renders artwork-less during the network fetch.
+  private static let placeholderArtwork: MPMediaItemArtwork = {
+    let image = PlaceholderArtwork.image
+    return MPMediaItemArtwork(boundsSize: image.size) { _ in image }
+  }()
+
+  /// Snapshot of the active receiver track for the lockscreen surface.
+  /// Pushed by `TrackPlayer` when the receiver's current track (resolved
+  /// by absolute queue index) changes. `nil` until the first push (or
+  /// after deactivate).
+  private struct TrackMetadata {
+    let title: String?
+    let artist: String?
+    let album: String?
+    let durationSec: Double
+    let artworkUrl: String?
+  }
+  private var currentMetadata: TrackMetadata?
+
+  private init() {}
+
+  // MARK: - Lifecycle
+
+  /// Begin observing the global router. Idempotent — repeat calls are
+  /// no-ops. Called from `TrackPlayer.configure` after the engine is
+  /// set up.
+  func start() {
+    if activeChangeDisposer != nil { return }
+    activeChangeDisposer = PlaybackStateRouter.shared.addActiveChangeListener {
+      [weak self] session in
+      self?.handleActiveChange(to: session)
+    }
+  }
+
+  /// Stop observing + tear down any active mirror. Called from
+  /// `TrackPlayer.internalDestroy`.
+  func stop() {
+    deactivate()
+    activeChangeDisposer?()
+    activeChangeDisposer = nil
+  }
+
+  /// Push current-track metadata. Called by `TrackPlayer` when the
+  /// receiver's active track resolves (via `CastEventBridge`, which reads
+  /// the absolute queue index from `GCKMediaQueue`). The controller
+  /// refreshes the lockscreen if a cast session is active.
+  func updateTrackMetadata(
+    title: String?,
+    artist: String?,
+    album: String?,
+    durationSec: Double,
+    artworkUrl: String?
+  ) {
+    currentMetadata = TrackMetadata(
+      title: title, artist: artist, album: album,
+      durationSec: durationSec, artworkUrl: artworkUrl
+    )
+    if currentSession != nil {
+      refreshNowPlayingInfo()
+      resolveArtwork()
+    }
+  }
+
+  /// Forward the player's artwork HTTP config so authenticated artwork
+  /// URLs resolve during cast. Called from `TrackPlayer.configure`.
+  func configureArtwork(headers: [String: String]?, userAgent: String?) {
+    artworkResolver.configHeaders = headers
+    artworkResolver.configUserAgent = userAgent
+  }
+
+  // MARK: - Active-flow observer
+
+  private func handleActiveChange(to session: CastSessionRemotePlayer?) {
+    if let session, !session.isPushSink {
+      activate(with: session)
+    } else {
+      deactivate()
+    }
+  }
+
+  private func activate(with session: CastSessionRemotePlayer) {
+    deactivate()
+    currentSession = session
+    startSilentAudio()
+    wireSessionListeners(session)
+    refreshNowPlayingInfo()
+    // Resolve artwork in case metadata was pushed before activation.
+    resolveArtwork()
+  }
+
+  private func deactivate() {
+    sessionListenerDisposers.forEach { $0() }
+    sessionListenerDisposers.removeAll()
+    stopSilentAudio()
+    artworkResolver.cancelInFlight()
+    currentSession = nil
+    MPNowPlayingInfoCenter.default().nowPlayingInfo = nil
+  }
+
+  // MARK: - Silent audio loop
+
+  private func startSilentAudio() {
+    guard
+      let url = Bundle(for: CastNowPlayingController.self)
+        .url(forResource: "QueuePlayer", withExtension: "bundle")
+        .flatMap({ Bundle(url: $0) })?
+        .url(forResource: "silence", withExtension: "m4a")
+        ?? Bundle.main.url(forResource: "silence", withExtension: "m4a")
+    else {
+      NSLog(
+        "[CastNowPlayingController] silence.m4a missing from bundle — lockscreen "
+        + "metadata will not stay visible during cast. Verify the QueuePlayer pod "
+        + "resource_bundles include ios/Resources/silence.m4a."
+      )
+      return
+    }
+    let loopPlayer = AVQueuePlayer()
+    loopPlayer.isMuted = true
+    let looper = AVPlayerLooper(
+      player: loopPlayer,
+      templateItem: AVPlayerItem(url: url)
+    )
+    loopPlayer.play()
+    silentPlayer = loopPlayer
+    silentLooper = looper
+  }
+
+  private func stopSilentAudio() {
+    silentPlayer?.pause()
+    silentPlayer?.replaceCurrentItem(with: nil)
+    silentPlayer = nil
+    silentLooper = nil
+  }
+
+  // MARK: - Session listeners
+
+  private func wireSessionListeners(_ session: CastSessionRemotePlayer) {
+    let stateDisposer = session.addStateListener { [weak self] state in
+      self?.onState(state)
+    }
+    let positionDisposer = session.addPositionListener {
+      [weak self] positionMs, durationMs, _ in
+      self?.onPosition(positionMs: positionMs, durationMs: durationMs)
+    }
+    sessionListenerDisposers.append(stateDisposer)
+    sessionListenerDisposers.append(positionDisposer)
+  }
+
+  // MARK: - Now Playing updates
+
+  /// Private snapshot of the values we last pushed to
+  /// `MPNowPlayingInfoCenter`. Lets `onPosition` / `onState` /
+  /// `refreshNowPlayingInfo` skip the system write when nothing
+  /// actually changed. iOS treats a high-rate `nowPlayingInfo` writer
+  /// as an unhealthy player.
+  private struct PushedSnapshot {
+    var title: String?
+    var artist: String?
+    var album: String?
+    var durationSec: Double?
+    var rate: Double = 0.0
+    var elapsedSec: Double = 0.0
+  }
+  private var pushed = PushedSnapshot()
+
+  private func onState(_ state: RemotePlaybackStateKind) {
+    let rate: Double = (state == .playing) ? 1.0 : 0.0
+    if pushed.rate == rate { return }
+    pushed.rate = rate
+    var info = MPNowPlayingInfoCenter.default().nowPlayingInfo ?? [:]
+    info[MPNowPlayingInfoPropertyPlaybackRate] = rate
+    info[MPNowPlayingInfoPropertyElapsedPlaybackTime] = pushed.elapsedSec
+    MPNowPlayingInfoCenter.default().nowPlayingInfo = info
+  }
+
+  /// Position updates fire at 1 Hz from the session. iOS extrapolates
+  /// between updates from rate + elapsed, so we only push when the
+  /// integer-second elapsed moves, or when the receiver first reports a
+  /// stream duration that differs from what's on the lockscreen —
+  /// bounded to ~1 write/sec even if the source pushes more often.
+  private func onPosition(positionMs: Int64, durationMs: Int64) {
+    let elapsed: Double = Double(positionMs) / 1000.0
+    let elapsedMoved = (elapsed - pushed.elapsedSec).magnitude >= 0.5
+
+    let duration: Double = durationMs > 0 ? Double(durationMs) / 1000.0 : 0
+    let durationMoved =
+      duration > 0 && (duration - (pushed.durationSec ?? 0)).magnitude >= 0.5
+
+    guard elapsedMoved || durationMoved else { return }
+
+    var info = MPNowPlayingInfoCenter.default().nowPlayingInfo ?? [:]
+    if elapsedMoved {
+      pushed.elapsedSec = elapsed
+      info[MPNowPlayingInfoPropertyElapsedPlaybackTime] = elapsed
+    }
+    if durationMoved {
+      pushed.durationSec = duration
+      info[MPMediaItemPropertyPlaybackDuration] = duration
+    }
+    MPNowPlayingInfoCenter.default().nowPlayingInfo = info
+  }
+
+  private func refreshNowPlayingInfo() {
+    guard let session = currentSession else { return }
+    let rate = (session.lastState == .playing) ? 1.0 : 0.0
+    let elapsed = Double(session.lastPositionMs) / 1000.0
+    let duration = resolvedDurationSec(session: session)
+
+    var info: [String: Any] = [
+      MPNowPlayingInfoPropertyMediaType: MPNowPlayingInfoMediaType.audio.rawValue,
+      MPNowPlayingInfoPropertyElapsedPlaybackTime: elapsed,
+      MPNowPlayingInfoPropertyPlaybackRate: rate,
+      MPMediaItemPropertyArtwork: Self.placeholderArtwork,
+    ]
+    if duration > 0 {
+      info[MPMediaItemPropertyPlaybackDuration] = duration
+    }
+
+    if let metadata = currentMetadata {
+      // Only write keys that have a real value — empty strings push
+      // the system's previously-set value out of view (CarPlay
+      // collapses the row), leaving the lockscreen blanker than
+      // necessary while metadata is in flight.
+      if let title = metadata.title { info[MPMediaItemPropertyTitle] = title }
+      if let artist = metadata.artist { info[MPMediaItemPropertyArtist] = artist }
+      if let album = metadata.album { info[MPMediaItemPropertyAlbumTitle] = album }
+      pushed.title = metadata.title
+      pushed.artist = metadata.artist
+      pushed.album = metadata.album
+    }
+
+    pushed.durationSec = duration
+    pushed.rate = rate
+    pushed.elapsedSec = elapsed
+    MPNowPlayingInfoCenter.default().nowPlayingInfo = info
+  }
+
+  /// Duration for the lockscreen scrubber: the receiver's reported
+  /// stream duration when known, else the consumer-supplied track
+  /// duration (which is untrusted and frequently 0/unset).
+  private func resolvedDurationSec(session: CastSessionRemotePlayer) -> Double {
+    if session.lastDurationMs > 0 {
+      return Double(session.lastDurationMs) / 1000.0
+    }
+    return currentMetadata?.durationSec ?? 0
+  }
+
+  // MARK: - Artwork
+
+  /// Resolve the current track's artwork URL and swap it onto the
+  /// lockscreen. The resolver's sequence counter drops a superseded
+  /// fetch when the track advances mid-flight, so a stale cover never
+  /// lands on the wrong track.
+  private func resolveArtwork() {
+    let url = currentMetadata?.artworkUrl
+    artworkResolver.resolve(url: url) { [weak self] image in
+      self?.applyArtwork(image)
+    }
+  }
+
+  /// Swap the resolver-supplied image into the current now-playing
+  /// dict. No-op when the cast surface was torn down (deactivate niled
+  /// the dict) — never resurrect a cleared surface from artwork alone.
+  private func applyArtwork(_ image: UIImage) {
+    guard currentSession != nil,
+          var info = MPNowPlayingInfoCenter.default().nowPlayingInfo
+    else { return }
+    info[MPMediaItemPropertyArtwork] =
+      MPMediaItemArtwork(boundsSize: image.size) { _ in image }
+    MPNowPlayingInfoCenter.default().nowPlayingInfo = info
+  }
+}

package/ios/Cast/Core/CastReceiverState.swift

@@ -0,0 +1,22 @@
+import Foundation
+
+/// Receiver-driven playback state, protocol-neutral. Chromecast maps
+/// `GCKMediaPlayerState` → this; DLNA / Sonos backends map their own
+/// equivalents. The lib's `PlayerState` (the JS-facing enum) is derived
+/// from this in `CastEventBridge`.
+enum RemotePlaybackStateKind: String {
+  case idle, loading, playing, paused, buffering, ended, error
+}
+
+/// Reason a track ended on the receiver. Maps each platform's idle-
+/// reason enum onto one neutral value.
+enum RemoteEndReasonKind: String {
+  case finished, interrupted, canceled, error
+}
+
+/// Receiver-reported media error payload. `code` is platform-native;
+/// `message` is the platform-native description when available.
+struct RemoteMediaErrorPayload {
+  let code: Int
+  let message: String?
+}

package/ios/Cast/Core/CastSession.swift

@@ -0,0 +1,147 @@
+import Foundation
+
+/// Receiver-queue repeat mode. Maps `MediaStatus.REPEAT_MODE_*` on
+/// Android and `GCKMediaRepeatMode*` on iOS onto one enum.
+/// `ALL_AND_SHUFFLE` intentionally absent — shuffle is a sender-side
+/// concept exposed via the lib's existing playback-mode surface.
+enum RemoteRepeatMode {
+  case off, single, all
+}
+
+/// Live cast session — what cast backends mint when a receiver
+/// connects. Two paradigms mirror the Android sealed class:
+///
+/// - **PcmStream**: sender keeps decoding and pushes PCM frames into
+///   an `AudioSink` (AirPlay). Not yet implemented on iOS.
+/// - **RemotePlayer**: receiver decodes; the sender forwards transport
+///   commands. Chromecast (today) + future DLNA/Sonos backends.
+protocol CastSession: AnyObject {
+  /// `true` when the backend expects the sender to keep decoding and
+  /// push PCM frames into a sink; `false` when the receiver pulls +
+  /// decodes itself. Read by `CastTransportRouter` to decide whether
+  /// to intercept `TrackPlayer.*` calls or let the local engine
+  /// handle them.
+  var isPushSink: Bool { get }
+
+  /// Adjust receiver volume `0.0...1.0`. No-op when not supported.
+  func setVolume(_ value: Float)
+
+  /// Tear down. Safe to call multiple times.
+  func close()
+}
+
+/// Paradigm B — backend is a remote player. Chromecast and future
+/// DLNA / Sonos backends implement.
+///
+/// State, position, and queue snapshots are exposed as `last*` getters
+/// (read at any time) plus `add*Listener` methods that register a
+/// multi-callback and return a disposer. `CastEventBridge` subscribes
+/// for the JS-event fan-out; `CastNowPlayingController` (7C.2) will
+/// subscribe alongside for the lockscreen mirror. The session is
+/// multi-listenable to support concurrent subscribers without forcing
+/// one to multiplex for the others.
+protocol CastSessionRemotePlayer: CastSession {
+
+  /// Snapshot of most-recent receiver-driven state.
+  var lastState: RemotePlaybackStateKind { get }
+
+  /// Most-recent receiver-reported stream position in milliseconds.
+  /// `0` before the first status arrives.
+  var lastPositionMs: Int64 { get }
+
+  /// Most-recent receiver-reported stream duration in milliseconds.
+  /// `0` for unknown / unbounded (e.g. live streams).
+  var lastDurationMs: Int64 { get }
+
+  /// Most-recent receiver-reported buffered position in milliseconds.
+  /// Often tracks `lastPositionMs` closely for Chromecast — the SDK
+  /// doesn't surface buffer-ahead as a first-class signal.
+  var lastBufferedMs: Int64 { get }
+
+  /// Most-recent ABSOLUTE index of the receiver's current item in the
+  /// full queue (lib-track index), resolved by the backend against the
+  /// whole queue (`GCKMediaQueue`) rather than the receiver's ~3-item
+  /// status window. `-1` before the first resolvable status.
+  var lastCurrentTrackIndex: Int { get }
+
+  /// Most-recent receiver-reported device volume `0.0...1.0`, or
+  /// `Float.nan` before the first `MediaStatus` has been seen.
+  var lastVolume: Float { get }
+
+  /// Subscribe to receiver-state transitions. Disposer removes the
+  /// listener. Listener fires on every state change pushed by the
+  /// receiver — not invoked on subscribe; read `lastState` for the
+  /// current snapshot.
+  func addStateListener(_ cb: @escaping (RemotePlaybackStateKind) -> Void) -> () -> Void
+
+  /// Subscribe to position / duration / buffered ticks (typically
+  /// 1 Hz). Callback receives `(positionMs, durationMs, bufferedMs)`.
+  func addPositionListener(_ cb: @escaping (Int64, Int64, Int64) -> Void) -> () -> Void
+
+  /// Subscribe to absolute-current-track-index changes — fires when the
+  /// receiver advances to a different queue item, carrying the lib-track
+  /// index resolved against the full queue (see `lastCurrentTrackIndex`).
+  func addCurrentTrackIndexListener(_ cb: @escaping (Int) -> Void) -> () -> Void
+
+  /// Subscribe to "track ended on the receiver" events.
+  func addEndedReasonListener(_ cb: @escaping (RemoteEndReasonKind) -> Void) -> () -> Void
+
+  /// Subscribe to receiver-reported media errors.
+  func addMediaErrorListener(_ cb: @escaping (RemoteMediaErrorPayload) -> Void) -> () -> Void
+
+  /// Subscribe to seek-completion events with the resolved position
+  /// (ms).
+  func addSeekCompletedListener(_ cb: @escaping (Int64) -> Void) -> () -> Void
+
+  /// Subscribe to device-volume changes. Fires whenever the receiver
+  /// reports a different `streamVolume` (dedup'd by the implementing
+  /// session against the last emitted value).
+  func addVolumeListener(_ cb: @escaping (Float) -> Void) -> () -> Void
+
+  // MARK: - Transport (fire-and-forget)
+
+  func play()
+  func pause()
+  func stop()
+  func seekTo(positionMs: Int64)
+  /// Seek the receiver by `deltaMs` relative to its current stream position
+  /// (positive = forward). Uses the Cast SDK's native relative seek so the
+  /// receiver computes the target — no reliance on the sender's polled
+  /// position snapshot.
+  func seekBy(deltaMs: Int64)
+  func queueNext()
+  func queuePrev()
+  /// Jump the receiver to the queue item at absolute lib-track `index`.
+  /// The backend resolves `index` to the receiver itemId against the full
+  /// queue (`GCKMediaQueue`), so callers pass lib indices, never opaque
+  /// receiver itemIds. Out-of-range / unresolved indices are a no-op.
+  func skipToQueueIndex(index: Int)
+  func setPlaybackRate(_ rate: Float)
+  func setRepeatMode(_ mode: RemoteRepeatMode)
+
+  // MARK: - Queue mutations (suspending)
+
+  /// Push the full `items` queue to the receiver starting at
+  /// `startIndex` + `startPositionMs`, beginning playback only when
+  /// `playWhenReady` is true (a handoff from a paused local session
+  /// starts the receiver paused at that position). Returns the receiver
+  /// itemIds in the same order as `items` as the load's success signal.
+  func load(
+    items: [CastMediaItem],
+    startIndex: Int,
+    startPositionMs: Int64,
+    playWhenReady: Bool
+  ) async throws -> [Int]
+
+  /// Insert `items` before the queue item at absolute lib-track
+  /// `beforeIndex` (resolved to a receiver itemId against the full
+  /// queue); `nil` / out-of-range appends.
+  func queueInsert(items: [CastMediaItem], beforeIndex: Int?) async throws
+  /// Remove the queue items at the given absolute lib-track indices.
+  func queueRemove(indices: [Int]) async throws
+  /// Move the queue item at `fromIndex` to `toIndex` (array-move
+  /// semantics).
+  func queueMove(fromIndex: Int, toIndex: Int) async throws
+  /// Remove every item from the receiver queue.
+  func queueClear() async throws
+}

package/ios/Cast/Core/CastTransportRouter.swift

@@ -0,0 +1,162 @@
+import Foundation
+
+/// Transport-side shim — `TrackPlayer`'s per-call entry point for
+/// "should this command route to the receiver, or hit the local
+/// engine?". Each `routeXxx` helper returns `true` when the command
+/// was accepted by a live remote session (caller skips local
+/// handling); `false` when there's no active remote (caller proceeds
+/// locally).
+///
+/// Reads the active remote through
+/// `PlaybackStateRouter.shared.activeRemote()`. Snapshot semantics —
+/// by the time the local fallback runs, the session may have ended,
+/// but the local path is the right thing for the next call anyway.
+///
+/// Mirrors Android's `internal object CastTransportRouter`.
+enum CastTransportRouter {
+
+  static func routePlay() -> Bool {
+    guard let remote = PlaybackStateRouter.shared.activeRemote() else { return false }
+    remote.play()
+    return true
+  }
+
+  static func routePause() -> Bool {
+    guard let remote = PlaybackStateRouter.shared.activeRemote() else { return false }
+    remote.pause()
+    return true
+  }
+
+  static func routeStop() -> Bool {
+    guard let remote = PlaybackStateRouter.shared.activeRemote() else { return false }
+    remote.stop()
+    return true
+  }
+
+  static func routeSeekTo(positionMs: Int64) -> Bool {
+    guard let remote = PlaybackStateRouter.shared.activeRemote() else { return false }
+    remote.seekTo(positionMs: positionMs)
+    return true
+  }
+
+  /// Interval-skip helper: relative-seek the receiver by `deltaMs` (positive =
+  /// forward) via the Cast SDK's native relative seek, so a lock-screen
+  /// skip-forward/back during a Chromecast session jumps from the receiver's
+  /// own position. Returns `true` when a remote handled it (no active GCK
+  /// session for AirPlay/local, where the caller seeks the local engine).
+  static func routeSeekBy(deltaMs: Int64) -> Bool {
+    guard let remote = PlaybackStateRouter.shared.activeRemote() else { return false }
+    remote.seekBy(deltaMs: deltaMs)
+    return true
+  }
+
+  static func routeSkipToNext() -> Bool {
+    guard let remote = PlaybackStateRouter.shared.activeRemote() else { return false }
+    remote.queueNext()
+    return true
+  }
+
+  static func routeSkipToPrevious() -> Bool {
+    guard let remote = PlaybackStateRouter.shared.activeRemote() else { return false }
+    remote.queuePrev()
+    return true
+  }
+
+  static func routeSkipToIndex(index: Int) -> Bool {
+    guard let remote = PlaybackStateRouter.shared.activeRemote() else { return false }
+    remote.skipToQueueIndex(index: index)
+    return true
+  }
+
+  static func routeSetVolume(value: Double) -> Bool {
+    guard let remote = PlaybackStateRouter.shared.activeRemote() else { return false }
+    remote.setVolume(Float(max(0.0, min(1.0, value))))
+    return true
+  }
+
+  /// `setQueue` awaits the receiver's `load()` round-trip. Returns the
+  /// receiver itemIds (in `tracks` order) as the load's success signal
+  /// when the remote handled it; `nil` when no remote is active. Throws
+  /// when remote was active but the load failed — caller decides whether
+  /// to fall through to local or surface the error.
+  static func routeSetQueue(
+    tracks: [CastMediaItem],
+    startIndex: Int,
+    startPositionMs: Int64,
+    playWhenReady: Bool
+  ) async throws -> [Int]? {
+    guard let remote = PlaybackStateRouter.shared.activeRemote() else { return nil }
+    return try await remote.load(
+      items: tracks,
+      startIndex: startIndex,
+      startPositionMs: startPositionMs,
+      playWhenReady: playWhenReady
+    )
+  }
+
+  // Queue mutations mirror to the receiver while the local queue stays the
+  // source of truth for the consumer's UI. `false` when no remote is active
+  // (the caller's local mutation is the only effect). Receiver errors are
+  // swallowed — a failed mirror must not fail the local mutation.
+
+  static func routeAddToQueue(items: [CastMediaItem], beforeIndex: Int?) async -> Bool {
+    guard let remote = PlaybackStateRouter.shared.activeRemote() else { return false }
+    try? await remote.queueInsert(items: items, beforeIndex: beforeIndex)
+    return true
+  }
+
+  static func routeRemoveFromQueue(indices: [Int]) async -> Bool {
+    guard let remote = PlaybackStateRouter.shared.activeRemote() else { return false }
+    try? await remote.queueRemove(indices: indices)
+    return true
+  }
+
+  static func routeMoveInQueue(fromIndex: Int, toIndex: Int) async -> Bool {
+    guard let remote = PlaybackStateRouter.shared.activeRemote() else { return false }
+    try? await remote.queueMove(fromIndex: fromIndex, toIndex: toIndex)
+    return true
+  }
+
+  static func routeClearQueue() async -> Bool {
+    guard let remote = PlaybackStateRouter.shared.activeRemote() else { return false }
+    try? await remote.queueClear()
+    return true
+  }
+}
+
+extension CastMediaItem {
+  /// Translate a `TrackItem` into a `CastMediaItem`. Consumer-supplied
+  /// fields are best-effort — only `track.url` is treated as required.
+  /// Empty / unparseable `track.url` returns `nil` so the caller can
+  /// drop the entry or surface an error instead of pushing a bogus
+  /// `file:///` to the receiver.
+  static func from(track: TrackItem) -> CastMediaItem? {
+    guard let url = URL(string: track.url), !track.url.isEmpty else {
+      return nil
+    }
+    let title = trimmedOrNil(track.title)
+    let artist = trimmedOrNil(track.artist)
+    let album = trimmedOrNil(track.album)
+    let artwork = trimmedOrNil(track.artworkUrl).flatMap { URL(string: $0) }
+    let durationMs: Int64?
+    if let dur = track.duration, dur > 0 {
+      durationMs = Int64(dur * 1000.0)
+    } else {
+      durationMs = nil
+    }
+    return CastMediaItem(
+      url: url,
+      title: title,
+      artist: artist,
+      album: album,
+      artwork: artwork,
+      durationMs: durationMs,
+      contentType: nil
+    )
+  }
+
+  private static func trimmedOrNil(_ s: String?) -> String? {
+    guard let s = s, !s.isEmpty else { return nil }
+    return s
+  }
+}