react-native-audio-browser 0.2.0-next.8 → 0.2.0

package/ios/CarPlay/CarPlayController.swift

@@ -29,48 +29,16 @@ public final class RNABCarPlayController: NSObject {
   private var isStarted = false
   private var listenerRemovals: [() -> Void] = []
 
-  /// 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.
-  private var navigatingPaths: Set<String> = []
-
-  /// Templates with a content load in flight. Guards a re-entrant load when a
-  /// still-loading template re-appears (back-and-forth navigation) from spawning
-  /// a second resolve + watchdog.
-  private var loadingTemplates: Set<ObjectIdentifier> = []
-
-  /// Tabs received while the user had templates pushed. Rebuilding the tab bar
-  /// replaces the root template, which tears down the pushed navigation stack —
-  /// so the rebuild is deferred until the user is back at the tab bar.
-  private var pendingTabs: [Track]?
-
-  /// Whether a gate is active. While set, tabs keep their tab-bar entries but
-  /// each path is resolved per-request via `gateDecision(for:)`: a gated path
-  /// renders the gate page instead of content; an allowed path shows real
-  /// content. Mirrors `audioBrowser.isGateActive`; seeded in start() so a gate
-  /// set before the scene connects renders at connect.
-  private var isGated = false
-
-  /// Drops a stale tab-bar build when a newer build supersedes it
-  /// (latest-build-wins). Shared across BOTH the gated and non-gated `showTabBar`
-  /// paths: each bumps and captures this at entry and bails before any
-  /// `setRootTemplate` / `updateTemplates` once it's been bumped past their
-  /// captured value. A build suspends the main actor at its `await` points
-  /// (per-tab `gateDecision` when gated, first-tab `loadContent` when not), so a
-  /// gate change can interleave a build of the opposite kind — most importantly a
-  /// `clearGate` kicking the non-gated build while a gated build is mid-await.
-  /// Covering both paths with one token means that clear-vs-gated interleave is
-  /// caught too (not just gated-vs-gated), so a stale gated build can't paint a
-  /// gate page over just-cleared content. Mirrors `albumArtistGeneration` in
-  /// `CarPlayNowPlayingManager`.
-  private var gateBuildGeneration: UInt = 0
-
-  /// How long a browse resolve may run before the destination's loading spinner
-  /// is replaced with an error state. The selection completion is fired
-  /// immediately (so CarPlay never blocks the list — per Apple's async handler
-  /// guidance we push the destination and fill it in), so this only bounds how
-  /// long the *destination screen* spins. Backing out and re-tapping retries.
-  private let resolveTimeout: Duration = .seconds(15)
+  /// Current navigation stack paths (for back navigation context)
+  private var navigationStack: [String] = []
+
+  /// Key (src ?? url) of the item currently being selected.
+  /// Prevents duplicate taps from triggering parallel async operations.
+  private var pendingSelectionKey: String?
+
+  /// URLs currently being resolved for navigation.
+  /// Prevents duplicate taps from pushing the same template twice.
+  private var pendingNavigationUrls: Set<String> = []
 
   /// Helper object for CPInterfaceControllerDelegate conformance
   private var interfaceDelegate: InterfaceControllerDelegate?
@@ -89,21 +57,9 @@ public final class RNABCarPlayController: NSObject {
     audioBrowser?.browserManager.config ?? BrowserConfig()
   }
 
-  /// Whether a list item identifies the currently active (loaded) track.
-  ///
-  /// Identity is the stable `Track.id` when both sides carry one — 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
+  /// Checks if the given src matches the currently active (loaded) track
+  private func isActiveTrack(src: String) -> Bool {
+    audioBrowser?.getPlayer()?.currentTrack?.src == src
   }
 
   // MARK: - Initialization
@@ -118,22 +74,10 @@ 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) }
-    }
   }
 
   // MARK: - Lifecycle
 
