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

package/ios/CarPlay/CarPlaySession+Refresher.swift

@@ -0,0 +1,43 @@
+import CarPlay
+import NitroModules
+
+extension CarPlaySession {
+  /// Re-resolves `path`, bypassing the cache, into every displayed template showing it.
+  func refreshContent(for path: String) async {
+    do {
+      let resolved = try await audioBrowser.browserManager.resolve(path, useCache: false)
+      guard !Task.isCancelled else { return }
+      refreshDisplayedTemplates(for: path, with: resolved)
+    } catch {
+      logger.error("Failed to refresh content for \(path): \(error.localizedDescription)")
+    }
+  }
+
+  func refreshDisplayedTemplates(for path: String, with content: ResolvedTrack) {
+    for template in displayedListTemplates() where template.contentPath == path {
+      updateTemplate(template, with: content)
+    }
+  }
+
+  /// Re-resolves every displayed template at once, bypassing the cache: all content was
+  /// invalidated (e.g. a locale change).
+  func refreshAllDisplayedTemplates() async {
+    let browserManager = audioBrowser.browserManager
+    let loads = displayedListTemplates().compactMap { template in
+      template.contentPath.map { path in
+        (template, Task<ResolvedTrack?, Never> { @MainActor [logger] in
+          do {
+            return try await browserManager.resolve(path, useCache: false)
+          } catch {
+            logger.error("invalidateAllContent: failed to refresh \(path): \(error.localizedDescription)")
+            return nil
+          }
+        })
+      }
+    }
+    for load in loads {
+      guard let resolved = await load.1.value, !Task.isCancelled else { continue }
+      updateTemplate(load.0, with: resolved)
+    }
+  }
+}

package/ios/CarPlay/CarPlaySession+TabBar.swift

