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

package/ios/CarPlay/CarPlayNowPlayingManager.swift

@@ -2,29 +2,26 @@ import CarPlay
 import Foundation
 import os.log
 
-/// Manages the Now Playing template, buttons, Up Next, and related state for CarPlay.
-///
-/// Responsibilities:
-/// - CPNowPlayingTemplate setup and button configuration
-/// - Button action handlers (shuffle, repeat, favorite, playback rate)
-/// - Button state updates (favorite appearance, Up Next enabled)
-/// - Up Next template creation and queue change handling
-/// - NowPlayingObserver for Up Next button taps
+/// The CarPlay Now Playing template for one session: its custom buttons, the album line's
+/// destination, Up Next, and the events that refresh them.
 @MainActor
 final class CarPlayNowPlayingManager {
   private let logger = Logger(subsystem: "com.audiobrowser", category: "CarPlayNowPlayingManager")
 
   private let interfaceController: CPInterfaceController
-  var listItemFactory: (Track, ((CPSelectableListItem, @escaping () -> Void) -> Void)?) -> CPListItem
-  /// Pushes a browse destination (wired to the controller's navigateToUrl).
-  var navigateToUrl: ((_ url: String, _ title: String) -> Void)?
-
-  private weak var audioBrowser: HybridAudioBrowser?
+  private let audioBrowser: HybridAudioBrowser
+  /// Read on each use: a re-setup replaces the bridge's player.
+  private var player: Player? { audioBrowser.getPlayer() }
+  private let listItem: (Track, ((CPSelectableListItem, @escaping () -> Void) -> Void)?) -> CPListItem
+  /// Pushes a browse destination: the album line's.
+  private let navigate: (_ path: String, _ title: String) -> Void
+
+  private var subscriptions: [Subscription] = []
   private var nowPlayingObserver: NowPlayingObserver?
   private weak var upNextTemplate: CPListTemplate?
   /// Everything the built button row renders — button types, the heart's
   /// favorited state, and the shuffle/repeat `isSelected` state. Rebuilds are
-  /// skipped while this is unchanged (`onConfigChanged` fires on unrelated
+  /// skipped while this is unchanged (`configChanged` fires on unrelated
   /// churn, and every `updateNowPlayingButtons` call re-renders ALL buttons).
   ///
   /// shuffle/repeat selected state is part of the snapshot because CarPlay
@@ -46,11 +43,11 @@ final class CarPlayNowPlayingManager {
   private var builtRow: BuiltButtonRow?
 
   /// Browse path the album line navigates to for the active track —
-  /// `track.albumUrl`, or the pre-resolved `resolveAlbumUrl` result. Resolved
+  /// `track.albumPath`, or the pre-resolved `resolveAlbumPath` result. Resolved
   /// at track-change time (not at tap) so the album line only surfaces when a
   /// destination actually exists.
   private var albumArtistDestination: String?
-  /// Drops a stale async `resolveAlbumUrl` result when the track changed while
+  /// Drops a stale async `resolveAlbumPath` result when the track changed while
   /// the resolver was in flight (latest-update-wins).
   private var albumArtistGeneration: UInt = 0
   /// The just-tapped track whose load is still in flight. CarPlay reads
@@ -60,57 +57,81 @@ final class CarPlayNowPlayingManager {
   /// from the tapped track at push time. Cleared when the active track changes.
   private var pendingAlbumArtistTrack: Track?
 
-  /// Convenience accessor for browser config
   private var config: BrowserConfig {
-    audioBrowser?.browserManager.config ?? BrowserConfig()
-  }
-
-  /// The active track's favorited state, from the authoritative favorite set
-  /// (see `HybridAudioBrowser.isActiveTrackFavorited`).
-  private var isActiveTrackFavorited: Bool {
-    audioBrowser?.isActiveTrackFavorited() ?? false
+    audioBrowser.browserManager.config
   }
 
-  init(interfaceController: CPInterfaceController) {
+  init(
+    interfaceController: CPInterfaceController,
+    audioBrowser: HybridAudioBrowser,
+    listItem: @escaping (Track, ((CPSelectableListItem, @escaping () -> Void) -> Void)?) -> CPListItem,
+    navigate: @escaping (_ path: String, _ title: String) -> Void,
+  ) {
     self.interfaceController = interfaceController
-    self.listItemFactory = { track, _ in CPListItem(text: track.title, detailText: nil) }
+    self.audioBrowser = audioBrowser
+    self.listItem = listItem
+    self.navigate = navigate
   }
 
   // MARK: - Lifecycle
 
-  func setup(audioBrowser: HybridAudioBrowser) {
-    self.audioBrowser = audioBrowser
-    setupNowPlayingTemplate()
+  func start() {
+    let observer = NowPlayingObserver(manager: self)
+    nowPlayingObserver = observer
+    CPNowPlayingTemplate.shared.add(observer)
+
+    let browserManager = audioBrowser.browserManager
+    subscriptions = [
+      browserManager.configChanged.subscribeOnMain { [weak self] _ in self?.refresh() },
+      audioBrowser.playerOptionsChangedEmitter.subscribeOnMain { [weak self] in self?.refresh() },
+      browserManager.favoritesChanged.subscribeOnMain { [weak self] in self?.refreshButtons() },
+      audioBrowser.favoriteChangedEmitter.subscribeOnMain { [weak self] _ in self?.refreshButtons() },
+      audioBrowser.repeatModeChangedEmitter.subscribeOnMain { [weak self] _ in self?.refreshButtons() },
+      audioBrowser.shuffleChangedEmitter.subscribeOnMain { [weak self] _ in self?.refreshButtons() },
+      audioBrowser.queueChangedEmitter.subscribeOnMain { [weak self] in self?.queueChanged($0) },
+      audioBrowser.showNowPlayingRequestedEmitter.subscribeOnMain { [weak self] in self?.showNowPlaying() },
+      audioBrowser.activeTrackChangedEmitter.subscribeOnMain { [weak self] _ in
+        // The player's current track is authoritative again.
+        self?.pendingAlbumArtistTrack = nil
+        self?.refresh()
+      },
+    ]
+    refresh()
   }
 
-  func teardown() {
-    if let observer = nowPlayingObserver {
-      CPNowPlayingTemplate.shared.remove(observer)
-      nowPlayingObserver = nil
-    }
+  func end() {
+    if let nowPlayingObserver { CPNowPlayingTemplate.shared.remove(nowPlayingObserver) }
+    nowPlayingObserver = nil
+    subscriptions = []
     pendingAlbumArtistTrack = nil
-    audioBrowser = nil
+    // A resolve still in flight must not set the shared template for the next session.
+    albumArtistGeneration &+= 1
   }
 
-  // MARK: - Now Playing Template
-
-  private func setupNowPlayingTemplate() {
-    let template = CPNowPlayingTemplate.shared
-
-    let observer = NowPlayingObserver(manager: self)
-    nowPlayingObserver = observer
-    template.add(observer)
+  /// Re-renders Up Next availability, the custom buttons and the album line's destination.
+  func refresh() {
+    updateUpNextButton()
+    refreshButtons()
+    updateAlbumArtistDestination()
+  }
 
-    setupNowPlayingButtons()
-    updateNowPlayingButtonStates()
+  /// Marks `track` as the just-tapped (still loading) track and derives the album line's
+  /// destination from it. Call before pushing Now Playing: CarPlay reads
+  /// `isAlbumArtistButtonEnabled` at display time, so enabling it after the push renders no
+  /// chevron.
+  func prepare(for track: Track) {
+    pendingAlbumArtistTrack = track
+    updateAlbumArtistDestination()
   }
 
-  /// Sets up custom Now Playing buttons based on configuration and current
-  /// player state, skipping the rebuild when nothing the row renders changed.
-  func setupNowPlayingButtons() {
-    // While a gate is active, custom buttons (favorite etc.) are hidden;
-    // the system transport controls stay — a gate never blocks playback.
-    let configured = (audioBrowser?.isGateActive ?? false) ? [] : (audioBrowser?.carPlayNowPlayingButtons ?? [])
+  // MARK: - Buttons
+
+  /// Builds the custom button row from the configuration and player state, skipping the
+  /// rebuild when nothing the row renders changed.
+  private func refreshButtons() {
+    // A gate hides the custom buttons; the transport controls stay, as a gate never blocks
+    // playback.
+    let configured = audioBrowser.browseGate.isActive ? [] : audioBrowser.carPlayNowPlayingButtons
     // The template caps custom buttons at 5 (CPNowPlayingTemplate.h) and says
     // nothing about overflow — unlike lists (trim) or the tab bar (throw). The
     // config comes straight from JS, where duplicates and excess are
@@ -120,12 +141,11 @@ final class CarPlayNowPlayingManager {
       deduped.append(button)
     }
     let buttons = Array(deduped.prefix(5))
-    let player = audioBrowser?.getPlayer()
     let row = BuiltButtonRow(
       types: buttons,
-      favorited: buttons.contains(.favorite) ? isActiveTrackFavorited : nil,
-      shuffleSelected: buttons.contains(.shuffle) ? (player?.shuffleEnabled ?? false) : nil,
-      repeatSelected: buttons.contains(.repeat) ? (player?.getRepeatMode() ?? .off) != .off : nil,
+      favorited: buttons.contains(.favorite) ? audioBrowser.isActiveTrackFavorited() : nil,
+      shuffleSelected: buttons.contains(.shuffle) ? player?.shuffleEnabled ?? false : nil,
+      repeatSelected: buttons.contains(.repeat) ? (player?.repeatMode ?? .off) != .off : nil,
     )
     guard row != builtRow else { return }
     builtRow = row
@@ -182,10 +202,10 @@ final class CarPlayNowPlayingManager {
   /// stack but buried under templates pushed on top of it (Up Next, the album
   /// line's browse destination): a user-initiated surface (tap, voice play)
   /// pops back to it, while the deferred post-resolve calls in
-  /// `handleItemSelection` pass `false` — they run seconds after the tap, and
+  /// `CarPlaySession.select` pass `false` — they run seconds after the tap, and
   /// popping then would yank away a screen the user navigated to meanwhile.
   func showNowPlaying(popToFront: Bool = true) {
-    updateNowPlayingButtonStates()
+    refresh()
     let nowPlayingTemplate = CPNowPlayingTemplate.shared
     if interfaceController.templates.contains(where: { $0 === nowPlayingTemplate }) {
       if popToFront {
@@ -196,58 +216,28 @@ final class CarPlayNowPlayingManager {
     }
   }
 
-  // MARK: - Button State Updates
-
-  /// Refreshes the row for a favorite/shuffle/repeat state change — the
-  /// snapshot diff in setupNowPlayingButtons makes this a no-op when nothing
-  /// the row renders actually changed.
-  func updateFavoriteButtonState() {
-    setupNowPlayingButtons()
-  }
-
-  /// Updates Now Playing button states based on config and current queue
-  func updateNowPlayingButtonStates() {
-    updateNowPlayingUpNextButton()
-    setupNowPlayingButtons()
-    updateAlbumArtistButtonState()
-  }
-
-  /// Re-resolves the album line's destination for the active track and
-  /// enables the (tappable) album/artist button only when one exists:
-  /// `track.albumUrl`, or the app's `resolveAlbumUrl` result.
-  /// Marks `track` as the just-tapped (still loading) track and derives the
-  /// album line's destination from it. Must run before the Now Playing
-  /// template is pushed — CarPlay reads `isAlbumArtistButtonEnabled` at display
-  /// time, so enabling after the push (when the load lands) renders no chevron.
-  func prepareAlbumArtistButton(for track: Track) {
-    pendingAlbumArtistTrack = track
-    updateAlbumArtistButtonState()
-  }
-
-  /// Clears the tap-time pending track (the player's `currentTrack` is now
-  /// authoritative) and refreshes all button states.
-  func handleActiveTrackChanged() {
-    pendingAlbumArtistTrack = nil
-    updateNowPlayingButtonStates()
-  }
+  // MARK: - Album Line
 
-  func updateAlbumArtistButtonState() {
+  /// Resolves the album line's destination for the active (or just-tapped) track and enables
+  /// the album/artist button only when one exists: `track.albumPath`, or the app's
+  /// `resolveAlbumPath` result.
+  private func updateAlbumArtistDestination() {
     albumArtistGeneration &+= 1
     let generation = albumArtistGeneration
 
     // The just-tapped track wins while its load is in flight: currentTrack
     // still points at the previous track (or nil) at push time.
-    guard let track = pendingAlbumArtistTrack ?? audioBrowser?.getPlayer()?.currentTrack else {
+    guard let track = pendingAlbumArtistTrack ?? player?.currentTrack else {
       logger.debug("AlbumArtist: no current track → disabled")
       setAlbumArtistDestination(nil)
       return
     }
-    logger.info("AlbumArtist: track=\(track.title) albumUrl=\(track.albumUrl ?? "nil") resolver=\(self.config.resolveAlbumUrl != nil)")
-    if let albumUrl = track.albumUrl {
-      setAlbumArtistDestination(albumUrl)
+    logger.info("AlbumArtist: track=\(track.title) albumPath=\(track.albumPath ?? "nil") resolver=\(self.config.resolveAlbumPath != nil)")
+    if let albumPath = track.albumPath {
+      setAlbumArtistDestination(albumPath)
       return
     }
-    guard let resolver = config.resolveAlbumUrl else {
+    guard let resolver = config.resolveAlbumPath else {
       setAlbumArtistDestination(nil)
       return
     }
@@ -256,7 +246,7 @@ final class CarPlayNowPlayingManager {
       do {
         path = try await resolver(track).await()
       } catch {
-        self?.logger.error("resolveAlbumUrl failed: \(error.localizedDescription)")
+        self?.logger.error("resolveAlbumPath failed: \(error.localizedDescription)")
         path = nil
       }
       guard let self, self.albumArtistGeneration == generation else { return }
@@ -276,18 +266,10 @@ final class CarPlayNowPlayingManager {
 
   // MARK: - Queue Changes
 
-  /// Handles queue changes - updates Up Next list if visible
-  func handleQueueChanged(_ tracks: [Track]) {
-    updateNowPlayingUpNextButton()
-
-    guard let template = upNextTemplate,
-          let player = audioBrowser?.getPlayer()
-    else {
-      return
-    }
-
-    logger.debug("Queue changed, updating Up Next list with \(tracks.count) tracks")
-    template.updateSections([createUpNextSection(tracks: tracks, player: player)])
+  private func queueChanged(_ tracks: [Track]) {
+    updateUpNextButton()
+    guard let upNextTemplate else { return }
+    upNextTemplate.updateSections([createUpNextSection(tracks: tracks)])
   }
 
   // MARK: - Private - Button Handlers
@@ -295,24 +277,25 @@ final class CarPlayNowPlayingManager {
   /// Returns the appropriate image for the favorite button based on state
   private func favoriteButtonImage(isFavorited: Bool) -> UIImage {
     let symbolName = isFavorited ? "heart.fill" : "heart"
-    guard let image = UIImage(systemName: symbolName)?.resized(to: CPNowPlayingButtonMaximumImageSize) else {
+    guard let image = UIImage(systemName: symbolName)?.fitted(
+      to: CPNowPlayingButtonMaximumImageSize,
+      scale: interfaceController.carTraitCollection.displayScale,
+    ) else {
       return UIImage()
     }
     return image
   }
 
   private func handleShuffleButtonTapped() {
-    guard let player = audioBrowser?.getPlayer() else { return }
-
+    guard let player else { return }
     let newEnabled = !player.shuffleEnabled
     player.shuffleEnabled = newEnabled
     logger.info("CarPlay shuffle mode changed: \(newEnabled)")
   }
 
   private func handleRepeatButtonTapped() {
-    guard let player = audioBrowser?.getPlayer() else { return }
-
-    let currentMode = player.getRepeatMode()
+    guard let player else { return }
+    let currentMode = player.repeatMode
     let newMode: RepeatMode = switch currentMode {
     case .off:
       .track
@@ -322,20 +305,22 @@ final class CarPlayNowPlayingManager {
       .off
     }
 
-    player.setRepeatMode(newMode)
+    player.repeatMode = newMode
     logger.info("CarPlay repeat mode changed: \(currentMode.stringValue) → \(newMode.stringValue)")
   }
 
   private func handleFavoriteButtonTapped() {
-    try? audioBrowser?.toggleActiveTrackFavorited()
+    do {
+      try audioBrowser.toggleActiveTrackFavorited()
+    } catch {
+      logger.error("favorite toggle failed: \(error.localizedDescription)")
+    }
     logger.info("CarPlay favorite toggled")
   }
 
   private func handlePlaybackRateButtonTapped() {
-    guard let audioBrowser, let player = audioBrowser.getPlayer() else { return }
-
     let rates = audioBrowser.playbackRates
-    guard !rates.isEmpty else { return }
+    guard !rates.isEmpty, let player else { return }
 
     let currentRate = Double(player.rate)
     let nextRate: Double
@@ -355,26 +340,20 @@ final class CarPlayNowPlayingManager {
 
   fileprivate func handleAlbumArtistButtonTapped() {
     guard let destination = albumArtistDestination else { return }
-    let track = pendingAlbumArtistTrack ?? audioBrowser?.getPlayer()?.currentTrack
+    let track = pendingAlbumArtistTrack ?? player?.currentTrack
     // The album line is what was tapped, so its text is the natural title for
     // the pushed destination (artist may be unset, or the live song).
     let title = track?.album ?? track?.artist ?? track?.title ?? ""
     logger.info("Album/Artist button tapped, navigating to \(destination)")
-    navigateToUrl?(destination, title)
+    navigate(destination, title)
   }
 
-  private func updateNowPlayingUpNextButton() {
-    let template = CPNowPlayingTemplate.shared
-    template.isUpNextButtonEnabled = (audioBrowser?.carPlayUpNextButton ?? true) && (audioBrowser?.getPlayer()?.tracks.count ?? 0) > 1
+  private func updateUpNextButton() {
+    CPNowPlayingTemplate.shared.isUpNextButtonEnabled = audioBrowser.carPlayUpNextButton && (player?.tracks.count ?? 0) > 1
   }
 
   fileprivate func handleUpNextButtonTapped() {
-    guard let player = audioBrowser?.getPlayer() else {
-      logger.warning("Player not available for Up Next")
-      return
-    }
-
-    let tracks = player.tracks
+    let tracks = player?.tracks ?? []
 
     guard !tracks.isEmpty else {
       logger.debug("No tracks in queue for Up Next")
@@ -389,7 +368,7 @@ final class CarPlayNowPlayingManager {
     let upNextTitle = CPNowPlayingTemplate.shared.upNextTitle
     let template = CPListTemplate(
       title: upNextTitle.isEmpty ? "Up Next" : upNextTitle,
-      sections: [createUpNextSection(tracks: tracks, player: player)],
+      sections: [createUpNextSection(tracks: tracks)],
     )
 
     upNextTemplate = template
@@ -397,7 +376,7 @@ final class CarPlayNowPlayingManager {
     interfaceController.safePush(template, animated: true)
   }
 
-  private func createUpNextSection(tracks: [Track], player: TrackPlayer) -> CPListSection {
+  private func createUpNextSection(tracks: [Track]) -> CPListSection {
     // Clamp to CarPlay's list limit (createSections does the same for browse
     // lists). Taking the prefix keeps item positions aligned with queue indices.
     let maxItems = CPListTemplate.maximumItemCount
@@ -405,10 +384,10 @@ final class CarPlayNowPlayingManager {
       logger.info("Up Next queue has \(tracks.count) tracks, clamping to CarPlay's limit of \(maxItems)")
     }
     let items = tracks.prefix(maxItems).enumerated().map { index, track -> CPListItem in
-      listItemFactory(track) { [weak self] _, completion in
+      listItem(track) { [weak self] _, completion in
         self?.logger.info("Skipping to track at index \(index): \(track.title)")
         do {
-          try player.skipTo(index, playWhenReady: true)
+          try self?.player?.skipTo(index, playWhenReady: true)
         } catch {
           self?.logger.error("Failed to skip to track: \(error.localizedDescription)")
         }
@@ -444,3 +423,17 @@ private final class NowPlayingObserver: NSObject, CPNowPlayingTemplateObserver,
     }
   }
 }
+
+private extension UIImage {
+  /// Draws the image centered in `targetSize`, keeping its aspect ratio, at the car screen's
+  /// display scale.
+  func fitted(to targetSize: CGSize, scale: CGFloat) -> UIImage? {
+    UIGraphicsBeginImageContextWithOptions(targetSize, false, scale)
+    defer { UIGraphicsEndImageContext() }
+    let fitScale = min(targetSize.width / size.width, targetSize.height / size.height)
+    let scaledSize = CGSize(width: size.width * fitScale, height: size.height * fitScale)
+    let origin = CGPoint(x: (targetSize.width - scaledSize.width) / 2, y: (targetSize.height - scaledSize.height) / 2)
+    draw(in: CGRect(origin: origin, size: scaledSize))
+    return UIGraphicsGetImageFromCurrentImageContext()?.withRenderingMode(.alwaysTemplate)
+  }
+}

package/ios/CarPlay/CarPlaySession+Navigator.swift

@@ -0,0 +1,114 @@
+import CarPlay
+import NitroModules
+
+extension CarPlaySession {
+  /// A row or tile was tapped. CarPlay is released at once, so the list never locks: a browse
+  /// pushes its destination and fills it in, and playback owns its loading state on Now Playing.
+  func select(_ track: Track, completion: @escaping () -> Void) {
+    logger.info("Selected track: \(track.title)")
+    // A tap queued before `end()`: the next run owns the screen.
+    guard !ended else {
+      completion()
+      return
+    }
+
+    if track.src != nil, let identity = track.identity, player?.currentTrack?.identity == identity {
+      try? audioBrowser.play()
+      nowPlaying.showNowPlaying()
+      completion()
+      return
+    }
+
+    // A playable track always lands on Now Playing, so it is pushed now with the tapped
+    // track's fields: the queue expansion and media resolve may both hit the network.
+    if track.src != nil {
+      audioBrowser.engine?.loadNowPlayingMetadata(for: track)
+      nowPlaying.prepare(for: track)
+      nowPlaying.showNowPlaying()
+    }
+    completion()
+
+    spawn { session in
+      guard let player = session.player else { return }
+      let result = await session.trackSelector.select(track: track, player: player)
+      guard !Task.isCancelled else {
+        if track.src != nil { session.restoreNowPlaying() }
+        return
+      }
+      switch result {
+      case let .play(intent):
+        session.player?.execute(intent)
+        session.nowPlaying.showNowPlaying(popToFront: false)
+      case .intercepted:
+        session.nowPlaying.showNowPlaying(popToFront: false)
+      case let .browse(path):
+        await session.navigate(to: path, title: track.title)
+      case .none:
+        break
+      }
+    }
+  }
+
+  /// Puts the current track back on the now-playing surface, over a tapped one that won't play.
+  private func restoreNowPlaying() {
+    guard let engine = audioBrowser.engine else { return }
+    if let current = player?.currentTrack {
+      engine.loadNowPlayingMetadata(for: current)
+      engine.nowPlayingUpdater.render()
+    } else {
+      engine.clearNowPlaying()
+    }
+  }
+
+  /// Pushes `path`'s page as an empty, spinning template that fills in once it appears; or the
+  /// Browse Gate's page when the gate gates it; or selects the tab that is that path.
+  func navigate(to path: String, title: String) async {
+    // A push lands asynchronously, so a double tap is caught by `navigatingPaths` until the
+    // pushed template appears.
+    guard interfaceController.topTemplate?.carPlayInfo?.path != path, !navigatingPaths.contains(path) else { return }
+    navigatingPaths.insert(path)
+    var pushing = false
+    defer { if !pushing { navigatingPaths.remove(path) } }
+
+    let chrome = audioBrowser.browseGate.isActive ? await gate(.browse, path: path) : nil
+    guard !Task.isCancelled else { return }
+    let template: CPTemplate
+    if let chrome {
+      template = makeGatePage(chrome, path: path, tab: nil)
+    } else if selectTab(owning: path) {
+      return
+    } else {
+      template = CPListTemplate.loading(title: title, path: path, loadingTitle: config.carPlayLoadingTitle)
+    }
+
+    pushing = true
+    interfaceController.safePush(template, animated: true) { [weak self] pushed, error in
+      guard !pushed else { return }
+      // It will never appear to clear the guard (e.g. at the depth limit).
+      self?.navigatingPaths.remove(path)
+      if let error { self?.logger.error("pushTemplate failed for \(path): \(error.localizedDescription)") }
+    }
+  }
+
+  /// Switches to the tab whose path this is, popping any pushed stack first, instead of pushing
+  /// a second copy of the tab into another tab's stack. False when no tab has the path, when
+  /// the root is not a tab bar, or before iOS 17, which cannot select a tab.
+  private func selectTab(owning path: String) -> Bool {
+    guard #available(iOS 17.0, *),
+          let tabBar = interfaceController.rootTemplate as? CPTabBarTemplate,
+          let tab = tabBar.templates.first(where: { $0.contentPath == path })
+    else { return false }
+    let isPushed = interfaceController.templates.count > 1
+    if tabBar.selectedTemplate === tab, !isPushed { return true }
+    guard isPushed else {
+      tabBar.select(tab)
+      return true
+    }
+    interfaceController.safePopToRoot(animated: true) { popped, _ in
+      // After a failed pop the selection would land under the pushed stack.
+      guard popped else { return }
+      tabBar.select(tab)
+    }
+    return true
+  }
+}

package/ios/CarPlay/CarPlaySession+PageLoader.swift

@@ -0,0 +1,92 @@
+import CarPlay
+import NitroModules
+
+extension CarPlaySession {
+  /// Loads a content template's page when it first appears, the moment CarPlay applies updates
+  /// (an update made straight after a push is dropped).
+  func loadContentIfNeeded(for template: CPListTemplate) {
+    guard let path = template.contentPath, template.sections.isEmpty else { return }
+    spawn { await $0.loadContent(for: path, into: template) }
+  }
+
+  /// Resolves `path` into a loading template, showing a centered message when the page is
+  /// empty, fails, or outlasts `resolveTimeout`.
+  func loadContent(for path: String, into template: CPListTemplate) async {
+    let templateId = ObjectIdentifier(template)
+    guard !loadingTemplates.contains(templateId) else { return }
+    loadingTemplates.insert(templateId)
+    defer { loadingTemplates.remove(templateId) }
+
+    let timeout = resolveTimeout
+    let watchdog = Task { @MainActor [weak self] in
+      do { try await Task.sleep(for: timeout) } catch { return }
+      guard let self, template.sections.isEmpty else { return }
+      logger.error("loadContent: resolve timed out for \(path)")
+      await showNavigationError(
+        NavigationError(code: .timeout, message: "", statusCode: nil, statusCodeSuccess: nil), path: path, on: template,
+      )
+    }
+    // Cancelled as soon as the resolve settles: formatting its error is a JS round trip the
+    // timeout must not overwrite.
+    defer { watchdog.cancel() }
+
+    do {
+      let resolved: ResolvedTrack
+      do {
+        resolved = try await audioBrowser.browserManager.resolve(path, useCache: true)
+      } catch {
+        watchdog.cancel()
+        throw error
+      }
+      watchdog.cancel()
+      guard !Task.isCancelled else { return }
+      // An assistant cell is content in itself, even with no rows; a page of empty sections is
+      // empty (ADR 0001).
+      let hasChildren = resolved.normalizedSections?.contains { !$0.children.isEmpty } ?? false
+      if hasChildren || resolved.carPlaySiriListButton != nil {
+        updateTemplate(template, with: resolved)
+      } else {
+        await showNavigationError(.code(.emptyContent), path: path, on: template)
+      }
+    } catch {
+      logger.error("Failed to load content for \(path): \(error.localizedDescription)")
+      await showNavigationError(NavigationError.from(error), path: path, on: template)
+    }
+  }
+
+  func updateTemplate(_ template: CPListTemplate, with resolvedTrack: ResolvedTrack) {
+    template.updateSections(listItemFactory.createSections(from: resolvedTrack))
+    template.assistantCellConfiguration = resolvedTrack.carPlaySiriListButton.map { position in
+      CPAssistantCellConfiguration(
+        position: position == .top ? .top : .bottom, visibility: .always, assistantAction: .playMedia,
+      )
+    }
+  }
+
+  /// Shows a navigation error, as the app's `formatNavigationError` formats it, as the
+  /// template's centered message (ADR 0001).
+  private func showNavigationError(_ error: NavigationError, path: String, on template: CPListTemplate) async {
+    let formatted = await audioBrowser.browserManager.formatted(error, path: path)
+    guard !Task.isCancelled else { return }
+    let title = formatted.title.isEmpty ? "Couldn't load" : formatted.title
+    if isTabRoot(template) {
+      // A tab root cannot be popped, so its message is set in place; it renders when the tab
+      // is selected.
+      if #available(iOS 18.4, *) {
+        template.showsSpinnerWhileEmpty = false
+      }
+      template.setMessage(title, subtitle: formatted.message)
+      template.updateSections([])
+    } else {
+      // A pushed template's empty view renders reliably only as its initial state, so it is
+      // replaced. The message has no path: backing out and re-tapping retries.
+      interfaceController.safeReplaceTop(
+        template, with: CPListTemplate.message(title, subtitle: formatted.message, listTitle: template.title), animated: false,
+      )
+    }
+  }
+
+  private func isTabRoot(_ template: CPTemplate) -> Bool {
+    (interfaceController.rootTemplate as? CPTabBarTemplate)?.templates.contains { $0 === template } ?? false
+  }
+}