-  /// Reports CarPlay scene connection to the library (drives the JS-side
-  /// `isCarPlayConnected` / `onCarPlayConnectedChanged`). Called by
-  /// RNABCarPlaySceneDelegate on scene connect/disconnect — deliberately not
-  /// from start()/stop(), which also cycle on a JS runtime reload.
-  @objc
-  public static func setConnected(_ connected: Bool) {
-    HybridAudioBrowser.setCarPlayConnected(connected)
-  }
-
   @objc
   public func start() {
     guard !isStarted else { return }
@@ -146,18 +90,6 @@ public final class RNABCarPlayController: NSObject {
     interfaceDelegate = delegate
     interfaceController.delegate = delegate
 
-    // Restart when a new HybridAudioBrowser replaces the shared instance
-    // (JS runtime reload) — our subscriptions point at the old instance's
-    // emitters and would otherwise go silent.
-    let instanceToken = HybridAudioBrowser.instanceChangedEmitter.addListener { [weak self] _ in
-      Task { @MainActor in
-        self?.restart()
-      }
-    }
-    listenerRemovals.append {
-      HybridAudioBrowser.instanceChangedEmitter.removeListener(instanceToken)
-    }
-
     // Show loading template while waiting
     showLoadingTemplate()
 
@@ -167,21 +99,20 @@ public final class RNABCarPlayController: NSObject {
       guard self.isStarted else { return }
       self.logger.debug("AudioBrowser and player ready, setting up CarPlay")
       self.audioBrowser = browser
-      self.isGated = browser.isGateActive
       self.trackSelector = TrackSelector(browserManager: browser.browserManager)
 
       // Create image loader with CarPlay display traits
       self.imageLoader = CarPlayImageLoader(
         carTraitCollection: self.interfaceController.carTraitCollection,
-        browserManager: browser.browserManager,
+        browserManager: browser.browserManager
       )
 
       // Create list item factory
       let factory = CarPlayListItemFactory(
-        isActiveTrack: { [weak self] id, src in self?.isActiveTrack(id: id, src: src) ?? false },
+        isActiveTrack: { [weak self] src in self?.isActiveTrack(src: src) ?? false },
         onItemSelected: { [weak self] track, completion in
           self?.handleItemSelection(track: track, completion: completion)
-        },
+        }
       )
       factory.imageLoader = self.imageLoader
       self.listItemFactory = factory
@@ -203,33 +134,18 @@ public final class RNABCarPlayController: NSObject {
     logger.info("Stopping CarPlay controller")
 
     // Remove all emitter listeners
-    for removal in listenerRemovals {
-      removal()
-    }
+    for removal in listenerRemovals { removal() }
     listenerRemovals.removeAll()
 
     // Clear config callback
     audioBrowser?.browserManager.onConfigChanged = nil
-    audioBrowser?.browserManager.onFavoritesChanged = nil
 
     nowPlayingManager.teardown()
     listItemFactory = nil
 
-    navigatingPaths.removeAll()
-    loadingTemplates.removeAll()
-    pendingTabs = nil
-  }
-
-  /// Full stop/start cycle. Used when the JS runtime reloads: the new
-  /// HybridAudioBrowser instance replaces the emitters this controller is
-  /// subscribed to and resets the readiness gate, so everything must be
-  /// re-subscribed against the live instance (start() waits for it).
-  @MainActor
-  private func restart() {
-    guard isStarted else { return }
-    logger.info("AudioBrowser instance changed — restarting CarPlay controller")
-    stop()
-    start()
+    navigationStack.removeAll()
+    pendingSelectionKey = nil
+    pendingNavigationUrls.removeAll()
   }
 
   // MARK: - Content Subscriptions
@@ -260,35 +176,10 @@ public final class RNABCarPlayController: NSObject {
       audioBrowser?.contentChangedEmitter.removeListener(contentToken)
     }
 
-    // Subscribe to config changes (for Now Playing buttons and per-track
-    // button state — e.g. resolveAlbumUrl appearing/disappearing)
+    // Subscribe to config changes (for Now Playing buttons)
     audioBrowser.browserManager.onConfigChanged = { [weak self] _ in
       Task { @MainActor in
         self?.nowPlayingManager.setupNowPlayingButtons()
-        self?.nowPlayingManager.updateNowPlayingButtonStates()
-      }
-    }
-
-    // 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).
-    let optionsToken = audioBrowser.playerOptionsChangedEmitter.addListener { [weak self] in
-      Task { @MainActor in
-        self?.nowPlayingManager.setupNowPlayingButtons()
-        self?.nowPlayingManager.updateNowPlayingButtonStates()
-      }
-    }
-    listenerRemovals.append { [weak audioBrowser] in
-      audioBrowser?.playerOptionsChangedEmitter.removeListener(optionsToken)
-    }
-
-    // Refresh the Now Playing heart when favorites change externally (app /
-    // webview). The favorite/active-track emitters only fire for the player's
-    // own toggles, so without this an in-app favorite leaves the CarPlay heart
-    // stale.
-    audioBrowser.browserManager.onFavoritesChanged = { [weak self] in
-      Task { @MainActor in
-        self?.nowPlayingManager.updateFavoriteButtonState()
       }
     }
 
@@ -302,54 +193,14 @@ public final class RNABCarPlayController: NSObject {
       audioBrowser?.favoriteChangedEmitter.removeListener(favoriteToken)
     }
 
-    // Repeat/shuffle mode changes re-stamp the now-playing buttons' serialized
-    // `isSelected` (a rebuild, skipped when unchanged) so CarPlay re-renders
-    // draw the correct selected background on the first frame — see
-    // CarPlayNowPlayingManager.BuiltButtonRow.
-    let repeatToken = audioBrowser.repeatModeChangedEmitter.addListener { [weak self] _ in
-      Task { @MainActor in
-        self?.nowPlayingManager.setupNowPlayingButtons()
-      }
-    }
-    listenerRemovals.append { [weak audioBrowser] in
-      audioBrowser?.repeatModeChangedEmitter.removeListener(repeatToken)
-    }
-    let shuffleToken = audioBrowser.shuffleChangedEmitter.addListener { [weak self] _ in
-      Task { @MainActor in
-        self?.nowPlayingManager.setupNowPlayingButtons()
-      }
-    }
-    listenerRemovals.append { [weak audioBrowser] in
-      audioBrowser?.shuffleChangedEmitter.removeListener(shuffleToken)
-    }
-
-    // Subscribe to external content changes (notifyContentChanged /
-    // invalidateAllContent).
+    // Subscribe to external content changes (from notifyContentChanged)
     let externalContentToken = audioBrowser.externalContentChangedEmitter.addListener { [weak self] path in
-      // Hop to the main actor like the sibling listeners — the emitter runs
-      // listeners synchronously on the emitting (JS) thread.
-      Task { @MainActor in
-        if path == HybridAudioBrowser.invalidateAllSentinel {
-          self?.invalidateAllContent()
-        } else {
-          self?.notifyContentChanged(path: path)
-        }
-      }
+      self?.notifyContentChanged(path: path)
     }
     listenerRemovals.append { [weak audioBrowser] in
       audioBrowser?.externalContentChangedEmitter.removeListener(externalContentToken)
     }
 
-    // Subscribe to gate changes (set / in-place update / clear)
-    let gateToken = audioBrowser.gateChangedEmitter.addListener { [weak self] active in
-      Task { @MainActor in
-        self?.handleGateChanged(active)
-      }
-    }
-    listenerRemovals.append { [weak audioBrowser] in
-      audioBrowser?.gateChangedEmitter.removeListener(gateToken)
-    }
-
     // Subscribe to active track changes (for playing indicator in lists)
     let activeTrackToken = audioBrowser.activeTrackChangedEmitter.addListener { [weak self] event in
       Task { @MainActor in
@@ -370,17 +221,6 @@ public final class RNABCarPlayController: NSObject {
       audioBrowser?.queueChangedEmitter.removeListener(queueToken)
     }
 
-    // A voice media intent started playback — surface Now Playing so the user
-    // lands on the playing station (Up Next holds the rest of the results).
-    let showNowPlayingToken = audioBrowser.showNowPlayingRequestedEmitter.addListener { [weak self] _ in
-      Task { @MainActor in
-        self?.nowPlayingManager.showNowPlaying()
-      }
-    }
-    listenerRemovals.append { [weak audioBrowser] in
-      audioBrowser?.showNowPlayingRequestedEmitter.removeListener(showNowPlayingToken)
-    }
-
     // Subscribe to navigation errors (from browser layer)
     let navErrorToken = audioBrowser.navigationErrorEmitter.addListener { [weak self] event in
       Task { @MainActor in
@@ -397,9 +237,8 @@ public final class RNABCarPlayController: NSObject {
   private func handleNavigationError(_ event: NavigationErrorEvent) {
     guard let error = event.error else { return }
     logger.warning("Navigation error: \(error.code.stringValue) - \(error.message)")
-    // Derive the current path from the live top template (authoritative) rather
-    // than a hand-maintained stack that goes stale on back navigation.
-    let path = interfaceController.topTemplate.flatMap { getPath(from: $0) } ?? "/"
+    // Use current path from navigation stack, or "/" as fallback
+    let path = navigationStack.last ?? "/"
     showNavigationError(error, path: path)
   }
 
@@ -409,9 +248,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),
-      )
+      showErrorTemplate(message: "Audio browser not initialized")
       return
     }
 
@@ -423,65 +260,33 @@ public final class RNABCarPlayController: NSObject {
     } else {
       // No tabs yet - query them
       logger.info("No tabs available, querying...")
-      // Config exists by now (start() waited for it), so re-show the loading
-      // root to pick up the app's localized loading title — the first loading
-      // template was created before config was available.
-      if config.carPlayLoadingTitle != nil {
-        showLoadingTemplate()
-      }
       do {
         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),
-          )
+          showErrorTemplate(message: "No content available")
         }
       } catch {
         logger.error("Failed to query tabs: \(error.localizedDescription)")
-        await showRootNavigationError(NavigationError.from(error))
+        showErrorTemplate(message: "Failed to load content")
       }
     }
   }
 
