react-native-audio-browser 0.2.0-next.12 → 0.2.0-next.14

package/ios/Browser/JsonModels.swift

@@ -77,30 +77,50 @@ extension JsonArtwork {
 struct JsonStyle: Codable, Equatable {
   let display: String?
   let gridWrap: Bool?
+  let gridTile: String?
   let artworkRendering: String?
+  let imageShape: String?
+  let accessorySymbol: String?
+  let cardTint: String?
+  let cardImage: String?
 
   init(
     display: String? = nil,
     gridWrap: Bool? = nil,
+    gridTile: String? = nil,
     artworkRendering: String? = nil,
+    imageShape: String? = nil,
+    accessorySymbol: String? = nil,
+    cardTint: String? = nil,
+    cardImage: String? = nil,
   ) {
     self.display = display
     self.gridWrap = gridWrap
+    self.gridTile = gridTile
     self.artworkRendering = artworkRendering
+    self.imageShape = imageShape
+    self.accessorySymbol = accessorySymbol
+    self.cardTint = cardTint
+    self.cardImage = cardImage
   }
 
   init(from decoder: Decoder) throws {
     // A non-object value (the retired `style: 'grid'` string) decodes as an
     // empty block rather than failing the parent.
     guard let container = try? decoder.container(keyedBy: CodingKeys.self) else {
-      display = nil
-      gridWrap = nil
-      artworkRendering = nil
+      self.init()
       return
     }
-    display = (try? container.decodeIfPresent(String.self, forKey: .display)) ?? nil
-    gridWrap = (try? container.decodeIfPresent(Bool.self, forKey: .gridWrap)) ?? nil
-    artworkRendering = (try? container.decodeIfPresent(String.self, forKey: .artworkRendering)) ?? nil
+    self.init(
+      display: (try? container.decodeIfPresent(String.self, forKey: .display)) ?? nil,
+      gridWrap: (try? container.decodeIfPresent(Bool.self, forKey: .gridWrap)) ?? nil,
+      gridTile: (try? container.decodeIfPresent(String.self, forKey: .gridTile)) ?? nil,
+      artworkRendering: (try? container.decodeIfPresent(String.self, forKey: .artworkRendering)) ?? nil,
+      imageShape: (try? container.decodeIfPresent(String.self, forKey: .imageShape)) ?? nil,
+      accessorySymbol: (try? container.decodeIfPresent(String.self, forKey: .accessorySymbol)) ?? nil,
+      cardTint: (try? container.decodeIfPresent(String.self, forKey: .cardTint)) ?? nil,
+      cardImage: (try? container.decodeIfPresent(String.self, forKey: .cardImage)) ?? nil,
+    )
   }
 }
 
@@ -114,20 +134,47 @@ extension JsonStyle {
   func toTrackStyle() -> TrackStyle? {
     let display = display.flatMap { StyleDisplay(fromString: $0.lowercased()) }
     let artworkRendering = artworkRendering.flatMap { ArtworkRendering(fromString: $0.lowercased()) }
-    guard display != nil || artworkRendering != nil else { return nil }
-    return TrackStyle(display: display, artworkRendering: artworkRendering)
+    let imageShape = imageShape.flatMap { ImageShape(fromString: $0.lowercased()) }
+    // The 'none' sentinel is a legitimate value; only emptiness collapses.
+    let accessorySymbol = accessorySymbol?.isEmpty == false ? accessorySymbol : nil
+    let cardTint = cardTint?.isEmpty == false ? cardTint : nil
+    let cardImage = cardImage.flatMap { CardImage(fromString: $0.lowercased()) }
+    guard display != nil || artworkRendering != nil || imageShape != nil
+      || accessorySymbol != nil || cardTint != nil || cardImage != nil
+    else { return nil }
+    return TrackStyle(
+      display: display,
+      artworkRendering: artworkRendering,
+      imageShape: imageShape,
+      accessorySymbol: accessorySymbol,
+      cardTint: cardTint,
+      cardImage: cardImage,
+    )
   }
 
   func toSectionStyle() -> SectionStyle? {
     let display = display.flatMap { StyleDisplay(fromString: $0.lowercased()) }
+    let gridTile = gridTile.flatMap { GridTile(fromString: $0.lowercased()) }
     let artworkRendering = artworkRendering.flatMap { ArtworkRendering(fromString: $0.lowercased()) }
-    guard display != nil || artworkRendering != nil || gridWrap != nil else { return nil }
+    let imageShape = imageShape.flatMap { ImageShape(fromString: $0.lowercased()) }
+    let accessorySymbol = accessorySymbol?.isEmpty == false ? accessorySymbol : nil
+    let cardTint = cardTint?.isEmpty == false ? cardTint : nil
+    let cardImage = cardImage.flatMap { CardImage(fromString: $0.lowercased()) }
+    guard display != nil || artworkRendering != nil || gridWrap != nil
+      || gridTile != nil || imageShape != nil || accessorySymbol != nil
+      || cardTint != nil || cardImage != nil
+    else { return nil }
     // Argument order is the generated init's (own properties before
     // inherited ones — Nitro flattens `extends` own-props-first).
     return SectionStyle(
       gridWrap: gridWrap,
+      gridTile: gridTile,
       display: display,
       artworkRendering: artworkRendering,
+      imageShape: imageShape,
+      accessorySymbol: accessorySymbol,
+      cardTint: cardTint,
+      cardImage: cardImage,
     )
   }
 
@@ -135,10 +182,18 @@ extension JsonStyle {
   /// An all-nil block snapshots as no block — the decoders collapse it to
   /// "no declaration" anyway, so never persist the distinction.
   init?(_ style: TrackStyle?) {
-    guard let style, style.display != nil || style.artworkRendering != nil else { return nil }
+    guard let style,
+          style.display != nil || style.artworkRendering != nil
+          || style.imageShape != nil || style.accessorySymbol != nil
+          || style.cardTint != nil || style.cardImage != nil
+    else { return nil }
     self.init(
       display: Self.string(style.display),
       artworkRendering: Self.string(style.artworkRendering),
+      imageShape: Self.string(style.imageShape),
+      accessorySymbol: style.accessorySymbol,
+      cardTint: style.cardTint,
+      cardImage: Self.string(style.cardImage),
     )
   }
 
@@ -157,6 +212,22 @@ extension JsonStyle {
     case nil: nil
     }
   }
+
+  private static func string(_ shape: ImageShape?) -> String? {
+    switch shape {
+    case .circular: "circular"
+    case .roundedRectangle: "rounded-rectangle"
+    case nil: nil
+    }
+  }
+
+  private static func string(_ mode: CardImage?) -> String? {
+    switch mode {
+    case .normal: "normal"
+    case .background: "background"
+    case nil: nil
+    }
+  }
 }
 
 /// JSON model for a page section (ADR 0010). Legacy `groupTitle`/`imageRow`
@@ -164,20 +235,17 @@ extension JsonStyle {
 /// ignored dead weight.
 struct JsonSection: Codable {
   let title: String?
-  let subtitle: String?
   let style: JsonStyle?
   let path: String?
   let children: [JsonTrack]
 
   init(
     title: String? = nil,
-    subtitle: String? = nil,
     style: JsonStyle? = nil,
     path: String? = nil,
     children: [JsonTrack],
   ) {
     self.title = title
-    self.subtitle = subtitle
     self.style = style
     self.path = path
     self.children = children
@@ -393,7 +461,6 @@ struct JsonTrack: Codable {
     func toNitro() -> Section {
       Section(
         title: title,
-        subtitle: subtitle,
         style: style?.toSectionStyle(),
         path: path,
         children: children.map { $0.toNitro() },
@@ -479,7 +546,6 @@ struct JsonTrack: Codable {
     func toNitro() -> Section {
       Section(
         title: title,
-        subtitle: subtitle,
         style: style?.toSectionStyle(),
         path: path,
         children: children.map { $0.toNitro() },

package/ios/Browser/SectionPresentation.swift

@@ -31,4 +31,34 @@ enum SectionPresentation: Equatable {
       self = .list
     }
   }
+
+  /// The accessory symbol a resolved block actually draws: nil when
+  /// undeclared, and nil for the `'none'` sentinel — the inheritance escape
+  /// that restores the derived accessory (a browsable row's chevron). Here,
+  /// not in the CarPlay factory, so the sentinel rule is testable off-device.
+  static func effectiveAccessorySymbol(_ style: TrackStyle?) -> String? {
+    guard let symbol = style?.accessorySymbol, symbol != "none" else { return nil }
+    return symbol
+  }
+
+  /// The element family a tile presentation renders on iOS 26+ — here, not
+  /// in the CarPlay factory, so the style→family mapping is testable
+  /// off-device. `gridTile` picks the family (plain by default); the plain
+  /// single-line shelf keeps row elements, the one plain element with a
+  /// subtitle slot. Pre-26 has no element API at all: the treatment drops
+  /// with the legacy image row (decorations drop before layout).
+  enum TileElementFamily: Equatable {
+    case rowElements
+    case imageGridElements
+    case cardElements
+    case condensedElements
+  }
+
+  static func tileFamily(for style: SectionStyle?, singleLine: Bool) -> TileElementFamily {
+    switch style?.gridTile {
+    case .card: .cardElements
+    case .condensed: .condensedElements
+    case .plain, nil: singleLine ? .rowElements : .imageGridElements
+    }
+  }
 }

package/ios/Browser/StyleResolver.swift

@@ -28,8 +28,13 @@ enum StyleResolver {
     // ones — Nitro flattens `extends` own-props-first); the stub mirrors it.
     SectionStyle(
       gridWrap: section?.gridWrap ?? page?.gridWrap,
+      gridTile: section?.gridTile ?? page?.gridTile,
       display: section?.display ?? page?.display,
       artworkRendering: section?.artworkRendering ?? page?.artworkRendering,
+      imageShape: section?.imageShape ?? page?.imageShape,
+      accessorySymbol: section?.accessorySymbol ?? page?.accessorySymbol,
+      cardTint: section?.cardTint ?? page?.cardTint,
+      cardImage: section?.cardImage ?? page?.cardImage,
     )
   }
 
@@ -42,6 +47,12 @@ enum StyleResolver {
       // for this item's own layout.
       display: nil,
       artworkRendering: track?.artworkRendering ?? section?.artworkRendering,
+      imageShape: track?.imageShape ?? section?.imageShape,
+      // `'none'` resolves like any value — it is the renderer that treats it
+      // as "no accessory, derived behavior" (the inheritance escape).
+      accessorySymbol: track?.accessorySymbol ?? section?.accessorySymbol,
+      cardTint: track?.cardTint ?? section?.cardTint,
+      cardImage: track?.cardImage ?? section?.cardImage,
     )
   }
 }

package/ios/Browser/TabBarEntries.swift

@@ -1,15 +1,21 @@
 /// Compares the tab-list fields the CarPlay tab bar actually renders.
 enum TabBarEntries {
   /// Whether two tab lists produce identical tab-bar entries — title, path,
-  /// and the artwork inputs of `applyTabBarEntry`. Used to suppress
+  /// the artwork inputs of `applyTabBarEntry`, and `disabled`. Used to suppress
   /// `tabsChanged` when a tabs re-query (e.g. from `invalidateAllContent()`)
   /// resolves to the same entries, so an unchanged result never churns the
   /// tab bar or resets its selection.
+  ///
+  /// `disabled` counts even though it renders nothing itself: a disabled tab is
+  /// filtered out of the tab bar entirely (`showTabBar`), so a tab flipping it
+  /// with otherwise-identical fields changes which tabs exist. Omitting it here
+  /// swallowed the emit, and the tab never appeared or disappeared.
   static func same(_ old: [Track]?, _ new: [Track]) -> Bool {
     guard let old, old.count == new.count else { return false }
     return zip(old, new).allSatisfy {
       $0.title == $1.title && $0.path == $1.path && $0.artwork == $1.artwork
         && $0.artworkSource?.uri == $1.artworkSource?.uri
+        && $0.disabled == $1.disabled
     }
   }
 }

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.
@@ -97,6 +110,19 @@ public final class RNABCarPlayController: NSObject {
     }
   }
 
+  /// 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.
   ///
   /// Compares track identities (`id` when non-blank, else `src`): the active
@@ -140,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")
 
@@ -167,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
@@ -202,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")
 
@@ -465,11 +494,7 @@ public final class RNABCarPlayController: NSObject {
 
   @MainActor
   private func showTabBar(tabs allTabs: [Track]) async {
-    // A disabled tab hides — CPTabBarTemplate has no gray affordance, so per
-    // Track.disabled's rendering ladder an unavailable tab must not render as
-    // a normal-looking control (matches Android Auto, which filters before
-    // its 4-tab cap).
-    let tabs = allTabs.filter { $0.disabled != true }
+    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
@@ -484,26 +509,31 @@ public final class RNABCarPlayController: NSObject {
     gateBuildGeneration &+= 1
     let generation = gateBuildGeneration
 
-    // 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 — and sits before the gate check, since a gated build from
-    // zero tabs is equally blank.
-    guard !tabs.isEmpty else {
-      await showRootNavigationError(.code(.emptyContent))
-      return
-    }
-
     // While gated, each tab path is resolved per-request: a gated tab renders
     // 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
@@ -543,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),
       )
@@ -554,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
     }
@@ -835,6 +869,9 @@ public final class RNABCarPlayController: NSObject {
   /// 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 navigateToPath(_ path: String, title: String) async {
     // The gate is resolved per-request: a gated path pushes the gate page
@@ -854,6 +891,9 @@ public final class RNABCarPlayController: NSObject {
         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) == path {
       return
@@ -877,6 +917,40 @@ public final class RNABCarPlayController: NSObject {
     }
   }
 
+  /// 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
@@ -951,16 +1025,18 @@ public final class RNABCarPlayController: NSObject {
   @MainActor
   private func handleTabsChanged(_ tabs: [Track]) {
     logger.debug("Tabs changed: \(tabs.count) tabs")
+    // 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.path })
+       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
@@ -1242,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)
@@ -1291,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] } ?? []
@@ -1382,12 +1485,13 @@ extension 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,