react-native-queue-player 1.0.0

package/ios/Cast/Chromecast/ChromecastSessionAdapter.swift

@@ -0,0 +1,114 @@
+import Foundation
+#if canImport(GoogleCast)
+import GoogleCast
+
+/// Adapter over `GCKSessionManagerListener` collapsing the SDK's nine
+/// session-lifecycle callbacks into three outcomes:
+///
+/// - **connected** — `didStart` or `didResumeCastSession` fired.
+/// - **disconnected** — `didEnd`, `didSuspend`, or `didFailToResumeSession` fired.
+/// - **error** — any `*FailTo*` variant.
+///
+/// `GCKErrorCodeCancelled` (SDK 4.8.4) is a non-retry contract: when
+/// `didFailToStart` or `didFailToResume` fires with that code, the
+/// backend MUST NOT re-call `startSession`/`resumeSession` on the same
+/// device in response. Auto-retry on cancel is exactly what the SDK
+/// is asking us not to do.
+///
+/// Cold-launch auto-resume is disabled: `willResumeCastSession` fires
+/// both for (a) the SDK's saved-session restore attempt on cold launch
+/// and (b) recovery from a mid-process suspend (network blip).
+/// `hasEverConnected` discriminates the two — false means case (a),
+/// so the abort runs; true means case (b), so the recovery is allowed.
+/// Matches Android's `CastOptions.setResumeSavedSession(false)` which
+/// only affects saved-session restore.
+final class ChromecastSessionAdapter: NSObject, GCKSessionManagerListener {
+
+  var onConnected: ((GCKCastSession) -> Void)?
+  var onDisconnected: ((String) -> Void)?
+  var onError: ((String) -> Void)?
+
+  /// True after the first in-process didStart / didResume has been
+  /// observed. Used to distinguish cold-launch saved-session restore
+  /// (false → abort the resume) from mid-process suspend recovery
+  /// (true → let the SDK resume).
+  private var hasEverConnected = false
+
+  /// Receiver-side device volume push from `GCKSessionManager` — fires
+  /// independently of `GCKMediaStatus`, so volume changes that arrive
+  /// before any media has loaded still surface. Carries `(volume,
+  /// muted)`.
+  var onVolumeChanged: ((Float, Bool) -> Void)?
+
+  func sessionManager(_ sessionManager: GCKSessionManager, didStart session: GCKSession) {
+    guard let cast = session as? GCKCastSession else { return }
+    hasEverConnected = true
+    onConnected?(cast)
+  }
+
+  func sessionManager(
+    _ sessionManager: GCKSessionManager,
+    session: GCKSession,
+    didReceiveDeviceVolume volume: Float,
+    muted: Bool
+  ) {
+    onVolumeChanged?(volume, muted)
+  }
+
+  func sessionManager(
+    _ sessionManager: GCKSessionManager,
+    didFailToStart session: GCKSession,
+    withError error: Error
+  ) {
+    let ns = error as NSError
+    onError?("start-failed:\(ns.code)")
+  }
+
+  func sessionManager(
+    _ sessionManager: GCKSessionManager,
+    didEnd session: GCKSession,
+    withError error: Error?
+  ) {
+    if let ns = error as NSError? {
+      onDisconnected?("ended:\(ns.code)")
+    } else {
+      onDisconnected?("ended")
+    }
+  }
+
+  func sessionManager(
+    _ sessionManager: GCKSessionManager,
+    willResumeCastSession session: GCKCastSession
+  ) {
+    // First in-process willResume with no prior didStart is the SDK's
+    // saved-session restore on cold launch — abort. Once an in-process
+    // session has been observed (`hasEverConnected`), any subsequent
+    // willResume is a mid-process suspend recovery and is allowed.
+    if !hasEverConnected {
+      sessionManager.endSessionAndStopCasting(false)
+    }
+  }
+
+  func sessionManager(_ sessionManager: GCKSessionManager, didResumeCastSession session: GCKCastSession) {
+    hasEverConnected = true
+    onConnected?(session)
+  }
+
+  func sessionManager(
+    _ sessionManager: GCKSessionManager,
+    didFailToResumeSession session: GCKSession,
+    withError error: Error
+  ) {
+    let ns = error as NSError
+    onError?("resume-failed:\(ns.code)")
+  }
+
+  func sessionManager(
+    _ sessionManager: GCKSessionManager,
+    didSuspend session: GCKSession,
+    with reason: GCKConnectionSuspendReason
+  ) {
+    onDisconnected?("suspended:\(reason.rawValue)")
+  }
+}
+#endif

