react-native-audio-browser 0.2.0-next.27 → 0.2.0-next.29

package/ios/CarPlay/CarPlaySession+Navigator.swift

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

package/ios/CarPlay/CarPlaySession+PageLoader.swift

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

package/ios/CarPlay/CarPlaySession+Refresher.swift

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

package/ios/CarPlay/CarPlaySession+TabBar.swift

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

package/ios/CarPlay/CarPlaySession.swift

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