react-native-queue-player 1.0.0

package/ios/CarPlayBrowseDataProvider.swift

@@ -0,0 +1,162 @@
+import Foundation
+
+/// Native cache for the most-recent [BrowseSnapshot] pushed by the
+/// consumer via `setBrowseSnapshot`. iOS mirror of the Android
+/// `BrowseDataProvider`. The CarPlay scene delegate's browse surface
+/// reads from this cache so a controller-driven re-fetch does not
+/// have to round-trip through JS.
+///
+/// Snapshot replacement is atomic: a single `NSLock` guards the
+/// stored reference. Concurrent readers see either the prior
+/// snapshot in full or the new one in full, never a torn mix.
+///
+/// Update notifications: a `Notification` named
+/// [CarPlayBrowseDataProvider.didUpdateNotification] fires on the
+/// main queue after every successful `setSnapshot`. The CarPlay
+/// scene delegate observes the notification + rebuilds the active
+/// template against the new snapshot.
+final class CarPlayBrowseDataProvider {
+
+  /// Notification posted on the main queue after `setSnapshot`. The
+  /// `userInfo` dictionary carries one key — `"changedParents"` —
+  /// mapping to a `Set<String>` of parent IDs whose children list
+  /// changed (root + every section id from the prior + new
+  /// snapshots). Observers loop the set + rebuild the affected
+  /// `CPListTemplate` rows.
+  static let didUpdateNotification = Notification.Name(
+    "com.margelo.nitro.queueplayer.CarPlayBrowseDataProvider.didUpdate"
+  )
+
+  /// `userInfo` key under [didUpdateNotification] carrying the
+  /// `Set<String>` of changed parent IDs.
+  static let changedParentsKey = "changedParents"
+
+  /// Replace the cached snapshot. Pass `nil` to clear. Returns the
+  /// set of parentIds whose children list changed (root + every
+  /// section id from the prior + new snapshots) so the caller can
+  /// fan out per-parent UI invalidations alongside the catch-all
+  /// notification.
+  ///
+  /// Returns an empty set when both the prior and the incoming
+  /// snapshot are `nil` (e.g. clearing a cache that was never
+  /// populated). The notification still fires with an empty
+  /// changedParents userInfo so observers can drop any stale
+  /// "loading…" placeholder.
+  @discardableResult
+  func setSnapshot(_ snapshot: BrowseSnapshot?) -> Set<String> {
+    var changedParents: Set<String> = []
+    lock.lock()
+    let previous = self.snapshot
+    self.snapshot = snapshot
+    lock.unlock()
+
+    if let p = previous {
+      changedParents.insert(p.rootId)
+      for section in p.sections {
+        changedParents.insert(section.id)
+      }
+    }
+    if let s = snapshot {
+      changedParents.insert(s.rootId)
+      for section in s.sections {
+        changedParents.insert(section.id)
+      }
+    }
+
+    let notify = {
+      NotificationCenter.default.post(
+        name: CarPlayBrowseDataProvider.didUpdateNotification,
+        object: self,
+        userInfo: [CarPlayBrowseDataProvider.changedParentsKey: changedParents]
+      )
+    }
+    if Thread.isMainThread {
+      notify()
+    } else {
+      DispatchQueue.main.async(execute: notify)
+    }
+    return changedParents
+  }
+
+  /// Read the current snapshot, or `nil` if none has been set.
+  func getSnapshot() -> BrowseSnapshot? {
+    lock.lock()
+    defer { lock.unlock() }
+    return snapshot
+  }
+
+  /// True when the parentId addresses the root of the cached
+  /// snapshot. False when no snapshot is set.
+  func isRoot(_ parentId: String) -> Bool {
+    lock.lock()
+    defer { lock.unlock() }
+    return snapshot?.rootId == parentId
+  }
+
+  /// Find a section by id. Returns nil when no snapshot is set or
+  /// no section matches.
+  func getSection(_ sectionId: String) -> BrowseSection? {
+    lock.lock()
+    defer { lock.unlock() }
+    return snapshot?.sections.first(where: { $0.id == sectionId })
+  }
+
+  /// Search the full snapshot for an item with the given id. Walks
+  /// every section in declaration order. Returns nil when no
+  /// snapshot is set or no item matches.
+  func getItem(_ itemId: String) -> BrowseItem? {
+    lock.lock()
+    defer { lock.unlock() }
+    guard let snapshot = snapshot else { return nil }
+    for section in snapshot.sections {
+      for item in section.items where item.id == itemId {
+        return item
+      }
+    }
+    return nil
+  }
+
+  /// Resolve a parentId to its children, paginated.
+  ///  - `parentId == snapshot.rootId` returns one synthetic item per
+  ///    section: `id = section.id, title = section.title,
+  ///    playable = false, hasChildren = true`.
+  ///  - `parentId == section.id` returns that section's items.
+  ///  - Anything else returns an empty list.
+  ///
+  ///  Pagination: 0-based page index. `pageSize <= 0` is treated as
+  ///  unbounded (returns the full list). Out-of-range pages return
+  ///  empty.
+  func getChildren(parentId: String, page: Int, pageSize: Int) -> [BrowseItem] {
+    lock.lock()
+    let local = snapshot
+    lock.unlock()
+
+    guard let snapshot = local else { return [] }
+    let items: [BrowseItem]
+    if parentId == snapshot.rootId {
+      items = snapshot.sections.map { section in
+        BrowseItem(
+          id: section.id,
+          title: section.title,
+          subtitle: nil,
+          artworkUrl: section.artworkUrl,
+          playable: false,
+          hasChildren: true
+        )
+      }
+    } else if let section = snapshot.sections.first(where: { $0.id == parentId }) {
+      items = Array(section.items)
+    } else {
+      return []
+    }
+    if pageSize <= 0 { return items }
+    if page < 0 { return [] }
+    let from = page * pageSize
+    if from >= items.count { return [] }
+    let to = min(from + pageSize, items.count)
+    return Array(items[from..<to])
+  }
+
+  private var snapshot: BrowseSnapshot?
+  private let lock = NSLock()
+}

