react-native-audio-browser 0.2.0-next.11 → 0.2.0-next.13

package/ios/CarPlay/CarPlayController.swift

@@ -26,9 +26,22 @@ public final class RNABCarPlayController: NSObject {
   private var trackSelector: TrackSelector?
 
   /// Track content subscriptions
-  private var isStarted = false
   private var listenerRemovals: [() -> Void] = []
 
+  /// Identifies the current `start()` run; nil while stopped.
+  ///
+  /// A run needs an identity, not just a flag, because `start()` parks an
+  /// untracked Task on the uncancellable `playerAndConfiguredBrowser.wait()`,
+  /// which stays queued across a `reset()` and resumes every waiter. `restart()`
+  /// is `stop(); start()`, so a boolean is `true` again by the time the old
+  /// waiter resumes and both runs proceed — duplicate subscriptions and a leaked
+  /// `NowPlayingObserver` for the session. Comparing the captured run against
+  /// this answers "still running?" and "still me?" in one condition.
+  private var currentRun: UInt?
+  private var runCounter: UInt = 0
+
+  private var isStarted: Bool { currentRun != nil }
+
   /// Paths whose loading template has been pushed but not yet appeared. Guards a
   /// rapid double-tap from pushing the same destination twice (the first push is
   /// async, so `topTemplate` may not reflect it yet). Cleared when it appears.
@@ -89,21 +102,37 @@ public final class RNABCarPlayController: NSObject {
     audioBrowser?.browserManager.config ?? BrowserConfig()
   }
 
+  /// The configured list playing-indicator location, in CarPlay-framework terms.
+  private var playingIndicatorLocation: CPListItemPlayingIndicatorLocation {
+    switch audioBrowser?.carPlayPlayingIndicatorLocation {
+    case .trailing: .trailing
+    case .leading, nil: .leading
+    }
+  }
+
+  /// The tabs the tab bar actually shows. A disabled tab hides rather than
+  /// greys: `CPTabBarTemplate` has no disabled affordance, so per `Track`'s
+  /// rendering ladder an unavailable tab must not render as a normal-looking
+  /// control (matches Android Auto, which filters before its 4-tab cap).
+  ///
+  /// Named once because every site that reasons about the tab bar must agree on
+  /// it — `showTabBar` builds from this list, and `handleTabsChanged` compares
+  /// against it. Those two disagreeing is exactly what made the in-place
+  /// restamp dead code whenever any tab was disabled.
+  private static func visibleTabs(_ tabs: [Track]) -> [Track] {
+    tabs.filter { $0.disabled != true }
+  }
+
   /// Whether a list item identifies the currently active (loaded) track.
   ///
-  /// Identity is the stable `Track.id` when both sides carry one — the active
+  /// Compares track identities (`id` when non-blank, else `src`): the active
   /// track may have been loaded outside the browse tree (the consumer's own
   /// `load`/`setQueue`) with a `src` that differs textually from the browse
   /// row's (absolute vs relative, extra query params) while being the same
-  /// item. Exact `src` equality remains the fallback for consumers that don't
-  /// assign ids.
-  private func isActiveTrack(id: String?, src: String?) -> Bool {
-    guard let currentTrack = audioBrowser?.getPlayer()?.currentTrack else { return false }
-    if let id, !id.isEmpty, let currentId = currentTrack.id, !currentId.isEmpty {
-      return id == currentId
-    }
-    guard let src else { return false }
-    return currentTrack.src == src
+  /// item. A nil identity on either side never matches.
+  private func isActiveTrack(identity: String?) -> Bool {
+    guard let identity, let currentTrack = audioBrowser?.getPlayer()?.currentTrack else { return false }
+    return currentTrack.identity == identity
   }
 
   // MARK: - Initialization
@@ -118,8 +147,8 @@ public final class RNABCarPlayController: NSObject {
       self?.listItemFactory?.createListItem(for: track, handler: handler)
         ?? CPListItem(text: track.title, detailText: nil)
     }
-    nowPlayingManager.navigateToUrl = { [weak self] url, title in
-      Task { @MainActor in await self?.navigateToUrl(url, title: title) }
+    nowPlayingManager.navigateToPath = { [weak self] path, title in
+      Task { @MainActor in await self?.navigateToPath(path, title: title) }
     }
   }
 
@@ -137,7 +166,9 @@ public final class RNABCarPlayController: NSObject {
   @objc
   public func start() {
     guard !isStarted else { return }
-    isStarted = true
+    runCounter &+= 1
+    currentRun = runCounter
+    let run = runCounter
 
     logger.info("Starting CarPlay controller")
 
@@ -164,7 +195,8 @@ public final class RNABCarPlayController: NSObject {
     // Wait for both browser and player to be ready
     Task { @MainActor in
       let (browser, _) = await playerAndConfiguredBrowser.wait()
-      guard self.isStarted else { return }
+      // Answers "still running?" and "still this run?" at once.
+      guard self.currentRun == run else { return }
       self.logger.debug("AudioBrowser and player ready, setting up CarPlay")
       self.audioBrowser = browser
       self.isGated = browser.isGateActive
@@ -178,12 +210,13 @@ public final class RNABCarPlayController: NSObject {
 
       // Create list item factory
       let factory = CarPlayListItemFactory(
-        isActiveTrack: { [weak self] id, src in self?.isActiveTrack(id: id, src: src) ?? false },
+        isActiveTrack: { [weak self] identity in self?.isActiveTrack(identity: identity) ?? false },
         onItemSelected: { [weak self] track, completion in
           self?.handleItemSelection(track: track, completion: completion)
         },
       )
       factory.imageLoader = self.imageLoader
+      factory.playingIndicatorLocation = self.playingIndicatorLocation
       self.listItemFactory = factory
 
       self.setupContentSubscriptions()
@@ -198,7 +231,7 @@ public final class RNABCarPlayController: NSObject {
   @objc
   public func stop() {
     guard isStarted else { return }
-    isStarted = false
+    currentRun = nil
 
     logger.info("Stopping CarPlay controller")
 
@@ -261,7 +294,7 @@ public final class RNABCarPlayController: NSObject {
     }
 
     // Subscribe to config changes (for Now Playing buttons and per-track
-    // button state — e.g. resolveAlbumUrl appearing/disappearing)
+    // button state — e.g. resolveAlbumPath appearing/disappearing)
     audioBrowser.browserManager.onConfigChanged = { [weak self] _ in
       Task { @MainActor in
         self?.nowPlayingManager.setupNowPlayingButtons()
@@ -269,13 +302,22 @@ public final class RNABCarPlayController: NSObject {
       }
     }
 
-    // Now-playing buttons + Up Next are runtime-updatable via updateOptions();
-    // refresh them when player options change (configureBrowser is no longer
-    // the only path that can change them).
+    // Now-playing buttons + Up Next + the list playing-indicator location are
+    // runtime-updatable via updateOptions(); refresh them when player options
+    // change (configureBrowser is no longer the only path that can change them).
     let optionsToken = audioBrowser.playerOptionsChangedEmitter.addListener { [weak self] in
       Task { @MainActor in
-        self?.nowPlayingManager.setupNowPlayingButtons()
-        self?.nowPlayingManager.updateNowPlayingButtonStates()
+        guard let self else { return }
+        self.nowPlayingManager.setupNowPlayingButtons()
+        self.nowPlayingManager.updateNowPlayingButtonStates()
+        // The factory's copy doubles as the last-applied value: sweep the
+        // templates only when the location actually changed, not on every
+        // updateOptions() call.
+        let location = self.playingIndicatorLocation
+        if let factory = self.listItemFactory, factory.playingIndicatorLocation != location {
+          factory.playingIndicatorLocation = location
+          self.updatePlayingIndicators()
+        }
       }
     }
     listenerRemovals.append { [weak audioBrowser] in
@@ -409,9 +451,7 @@ public final class RNABCarPlayController: NSObject {
   private func buildInitialInterface() async {
     guard let audioBrowser else {
       logger.error("AudioBrowser not available")
-      await showRootNavigationError(
-        NavigationError(code: .unknownError, message: "", statusCode: nil, statusCodeSuccess: nil),
-      )
+      await showRootNavigationError(.code(.unknownError))
       return
     }
 
@@ -430,16 +470,10 @@ public final class RNABCarPlayController: NSObject {
         showLoadingTemplate()
       }
       do {
+        // An empty query result routes to the .emptyContent error page inside
+        // showTabBar, shared with runtime tab changes.
         let queriedTabs = try await audioBrowser.browserManager.queryTabs()
-        if !queriedTabs.isEmpty {
-          await showTabBar(tabs: queriedTabs)
-        } else {
-          // Empty is a navigation error (.emptyContent) so it formats through
-          // the app's formatNavigationError like every other failure (ADR 0001).
-          await showRootNavigationError(
-            NavigationError(code: .emptyContent, message: "", statusCode: nil, statusCodeSuccess: nil),
-          )
-        }
+        await showTabBar(tabs: queriedTabs)
       } catch {
         logger.error("Failed to query tabs: \(error.localizedDescription)")
         await showRootNavigationError(NavigationError.from(error))
@@ -459,7 +493,9 @@ public final class RNABCarPlayController: NSObject {
   // MARK: - Tab Bar
 
   @MainActor
-  private func showTabBar(tabs: [Track]) async {
+  private func showTabBar(tabs allTabs: [Track]) async {
+    let tabs = Self.visibleTabs(allTabs)
+
     // Serialize concurrent tab-bar builds across BOTH the gated and non-gated
     // paths with one shared generation token: bump at entry, capture, and bail
     // before any template mutation once a newer build supersedes us. Both paths
@@ -477,11 +513,27 @@ public final class RNABCarPlayController: NSObject {
     // the gate page with that request's chrome; an allowed tab shows real
     // content. This generalizes the old "all tabs show the gate" — a path the
     // resolver allows now shows real content.
+    //
+    // Ahead of the empty guard below, because a gated build from zero tabs is
+    // NOT blank: it paints a full-screen gate page as root (a gate raised
+    // before config loads is exactly that case). `showGatedTabBar` owns the
+    // empty-tabs decision and falls back to the same .emptyContent page when
+    // the resolver allows the root.
     if isGated {
       await showGatedTabBar(tabs: tabs, generation: generation)
       return
     }
 
+    // A zero-tab CPTabBarTemplate renders blank, with no copy, so empty routes
+    // to the .emptyContent error page like every other failure (formatted
+    // through the app's formatNavigationError, ADR 0001). The guard lives at
+    // this choke point — both the initial build and runtime tab changes pass
+    // through here.
+    guard !tabs.isEmpty else {
+      await showRootNavigationError(.code(.emptyContent))
+      return
+    }
+
     logger.info("Building tab bar with \(tabs.count) tabs")
 
     let maxTabs = CPTabBarTemplate.maximumTabCount
@@ -501,8 +553,8 @@ public final class RNABCarPlayController: NSObject {
     interfaceController.safeSetRoot(tabBar, animated: true)
 
     // Load content for the first tab only - others load lazily when selected
-    if let firstTemplate = tabTemplates.first, let firstTab = tabs.first, let url = firstTab.url {
-      await loadContent(for: url, into: firstTemplate)
+    if let firstTemplate = tabTemplates.first, let firstTab = tabs.first, let path = firstTab.path {
+      await loadContent(for: path, into: firstTemplate)
     }
   }
 
@@ -521,8 +573,7 @@ public final class RNABCarPlayController: NSObject {
 
     guard !tabs.isEmpty else {
       // Tabs unknown (config not loaded yet, or none) — resolve the root path
-      // and show a single gate page (or, if allowed, fall back to a normal
-      // build once tabs arrive).
+      // and show a single gate page.
       let outcome = await audioBrowser.gateDecision(
         for: NativeGateRequest(reason: .browse, path: nil, search: nil),
       )
@@ -532,6 +583,11 @@ public final class RNABCarPlayController: NSObject {
         interfaceController.safeSetRoot(
           makeGateTemplate(gate: outcome.chrome, tab: nil), animated: true,
         )
+      } else {
+        // The resolver allows the root, and there are no tabs to show — the
+        // same nothing-to-render case the ungated build routes to .emptyContent.
+        // Without this the loading spinner would stay as root forever.
+        await showRootNavigationError(.code(.emptyContent))
       }
       return
     }
@@ -540,7 +596,7 @@ public final class RNABCarPlayController: NSObject {
     var templates: [CPListTemplate] = []
     for tab in limitedTabs {
       let outcome = await audioBrowser.gateDecision(
-        for: NativeGateRequest(reason: .browse, path: tab.url, search: nil),
+        for: NativeGateRequest(reason: .browse, path: tab.path, search: nil),
       )
       guard gateBuildGeneration == generation else { return } // superseded by a newer build
       if outcome.gated {
@@ -566,8 +622,8 @@ public final class RNABCarPlayController: NSObject {
     // Eagerly fill any allowed (content) tabs: templateDidAppear isn't
     // guaranteed to re-fire for templates swapped in via updateTemplates.
     for (tab, template) in zip(limitedTabs, templates) {
-      guard getPath(from: template) != nil, let url = tab.url else { continue }
-      await loadContent(for: url, into: template)
+      guard getPath(from: template) != nil, let path = tab.path else { continue }
+      await loadContent(for: path, into: template)
     }
   }
 
@@ -576,7 +632,7 @@ public final class RNABCarPlayController: NSObject {
   /// until its content lazy-loads on first appearance.
   private func createTabTemplate(for track: Track) -> CPListTemplate {
     // The path stored on the template drives lazy loading and refresh.
-    let template = makeLoadingTemplate(title: track.title, path: track.url)
+    let template = makeLoadingTemplate(title: track.title, path: track.path)
     applyTabBarEntry(to: template, for: track)
     return template
   }
@@ -682,14 +738,13 @@ public final class RNABCarPlayController: NSObject {
       // even with no rows — the "Ask Siri to Play" cell IS its content — so it
       // renders rather than falling through to the empty-content state.
       let hasAssistantCell = resolved.carPlaySiriListButton != nil
-      if resolved.children?.isEmpty ?? true, !hasAssistantCell {
+      // A page of empty sections is still empty.
+      let hasChildren = resolved.normalizedSections?.contains { !$0.children.isEmpty } ?? false
+      if !hasChildren, !hasAssistantCell {
         // Empty is modeled as a navigation error (code .emptyContent) so it goes
         // through the same path-aware formatter as failures — letting an app give
         // an empty Favorites tab different copy than an empty search. ADR 0001.
-        let empty = NavigationError(
-          code: .emptyContent, message: "", statusCode: nil, statusCodeSuccess: nil,
-        )
-        await showNavigationErrorView(empty, path: path, on: template)
+        await showNavigationErrorView(.code(.emptyContent), path: path, on: template)
       } else {
         updateTemplate(template, with: resolved)
       }
@@ -749,7 +804,7 @@ public final class RNABCarPlayController: NSObject {
     }
 
     // If this track is already loaded, resume playback and show Now Playing.
-    if track.src != nil, isActiveTrack(id: track.id, src: track.src) {
+    if track.src != nil, isActiveTrack(identity: track.identity) {
       try? audioBrowser.play()
       nowPlayingManager.showNowPlaying()
       completion()
@@ -777,7 +832,7 @@ public final class RNABCarPlayController: NSObject {
 
     // Release CarPlay immediately so the list never locks up. Apple's handler
     // guidance is to finish processing the tap promptly; for a browse we "finish"
-    // by pushing the destination and filling it in (see navigateToUrl), and for
+    // by pushing the destination and filling it in (see navigateToPath), and for
     // playback the Now Playing surface owns its own loading state.
     completion()
 
@@ -790,8 +845,8 @@ public final class RNABCarPlayController: NSObject {
         self.nowPlayingManager.showNowPlaying(popToFront: false)
       case .intercepted:
         self.nowPlayingManager.showNowPlaying(popToFront: false)
-      case let .browse(url):
-        await self.navigateToUrl(url, title: track.title)
+      case let .browse(path):
+        await self.navigateToPath(path, title: track.title)
       case .none:
         break
       }
@@ -809,53 +864,93 @@ public final class RNABCarPlayController: NSObject {
     }
   }
 
-  /// Pushes a browsable URL's destination immediately as an empty, spinning list
+  /// Pushes a browsable path's destination immediately as an empty, spinning list
   /// template — so the list the user tapped from is never blocked. The content is
   /// filled by `templateDidAppear` → `loadContentIfNeeded` → `loadContent`, which
   /// runs once the template is on screen (the timing CarPlay needs: updates made
   /// right after a push are dropped). Backing out and re-tapping retries.
+  ///
+  /// One exception to pushing: a path that IS a tab selects that tab (see
+  /// `selectTab`).
   @MainActor
-  private func navigateToUrl(_ url: String, title: String) async {
+  private func navigateToPath(_ path: String, title: String) async {
     // The gate is resolved per-request: a gated path pushes the gate page
     // (with this request's chrome) instead of browsing into content; this also
     // blocks indirect entries like the Now Playing album line. An allowed path
     // browses normally even while a gate is active.
     if isGated, let audioBrowser {
       let outcome = await audioBrowser.gateDecision(
-        for: NativeGateRequest(reason: .browse, path: url, search: nil),
+        for: NativeGateRequest(reason: .browse, path: path, search: nil),
       )
       if outcome.gated {
         audioBrowser.onGate(GateEvent(reason: .browse))
-        if let top = interfaceController.topTemplate, getPath(from: top) == url { return }
+        if let top = interfaceController.topTemplate, getPath(from: top) == path { return }
         interfaceController.safePush(
           makeGateTemplate(gate: outcome.chrome, tab: nil), animated: true,
         )
         return
       }
     }
+    // A link to a tab's own path switches to that tab instead of pushing a
+    // second copy of it into the current tab's stack.
+    if selectTab(owning: path) { return }
     // Avoid pushing a duplicate if the top template already shows this path.
-    if let top = interfaceController.topTemplate, getPath(from: top) == url {
+    if let top = interfaceController.topTemplate, getPath(from: top) == path {
       return
     }
     // …and guard a rapid double-tap whose first push hasn't appeared yet (so the
     // check above can't see it). Cleared when the pushed template appears.
-    guard !navigatingPaths.contains(url) else { return }
-    navigatingPaths.insert(url)
+    guard !navigatingPaths.contains(path) else { return }
+    navigatingPaths.insert(path)
 
-    let template = makeLoadingTemplate(title: title, path: url)
+    let template = makeLoadingTemplate(title: title, path: path)
     interfaceController.safePush(template, animated: true) { [weak self] pushed, error in
       guard !pushed else { return }
       // The push can fail (e.g. CarPlay's template stack depth limit). The
       // appear callback that normally clears the guard will never fire, so
       // clear it here — otherwise the destination stays unreachable until
       // CarPlay reconnects.
-      self?.navigatingPaths.remove(url)
+      self?.navigatingPaths.remove(path)
       if let error {
-        self?.logger.error("pushTemplate failed for \(url): \(error.localizedDescription)")
+        self?.logger.error("pushTemplate failed for \(path): \(error.localizedDescription)")
       }
     }
   }
 
+  /// Switches to the tab that owns `path`, if any — a "view all" header or row
+  /// pointing at a tab's own path belongs in the tab bar, not pushed on top of
+  /// whichever tab the user tapped from (which would strand them one level deep
+  /// in a list the bar already offers, with a Back button to a page they never
+  /// came from). Any pushed stack is popped first, so the tab opens at its root.
+  ///
+  /// Returns false — and the caller pushes as usual — when `path` is no tab,
+  /// when the root isn't the tab bar (the gate replaces it), or before iOS 17,
+  /// which has no tab-selection API.
+  @MainActor
+  private func selectTab(owning path: String) -> Bool {
+    guard #available(iOS 17.0, *),
+          let tabBar = interfaceController.rootTemplate as? CPTabBarTemplate,
+          let tab = tabBar.templates.first(where: { getPath(from: $0) == path })
+    else { return false }
+    let isPushed = interfaceController.templates.count > 1
+    // Already showing: the destination is where the user asked to be, so this
+    // is handled — just don't animate a pop-and-select over it.
+    if tabBar.selectedTemplate === tab, !isPushed { return true }
+    logger.debug("Navigating to tab \(path) instead of pushing it")
+    guard isPushed else {
+      tabBar.select(tab)
+      return true
+    }
+    interfaceController.safePopToRoot(animated: true) { popped, _ in
+      // Selecting after a failed pop would leave the pushed stack over the
+      // newly selected tab; the caller has already returned, so a failure just
+      // leaves the user where they were.
+      guard popped else { return }
+      tabBar.select(tab)
+    }
+    return true
+  }
+
   /// Builds an empty list template for content that is still resolving.
   /// On iOS 18.4+ it shows the system spinner (`showsSpinnerWhileEmpty`). On older
   /// iOS it shows the app-localized `carPlayLoadingTitle` as the centered empty
@@ -930,16 +1025,18 @@ public final class RNABCarPlayController: NSObject {
   @MainActor
   private func handleTabsChanged(_ tabs: [Track]) {
     logger.debug("Tabs changed: \(tabs.count) tabs")
-    // Same tabs by URL while ungated → only the tab-bar entries changed
+    // Compare against the list showTabBar builds templates from, not the raw one.
+    let visibleTabs = Self.visibleTabs(tabs)
+    // Same tabs by path while ungated → only the tab-bar entries changed
     // (e.g. titles after a locale switch): restamp them in place. No rebuild,
     // so the selected tab and any pushed navigation stack survive. (Gate
     // templates carry no path, so a gated tab bar never matches here.)
     if !isGated,
        let tabBar = interfaceController.rootTemplate as? CPTabBarTemplate,
-       tabBar.templates.count == min(tabs.count, CPTabBarTemplate.maximumTabCount),
-       zip(tabBar.templates, tabs).allSatisfy({ getPath(from: $0) == $1.url })
+       tabBar.templates.count == min(visibleTabs.count, CPTabBarTemplate.maximumTabCount),
+       zip(tabBar.templates, visibleTabs).allSatisfy({ getPath(from: $0) == $1.path })
     {
-      for (template, tab) in zip(tabBar.templates, tabs) {
+      for (template, tab) in zip(tabBar.templates, visibleTabs) {
         applyTabBarEntry(to: template, for: tab)
       }
       pendingTabs = nil
@@ -978,7 +1075,7 @@ public final class RNABCarPlayController: NSObject {
     // This callback fires when the main browser's content changes.
     // For CarPlay-specific refreshes (e.g., favorites), use notifyContentChanged instead.
     guard let content else { return }
-    refreshTemplatesForPath(content.url, with: content)
+    refreshTemplatesForPath(content.path, with: content)
   }
 
   @MainActor
@@ -990,9 +1087,11 @@ public final class RNABCarPlayController: NSObject {
     nowPlayingManager.handleActiveTrackChanged()
   }
 
-  /// Updates the isPlaying state on all list items based on the current active track.
+  /// Updates the isPlaying state (and indicator location, which options can
+  /// change at runtime) on all list items based on the current active track.
   @MainActor
   fileprivate func updatePlayingIndicators() {
+    let location = playingIndicatorLocation
     var templates: [CPListTemplate] = []
 
     if let tabBar = interfaceController.rootTemplate as? CPTabBarTemplate {
@@ -1015,16 +1114,20 @@ public final class RNABCarPlayController: NSObject {
         for item in section.items {
           guard let listItem = item as? CPListItem,
                 let info = listItem.carPlayItemInfo,
-                info.src != nil
+                info.identity != nil
           else { continue }
 
-          let isPlaying = isActiveTrack(id: info.id, src: info.src)
+          let isPlaying = isActiveTrack(identity: info.identity)
           if listItem.isPlaying != isPlaying {
             logger.debug(
-              "Updating isPlaying for \(info.id ?? info.src ?? ""): \(listItem.isPlaying) → \(isPlaying)")
+              "Updating isPlaying for \(info.identity ?? ""): \(listItem.isPlaying) → \(isPlaying)")
             listItem.isPlaying = isPlaying
             templateChanged = true
           }
+          if listItem.playingIndicatorLocation != location {
+            listItem.playingIndicatorLocation = location
+            templateChanged = true
+          }
         }
       }
       // Setting isPlaying on an already-displayed item does not reliably reach
@@ -1215,15 +1318,29 @@ public final class RNABCarPlayController: NSObject {
       logger.debug("Calling formatNavigationError callback...")
       // Call the JS callback and handle result
       let params = FormatNavigationErrorParams(error: error, defaultFormatted: defaultFormatted, path: path)
+      // The result callbacks are @Sendable and hop back explicitly: Nitro resolves
+      // its promises synchronously on the JS thread, so a plain closure would
+      // inherit this type's MainActor isolation and trap on entry under Swift 6's
+      // dynamic isolation check — and would otherwise drive UIKit off the main
+      // thread. Same pattern as HybridAudioBrowser.handleNavigationError and
+      // NowPlayingUpdater.render.
       formatter(params)
-        .then { [weak self] customDisplay in
-          self?.logger.debug("formatNavigationError returned: \(String(describing: customDisplay))")
-          self?.presentErrorActionSheet(customDisplay: customDisplay ?? defaultFormatted)
+        .then { @Sendable [weak self] customDisplay in
+          let description = String(describing: customDisplay)
+          Task { @MainActor in
+            guard let self else { return }
+            self.logger.debug("formatNavigationError returned: \(description)")
+            self.presentErrorActionSheet(customDisplay: customDisplay ?? defaultFormatted)
+          }
         }
-        .catch { [weak self] callbackError in
-          self?.logger.error("formatNavigationError failed: \(callbackError)")
-          // On error, fall back to defaults
-          self?.presentErrorActionSheet(customDisplay: defaultFormatted)
+        .catch { @Sendable [weak self] callbackError in
+          let message = callbackError.localizedDescription
+          Task { @MainActor in
+            guard let self else { return }
+            self.logger.error("formatNavigationError failed: \(message)")
+            // On error, fall back to defaults
+            self.presentErrorActionSheet(customDisplay: defaultFormatted)
+          }
         }
     } else {
       presentErrorActionSheet(customDisplay: defaultFormatted)
@@ -1264,9 +1381,22 @@ public final class RNABCarPlayController: NSObject {
   /// view formatted via the app's `formatNavigationError` (path "/"), like every
   /// other browse failure. The empty view renders reliably here because it's the
   /// template's initial state at set-root time.
+  ///
+  /// Formatting awaits the app's `formatNavigationError` callback, so a tab-bar
+  /// build can start and paint during the hop — this error root must not
+  /// clobber it. Captured here rather than passed in: the `showTabBar` /
+  /// `showGatedTabBar` callers hold the newest generation when they call, so
+  /// capturing is equivalent for them and covers the others for free.
+  ///
+  /// Not airtight for `buildInitialInterface`'s two callers: that function
+  /// doesn't participate in `gateBuildGeneration` and suspends at `queryTabs()`,
+  /// so a build that superseded it *before* this was entered isn't caught.
+  /// Closing that needs a generation captured at `buildInitialInterface` entry.
   @MainActor
   private func showRootNavigationError(_ navError: NavigationError) async {
+    let generation = gateBuildGeneration
     let formatted = await formattedNavigationError(navError, path: "/")
+    guard gateBuildGeneration == generation else { return }
     let template = CPListTemplate(title: nil, sections: [])
     template.emptyViewTitleVariants = [formatted.title]
     template.emptyViewSubtitleVariants = formatted.message.flatMap { $0.isEmpty ? nil : [$0] } ?? []
@@ -1336,20 +1466,32 @@ private extension RNABCarPlayController {
   }
 }
 
+// MARK: - NavigationError Shorthand
+
+extension NavigationError {
+  /// A code-only error: the user-facing copy comes from the app's
+  /// formatNavigationError (ADR 0001), so no message travels with it.
+  static func code(_ code: NavigationErrorType) -> NavigationError {
+    NavigationError(code: code, message: "", statusCode: nil, statusCodeSuccess: nil)
+  }
+}
+
 // MARK: - UIImage Resize
 
 extension UIImage {
-  /// Draws the image centered within the target size, maintaining aspect ratio
-  func resized(to targetSize: CGSize) -> UIImage? {
-    UIGraphicsBeginImageContextWithOptions(targetSize, false, 0.0)
+  /// Draws the image centered within the target size, maintaining aspect
+  /// ratio, at the given display scale (the car screen's, not the phone's).
+  func resized(to targetSize: CGSize, scale: CGFloat) -> UIImage? {
+    UIGraphicsBeginImageContextWithOptions(targetSize, false, scale)
     defer { UIGraphicsEndImageContext() }
 
-    // Scale to fit while maintaining aspect ratio
+    // Scale to fit while maintaining aspect ratio. Named `fitScale` so it does
+    // not shadow the `scale` parameter (the display scale) it sits next to.
     let widthRatio = targetSize.width / size.width
     let heightRatio = targetSize.height / size.height
-    let scale = min(widthRatio, heightRatio)
+    let fitScale = min(widthRatio, heightRatio)
 
-    let scaledSize = CGSize(width: size.width * scale, height: size.height * scale)
+    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,