@@ -0,0 +1,193 @@
+import CarPlay
+import NitroModules
+
+extension CarPlaySession {
+  /// The tabs the tab bar shows: a disabled tab hides, as `CPTabBarTemplate` has no disabled
+  /// state (Android Auto filters the same way).
+  static func visibleTabs(_ tabs: [Track]) -> [Track] {
+    tabs.filter { $0.disabled != true }
+  }
+
+  func buildInitialInterface() async {
+    let build = beginRootBuild()
+    if let tabs = audioBrowser.browserManager.tabs, !tabs.isEmpty {
+      await showTabBar(tabs)
+      return
+    }
+    // The first loading root predates the config; re-show it with the app's loading title.
+    if let loadingTitle = config.carPlayLoadingTitle {
+      interfaceController.safeSetRoot(CPListTemplate.loading(title: nil, path: nil, loadingTitle: loadingTitle), animated: false)
+    }
+    do {
+      let tabs = try await audioBrowser.browserManager.queryTabs()
+      guard isCurrent(build) else { return }
+      await showTabBar(tabs)
+    } catch {
+      logger.error("Failed to query tabs: \(error.localizedDescription)")
+      await showRootError(NavigationError.from(error), build: build)
+    }
+  }
+
+  /// Builds the tab bar. While the Browse Gate is active each tab is decided on its own: a
+  /// gated tab becomes its gate page, an allowed one shows content.
+  func showTabBar(_ allTabs: [Track]) async {
+    let build = beginRootBuild()
+    builtTabs = allTabs
+    let tabs = Array(Self.visibleTabs(allTabs).prefix(CPTabBarTemplate.maximumTabCount))
+    let gated = audioBrowser.browseGate.isActive
+
+    // A tab bar with no tabs renders blank. A gate shows one full-screen page instead;
+    // otherwise it is the empty-content error, like any other failure (ADR 0001).
+    guard !tabs.isEmpty else {
+      if gated, let chrome = await audioBrowser.browseGate.decide(NativeGateRequest(reason: .browse, path: nil, search: nil)) {
+        guard isCurrent(build) else { return }
+        audioBrowser.onGate(GateEvent(reason: .browse))
+        interfaceController.safeSetRoot(makeGatePage(chrome, path: nil, tab: nil), animated: true)
+      } else {
+        await showRootError(.code(.emptyContent), build: build)
+      }
+      return
+    }
+
+    let chromes = gated ? await gates(for: tabs) : tabs.map { _ in nil }
+    guard isCurrent(build) else { return }
+    for _ in chromes.compactMap(\.self) {
+      audioBrowser.onGate(GateEvent(reason: .browse))
+    }
+    let templates = zip(tabs, chromes).map { tab, chrome in
+      chrome.map { makeGatePage($0, path: tab.path, tab: tab) } ?? makeTabTemplate(for: tab)
+    }
+
+    if gated, let tabBar = interfaceController.rootTemplate as? CPTabBarTemplate,
+       tabBar.templates.count == templates.count
+    {
+      // An equal-count swap keeps the selected tab.
+      tabBar.updateTemplates(templates)
+    } else {
+      interfaceController.safeSetRoot(CPTabBarTemplate(templates: templates), animated: true)
+    }
+
+    // Tabs fill lazily on first appearance. The first one is on screen already, and a template
+    // swapped in by `updateTemplates` may never report appearing.
+    let eager = gated ? templates : Array(templates.prefix(1))
+    for template in eager {
+      guard let path = template.contentPath else { continue }
+      await loadContent(for: path, into: template)
+    }
+  }
+
+  /// The tabs changed: restamp their entries in place when the paths are the same, else
+  /// rebuild, once the user is back at the root.
+  func tabsChanged(_ tabs: [Track]) {
+    guard !TabBarEntries.same(builtTabs, tabs) else { return }
+    let visible = Self.visibleTabs(tabs)
+    if !audioBrowser.browseGate.isActive,
+       let tabBar = interfaceController.rootTemplate as? CPTabBarTemplate,
+       tabBar.templates.count == min(visible.count, CPTabBarTemplate.maximumTabCount),
+       zip(tabBar.templates, visible).allSatisfy({ $0.contentPath == $1.path })
+    {
+      for (template, tab) in zip(tabBar.templates, visible) {
+        applyTabBarEntry(to: template, for: tab)
+      }
+      builtTabs = tabs
+      needsTabRebuild = false
+      return
+    }
+    needsTabRebuild = true
+    _ = rebuildTabsIfAtRoot()
+  }
+
+  /// Rebuilds the tab bar if a rebuild is due and the user is at the root. True when it did,
+  /// so the caller can skip work on a template about to be replaced.
+  func rebuildTabsIfAtRoot() -> Bool {
+    guard needsTabRebuild, interfaceController.templates.count <= 1 else { return false }
+    needsTabRebuild = false
+    spawn { await $0.showTabBar($0.audioBrowser.browserManager.tabs ?? []) }
+    return true
+  }
+
+  /// The gate was set or cleared: pushed content must not stay reachable behind it, and a
+  /// clear returns to the root.
+  func gateChanged() {
+    let tabs = audioBrowser.browserManager.tabs ?? []
+    if tabs.isEmpty, !audioBrowser.browseGate.isActive {
+      spawn { await $0.buildInitialInterface() }
+    } else {
+      interfaceController.safePopToRoot(animated: false)
+      spawn { await $0.showTabBar(tabs) }
+    }
+    nowPlaying.refresh()
+  }
+
+  /// The chrome to show if the Browse Gate gates this request, reporting it to JS; nil when the
+  /// request is allowed.
+  func gate(_ reason: GateReason, path: String?, search: SearchParams? = nil) async -> Gate? {
+    let chrome = await audioBrowser.browseGate.decide(NativeGateRequest(reason: reason, path: path, search: search))
+    if chrome != nil { audioBrowser.onGate(GateEvent(reason: reason)) }
+    return chrome
+  }
+
+  /// One decision per tab, made concurrently and returned in tab order. Reports nothing: the
+  /// caller fires `onGate` once it knows its build is still current.
+  private func gates(for tabs: [Track]) async -> [Gate?] {
+    let browseGate = audioBrowser.browseGate
+    let decisions = tabs.map { tab in
+      Task<Gate?, Never> { @MainActor in
+        await browseGate.decide(NativeGateRequest(reason: .browse, path: tab.path, search: nil))
+      }
+    }
+    var chromes: [Gate?] = []
+    for decision in decisions {
+      await chromes.append(decision.value)
+    }
+    return chromes
+  }
+
+  /// A tab's content shell, which loads when it first appears.
+  private func makeTabTemplate(for tab: Track) -> CPListTemplate {
+    let template = CPListTemplate.loading(title: tab.title, path: tab.path, loadingTitle: config.carPlayLoadingTitle)
+    applyTabBarEntry(to: template, for: tab)
+    return template
+  }
+
+  /// The gate page: a list template, because the audio entitlement does not allow
+  /// `CPInformationTemplate` (the tab bar raises on one), showing the chrome as its centered
+  /// empty view. No action button: a gate withholds content, and the app offers any
+  /// "subscribe" in its own UI.
+  func makeGatePage(_ chrome: Gate, path: String?, tab: Track?) -> CPListTemplate {
+    let template = CPListTemplate.message(
+      chrome.title, subtitle: chrome.message, listTitle: chrome.title,
+      info: CarPlayTemplateInfo(path: path, kind: .gate),
+    )
+    if let tab { applyTabBarEntry(to: template, for: tab) }
+    return template
+  }
+
+  /// Stamps a template's tab-bar title and image: an SF Symbol, loaded artwork, or none. Tab
+  /// icons are 24 pt (CarPlay Developer Guide).
+  func applyTabBarEntry(to template: CPTemplate, for track: Track) {
+    template.tabTitle = track.title
+    if let artwork = track.artwork?.url, SFSymbolRenderer.isSFSymbol(artwork) {
+      let (symbolName, _, _) = SFSymbolRenderer.parseArtwork(artwork)
+      if let image = imageLoader.sfSymbolImage(symbolName) {
+        template.tabImage = image
+      }
+    } else if track.artwork != nil || track.artworkSource != nil {
+      imageLoader.loadArtwork(for: track, size: CGSize(width: 24, height: 24)) { [weak template] image in
+        Task { @MainActor in
+          if let image { template?.tabImage = image }
+        }
+      }
+    } else {
+      // A restamp must not leave an old icon on a now title-only tab.
+      template.tabImage = nil
+    }
+  }
+
+  /// Shows a navigation error as the root: the app's formatting of it at path "/" (ADR 0001).
+  func showRootError(_ error: NavigationError, build: UInt) async {
+    let formatted = await audioBrowser.browserManager.formatted(error, path: "/")
+    guard isCurrent(build) else { return }
+    interfaceController.safeSetRoot(CPListTemplate.message(formatted.title, subtitle: formatted.message), animated: true)
+  }
+}