-  /// Shows a loading template as root while waiting for initialization. Before
-  /// the browser is configured this can only show the spinner (iOS 18.4+) — the
-  /// app's `carPlayLoadingTitle` isn't known yet; `buildInitialInterface`
-  /// re-shows it once config is available.
+  /// Shows a loading template while waiting for initialization
   private func showLoadingTemplate() {
-    let template = makeLoadingTemplate(title: nil, path: nil)
-    interfaceController.safeSetRoot(template, animated: false)
+    let template = CPListTemplate(
+      title: nil,
+      sections: [],
+    )
+    interfaceController.setRootTemplate(template, animated: false, completion: nil)
   }
 
   // MARK: - Tab Bar
 
   @MainActor
   private func showTabBar(tabs: [Track]) async {
-    // 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
-    // suspend the main actor at `await` points (per-tab `gateDecision` when
-    // gated, first-tab `loadContent` when not), so a gate change can interleave
-    // a build of the opposite kind — a `clearGate` kicking the non-gated build
-    // while a gated build is mid-await, or vice versa. A single token covers the
-    // clear-vs-gated interleave too, not just gated-vs-gated: the superseding
-    // build bumps it, and the in-flight build bails before painting (preventing
-    // a stale gate page over just-cleared content, or a clobbered root template).
-    gateBuildGeneration &+= 1
-    let generation = gateBuildGeneration
-
-    // 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.
-    if isGated {
-      await showGatedTabBar(tabs: tabs, generation: generation)
-      return
-    }
-
     logger.info("Building tab bar with \(tabs.count) tabs")
 
     let maxTabs = CPTabBarTemplate.maximumTabCount
@@ -491,14 +296,10 @@ public final class RNABCarPlayController: NSObject {
       createTabTemplate(for: tab)
     }
 
-    // A newer build (e.g. a gate raised mid-clear) superseded us — don't clobber
-    // its root template.
-    guard gateBuildGeneration == generation else { return }
-
     // Set the tab bar immediately so UI appears fast
     logger.info("Setting tab bar root template with \(tabTemplates.count) templates")
     let tabBar = CPTabBarTemplate(templates: tabTemplates)
-    interfaceController.safeSetRoot(tabBar, animated: true)
+    interfaceController.setRootTemplate(tabBar, animated: true, completion: nil)
 
     // 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 {
@@ -506,93 +307,27 @@ public final class RNABCarPlayController: NSObject {
     }
   }
 