package/ios/Cast/Chromecast/ChromecastSupport.swift

@@ -0,0 +1,63 @@
+import Foundation
+#if canImport(GoogleCast)
+import GoogleCast
+#endif
+
+/// Top-level install entry point for the iOS Chromecast backend.
+/// Consumer apps call `ChromecastSupport.installWithDefaults()` from
+/// their `AppDelegate.application(_:didFinishLaunchingWithOptions:)`
+/// (the lib's Expo plugin emits the call site when `{ chromecast:
+/// true }` is configured).
+@objc(ChromecastSupport)
+public final class ChromecastSupport: NSObject {
+
+  /// Google's Default Media Receiver — handles MP4/MP3/HLS with no
+  /// custom receiver code.
+  @objc public static let defaultReceiverApplicationID = "CC1AD845"
+
+  /// Info.plist key the lib's Expo plugin writes when the consumer
+  /// pins a host-app receiver ID at build time.
+  @objc public static let infoPlistReceiverApplicationIDKey =
+    "QueuePlayerChromecastReceiverApplicationID"
+
+  /// Reads receiver app ID from Info.plist, falls back to default.
+  /// Stable selector for the AppDelegate snippet's NSSelectorFromString
+  /// dispatch.
+  @objc public static func installWithDefaults() {
+    let configured = (Bundle.main.infoDictionary?[infoPlistReceiverApplicationIDKey] as? String)?
+      .trimmingCharacters(in: .whitespacesAndNewlines)
+    let receiverID = (configured?.isEmpty == false ? configured! : defaultReceiverApplicationID)
+    install(receiverApplicationID: receiverID)
+  }
+
+  /// Installs and configures `GCKCastContext` with the supplied
+  /// receiver application ID. Must be called on the main thread.
+  /// Idempotent — calling twice is a no-op.
+  @objc public static func install(receiverApplicationID: String = defaultReceiverApplicationID) {
+    #if canImport(GoogleCast)
+    guard Thread.isMainThread else {
+      DispatchQueue.main.async { install(receiverApplicationID: receiverApplicationID) }
+      return
+    }
+
+    if GCKCastContext.isSharedInstanceInitialized() { return }
+
+    let discoveryCriteria = GCKDiscoveryCriteria(applicationID: receiverApplicationID)
+    let options = GCKCastOptions(discoveryCriteria: discoveryCriteria)
+    options.physicalVolumeButtonsWillControlDeviceVolume = true
+    options.suspendSessionsWhenBackgrounded = false
+    // Defer discovery entirely to `Cast.startDiscovery()` (typically
+    // the picker open). With autostart on, the SDK opens a
+    // `_googlecast._tcp.` Bonjour browser + multicast UDP socket
+    // synchronously inside `setSharedInstanceWith`; the first
+    // multicast send triggers the iOS Local Network permission prompt
+    // during a window the user has not asked for cast yet — wasteful
+    // for cast-disabled users + a known UX regression.
+    // `ChromecastBackend.startDiscovery` calls
+    // `discoveryManager.startDiscovery()` explicitly when JS asks.
+    options.disableDiscoveryAutostart = true
+
+    GCKCastContext.setSharedInstanceWith(options)
+    #endif
+  }
+}

package/ios/Cast/Chromecast/MediaInfoBuilder.swift