package/ios/CarPlay/CarPlaySession.swift

@@ -0,0 +1,209 @@
+import CarPlay
+import NitroModules
+import os.log
+
+/// One CarPlay run, from the moment the player and a configured browser exist until the scene
+/// stops or the bridge is replaced. It owns its subscriptions and tasks: `end()` cancels them,
+/// so nothing a stopped run started can paint over the next one.
+@MainActor
+final class CarPlaySession {
+  let logger = Logger(subsystem: "com.audiobrowser", category: "CarPlaySession")
+
+  let interfaceController: CPInterfaceController
+  let audioBrowser: HybridAudioBrowser
+  /// Read on each use: a re-setup replaces the bridge's player.
+  var player: Player? { audioBrowser.getPlayer() }
+  let trackSelector: TrackSelector
+  let imageLoader: CarPlayImageLoader
+  let listItemFactory: CarPlayListItemFactory
+  private(set) var nowPlaying: CarPlayNowPlayingManager!
+
+  private var subscriptions: [Subscription] = []
+  private var tasks: [UUID: Task<Void, Never>] = [:]
+  private(set) var ended = false
+
+  /// Paths whose pushed template has not appeared yet; guards a double tap, since
+  /// `topTemplate` only shows a push once it lands.
+  var navigatingPaths: Set<String> = []
+
+  /// Templates with a content load in flight, so a re-appearing one doesn't start another.
+  var loadingTemplates: Set<ObjectIdentifier> = []
+
+  /// Set when the tabs change while the user is browsing: rebuilding the tab bar would tear
+  /// down the pushed stack, so it waits until they are back at the root.
+  var needsTabRebuild = false
+
+  /// The tabs the current root was built from; their change event, which the browser delivers
+  /// after the build has begun, has nothing left to change.
+  var builtTabs: [Track]?
+
+  /// Bumped by every root build (initial interface, tab bar, root error). A build that
+  /// suspended and finds it bumped has been superseded, and leaves the root alone.
+  private var rootBuildGeneration: UInt = 0
+
+  /// How long a destination may spin before it shows an error.
+  let resolveTimeout: Duration = .seconds(15)
+
+  var config: BrowserConfig {
+    audioBrowser.browserManager.config
+  }
+
+  init(interfaceController: CPInterfaceController, audioBrowser: HybridAudioBrowser) {
+    self.interfaceController = interfaceController
+    self.audioBrowser = audioBrowser
+    trackSelector = TrackSelector(browserManager: audioBrowser.browserManager)
+    imageLoader = CarPlayImageLoader(
+      carTraitCollection: interfaceController.carTraitCollection,
+      browserManager: audioBrowser.browserManager,
+    )
+    listItemFactory = CarPlayListItemFactory(
+      isActiveTrack: { [weak audioBrowser] identity in
+        identity != nil && audioBrowser?.getPlayer()?.currentTrack?.identity == identity
+      },
+    )
+    listItemFactory.imageLoader = imageLoader
+    nowPlaying = CarPlayNowPlayingManager(
+      interfaceController: interfaceController,
+      audioBrowser: audioBrowser,
+      listItem: { [weak self] track, handler in
+        self?.listItemFactory.createListItem(for: track, handler: handler) ?? CPListItem(text: track.title, detailText: nil)
+      },
+      navigate: { [weak self] path, title in self?.spawn { await $0.navigate(to: path, title: title) } },
+    )
+    listItemFactory.onItemSelected = { [weak self] track, completion in self?.select(track, completion: completion) }
+    listItemFactory.onNavigate = { [weak self] path, title in self?.spawn { await $0.navigate(to: path, title: title) } }
+    listItemFactory.playingIndicatorLocation = playingIndicatorLocation
+  }
+
+  func start() {
+    let browserManager = audioBrowser.browserManager
+    subscriptions = [
+      browserManager.tabsChanged.subscribeOnMain { [weak self] in self?.tabsChanged($0) },
+      browserManager.contentChanged.subscribeOnMain { [weak self] content in
+        guard let content else { return }
+        self?.refreshDisplayedTemplates(for: content.path, with: content)
+      },
+      audioBrowser.playerOptionsChangedEmitter.subscribeOnMain { [weak self] in self?.playerOptionsChanged() },
+      audioBrowser.externalContentChangedEmitter.subscribeOnMain { [weak self] path in
+        guard let self else { return }
+        if path == HybridAudioBrowser.invalidateAllSentinel {
+          spawn { await $0.refreshAllDisplayedTemplates() }
+        } else {
+          spawn { await $0.refreshContent(for: path) }
+        }
+      },
+      audioBrowser.browseGate.changed.subscribeOnMain { [weak self] _ in self?.gateChanged() },
+      audioBrowser.activeTrackChangedEmitter.subscribeOnMain { [weak self] _ in self?.updatePlayingIndicators() },
+    ]
+    nowPlaying.start()
+    spawn { await $0.buildInitialInterface() }
+  }
+
+  func end() {
+    ended = true
+    for task in tasks.values {
+      task.cancel()
+    }
+    tasks = [:]
+    subscriptions = []
+    nowPlaying.end()
+  }
+
+  /// Runs `work` as a task this session owns, cancelled by `end()`.
+  func spawn(_ work: @escaping @MainActor (CarPlaySession) async -> Void) {
+    // A handler queued before `end()` can still call in; the next run owns the screen.
+    guard !ended else { return }
+    let id = UUID()
+    tasks[id] = Task { [weak self] in
+      guard let self else { return }
+      await work(self)
+      tasks[id] = nil
+    }
+  }
+
+  // MARK: - Root Builds
+
+  /// Starts a root build; pass the result to `isCurrent(_:)` after every suspension.
+  func beginRootBuild() -> UInt {
+    builtTabs = nil
+    rootBuildGeneration &+= 1
+    return rootBuildGeneration
+  }
+
+  func isCurrent(_ build: UInt) -> Bool {
+    build == rootBuildGeneration && !Task.isCancelled
+  }
+
+  // MARK: - Template Events
+
+  func templateDidAppear(_ template: CPTemplate) {
+    // Popping back from Now Playing reveals the tab bar, not a list; both repaint the playing
+    // indicator, which may have changed while the list was covered.
+    guard template is CPListTemplate || template is CPTabBarTemplate else { return }
+    if let path = template.carPlayInfo?.path { navigatingPaths.remove(path) }
+    if rebuildTabsIfAtRoot() { return }
+    updatePlayingIndicators()
+    if let list = template as? CPListTemplate { loadContentIfNeeded(for: list) }
+  }
+
+  func templateDidDisappear(_ template: CPTemplate) {
+    // Whether popping Now Playing reports the list appearing or only Now Playing leaving is a
+    // platform detail; both repaint the indicator.
+    guard template is CPNowPlayingTemplate else { return }
+    updatePlayingIndicators()
+  }
+
+  // MARK: - Playing Indicators
+
+  var playingIndicatorLocation: CPListItemPlayingIndicatorLocation {
+    switch audioBrowser.carPlayPlayingIndicatorLocation {
+    case .trailing: .trailing
+    case .leading: .leading
+    }
+  }
+
+  private func playerOptionsChanged() {
+    // The factory's copy is the last-applied location: sweep only on a real change.
+    let location = playingIndicatorLocation
+    guard listItemFactory.playingIndicatorLocation != location else { return }
+    listItemFactory.playingIndicatorLocation = location
+    updatePlayingIndicators()
+  }
+
+  /// Updates every displayed list item's playing flag and indicator location.
+  func updatePlayingIndicators() {
+    let location = playingIndicatorLocation
+    for template in displayedListTemplates() {
+      var changed = false
+      for section in template.sections {
+        for case let item as CPListItem in section.items {
+          guard let identity = item.carPlayItemInfo?.identity else { continue }
+          let isPlaying = player?.currentTrack?.identity == identity
+          if item.isPlaying != isPlaying {
+            item.isPlaying = isPlaying
+            changed = true
+          }
+          if item.playingIndicatorLocation != location {
+            item.playingIndicatorLocation = location
+            changed = true
+          }
+        }
+      }
+      // A flag set on a displayed item does not reliably reach the car screen; re-pushing the
+      // sections re-serializes every item, so it is done only when something changed.
+      if changed { template.updateSections(template.sections) }
+    }
+  }
+
+  /// The list templates on screen or one tap away: the tab roots, then the pushed stack.
+  func displayedListTemplates() -> [CPListTemplate] {
+    var templates: [CPListTemplate] = []
+    let tabRoots = (interfaceController.rootTemplate as? CPTabBarTemplate)?.templates ?? []
+    for case let list as CPListTemplate in tabRoots + interfaceController.templates
+      where !templates.contains(where: { $0 === list })
+    {
+      templates.append(list)
+    }
+    return templates
+  }
+}