package/ios/CarPlayCoordinator.swift

@@ -0,0 +1,42 @@
+import Foundation
+
+/// Process-wide singleton owning the CarPlay collaborators that
+/// outlive any one scene + any one Hybrid configure cycle:
+/// the [CarPlayBrowseDataProvider] cache, the [CarPlayBridge] JS
+/// callback registry, the [PendingBrowseRequests] race-handler queue,
+/// and the [ArtworkLoader] image fetcher.
+///
+/// The coordinator itself owns nothing user-visible. Both ends of
+/// the integration reach in:
+///  - [TrackPlayer.swift] writes through `dataProvider.setSnapshot`
+///    when the consumer calls `setBrowseSnapshot`, and registers JS
+///    callbacks on `bridge` when the consumer calls
+///    `onBrowseRequest` / `onPlayFromSearchRequest` / etc.
+///  - [CarPlaySceneDelegate.swift] reads from `dataProvider` when
+///    the scene attaches, observes
+///    `CarPlayBrowseDataProvider.didUpdateNotification` to rebuild on
+///    snapshot push, drains `pending` after a snapshot lands, and
+///    dispatches into `bridge` callbacks when the controller asks
+///    for children / play.
+///
+/// The singleton pattern mirrors `Equalizer.current` / `Visualizer.current`
+/// used elsewhere in the lib — the JS-side singleton constraint that
+/// arises naturally from the Nitro Hybrid lifecycle. CarPlay's scene
+/// delegate has no constructor injection point, so a singleton is
+/// the only way to hand it the same instances the Hybrid binds.
+final class CarPlayCoordinator {
+
+  static let shared = CarPlayCoordinator()
+
+  let dataProvider: CarPlayBrowseDataProvider
+  let bridge: CarPlayBridge
+  let pending: PendingBrowseRequests
+  let loader: ArtworkLoader
+
+  private init() {
+    self.dataProvider = CarPlayBrowseDataProvider()
+    self.bridge = CarPlayBridge()
+    self.pending = PendingBrowseRequests()
+    self.loader = ArtworkLoader()
+  }
+}

package/ios/CarPlaySceneDelegate.swift