@@ -0,0 +1,104 @@
+import Foundation
+#if canImport(GoogleCast)
+import GoogleCast
+
+/// Translate a `CastMediaItem` into a Cast SDK `GCKMediaInformation`
+/// ready for `GCKRemoteMediaClient.loadMedia(_:with:)`.
+///
+/// URL decision table:
+/// - `file://` (or no scheme) → register via `MediaServerHandle`, use
+///   the returned LAN `http://` URL
+/// - `http(s)://` → pass through
+/// - anything else → throw `unsupportedScheme`
+enum MediaInfoBuilder {
+
+  enum BuildError: Error, LocalizedError {
+    case unsupportedScheme(String)
+    case missingLANAddress
+    case localFileNotFound(String)
+    case serverUnavailable
+
+    var errorDescription: String? {
+      switch self {
+      case .unsupportedScheme(let s): return "Unsupported URL scheme '\(s)' for Chromecast"
+      case .missingLANAddress: return "No LAN address available — cannot serve local file"
+      case .localFileNotFound(let p): return "Local file does not exist: \(p)"
+      case .serverUnavailable: return "MediaServerHandle returned nil URL — server not running?"
+      }
+    }
+  }
+
+  static func build(
+    item: CastMediaItem,
+    handle: MediaServerHandle,
+    lanAddress: String?
+  ) throws -> GCKMediaInformation {
+    let scheme = item.url.scheme?.lowercased()
+    let resolvedURL: URL
+    switch scheme {
+    case "http", "https":
+      resolvedURL = item.url
+    case "file", nil:
+      let path = item.url.path
+      guard FileManager.default.fileExists(atPath: path) else {
+        throw BuildError.localFileNotFound(path)
+      }
+      guard let address = lanAddress else {
+        throw BuildError.missingLANAddress
+      }
+      let fileURL = item.url.scheme == "file" ? item.url : URL(fileURLWithPath: path)
+      guard let served = handle.register(
+        fileURL: fileURL,
+        lanAddress: address,
+        contentType: item.contentType
+      ) else {
+        throw BuildError.serverUnavailable
+      }
+      resolvedURL = served
+    default:
+      throw BuildError.unsupportedScheme(scheme ?? "")
+    }
+
+    let metadata = GCKMediaMetadata(metadataType: .musicTrack)
+    if let t = item.title { metadata.setString(t, forKey: kGCKMetadataKeyTitle) }
+    if let a = item.artist {
+      metadata.setString(a, forKey: kGCKMetadataKeyArtist)
+      metadata.setString(a, forKey: kGCKMetadataKeyAlbumArtist)
+    }
+    if let al = item.album {
+      metadata.setString(al, forKey: kGCKMetadataKeyAlbumTitle)
+    }
+    if let artwork = item.artwork,
+       let s = artwork.scheme?.lowercased(),
+       s == "http" || s == "https" {
+      metadata.addImage(GCKImage(url: artwork, width: 480, height: 480))
+    }
+
+    let contentType = item.contentType ?? inferContentType(from: resolvedURL)
+    let builder = GCKMediaInformationBuilder(contentURL: resolvedURL)
+    builder.streamType = .buffered
+    builder.contentType = contentType
+    builder.metadata = metadata
+    if let ms = item.durationMs, ms > 0 {
+      builder.streamDuration = TimeInterval(ms) / 1000.0
+    }
+    return builder.build()
+  }
+
+  private static func inferContentType(from url: URL) -> String {
+    let ext = url.pathExtension.lowercased()
+    switch ext {
+    case "mp3": return "audio/mpeg"
+    case "m4a", "mp4": return "audio/mp4"
+    case "aac": return "audio/aac"
+    case "flac": return "audio/flac"
+    case "ogg", "oga", "opus": return "audio/ogg"
+    case "wav", "wave": return "audio/x-wav"
+    // Some Chromecast receivers reject `audio/*` as a content type
+    // hint and fail the load; `application/octet-stream` is the
+    // safer fallback when the extension doesn't disambiguate.
+    default: return "application/octet-stream"
+    }
+  }
+}
+#endif

package/ios/Cast/Chromecast/RemoteMediaObserver.swift