-  /// Builds the tab bar while a gate is active. Each tab's path is run through
-  /// the single gate choke point (`gateDecision(for:)`): a gated tab becomes a
-  /// gate page carrying that decision's chrome (and fires `onGate`); an allowed
-  /// tab becomes a normal content shell that lazy-loads. With a static gate (no
-  /// resolver) every tab is gated with the default chrome — today's behaviour.
-  ///
-  /// `generation` is the shared `gateBuildGeneration` captured by the calling
-  /// `showTabBar`; we bail before any template mutation once a newer build (of
-  /// either kind) bumps it past `generation`.
-  @MainActor
-  private func showGatedTabBar(tabs: [Track], generation: UInt) async {
-    guard let audioBrowser else { return }
-
-    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).
-      let outcome = await audioBrowser.gateDecision(
-        for: NativeGateRequest(reason: .browse, path: nil, search: nil),
-      )
-      guard gateBuildGeneration == generation else { return } // superseded by a newer build
-      if outcome.gated {
-        audioBrowser.onGate(GateEvent(reason: .browse))
-        interfaceController.safeSetRoot(
-          makeGateTemplate(gate: outcome.chrome, tab: nil), animated: true,
-        )
-      }
-      return
-    }
-
-    let limitedTabs = Array(tabs.prefix(CPTabBarTemplate.maximumTabCount))
-    var templates: [CPListTemplate] = []
-    for tab in limitedTabs {
-      let outcome = await audioBrowser.gateDecision(
-        for: NativeGateRequest(reason: .browse, path: tab.url, search: nil),
-      )
-      guard gateBuildGeneration == generation else { return } // superseded by a newer build
-      if outcome.gated {
-        audioBrowser.onGate(GateEvent(reason: .browse))
-        templates.append(makeGateTemplate(gate: outcome.chrome, tab: tab))
-      } else {
-        // This path is allowed even though a gate is active — show real content.
-        templates.append(createTabTemplate(for: tab))
-      }
-    }
-
-    if let tabBar = interfaceController.rootTemplate as? CPTabBarTemplate,
-       tabBar.templates.count == templates.count
-    {
-      // Equal-count in-place swap keeps the selected tab index.
-      tabBar.updateTemplates(templates)
-    } else {
-      interfaceController.safeSetRoot(
-        CPTabBarTemplate(templates: templates), animated: true,
-      )
-    }
-
-    // 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)
-    }
-  }
-
-  /// Creates a tab template shell without loading content (synchronous).
-  /// The shell carries the loading state (spinner / `carPlayLoadingTitle`)
-  /// until its content lazy-loads on first appearance.
+  /// Creates a tab template shell without loading content (synchronous)
   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)
-    applyTabBarEntry(to: template, for: track)
-    return template
-  }
+    let template = CPListTemplate(
+      title: track.title,
+      sections: [],
+    )
 
-  /// Stamps a template's tab-bar entry: title and image (default, SF Symbol,
-  /// or loaded artwork). Shared by content tabs and gate-page tabs so a gate
-  /// keeps the familiar tab bar.
-  private func applyTabBarEntry(to template: CPTemplate, for track: Track) {
     // Set tab title explicitly (required for tab bar display)
     template.tabTitle = track.title
 
-    // Set tab image only when the tab supplies one (SF Symbol / artwork /
-    // artworkSource). A tab with no icon stays title-only — CPTemplate renders
-    // fine with just `tabTitle`. Tab bar icons are 24pt x 24pt per the CarPlay
-    // Developer Guide: https://developer.apple.com/download/files/CarPlay-Developer-Guide.pdf
-    if let artwork = track.artwork?.url, SFSymbolRenderer.isSFSymbol(artwork) {
+    // Store path for lazy loading and refresh
+    if let url = track.url {
+      template.userInfo = ["path": url] as [String: Any]
+    }
+
+    // Set tab image - CarPlay requires an image for proper tab display
+    // Tab bar icons are 24pt x 24pt per CarPlay Developer Guide
+    // https://developer.apple.com/download/files/CarPlay-Developer-Guide.pdf
+    template.tabImage = imageLoader?.defaultTabImage()
+
+    if let artwork = track.artwork, SFSymbolRenderer.isSFSymbol(artwork) {
       let (symbolName, _, _) = SFSymbolRenderer.parseArtwork(artwork)
       if let image = imageLoader?.sfSymbolImage(symbolName) {
         template.tabImage = image
@@ -607,15 +342,28 @@ public final class RNABCarPlayController: NSObject {
           }
         }
       }
-    } else {
-      // No icon supplied: clear any prior image so a restamp (handleTabsChanged)
-      // of an existing template doesn't leave a stale icon on a now title-only tab.
-      template.tabImage = nil
     }
+
+    return template
   }
 
   // MARK: - List Templates
 