@@ -0,0 +1,199 @@
+import CarPlay
+import Foundation
+
+/// Lib-side `CPTemplateApplicationSceneDelegate` that drives the
+/// CarPlay browse + Now Playing surfaces. Lifetime matches the
+/// CarPlay scene's — UIKit constructs an instance per scene attach,
+/// retains it until the scene tears down.
+///
+/// Hybrid scene strategy: the delegate runs alongside the consumer's
+/// existing `UIApplicationDelegate` rather than replacing it. The
+/// phone app continues to use legacy
+/// `didFinishLaunchingWithOptions`; this delegate only activates
+/// when CarPlay is connected.
+///
+/// The delegate reaches into [CarPlayCoordinator.shared] to access
+/// the live `BrowseDataProvider`, `CarPlayBridge`,
+/// `PendingBrowseRequests`, and `ArtworkLoader` — all of which are
+/// also written from the JS-side `TrackPlayer` Hybrid path, so the
+/// scene delegate sees fresh data without needing a constructor
+/// injection seam.
+/// **Class is `internal` (not `public`) and uses `@objc(<bare-name>)`:**
+/// the auto-generated `<Module>-Swift.h` only emits public Swift
+/// classes; `internal` keeps this one out of the bridging header so
+/// its `CPInterfaceController` / `CPTemplateApplicationScene`
+/// parameter types do not trigger an import-CarPlay-fail in the
+/// lib's auto-generated Obj-C bridging header. The `@objc(<bare-name>)`
+/// annotation makes the runtime name resolvable via
+/// `NSClassFromString("CarPlaySceneDelegate")` from Info.plist
+/// regardless of the lib pod's Swift module name. Apple Developer
+/// docs: "Using @objc inference" — explicit `@objc(<name>)` is the
+/// only safe way to fix a Swift class's Obj-C runtime name across
+/// module boundaries.
+@available(iOS 14.0, *)
+@objc(CarPlaySceneDelegate)
+internal class CarPlaySceneDelegate: UIResponder, CPTemplateApplicationSceneDelegate {
+
+  /// Live interface controller for the connected CarPlay scene.
+  /// Stashed so the delegate can push child templates on row tap +
+  /// swap the root template when the consumer pushes a fresh
+  /// snapshot. Cleared on scene disconnect.
+  private var interfaceController: CPInterfaceController?
+
+  /// Live root `CPTabBarTemplate`. Held so snapshot updates can swap
+  /// the tab list via `updateTemplates(_:)` instead of
+  /// `setRootTemplate` (which tears down the live UI). Built once at
+  /// `didConnect` — placeholder tab if the snapshot hasn't landed, or
+  /// real tabs if it has — and never replaced for this scene's
+  /// lifetime; only the inner templates swap.
+  private var rootTabBar: CPTabBarTemplate?
+
+  /// Snapshot-update observer. Removed on scene disconnect so the
+  /// delegate doesn't leak past its scene's lifetime.
+  private var snapshotObserver: NSObjectProtocol?
+
+  /// Cached scene-construction template builder. Stateless; the
+  /// live tab-bar reference above is what survives across snapshot
+  /// updates.
+  private let builder = CarPlayBrowseBuilder()
+
+  // MARK: - CPTemplateApplicationSceneDelegate
+
+  public func templateApplicationScene(
+    _ templateApplicationScene: CPTemplateApplicationScene,
+    didConnect interfaceController: CPInterfaceController
+  ) {
+    self.interfaceController = interfaceController
+    // Configure the shared Now Playing template at didConnect so the
+    // template carries its full layout the moment it appears on screen
+    // (cover art, scrub bar, duration, stacked title/artist). Apple
+    // Developer Forums: "configure CPNowPlayingTemplate at the time of
+    // the didConnect delegate method, not when you push to it, because
+    // CPNowPlayingTemplate may be triggered by 'playing' and the Now
+    // Playing Button rather than by an active push."
+    configureNowPlayingTemplate()
+    // Wire row-tap auto-nav: after a playable row's play callback
+    // resolves, push the shared Now Playing template onto the nav
+    // stack so the user lands on the playback surface immediately
+    // (Spotify / Apple Music UX). Guarded against double-push by a
+    // `topTemplate` check inside the closure.
+    builder.pushNowPlaying = { [weak self] in
+      guard let controller = self?.interfaceController else { return }
+      if controller.topTemplate === CPNowPlayingTemplate.shared { return }
+      controller.pushTemplate(
+        CPNowPlayingTemplate.shared,
+        animated: true,
+        completion: nil
+      )
+    }
+
+    let coordinator = CarPlayCoordinator.shared
+    let initialTabBar = builder.buildRootTemplate(
+      provider: coordinator.dataProvider,
+      bridge: coordinator.bridge,
+      pending: coordinator.pending,
+      loader: coordinator.loader,
+      pushTemplate: { [weak self] template in
+        self?.pushNextTemplate(template)
+      }
+    ) ?? builder.buildPlaceholderRootTabBar()
+    self.rootTabBar = initialTabBar
+
+    NSLog("[RNQP-CarPlay] scene didConnect; usingPlaceholder=%@",
+          coordinator.dataProvider.getSnapshot() == nil ? "true" : "false")
+    interfaceController.setRootTemplate(initialTabBar, animated: false) { [weak self] ok, err in
+      NSLog("[RNQP-CarPlay] setRootTemplate(initial) ok=%@ err=%@",
+            ok ? "true" : "false",
+            err.map { String(describing: $0) } ?? "nil")
+      // A snapshot push that landed AFTER scene attach but DURING this
+      // in-flight install couldn't update the tab bar yet (we hadn't
+      // set the root). Run one catch-up swap on completion so the
+      // latest snapshot wins without depending on a future snapshot
+      // push. Uses `updateTemplates` (not setRootTemplate) — the root
+      // tab bar stays the same instance for the scene's lifetime.
+      self?.refreshRootTemplate()
+    }
+
+    snapshotObserver = NotificationCenter.default.addObserver(
+      forName: CarPlayBrowseDataProvider.didUpdateNotification,
+      object: coordinator.dataProvider,
+      queue: .main
+    ) { [weak self] _ in
+      self?.refreshRootTemplate()
+    }
+
+    coordinator.bridge.carConnectCallback()?()
+  }
+
+  private func pushNextTemplate(_ template: CPListTemplate) {
+    interfaceController?.pushTemplate(template, animated: true) { _, _ in }
+  }
+
+  public func templateApplicationScene(
+    _ templateApplicationScene: CPTemplateApplicationScene,
+    didDisconnectInterfaceController interfaceController: CPInterfaceController
+  ) {
+    if let observer = snapshotObserver {
+      NotificationCenter.default.removeObserver(observer)
+      snapshotObserver = nil
+    }
+    self.interfaceController = nil
+    self.rootTabBar = nil
+    CarPlayCoordinator.shared.bridge.carDisconnectCallback()?()
+    // Pending entries from this scene's session are stale — the
+    // next scene attach starts from a fresh snapshot read, so
+    // dropping the queue avoids a phantom "loading…" rebuild on
+    // reconnect.
+    CarPlayCoordinator.shared.pending.clear()
+  }
+
+  // MARK: - Internal
+
+  private func refreshRootTemplate() {
+    guard interfaceController != nil else {
+      NSLog("[RNQP-CarPlay] refreshRootTemplate skipped — no interfaceController")
+      return
+    }
+    guard let rootTabBar = rootTabBar else {
+      NSLog("[RNQP-CarPlay] refreshRootTemplate skipped — root tab bar not installed yet")
+      return
+    }
+    let coordinator = CarPlayCoordinator.shared
+    guard let snapshot = coordinator.dataProvider.getSnapshot() else {
+      NSLog("[RNQP-CarPlay] refreshRootTemplate: snapshot still null, leaving placeholder")
+      return
+    }
+    let newTabs = builder.buildTabs(
+      snapshot: snapshot,
+      bridge: coordinator.bridge,
+      loader: coordinator.loader,
+      pushTemplate: { [weak self] template in
+        self?.pushNextTemplate(template)
+      }
+    )
+    rootTabBar.updateTemplates(newTabs)
+    NSLog("[RNQP-CarPlay] refreshRootTemplate: updateTemplates(count=%d)", newTabs.count)
+    // updateTemplates is the catch-all rebuild — every connected
+    // controller re-fetches the affected hierarchy, so any pending
+    // requests that landed before this snapshot are implicitly
+    // serviced by the new tab state. Clearing here ensures a
+    // subsequent partial-update path doesn't see stale entries.
+    coordinator.pending.clear()
+  }
+
+  /// Touch `CPNowPlayingTemplate.shared` at scene didConnect so the
+  /// singleton is alive when a row-tap push lands. Pushing onto the
+  /// nav stack via `pushTemplate(CPNowPlayingTemplate.shared, ...)`
+  /// is the supported path for `com.apple.developer.carplay-audio`
+  /// apps; embedding the same template in a `CPTabBarTemplate` root
+  /// is NOT — that raises `NSInvalidArgumentException`. Property
+  /// mutation here is intentionally avoided — earlier iOS 26 sim
+  /// experiments setting `isUpNextButtonEnabled = false` /
+  /// `isAlbumArtistButtonEnabled = false` left the template rendering
+  /// blank; baseline defaults work.
+  private func configureNowPlayingTemplate() {
+    _ = CPNowPlayingTemplate.shared
+    NSLog("[RNQP-CarPlay] CPNowPlayingTemplate.shared touched")
+  }
+
+}