@@ -0,0 +1,147 @@
+import Foundation
+#if canImport(GoogleCast)
+import GoogleCast
+
+/// Bridges `GCKRemoteMediaClient` status updates onto callbacks +
+/// polls `approximateStreamPosition` at 1 Hz while attached. Cast SDK
+/// on iOS has no push-driven progress; `approximateStreamPosition`
+/// is cheap (SDK interpolates from last known + elapsed time).
+extension RemotePlaybackStateKind {
+  static func from(mediaStatus: GCKMediaStatus) -> RemotePlaybackStateKind {
+    switch mediaStatus.playerState {
+    case .playing: return .playing
+    case .paused: return .paused
+    case .buffering: return .buffering
+    case .loading: return .loading
+    case .idle:
+      switch mediaStatus.idleReason {
+      case .finished: return .ended
+      case .error: return .error
+      default: return .idle
+      }
+    default: return .idle
+    }
+  }
+}
+
+extension RemoteEndReasonKind {
+  static func from(idleReason: GCKMediaPlayerIdleReason) -> RemoteEndReasonKind {
+    switch idleReason {
+    case .finished: return .finished
+    case .interrupted: return .interrupted
+    case .cancelled: return .canceled
+    case .error: return .error
+    default: return .canceled
+    }
+  }
+}
+
+final class RemoteMediaObserver: NSObject, GCKRemoteMediaClientListener {
+
+  var onStateChanged: ((RemotePlaybackStateKind) -> Void)?
+  var onPositionChanged: ((_ positionMs: Int64, _ durationMs: Int64, _ bufferedMs: Int64) -> Void)?
+  /// Absolute index of the current item in the receiver's full queue,
+  /// resolved via `GCKMediaQueue` (which stays in sync with the whole
+  /// queue, not the ~3-item status window). This is the lib-track index.
+  var onCurrentTrackIndexChanged: ((Int) -> Void)?
+  var onEndedReason: ((RemoteEndReasonKind) -> Void)?
+
+  /// Receiver-side media errors. Not driven by `didUpdate mediaStatus`
+  /// (which only reports state/idle-reason); the owning
+  /// `ChromecastSession` plumbs request-failure outcomes into this
+  /// slot so consumers have a single observation surface.
+  var onMediaError: ((RemoteMediaErrorPayload) -> Void)?
+
+  /// Fires once per completed seek with the resolved position (ms).
+  /// Wired by the owning `ChromecastSession`'s `seek(with:)` request
+  /// delegate; the observer is the convenient sink, not the source.
+  var onSeekCompleted: ((Int64) -> Void)?
+
+  private weak var currentClient: GCKRemoteMediaClient?
+  private var progressTimer: Timer?
+
+  private var lastDurationMs: Int64 = 0
+  private var lastBufferedMs: Int64 = 0
+  // Dedup for the absolute-index emit. Persists across a same-session
+  // queue reload (`setQueue` during cast): if the new queue starts at the
+  // same absolute index the prior one was on, the emit is suppressed —
+  // benign because that `setQueue` drives its own current-track update;
+  // the cast emit only carries receiver-driven advances.
+  private var lastTrackIndex: Int = -1
+  private var lastIdleReasonEmitted: GCKMediaPlayerIdleReason = .none
+
+  func attach(_ client: GCKRemoteMediaClient) {
+    if currentClient === client { return }
+    detach()
+    currentClient = client
+    client.add(self)
+    startProgressTimer()
+  }
+
+  func detach() {
+    progressTimer?.invalidate()
+    progressTimer = nil
+    currentClient?.remove(self)
+    currentClient = nil
+  }
+
+  private func startProgressTimer() {
+    progressTimer?.invalidate()
+    progressTimer = nil
+    let timer = Timer(timeInterval: 1.0, repeats: true) { [weak self] _ in
+      guard let self = self, let client = self.currentClient else { return }
+      let ms = Int64(client.approximateStreamPosition() * 1000.0)
+      if ms >= 0 {
+        self.onPositionChanged?(ms, self.lastDurationMs, self.lastBufferedMs)
+      }
+    }
+    RunLoop.main.add(timer, forMode: .common)
+    progressTimer = timer
+  }
+
+  private func durationMs(from status: GCKMediaStatus) -> Int64 {
+    let d = status.mediaInformation?.streamDuration ?? 0
+    guard d.isFinite, d > 0 else { return 0 }
+    return Int64(d * 1000.0)
+  }
+
+  private func bufferedMs(from status: GCKMediaStatus) -> Int64 {
+    let pos = status.streamPosition
+    guard pos.isFinite, pos >= 0 else { return 0 }
+    return Int64(pos * 1000.0)
+  }
+
+  // MARK: - GCKRemoteMediaClientListener
+
+  func remoteMediaClient(_ client: GCKRemoteMediaClient, didUpdate mediaStatus: GCKMediaStatus?) {
+    guard let status = mediaStatus else {
+      onStateChanged?(.idle)
+      return
+    }
+    lastDurationMs = durationMs(from: status)
+    lastBufferedMs = bufferedMs(from: status)
+    onStateChanged?(RemotePlaybackStateKind.from(mediaStatus: status))
+
+    // Resolve the current item's ABSOLUTE index in the full queue via
+    // `GCKMediaQueue` (the SDK keeps the whole queue in sync; the status
+    // only exposes a ~3-item window). `indexOfItem(withID:)` returns
+    // `NSNotFound` until the queue model knows the id — keep the prior
+    // index then. This is the lib-track index, equivalent to Android's
+    // `Player.currentMediaItemIndex`.
+    let qIndex = client.mediaQueue.indexOfItem(withID: status.currentItemID)
+    if qIndex != NSNotFound, qIndex != lastTrackIndex {
+      lastTrackIndex = qIndex
+      onCurrentTrackIndexChanged?(qIndex)
+    }
+
+    if status.playerState == .idle, status.idleReason != .none {
+      if status.idleReason != lastIdleReasonEmitted {
+        lastIdleReasonEmitted = status.idleReason
+        onEndedReason?(RemoteEndReasonKind.from(idleReason: status.idleReason))
+      }
+    } else if status.playerState != .idle {
+      lastIdleReasonEmitted = .none
+    }
+  }
+}
+#endif