package/ios/CarPlay/CarPlayTemplates.swift

@@ -0,0 +1,63 @@
+import CarPlay
+
+/// What a CarPlay template shows, kept in its `userInfo`.
+struct CarPlayTemplateInfo {
+  enum Kind {
+    /// Content that `path` resolves to; loaded lazily and refreshed.
+    case content
+    /// The Browse Gate's page for `path`, which is never loaded.
+    case gate
+  }
+
+  /// The browse path the template stands for. Nil only for a gate page shown at the root.
+  let path: String?
+  let kind: Kind
+}
+
+extension CPTemplate {
+  var carPlayInfo: CarPlayTemplateInfo? {
+    get { userInfo as? CarPlayTemplateInfo }
+    set { userInfo = newValue }
+  }
+
+  /// The path this template loads content from; nil for gate and message pages.
+  var contentPath: String? {
+    guard let info = carPlayInfo, info.kind == .content else { return nil }
+    return info.path
+  }
+}
+
+extension CPListTemplate {
+  /// A list template whose content is still resolving: the system spinner on iOS 18.4+, and
+  /// the app's `loadingTitle`, when it set one, as the empty-view subtitle. A title-slot hint
+  /// would render at CarPlay's large empty-state size.
+  static func loading(title: String?, path: String?, loadingTitle: String?) -> CPListTemplate {
+    let template = CPListTemplate(title: title, sections: [])
+    if let path { template.carPlayInfo = CarPlayTemplateInfo(path: path, kind: .content) }
+    if let loadingTitle { template.emptyViewSubtitleVariants = [loadingTitle] }
+    if #available(iOS 18.4, *) {
+      template.showsSpinnerWhileEmpty = true
+    }
+    return template
+  }
+
+  /// An empty list template showing a centered message. CarPlay renders an empty view reliably
+  /// only as a template's initial state, so a pushed page's message is a new template.
+  static func message(
+    _ title: String,
+    subtitle: String?,
+    listTitle: String? = nil,
+    info: CarPlayTemplateInfo? = nil,
+  ) -> CPListTemplate {
+    let template = CPListTemplate(title: listTitle, sections: [])
+    template.setMessage(title, subtitle: subtitle)
+    template.carPlayInfo = info
+    return template
+  }
+
+  /// Newlines collapse to spaces: the variants are width alternatives, not lines.
+  func setMessage(_ title: String, subtitle: String?) {
+    emptyViewTitleVariants = [title]
+    emptyViewSubtitleVariants = subtitle.flatMap { $0.isEmpty ? nil : [$0.replacingOccurrences(of: "\n", with: " ")] } ?? []
+  }
+}