package/ios/Cast/AirPlayRouteState.swift

@@ -0,0 +1,281 @@
+import AVFoundation
+import AVKit
+import UIKit
+
+/// Wraps `AVAudioSession.routeChangeNotification` and translates the
+/// current audio route into the lib's Nitro `CastRoute` shape.
+/// Survives backgrounding via re-subscribe (iOS may tear down
+/// background notification observers).
+///
+/// `startObserving()` delivers the current route synchronously to
+/// freshly-subscribed listeners (mirrors Android StateFlow replay).
+final class AirPlayRouteState {
+
+  /// Callback fired on every route change + once synchronously on
+  /// `startObserving()`. CastManager sets this to forward to JS
+  /// listeners + update its cached currentRoute.
+  var onRouteChanged: ((CastRoute) -> Void)?
+
+  /// Companion callback firing on every route change + once
+  /// synchronously on subscribe, delivering the full audio-output
+  /// snapshot (BT, wired, USB, HDMI, AirPlay, etc.). CastManager
+  /// forwards to the JS `onAudioRouteChange` listener registry.
+  var onAudioRouteChanged: ((AudioRoute) -> Void)?
+
+  private var isObserving = false
+
+  func startObserving() {
+    guard !isObserving else { return }
+    isObserving = true
+    NotificationCenter.default.addObserver(
+      self,
+      selector: #selector(handleRouteChange),
+      name: AVAudioSession.routeChangeNotification,
+      object: nil
+    )
+    patchRouteSharingPolicy()
+    deliverCurrentRoute()
+  }
+
+  func stopObserving() {
+    guard isObserving else { return }
+    isObserving = false
+    NotificationCenter.default.removeObserver(
+      self,
+      name: AVAudioSession.routeChangeNotification,
+      object: nil
+    )
+  }
+
+  /// Snapshot the current cast-style route. Callable any time; doesn't
+  /// require an active observer.
+  func currentRoute() -> CastRoute {
+    let route = AVAudioSession.sharedInstance().currentRoute
+    guard let output = route.outputs.first else {
+      return Self.localRoute()
+    }
+    return Self.castRouteFrom(port: output)
+  }
+
+  /// Snapshot the current audio output (broader surface than
+  /// `currentRoute` — covers BT, wired, USB, HDMI, etc.).
+  func currentAudioRoute() -> AudioRoute {
+    let route = AVAudioSession.sharedInstance().currentRoute
+    guard let output = route.outputs.first else {
+      return Self.localAudioRoute()
+    }
+    return Self.audioRouteFrom(port: output)
+  }
+
+  /// Present the system `AVRoutePickerView` sheet programmatically by
+  /// dispatching a tap to the picker's internal UIButton. Used by
+  /// `CastManager.showSystemPicker()`.
+  ///
+  /// Caveat: the internal button is private layout, walked via
+  /// recursive subview search rather than direct child lookup so the
+  /// picker keeps working when Apple reshapes the view hierarchy
+  /// (iOS 15 nested the button one level deeper; further reshuffles
+  /// are likely). The mitigation here is "best-effort + fail-quiet":
+  /// when no UIButton is found the call is a no-op and the consumer
+  /// can fall back to rendering its own `AVRoutePickerView` in app UI
+  /// (Apple's recommended pattern).
+  func showSystemPicker() {
+    DispatchQueue.main.async {
+      let picker = self.getOrCreatePicker()
+      if let button = Self.firstButton(in: picker) {
+        button.sendActions(for: .touchUpInside)
+      }
+    }
+  }
+
+  /// Recursive first-button search — Apple has moved the internal
+  /// button between top-level and nested children across iOS releases.
+  private static func firstButton(in view: UIView) -> UIButton? {
+    for subview in view.subviews {
+      if let button = subview as? UIButton { return button }
+      if let nested = firstButton(in: subview) { return nested }
+    }
+    return nil
+  }
+
+  // MARK: - Internal
+
+  @objc private func handleRouteChange(_ notification: Notification) {
+    deliverCurrentRoute()
+  }
+
+  private func deliverCurrentRoute() {
+    onRouteChanged?(currentRoute())
+    onAudioRouteChanged?(currentAudioRoute())
+  }
+
+  /// WWDC '23 guidance: any app intending long-form audio playback
+  /// should set `.longFormAudio` so the OS routes to the user's last-
+  /// active long-form output (AirPods, AirPlay 2, CarPlay) on cold
+  /// start. Idempotent — bails if already set.
+  private func patchRouteSharingPolicy() {
+    let session = AVAudioSession.sharedInstance()
+    if session.routeSharingPolicy == .longFormAudio { return }
+    do {
+      try session.setCategory(
+        session.category,
+        mode: session.mode,
+        policy: .longFormAudio,
+        options: session.categoryOptions
+      )
+    } catch {
+      // Best-effort — falls back to default routing.
+    }
+  }
+
+  private var hiddenPicker: AVRoutePickerView?
+
+  private func getOrCreatePicker() -> AVRoutePickerView {
+    let currentWindow = Self.currentKeyWindow()
+    // Recreate the cached picker if the window it was attached to
+    // is no longer the foreground key window (multi-scene teardown,
+    // new scene launch). Otherwise its `sendActions` dispatches into
+    // a discarded view hierarchy.
+    if let p = hiddenPicker, p.window === currentWindow, currentWindow != nil {
+      return p
+    }
+    // The picker must be in the view hierarchy with a non-zero frame
+    // and laid-out subviews for `sendActions(for:.touchUpInside)` on
+    // the internal button to present the system picker sheet. Hidden
+    // views (`isHidden = true`) skip layout in UIKit, so the internal
+    // button isn't created — `firstButton(in:)` returns nil and the
+    // tap silently no-ops. `alpha = 0` + a small frame keeps the
+    // picker invisible to the user while UIKit still lays out its
+    // private subview tree.
+    hiddenPicker?.removeFromSuperview()
+    let picker = AVRoutePickerView(frame: CGRect(x: 0, y: 0, width: 40, height: 40))
+    picker.alpha = 0
+    picker.isUserInteractionEnabled = true
+    picker.prioritizesVideoDevices = false
+    if let window = currentWindow {
+      window.addSubview(picker)
+      picker.setNeedsLayout()
+      picker.layoutIfNeeded()
+    }
+    hiddenPicker = picker
+    return picker
+  }
+
+  /// Foreground-active scene's key window — the right presenter for a
+  /// programmatically-triggered system picker. `connectedScenes.first`
+  /// is an arbitrary scene (could be a background scene on iPad with
+  /// split-view), and `windows.first` is an arbitrary window inside
+  /// that scene; either can mis-route the picker presentation. Filter
+  /// to foreground-active + key.
+  private static func currentKeyWindow() -> UIWindow? {
+    return UIApplication.shared.connectedScenes
+      .compactMap { $0 as? UIWindowScene }
+      .first(where: { $0.activationState == .foregroundActive })?
+      .windows
+      .first(where: { $0.isKeyWindow })
+  }
+
+  // MARK: - Route mapping
+
+  static func castRouteFrom(port: AVAudioSessionPortDescription) -> CastRoute {
+    let proto = mapProtocol(port.portType)
+    let iconHint = mapDeviceKind(port.portType, portName: port.portName)
+    return CastRoute(
+      castProtocol: proto,
+      receiverId: proto == .local ? "" : port.uid,
+      name: port.portName,
+      iconHint: iconHint,
+      capabilities: CastReceiverCapabilities(
+        // iOS handles AirPlay volume via hardware buttons; the app
+        // does not have programmatic volume control over AirPlay.
+        supportsRemoteVolume: false,
+        streamingModel: .pushpcm,
+        requiresPairing: false
+      ),
+      protocolVersion: ""
+    )
+  }
+
+  static func localRoute() -> CastRoute {
+    CastRoute(
+      castProtocol: .local,
+      receiverId: "",
+      name: "Phone speaker",
+      iconHint: .phone,
+      capabilities: CastReceiverCapabilities(
+        supportsRemoteVolume: false,
+        streamingModel: .pushpcm,
+        requiresPairing: false
+      ),
+      protocolVersion: ""
+    )
+  }
+
+  static func audioRouteFrom(port: AVAudioSessionPortDescription) -> AudioRoute {
+    let kind = mapAudioRouteKind(port.portType)
+    return AudioRoute(
+      kind: kind,
+      name: port.portName,
+      identifier: port.uid,
+      isExternal: kind != .speaker && kind != .receiver,
+      isSystemManaged: true
+    )
+  }
+
+  static func localAudioRoute() -> AudioRoute {
+    AudioRoute(
+      kind: .speaker,
+      name: "Phone speaker",
+      identifier: "",
+      isExternal: false,
+      isSystemManaged: true
+    )
+  }
+
+  private static func mapProtocol(_ portType: AVAudioSession.Port) -> CastProtocol {
+    switch portType {
+    case .airPlay: return .airplay
+    default: return .local
+    }
+  }
+
+  /// Map an `AVAudioSession.Port` to the lib's `AudioRouteKind`. Every
+  /// real-world consumer-music output port is covered; rarely-seen
+  /// pro-audio routes (`.AVB`, `.displayPort`, `.thunderbolt`) + the
+  /// I/O-only ports (`.builtInMic`, `.continuityMicrophone`, etc.)
+  /// fall through to `.unknown` so the picker still renders the port
+  /// name without forcing a kind-classification we can't justify.
+  /// Enum case names are Nitrogen-lowercased (e.g. `bluetootha2dp`) —
+  /// JS reads the original camelCase via the string-union surface.
+  private static func mapAudioRouteKind(_ portType: AVAudioSession.Port) -> AudioRouteKind {
+    switch portType {
+    case .builtInSpeaker: return .speaker
+    case .builtInReceiver: return .receiver
+    case .headphones, .lineOut: return .wired
+    case .usbAudio: return .usb
+    case .HDMI: return .hdmi
+    case .bluetoothA2DP: return .bluetootha2dp
+    case .bluetoothLE: return .bluetoothle
+    case .bluetoothHFP: return .bluetoothhfp
+    case .carAudio: return .carplay
+    case .airPlay: return .airplay
+    default: return .unknown
+    }
+  }
+
+  private static func mapDeviceKind(
+    _ portType: AVAudioSession.Port,
+    portName: String
+  ) -> CastDeviceKind {
+    switch portType {
+    case .builtInSpeaker, .builtInReceiver: return .phone
+    case .headphones, .bluetoothA2DP, .bluetoothLE, .bluetoothHFP: return .speaker
+    case .airPlay:
+      let lower = portName.lowercased()
+      return (lower.contains("tv") || lower.contains("apple tv")) ? .tv : .speaker
+    case .HDMI: return .tv
+    case .carAudio: return .speaker
+    default: return .unknown
+    }
+  }
+}