package/ios/Cast/Core/CastEventBridge.swift

@@ -0,0 +1,210 @@
+import Foundation
+import NitroModules
+
+/// Bridges cast `CastSessionRemotePlayer` session state back into the
+/// lib's existing event surface (`onStateChange` / etc.). Observes
+/// `PlaybackStateRouter.shared`: when a session becomes active, the
+/// bridge subscribes to its state listener + fans receiver updates
+/// through `TrackPlayer.emitRemoteState`. When the session ends, the
+/// bridge captures a snapshot of the receiver's last-known
+/// `(positionMs, currentTrackIndex, isPlaying)` so the local engine
+/// can pick up where the receiver left off, then tears down its per-
+/// session subscriptions cleanly.
+///
+/// Stale-event guarantee comes from atomic listener detachment in
+/// `setActive`: once a session is removed from the router and its
+/// listeners are disposed, no further events from it can fire
+/// `owner.emitRemoteState`.
+final class CastEventBridge {
+
+  private weak var owner: TrackPlayer?
+
+  /// Disposer for the active-change listener on `PlaybackStateRouter.
+  /// shared`. Held for the bridge's lifetime so the active flow
+  /// observation stops when `stop()` is called.
+  private var activeChangeDisposer: (() -> Void)?
+
+  /// Disposers for the listeners currently attached to the active
+  /// session. Cleared atomically when the session changes.
+  private var sessionListenerDisposers: [() -> Void] = []
+
+  /// Currently-active session, captured at the moment the router
+  /// fires `activeRemote = X`. Held weakly because the session is
+  /// owned by `CastManager` (and ultimately `ChromecastBackend`);
+  /// the bridge is an observer, not an owner.
+  private weak var currentActiveSession: CastSessionRemotePlayer?
+
+  /// Receiver position at the moment the active session was cleared.
+  /// The local engine can read this to resume from where the
+  /// receiver was. Cleared when a new session activates.
+  private(set) var lastPositionMsOnDeactivate: Int64 = 0
+
+  /// Receiver-side current track index at deactivation. `-1` when
+  /// unknown.
+  private(set) var lastTrackIndexOnDeactivate: Int = -1
+
+  /// Last lib index emitted for the receiver's current item. Dedups
+  /// repeat receiver statuses carrying the same resolved index so
+  /// `onTrackChange` + the lockscreen push fire only on real advances.
+  /// Reset when the active session changes.
+  private var lastEmittedRemoteIndex: Int = -1
+
+  init(owner: TrackPlayer) {
+    self.owner = owner
+  }
+
+  func start() {
+    if activeChangeDisposer != nil { return }
+    activeChangeDisposer = PlaybackStateRouter.shared.addActiveChangeListener {
+      [weak self] session in
+      self?.handleActiveSessionChange(to: session)
+    }
+  }
+
+  func stop() {
+    activeChangeDisposer?()
+    activeChangeDisposer = nil
+    sessionListenerDisposers.forEach { $0() }
+    sessionListenerDisposers.removeAll()
+    currentActiveSession = nil
+  }
+
+  /// Seed the deactivation snapshot from the local pre-handoff position +
+  /// index so a disconnect before the receiver reports a resolvable item
+  /// (rapid connect/disconnect, before the load round-trip settles) still
+  /// lands local on the right spot. A receiver item resolved at
+  /// deactivation takes precedence.
+  func seedDeactivationSnapshot(trackIndex: Int, positionMs: Int64) {
+    lastTrackIndexOnDeactivate = trackIndex
+    lastPositionMsOnDeactivate = positionMs
+  }
+
+  // MARK: - Active-flow observer
+
+  private func handleActiveSessionChange(to newSession: CastSessionRemotePlayer?) {
+    let prior = currentActiveSession
+    if newSession == nil, let prior = prior {
+      // Capture deactivation snapshot BEFORE tearing down listeners so
+      // the local engine's resume path can read the receiver's last-known
+      // state. Use the receiver's resolved absolute track index; when it
+      // resolved (>= 0) prefer the receiver's position + play-state. When
+      // it never did (a disconnect before the first resolvable status),
+      // keep the local pre-handoff snapshot seeded at handoff time.
+      if prior.lastCurrentTrackIndex >= 0 {
+        lastTrackIndexOnDeactivate = prior.lastCurrentTrackIndex
+        lastPositionMsOnDeactivate = prior.lastPositionMs
+      }
+      // Seek local back to where the receiver left off and stay paused
+      // (the user resumes locally) — never auto-blast the phone speaker.
+      owner?.resumeLocalAfterCast(
+        trackIndex: lastTrackIndexOnDeactivate,
+        positionMs: lastPositionMsOnDeactivate
+      )
+    } else if newSession != nil {
+      // New session — clear the deactivation cache (caches are only
+      // valid in the window between session-end and the next start).
+      lastPositionMsOnDeactivate = 0
+      lastTrackIndexOnDeactivate = -1
+      // Hand off the current local queue + playhead + play/pause to the
+      // receiver so playback continues where it was, then silence the
+      // local engine. The router short-circuits JS-side transport, but
+      // continuity needs the position + play-state pushed explicitly.
+      owner?.handoffCurrentPlaybackToCast()
+    }
+
+    sessionListenerDisposers.forEach { $0() }
+    sessionListenerDisposers.removeAll()
+    currentActiveSession = newSession
+    // The dedup index is per-session: a fresh session must re-emit its
+    // current track even if it resolves to the same lib index the prior
+    // session last reported.
+    lastEmittedRemoteIndex = -1
+
+    guard let session = newSession else { return }
+
+    let stateDisposer = session.addStateListener { [weak self] state in
+      guard let self = self, let owner = self.owner else { return }
+      owner.emitRemoteState(state.asPlayerState, reason: .system)
+    }
+    sessionListenerDisposers.append(stateDisposer)
+
+    // Receiver advanced to a different queue item. The backend resolves the
+    // current item's ABSOLUTE index against the full queue (via GCKMediaQueue
+    // / the Cast Player), so this carries the lib-track index directly — no
+    // window-relative itemId mapping.
+    let trackIndexDisposer = session.addCurrentTrackIndexListener { [weak self] _ in
+      self?.refreshCurrentRemoteTrack()
+    }
+    sessionListenerDisposers.append(trackIndexDisposer)
+
+    // Receiver position / duration — fan to JS `onProgress` so the player
+    // screen's progress bar, position, and duration track the receiver
+    // while the cast session is active (the local engine is paused, so its
+    // periodic progress emit is silent).
+    let positionDisposer = session.addPositionListener { [weak self] positionMs, durationMs, bufferedMs in
+      self?.owner?.emitRemoteProgress(
+        positionMs: positionMs, durationMs: durationMs, bufferedMs: bufferedMs
+      )
+    }
+    sessionListenerDisposers.append(positionDisposer)
+  }
+
+  // MARK: - Lockscreen metadata mirror
+
+  /// Seed the start track's lockscreen metadata after a `setQueue` so the
+  /// surface doesn't wait for the first receiver status. Called on the
+  /// main thread from `TrackPlayer.setQueue`.
+  func seedStartMetadata(startIndex: Int) {
+    pushMetadata(forIndex: startIndex)
+  }
+
+  /// Push the receiver's current track to the JS surface + lockscreen when
+  /// it advances. The backend resolves the absolute lib-track index against
+  /// the full queue (`lastCurrentTrackIndex`), so no window-relative itemId
+  /// mapping is involved. Dedup'd on `lastEmittedRemoteIndex` so repeat
+  /// statuses carrying the same index fire the surface only on real
+  /// advances; `-1` (not yet resolvable) is ignored.
+  private func refreshCurrentRemoteTrack() {
+    guard let session = currentActiveSession else { return }
+    let index = session.lastCurrentTrackIndex
+    guard index >= 0, index != lastEmittedRemoteIndex else { return }
+    lastEmittedRemoteIndex = index
+    pushMetadata(forIndex: index)
+    owner?.emitRemoteTrackChange(index: index)
+  }
+
+  /// Resolve a lib track index to its `TrackItem` and push its metadata
+  /// to the cast lockscreen controller. Out-of-range indices are
+  /// ignored (the controller keeps its prior snapshot).
+  private func pushMetadata(forIndex index: Int) {
+    guard let owner = owner else { return }
+    let tracks = owner.tracks
+    guard index >= 0, index < tracks.count else { return }
+    let track = tracks[index]
+    CastNowPlayingController.shared.updateTrackMetadata(
+      title: track.title,
+      artist: track.artist,
+      album: track.album,
+      durationSec: track.duration ?? 0,
+      artworkUrl: track.artworkUrl
+    )
+  }
+
+}
+
+extension RemotePlaybackStateKind {
+  /// Map the protocol-neutral receiver state to the JS-facing
+  /// `PlayerState`. Used by `CastEventBridge` to fan state changes
+  /// to `TrackPlayer.emitRemoteState`, and by `CastNowPlayingController`
+  /// to decide the lockscreen playback rate.
+  var asPlayerState: PlayerState {
+    switch self {
+    case .playing: return .playing
+    case .paused: return .paused
+    case .loading, .buffering: return .buffering
+    case .idle: return .none
+    case .ended: return .ended
+    case .error: return .error
+    }
+  }
+}