package/ios/CarPlay/HybridAudioBrowser+IntentFavorite.swift

@@ -0,0 +1,20 @@
+import Foundation
+import os.log
+
+private let intentLogger = Logger(subsystem: "com.audiobrowser", category: "MediaIntent")
+
+extension HybridAudioBrowser {
+  /// Sets the favorite state of the playing track for a Siri intent, through the same path as
+  /// the CarPlay favorite button. False when nothing is playing, the playing track has no
+  /// identity to favorite, or the change throws.
+  @MainActor
+  static func favoriteCurrentTrack(_ favorited: Bool) -> Bool {
+    guard let browser = shared else { return false }
+    do {
+      return try browser.favoriteActiveTrack(favorited)
+    } catch {
+      intentLogger.error("favoriteCurrentTrack(\(favorited)) failed: \(error.localizedDescription)")
+      return false
+    }
+  }
+}

package/ios/{Player → CarPlay}/MediaIntentCriteria.swift

@@ -43,7 +43,7 @@ public struct MediaIntentCriteria: Sendable {
     artist: String? = nil,
     album: String? = nil,
     title: String? = nil,
-    playlist: String? = nil
+    playlist: String? = nil,
   ) {
     self.query = query
     self.reference = reference
@@ -90,7 +90,7 @@ public struct MediaIntentCriteria: Sendable {
     mediaTypeMode: String?,
     reference: Reference,
     hasMediaType: Bool,
-    appName: String?
+    appName: String?,
   ) -> MediaIntentCriteria {
     let name = (mediaName ?? "").trimmingCharacters(in: .whitespacesAndNewlines)
     let trimmedNonEmpty: (String?) -> String? = {
@@ -115,25 +115,33 @@ public struct MediaIntentCriteria: Sendable {
       hasGenres: !genreNames.isEmpty,
       hasMediaType: hasMediaType,
       matchesAppName: queryMatchesAppName(query, appName: appName),
-      searchMode: mediaTypeMode,   // mode is the vertical, verbatim — no derivation
+      searchMode: mediaTypeMode, // mode is the vertical, verbatim — no derivation
       genre: genre,
       artist: artist,
       album: album,
       title: title,
-      playlist: playlist
+      playlist: playlist,
     )
   }
 
   /// Whether `query` is effectively the host app's own name. Case- and
   /// diacritic-insensitive.
+  ///
+  /// Whole-word subset match in either direction. Siri may deliver only part of
+  /// the name ("Name" for «App Name»), so a partial match must count — but a
+  /// substring match swallowed any query appearing inside the app name, making
+  /// one-word stations unreachable by voice.
   private static func queryMatchesAppName(_ query: String, appName: String?) -> Bool {
     guard let appName else { return false }
-    let normalize: (String) -> String = {
-      $0.folding(options: [.diacriticInsensitive, .caseInsensitive], locale: nil)
-        .trimmingCharacters(in: .whitespacesAndNewlines)
+    let tokens: (String) -> Set<String> = {
+      Set(
+        $0.folding(options: [.diacriticInsensitive, .caseInsensitive], locale: nil)
+          .split(whereSeparator: { !$0.isLetter && !$0.isNumber })
+          .map(String.init),
+      )
     }
-    let q = normalize(query), a = normalize(appName)
+    let q = tokens(query), a = tokens(appName)
     guard !q.isEmpty, !a.isEmpty else { return false }
-    return a.contains(q) || q.contains(a)
+    return q.isSubset(of: a) || a.isSubset(of: q)
   }
 }

package/ios/CarPlay/MediaIntentPlayback.swift

@@ -0,0 +1,74 @@
+import Foundation
+import NitroModules
+import os.log
+
+private let logger = Logger(subsystem: "com.audiobrowser", category: "MediaIntentPlayback")
+
+/// Plays a Siri play-media intent through the single voice play funnel (ADR 0002): resume, or
+/// search → queue → play, then surface Now Playing.
+enum MediaIntentPlayback {
+  /// Callable before the bridge exists: it waits, within the assistant's budget, for the player
+  /// and a configured browser, which come up once React Native boots. Each await may outlive the
+  /// bridge or its player (a JS reload or a second setup replaces them), so the player is looked
+  /// up again after one, and the intent fails once the bridge is gone.
+  @MainActor
+  static func play(criteria: MediaIntentCriteria) async -> Bool {
+    guard let (browser, player) = await playerAndConfiguredBrowser.wait(timeout: .seconds(8)) else {
+      logger.error("browser/player not ready within budget")
+      return false
+    }
+    // Resume is not gated: the gate blocks finding content, never hearing the active or
+    // persisted track.
+    if criteria.isResume {
+      if player.currentTrack != nil {
+        logger.info("resume: warm — playing current track")
+        player.play()
+      } else {
+        guard let session = player.persistedSession() else { return false }
+        var expanded: (tracks: [Track], selectedIndex: Int)?
+        if let path = session.track.path {
+          expanded = try? await browser.browserManager.expandQueueFromContextualPath(path)
+        }
+        guard let player = livePlayer(of: browser) else { return false }
+        player.resume(session, queue: expanded)
+      }
+      browser.showNowPlayingRequestedEmitter.emit(())
+      return true
+    }
+
+    // The API still text-searches `q`; the structured fields are forward-compatible, as on
+    // Android.
+    let params = SearchParams(
+      mode: criteria.searchMode.flatMap { SearchMode(fromString: $0) },
+      query: criteria.query,
+      genre: criteria.genre,
+      artist: criteria.artist,
+      album: criteria.album,
+      title: criteria.title,
+      playlist: criteria.playlist,
+      reference: criteria.reference == .my ? .my : .unknown,
+    )
+    guard await browser.browseGate.decide(NativeGateRequest(reason: .search, path: nil, search: params)) == nil else {
+      logger.info("search refused — gated")
+      browser.onGate(GateEvent(reason: .search))
+      return false
+    }
+    do {
+      guard let tracks = try await browser.browserManager.searchPlayable(params),
+            let player = livePlayer(of: browser) else { return false }
+      player.setQueue(tracks, initialIndex: 0, playWhenReady: true)
+      browser.showNowPlayingRequestedEmitter.emit(())
+      return true
+    } catch {
+      logger.error("search failed: \(error.localizedDescription)")
+      return false
+    }
+  }
+
+  /// `browser`'s player while `browser` is still the live bridge; a replaced bridge keeps its
+  /// destroyed player.
+  @MainActor
+  private static func livePlayer(of browser: HybridAudioBrowser) -> Player? {
+    HybridAudioBrowser.shared === browser ? browser.getPlayer() : nil
+  }
+}