+  @MainActor
+  private func createListTemplate(
+    for resolvedTrack: ResolvedTrack,
+    path: String,
+  ) -> CPListTemplate {
+    let template = CPListTemplate(
+      title: resolvedTrack.title,
+      sections: [],
+    )
+    updateTemplate(template, with: resolvedTrack)
+    template.userInfo = ["path": path] as [String: Any]
+
+    return template
+  }
+
   /// Finds the path associated with a template, if any
   private func getPath(from template: CPTemplate) -> String? {
     (template.userInfo as? [String: Any])?["path"] as? String
@@ -631,6 +379,7 @@ public final class RNABCarPlayController: NSObject {
   /// Configures the assistant cell ("Ask Siri to Play Audio") on a template
   /// based on the `carPlaySiriListButton` property of the resolved content.
   private func configureAssistantCell(on template: CPListTemplate, from resolvedTrack: ResolvedTrack) {
+    guard #available(iOS 15.4, *) else { return }
     guard let position = resolvedTrack.carPlaySiriListButton else {
       template.assistantCellConfiguration = nil
       return
@@ -645,96 +394,15 @@ public final class RNABCarPlayController: NSObject {
 
   // MARK: - Content Loading
 
-  /// Resolves `path` and fills an empty (loading) template. Driven by
-  /// `templateDidAppear` → `loadContentIfNeeded`, so it runs once the template is
-  /// on screen — the timing where CarPlay actually applies updates (updates made
-  /// earlier, e.g. straight after push, are dropped). Shows a centered empty
-  /// state on empty/error/timeout.
   @MainActor
   private func loadContent(for path: String, into template: CPListTemplate) async {
     guard let audioBrowser else { return }
 
-    // Single-flight: don't start a second load if one is already in flight for
-    // this template (e.g. the user backed out and into a still-loading screen).
-    let templateId = ObjectIdentifier(template)
-    guard !loadingTemplates.contains(templateId) else { return }
-    loadingTemplates.insert(templateId)
-    defer { loadingTemplates.remove(templateId) }
-
-    // Watchdog: if still loading (no rows) after the timeout, show an error.
-    let timeout = resolveTimeout
-    let watchdog = Task { @MainActor [weak self] in
-      do { try await Task.sleep(for: timeout) } catch { return } // cancelled → abort
-      guard let self, template.sections.isEmpty else { return }
-      self.logger.error("loadContent: resolve timed out for \(path)")
-      // A timeout is a navigation error (code .timeout) too, so it formats through
-      // the app's formatNavigationError like every other browse failure.
-      let timedOut = NavigationError(
-        code: .timeout, message: "", statusCode: nil, statusCodeSuccess: nil,
-      )
-      await self.showNavigationErrorView(timedOut, path: path, on: template)
-    }
-
     do {
       let resolved = try await audioBrowser.browserManager.resolve(path, useCache: true)
-      watchdog.cancel()
-      // A page carrying an assistant cell (carPlaySiriListButton) is meaningful
-      // 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 {
-        // 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)
-      } else {
-        updateTemplate(template, with: resolved)
-      }
+      updateTemplate(template, with: resolved)
     } catch {
-      watchdog.cancel()
       logger.error("Failed to load content for \(path): \(error.localizedDescription)")
-      await showNavigationErrorView(NavigationError.from(error), path: path, on: template)
-    }
-  }
-
-  /// Renders a navigation error as the template's centered empty/error view,
-  /// formatted via the app's `formatNavigationError` (or the built-in default):
-  /// `title → view title`, `message → subtitle`. Used for both real failures and
-  /// the empty-content case (ADR 0001).
-  @MainActor
-  private func showNavigationErrorView(
-    _ navError: NavigationError,
-    path: String,
-    on template: CPListTemplate,
-  ) async {
-    let formatted = await formattedNavigationError(navError, path: path)
-    showMessage(
-      on: template,
-      title: formatted.title,
-      subtitle: formatted.message.flatMap { $0.isEmpty ? nil : $0 },
-    )
-  }
-
-  /// Resolves a navigation error to its display form via the app's
-  /// `formatNavigationError` callback, falling back to the default if unset/failed.
-  @MainActor
-  private func formattedNavigationError(
-    _ navError: NavigationError,
-    path: String,
-  ) async -> FormattedNavigationError {
-    let fallback = navError.defaultFormatted()
-    guard let formatter = config.formatNavigationError else { return fallback }
-    let params = FormatNavigationErrorParams(
-      error: navError, defaultFormatted: fallback, path: path,
-    )
-    do {
-      let custom = try await formatter(params).await()
-      return custom ?? fallback
-    } catch {
-      return fallback
     }
   }
 
@@ -748,8 +416,17 @@ public final class RNABCarPlayController: NSObject {
       return
     }
 
-    // If this track is already loaded, resume playback and show Now Playing.
-    if track.src != nil, isActiveTrack(id: track.id, src: track.src) {
+    // Deduplicate: ignore if the same item is already being loaded
+    let key = track.src ?? track.url
+    if let key, key == pendingSelectionKey {
+      completion()
+      return
+    }
+    pendingSelectionKey = key
+
+    // If this track is already loaded, resume playback and show Now Playing
+    if let src = track.src, isActiveTrack(src: src) {
+      pendingSelectionKey = nil
       try? audioBrowser.play()
       nowPlayingManager.showNowPlaying()
       completion()
@@ -757,171 +434,78 @@ public final class RNABCarPlayController: NSObject {
     }
 
     guard let player = audioBrowser.getPlayer(), let trackSelector else {
+      pendingSelectionKey = nil
       completion()
       return
     }
 
-    // A playable track always lands on the Now Playing surface (selection
-    // resolves to .play or .intercepted, never .browse) — push it now and stamp
-    // the tapped track's metadata, instead of after selection resolves: queue
-    // expansion and the media URL resolve can both hit the network, and waiting
-    // animates in a blank Now Playing screen. The load pipeline re-publishes
-    // the same fields and dedupes.
-    if track.src != nil {
-      player.loadNowPlayingMetadata(for: track)
-      // Derive the album line's destination from the tapped track before the
-      // push — CarPlay reads isAlbumArtistButtonEnabled at display time.
-      nowPlayingManager.prepareAlbumArtistButton(for: track)
-      nowPlayingManager.showNowPlaying()
-    }
-
-    // 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
-    // playback the Now Playing surface owns its own loading state.
-    completion()
-
-    Task { [weak self] in
+    Task {
+      defer { self.pendingSelectionKey = nil }
       let result = await trackSelector.select(track: track, player: player)
-      guard let self else { return }
       switch result {
-      case let .play(intent):
+      case .play(let intent):
         self.executePlayback(intent, player: player)
-        self.nowPlayingManager.showNowPlaying(popToFront: false)
+        self.nowPlayingManager.showNowPlaying()
       case .intercepted:
-        self.nowPlayingManager.showNowPlaying(popToFront: false)
-      case let .browse(url):
-        await self.navigateToUrl(url, title: track.title)
+        self.nowPlayingManager.showNowPlaying()
+      case .browse(let url):
+        self.navigateToUrl(url, completion: completion)
+        return // navigateToUrl handles its own completion
       case .none:
         break
       }
+      completion()
     }
   }
 
   private func executePlayback(_ intent: TrackSelector.PlaybackIntent, player: TrackPlayer) {
     switch intent {
-    case let .skipTo(index):
+    case .skipTo(let index):
       try? player.skipTo(index, playWhenReady: true)
-    case let .setQueue(tracks, startIndex, sourcePath):
+    case .setQueue(let tracks, let startIndex, let sourcePath):
       player.setQueue(tracks, initialIndex: startIndex, playWhenReady: true, sourcePath: sourcePath)
-    case let .loadTrack(track):
+    case .loadTrack(let track):
       player.load(track, playWhenReady: true)
     }
   }
 
-  /// Pushes a browsable URL'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.
-  @MainActor
-  private func navigateToUrl(_ url: 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),
-      )
-      if outcome.gated {
-        audioBrowser.onGate(GateEvent(reason: .browse))
-        if let top = interfaceController.topTemplate, getPath(from: top) == url { return }
-        interfaceController.safePush(
-          makeGateTemplate(gate: outcome.chrome, tab: nil), animated: true,
-        )
-        return
-      }
-    }
-    // Avoid pushing a duplicate if the top template already shows this path.
-    if let top = interfaceController.topTemplate, getPath(from: top) == url {
+  /// Navigates to a browsable URL path, showing error action sheet on failure with retry option.
+  private func navigateToUrl(_ url: String, completion: @escaping () -> Void) {
+    guard let audioBrowser else {
+      completion()
       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)
-
-    let template = makeLoadingTemplate(title: title, path: url)
-    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)
-      if let error {
-        self?.logger.error("pushTemplate failed for \(url): \(error.localizedDescription)")
-      }
-    }
-  }
-
-  /// 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
-  /// state when configured; otherwise it stays blank rather than ship a
-  /// hardcoded, un-localized "Loading…". The empty view is set at creation —
-  /// the timing CarPlay renders reliably (see `replaceWithMessage`).
-  private func makeLoadingTemplate(title: String?, path: String?) -> CPListTemplate {
-    let template = CPListTemplate(title: title, sections: [])
-    if let path {
-      template.userInfo = ["path": path] as [String: Any]
-    }
-    if let loadingTitle = config.carPlayLoadingTitle {
-      // Subtitle slot on purpose: the title slot renders at CarPlay's large
-      // empty-state size, which is too heavy for a transient loading hint.
-      template.emptyViewSubtitleVariants = [loadingTitle]
-    }
-    if #available(iOS 18.4, *) {
-      template.showsSpinnerWhileEmpty = true
-    }
-    return template
-  }
 
-  /// Shows a centered empty/error message on a loading template. A *pushed*
-  /// template is replaced (see `replaceWithMessage`); a *tab root* can't be
-  /// popped, so its empty view is set in place (best-effort — a tab renders its
-  /// empty view when selected).
-  private func showMessage(on template: CPListTemplate, title: String, subtitle: String?) {
-    if isTabRoot(template) {
-      if #available(iOS 18.4, *) {
-        template.showsSpinnerWhileEmpty = false
-      }
-      template.emptyViewTitleVariants = [title.isEmpty ? "Couldn't load" : title]
-      template.emptyViewSubtitleVariants = subtitle.map { [$0] } ?? []
-      template.updateSections([])
-    } else {
-      replaceWithMessage(template, title: title, subtitle: subtitle)
+    // Deduplicate: ignore if already navigating to this URL
+    guard !pendingNavigationUrls.contains(url) else {
+      completion()
+      return
     }
-  }
+    pendingNavigationUrls.insert(url)
 
-  /// Whether `template` is a tab's root template (a child of the tab bar). Such
-  /// templates can't be popped, so the replace-by-pop strategy doesn't apply.
-  private func isTabRoot(_ template: CPTemplate) -> Bool {
-    guard let tabBar = interfaceController.rootTemplate as? CPTabBarTemplate else { return false }
-    return tabBar.templates.contains { $0 === template }
-  }
+    Task {
+      defer { self.pendingNavigationUrls.remove(url) }
+      do {
+        let resolved = try await audioBrowser.browserManager.resolve(url, useCache: true)
+
+        // Guard against duplicate push if top template already shows this path
+        if let top = self.interfaceController.topTemplate,
+           self.getPath(from: top) == url
+        {
+          completion()
+          return
+        }
 
-  /// Replaces an on-screen loading template with a fresh list template showing a
-  /// centered empty-state message (empty result, or an error).
-  ///
-  /// We *replace* rather than mutate because CarPlay reliably renders a list
-  /// template's empty view only as its **initial** state at push time — changing
-  /// `emptyViewTitleVariants` / `showsSpinnerWhileEmpty` on an already-pushed
-  /// template is unreliable (it renders late, or not at all). The replacement
-  /// carries no `path`, so `loadContentIfNeeded` won't lazy-reload it; backing
-  /// out and re-tapping retries.
-  private func replaceWithMessage(_ loadingTemplate: CPListTemplate, title: String, subtitle: String?) {
-    // Only replace if the loading template is still the visible top template
-    // (the user may have backed out while the resolve was in flight).
-    guard interfaceController.topTemplate === loadingTemplate else { return }
-
-    let message = CPListTemplate(title: loadingTemplate.title, sections: [])
-    message.emptyViewTitleVariants = [title.isEmpty ? "Couldn't load" : title]
-    message.emptyViewSubtitleVariants = subtitle.map { [$0] } ?? []
-
-    interfaceController.safePop(animated: false) { [weak self] _, _ in
-      self?.interfaceController.safePush(message, animated: false)
+        let listTemplate = self.createListTemplate(for: resolved, path: url)
+        self.navigationStack.append(url)
+        self.interfaceController.pushTemplate(listTemplate, animated: true, completion: nil)
+        completion()
+      } catch {
+        logger.error("Failed to navigate to \(url): \(error.localizedDescription)")
+        let navError = NavigationError.from(error)
+        self.showNavigationError(navError, path: url)
+        completion()
+      }
     }
   }
 
@@ -930,49 +514,12 @@ 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
-    // (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 })
-    {
-      for (template, tab) in zip(tabBar.templates, tabs) {
-        applyTabBarEntry(to: template, for: tab)
-      }
-      pendingTabs = nil
-      return
-    }
-    // Rebuilding replaces the root template, tearing down any pushed
-    // navigation stack. If the user is browsing, defer until they're back at
-    // the tab bar (applied from templateDidAppear).
-    guard interfaceController.templates.count <= 1 else {
-      pendingTabs = tabs
-      return
-    }
-    pendingTabs = nil
+    // Rebuild tab bar if we're at the root
     Task {
       await showTabBar(tabs: tabs)
     }
   }
 
-  /// Applies a deferred tab change once the user has popped back to the tab
-  /// bar. Returns true if a rebuild was kicked off (the appeared template is
-  /// about to be replaced, so callers should skip further work on it).
-  @MainActor
-  fileprivate func applyPendingTabsIfAtRoot() -> Bool {
-    guard let tabs = pendingTabs, interfaceController.templates.count <= 1 else {
-      return false
-    }
-    pendingTabs = nil
-    Task {
-      await showTabBar(tabs: tabs)
-    }
-    return true
-  }
-
   @MainActor
   private func handleContentChanged(_ content: ResolvedTrack?) {
     // This callback fires when the main browser's content changes.
@@ -985,9 +532,8 @@ public final class RNABCarPlayController: NSObject {
   private func handleActiveTrackChanged(_ event: PlaybackActiveTrackChangedEvent) {
     logger.debug("handleActiveTrackChanged: \(event.lastTrack?.src ?? "nil") → \(event.track?.src ?? "nil")")
     updatePlayingIndicators()
-    // Refresh per-track button state: favorite heart, Up Next availability,
-    // and the album line's pre-resolved destination.
-    nowPlayingManager.handleActiveTrackChanged()
+    // Update favorite button to reflect the new track's favorite state
+    nowPlayingManager.updateFavoriteButtonState()
   }
 
   /// Updates the isPlaying state on all list items based on the current active track.
@@ -1010,31 +556,19 @@ public final class RNABCarPlayController: NSObject {
     }
 
     for template in templates {
-      var templateChanged = false
       for section in template.sections {
         for item in section.items {
           guard let listItem = item as? CPListItem,
-                let info = listItem.carPlayItemInfo,
-                info.src != nil
+                let itemSrc = listItem.carPlayItemInfo?.src
           else { continue }
 
-          let isPlaying = isActiveTrack(id: info.id, src: info.src)
+          let isPlaying = isActiveTrack(src: itemSrc)
           if listItem.isPlaying != isPlaying {
-            logger.debug(
-              "Updating isPlaying for \(info.id ?? info.src ?? ""): \(listItem.isPlaying) → \(isPlaying)")
+            logger.debug("Updating isPlaying for \(itemSrc): \(listItem.isPlaying) → \(isPlaying)")
             listItem.isPlaying = isPlaying
-            templateChanged = true
           }
         }
       }
-      // Setting isPlaying on an already-displayed item does not reliably reach
-      // the CarPlay screen (rdar-known; the flag only renders when the item is
-      // pushed with it already set). Re-pushing the same sections re-serializes
-      // every item with its current flags — done only when something actually
-      // changed, so routine appear-time passes don't churn the display.
-      if templateChanged {
-        template.updateSections(template.sections)
-      }
     }
   }
 
@@ -1098,108 +632,6 @@ public final class RNABCarPlayController: NSObject {
     }
   }
 
-  /// Refreshes every currently-displayed template (tabs + navigation stack) by
-  /// re-fetching each path with the cache bypassed. Called when all content was
-  /// invalidated app-wide (e.g. a locale change).
-  @MainActor
-  public func invalidateAllContent() {
-    guard isStarted else { return }
-    Task { @MainActor in await refreshAllDisplayedTemplates() }
-  }
-
-  @MainActor
-  private func refreshAllDisplayedTemplates() async {
-    guard let audioBrowser else { return }
-
-    var templates: [CPListTemplate] = []
-    if let tabBar = interfaceController.rootTemplate as? CPTabBarTemplate {
-      for template in tabBar.templates {
-        if let listTemplate = template as? CPListTemplate {
-          templates.append(listTemplate)
-        }
-      }
-    }
-    for template in interfaceController.templates {
-      if let listTemplate = template as? CPListTemplate,
-         !templates.contains(where: { $0 === listTemplate })
-      {
-        templates.append(listTemplate)
-      }
-    }
-
-    for template in templates {
-      guard let path = getPath(from: template) else { continue }
-      do {
-        let resolved = try await audioBrowser.browserManager.resolve(path, useCache: false)
-        updateTemplate(template, with: resolved)
-      } catch {
-        logger.error("invalidateAllContent: failed to refresh \(path): \(error.localizedDescription)")
-      }
-    }
-  }
-
-  // MARK: - Gate
-
-  /// Applies a gate state change: set or clear. The per-request chrome is
-  /// obtained at render time via `gateDecision(for:)`, so this just tears down
-  /// any pushed navigation and rebuilds the tab bar — `showTabBar` routes to the
-  /// gated build while a gate is active and to the normal build once cleared.
-  /// Custom Now Playing buttons (e.g. favorite) hide while gated and return on
-  /// clear.
-  @MainActor
-  private func handleGateChanged(_ active: Bool) {
-    isGated = active
-    let tabs = audioBrowser?.browserManager.getTabs() ?? []
-    if tabs.isEmpty, !active {
-      // Never had tabs (gate was up since before config) — full initial build.
-      Task { await buildInitialInterface() }
-    } else {
-      // Tear down any pushed navigation — gated content must not stay reachable
-      // behind the gate, and on clear we return to the root. (No-op at root.)
-      interfaceController.safePopToRoot(animated: false)
-      Task { await showTabBar(tabs: tabs) }
-    }
-    nowPlayingManager.setupNowPlayingButtons()
-    nowPlayingManager.updateNowPlayingButtonStates()
-  }
-
-  /// Builds the gate page for one tab-bar slot, carrying the tab's entry so
-  /// the tab bar itself stays familiar.
-  ///
-  /// A CPListTemplate, NOT a CPInformationTemplate: CarPlay enforces
-  /// per-entitlement template allowances at runtime, and the audio
-  /// entitlement does not include the information template — handing one to
-  /// CPTabBarTemplate throws an unhandled ObjC exception (crash at init).
-  ///
-  /// Within a list, tab children never show navigation-bar buttons (the tab
-  /// bar owns that chrome), and the centered empty view renders only when the
-  /// list has NO rows. The gate is a plain centered message — `title` as the
-  /// empty-view title and `message` as its subtitle, where newlines collapse
-  /// to spaces (the "variants" are width alternatives, not lines). No action
-  /// button: a gate withholds content; the consumer surfaces any "subscribe"
-  /// affordance in its own UI, not on the car surface.
-  private func makeGateTemplate(gate gateChrome: Gate?, tab: Track?) -> CPListTemplate {
-    // A gated decision with neither an override nor a stored default chrome
-    // (resolver-only `true`) falls back to the built-in minimal gate.
-    let gate = gateChrome ?? HybridAudioBrowser.builtInGate
-    let template = CPListTemplate(title: gate.title, sections: [])
-    // Set at creation — the timing CarPlay renders the empty view reliably
-    // (see replaceWithMessage).
-    template.emptyViewTitleVariants = [gate.title]
-    if let message = gate.message, !message.isEmpty {
-      template.emptyViewSubtitleVariants = [
-        message.replacingOccurrences(of: "\n", with: " "),
-      ]
-    }
-    // Marks the page as a gate (vs. a content tab, which carries a `path`),
-    // so the lazy-loader and refresh paths never try to fill it.
-    template.userInfo = ["gate": true] as [String: Any]
-    if let tab {
-      applyTabBarEntry(to: template, for: tab)
-    }
-    return template
-  }
-
   // MARK: - Error Handling
 
   /// Shows a navigation error using CPActionSheetTemplate.
@@ -1235,7 +667,7 @@ public final class RNABCarPlayController: NSObject {
   private func presentErrorActionSheet(customDisplay: FormattedNavigationError) {
     // If another template is already presented, dismiss it first
     if interfaceController.presentedTemplate != nil {
-      interfaceController.safeDismiss(animated: false) { [weak self] _, _ in
+      interfaceController.dismissTemplate(animated: false) { [weak self] _, _ in
         self?.showErrorActionSheet(customDisplay: customDisplay)
       }
     } else {
@@ -1248,7 +680,7 @@ public final class RNABCarPlayController: NSObject {
     // OK action - dismiss the action sheet (use system-localized "OK")
     let okTitle = Bundle(for: UIAlertController.self).localizedString(forKey: "OK", value: "OK", table: nil)
     let ok = CPAlertAction(title: okTitle, style: .cancel) { [weak self] _ in
-      self?.interfaceController.safeDismiss(animated: true)
+      self?.interfaceController.dismissTemplate(animated: true, completion: nil)
     }
 
     let actionSheet = CPActionSheetTemplate(
@@ -1257,20 +689,19 @@ public final class RNABCarPlayController: NSObject {
       actions: [ok],
     )
 
-    interfaceController.safePresent(actionSheet, animated: true)
+    interfaceController.presentTemplate(actionSheet, animated: true, completion: nil)
   }
 
-  /// Shows an initialization failure as the root template — a centered empty
-  /// 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.
-  @MainActor
-  private func showRootNavigationError(_ navError: NavigationError) async {
-    let formatted = await formattedNavigationError(navError, path: "/")
-    let template = CPListTemplate(title: nil, sections: [])
-    template.emptyViewTitleVariants = [formatted.title]
-    template.emptyViewSubtitleVariants = formatted.message.flatMap { $0.isEmpty ? nil : [$0] } ?? []
-    interfaceController.safeSetRoot(template, animated: true)
+  /// Shows a simple error template as root (for initialization errors when no other template exists)
+  private func showErrorTemplate(message: String) {
+    // CPAlertTemplate cannot be set as root - use a list template instead
+    let errorItem = CPListItem(text: message, detailText: nil)
+    errorItem.isEnabled = false
+    let template = CPListTemplate(
+      title: "Error",
+      sections: [CPListSection(items: [errorItem])],
+    )
+    interfaceController.setRootTemplate(template, animated: true, completion: nil)
   }
 }
 
@@ -1286,30 +717,13 @@ private final class InterfaceControllerDelegate: NSObject, CPInterfaceController
   }
 
   func templateDidAppear(_ aTemplate: CPTemplate, animated _: Bool) {
-    // Popping back from Now Playing surfaces the tab bar (not a list), so the
-    // guard must let both through — the playing indicator was toggled while
-    // the list was covered, and this appearance is the moment to repaint it.
-    guard aTemplate is CPListTemplate || aTemplate is CPTabBarTemplate else { return }
-
-    // A tab change deferred while the user was browsing replaces the whole
-    // tab bar — no point updating a template that's about to be discarded.
-    if controller?.applyPendingTabsIfAtRoot() == true { return }
+    guard let listTemplate = aTemplate as? CPListTemplate else { return }
 
     // Update playing indicators when navigating back to a list template
     controller?.updatePlayingIndicators()
 
     // Lazy load content for tabs that haven't been loaded yet
-    if let listTemplate = aTemplate as? CPListTemplate {
-      controller?.loadContentIfNeeded(for: listTemplate)
-    }
-  }
-
-  func templateDidDisappear(_ aTemplate: CPTemplate, animated _: Bool) {
-    // The complement of the appear hook: whether popping Now Playing reports
-    // "tab bar appeared" or only "now playing disappeared" is a platform
-    // detail — cover both so the revealed list always repaints its indicator.
-    guard aTemplate is CPNowPlayingTemplate else { return }
-    controller?.updatePlayingIndicators()
+    controller?.loadContentIfNeeded(for: listTemplate)
   }
 }
 
@@ -1318,16 +732,12 @@ private final class InterfaceControllerDelegate: NSObject, CPInterfaceController
 private extension RNABCarPlayController {
   /// Loads content for a template if it hasn't been loaded yet (lazy loading for tabs)
   func loadContentIfNeeded(for template: CPListTemplate) {
+    // Skip if already has content
+    guard template.sections.isEmpty else { return }
+
     // Get path from userInfo
     guard let path = getPath(from: template) else { return }
 
-    // The template is now on screen, so a queued duplicate navigation to it is
-    // no longer a concern (the top-template check will catch any further taps).
-    navigatingPaths.remove(path)
-
-    // Skip if already has content (single-flight in loadContent guards re-entry).
-    guard template.sections.isEmpty else { return }
-
     logger.debug("Lazy loading content for tab: \(path)")
 
     Task {