package/ios/Cast/Core/CastMediaItem.swift

@@ -0,0 +1,41 @@
+import Foundation
+
+/// Protocol-neutral media item handed to cast backends for playback.
+/// Cast backends (Chromecast, future DLNA / Sonos) consume the typed
+/// fields directly — no reflection, no NSDictionary casts inside the
+/// backend. Translation from the Nitro `TrackItem` happens at the
+/// bridge boundary (`CastMediaItem.from(track:)`), so the protocol-
+/// specific backends don't depend on the Nitro JS-bridge contract.
+struct CastMediaItem {
+  /// Source URL. `file://` → served via `LocalMediaServer` for
+  /// receivers that need HTTP. `http(s)://` → passed through. Other
+  /// schemes rejected by the backend.
+  let url: URL
+  let title: String?
+  let artist: String?
+  let album: String?
+  let artwork: URL?
+  /// Milliseconds. `nil` when unknown.
+  let durationMs: Int64?
+  /// Explicit MIME type; when `nil` the backend infers from URL
+  /// extension via `MimeTypes`.
+  let contentType: String?
+
+  init(
+    url: URL,
+    title: String? = nil,
+    artist: String? = nil,
+    album: String? = nil,
+    artwork: URL? = nil,
+    durationMs: Int64? = nil,
+    contentType: String? = nil
+  ) {
+    self.url = url
+    self.title = title
+    self.artist = artist
+    self.album = album
+    self.artwork = artwork
+    self.durationMs = durationMs
+    self.contentType = contentType
+  }
+}