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

package/ios/Browser/StyleResolver.swift

@@ -0,0 +1,47 @@
+#if canImport(NitroModules)
+  import NitroModules
+#endif
+
+/// The one place style declarations resolve to effective values (ADR 0011).
+///
+/// Two mechanisms, deliberately distinct:
+/// - **Inherited item properties** resolve `track ?? section ?? page`,
+///   per property — a track's own declaration wins over the blocks that
+///   contain it.
+/// - **Container properties and the positional `display`** resolve by scope
+///   override: `section ?? page` — the page declares for its whole scope, a
+///   section overrides for its own children. `display` is never inherited
+///   item-to-container: each holder describes its own children, and a
+///   track's `display` is the promise for the page *it* opens, not its
+///   rendering inside this section.
+///
+/// Every key of `SectionStyle` must be read by `sectionStyle(section:page:)`
+/// and every inherited key of `TrackStyle` by `trackStyle(track:section:)` —
+/// Nitro flattens the spec's `extends`, so `src/style-resolution.test.ts`
+/// enforces this completeness, not the type system.
+enum StyleResolver {
+  /// Folds the page block into a section's block: every `SectionStyle` key
+  /// resolves `section ?? page`. The result is the section's effective
+  /// block; item resolution then only needs `track ?? section`.
+  static func sectionStyle(section: SectionStyle?, page: SectionStyle?) -> SectionStyle {
+    // Argument order is the generated init's (own properties before inherited
+    // ones — Nitro flattens `extends` own-props-first); the stub mirrors it.
+    SectionStyle(
+      gridWrap: section?.gridWrap ?? page?.gridWrap,
+      display: section?.display ?? page?.display,
+      artworkRendering: section?.artworkRendering ?? page?.artworkRendering,
+    )
+  }
+
+  /// Resolves a track's effective item properties against its (page-folded)
+  /// section block.
+  static func trackStyle(track: TrackStyle?, section: SectionStyle?) -> TrackStyle {
+    TrackStyle(
+      // Positional deny-list: `display` is never inherited onto an item —
+      // resolved nil, so no renderer can mistake the handle's page promise
+      // for this item's own layout.
+      display: nil,
+      artworkRendering: track?.artworkRendering ?? section?.artworkRendering,
+    )
+  }
+}

package/ios/Browser/TabBarEntries.swift

@@ -1,6 +1,6 @@
 /// Compares the tab-list fields the CarPlay tab bar actually renders.
 enum TabBarEntries {
-  /// Whether two tab lists produce identical tab-bar entries — title, url,
+  /// Whether two tab lists produce identical tab-bar entries — title, path,
   /// and the artwork inputs of `applyTabBarEntry`. 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
@@ -8,7 +8,7 @@ enum TabBarEntries {
   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.url == $1.url && $0.artwork == $1.artwork
+      $0.title == $1.title && $0.path == $1.path && $0.artwork == $1.artwork
         && $0.artworkSource?.uri == $1.artworkSource?.uri
     }
   }

package/ios/Browser/TrackIdTemplate.swift

@@ -0,0 +1,37 @@
+import Foundation
+
+/// `{id}` template-token substitution for request-config string values (path, query values,
+/// header values), used by artwork URL resolution so a `nowPlayingArtwork` like
+/// `{ path: "/artwork/{id}" }` resolves per track.
+///
+/// A track without a non-blank id leaves the token LITERALLY in place — the request then
+/// visibly 404s, which is intended (garbage in, garbage out with a self-describing error
+/// trail; the caller logs a single warning when `containsToken` still matches after
+/// substitution). Mirrors Android's `substituteTrackId` / `configContainsIdToken` in
+/// `BrowserUrlResolution.kt` — keep the two in sync.
+enum TrackIdTemplate {
+  static let token = "{id}"
+
+  /// Replaces the token when `id` is non-blank; otherwise returns the value unchanged
+  /// (token left literal).
+  static func substitute(_ value: String?, id: String?) -> String? {
+    guard let id, !id.isEmpty else { return value }
+    return value?.replacingOccurrences(of: token, with: id)
+  }
+
+  /// Dictionary-value variant of `substitute` (query / header values).
+  static func substitute(_ values: [String: String]?, id: String?) -> [String: String]? {
+    guard let id, !id.isEmpty else { return values }
+    return values?.mapValues { $0.replacingOccurrences(of: token, with: id) }
+  }
+
+  /// Whether the value still carries the token (an unfilled `{id}`).
+  static func containsToken(_ value: String?) -> Bool {
+    value?.contains(token) == true
+  }
+
+  /// Whether any dictionary value still carries the token.
+  static func containsToken(_ values: [String: String]?) -> Bool {
+    values?.values.contains { $0.contains(token) } == true
+  }
+}

package/ios/CarPlay/CarPlayArtworkResolver.swift

@@ -29,7 +29,8 @@ enum CarPlayArtworkResolver {
   /// - Parameters:
   ///   - artwork: The track's `artwork` field (may be an SF Symbol string or URL)
   ///   - artworkSourceUri: The track's `artworkSource?.uri` field
-  ///   - artworkCarPlayTinted: Whether to apply light/dark tinting
+  ///   - stencil: Whether the artwork renders as a monochrome glyph tinted to
+  ///     the surface appearance (`style.artworkRendering: 'stencil'`)
   ///   - targetWidth: Target width in points
   ///   - targetHeight: Target height in points
   ///   - displayScale: The CarPlay display scale factor
@@ -37,7 +38,7 @@ enum CarPlayArtworkResolver {
   static func resolve(
     artwork: String?,
     artworkSourceUri: String?,
-    artworkCarPlayTinted: Bool?,
+    stencil: Bool,
     targetWidth: Double,
     targetHeight: Double,
     displayScale: Double,
@@ -57,7 +58,7 @@ enum CarPlayArtworkResolver {
           return resolveDirectFallback(
             artwork: artwork,
             artworkSourceUri: artworkSourceUri,
-            artworkCarPlayTinted: artworkCarPlayTinted,
+            stencil: stencil,
             targetWidth: targetWidth,
             targetHeight: targetHeight,
           )
@@ -66,7 +67,7 @@ enum CarPlayArtworkResolver {
         return .fetch(
           uri: resolved.uri,
           headers: resolved.headers,
-          shouldTint: artworkCarPlayTinted ?? false,
+          shouldTint: stencil,
           isSvg: isSvg,
         )
       }
@@ -76,7 +77,7 @@ enum CarPlayArtworkResolver {
     return resolveDirectFallback(
       artwork: artwork,
       artworkSourceUri: artworkSourceUri,
-      artworkCarPlayTinted: artworkCarPlayTinted,
+      stencil: stencil,
       targetWidth: targetWidth,
       targetHeight: targetHeight,
     )
@@ -85,7 +86,7 @@ enum CarPlayArtworkResolver {
   private static func resolveDirectFallback(
     artwork: String?,
     artworkSourceUri: String?,
-    artworkCarPlayTinted: Bool?,
+    stencil: Bool,
     targetWidth: Double,
     targetHeight: Double,
   ) -> ArtworkLoadAction {
@@ -100,7 +101,7 @@ enum CarPlayArtworkResolver {
     return .fetch(
       uri: directUri,
       headers: nil,
-      shouldTint: artworkCarPlayTinted ?? false,
+      shouldTint: stencil,
       isSvg: isSvg,
     )
   }

package/ios/CarPlay/CarPlayController.swift

@@ -89,21 +89,24 @@ public final class RNABCarPlayController: NSObject {
     audioBrowser?.browserManager.config ?? BrowserConfig()
   }
 
+  /// The configured list playing-indicator location, in CarPlay-framework terms.
+  private var playingIndicatorLocation: CPListItemPlayingIndicatorLocation {
+    switch audioBrowser?.carPlayPlayingIndicatorLocation {
+    case .trailing: .trailing
+    case .leading, nil: .leading
+    }
+  }
+
   /// Whether a list item identifies the currently active (loaded) track.
   ///
-  /// Identity is the stable `Track.id` when both sides carry one — the active
+  /// Compares track identities (`id` when non-blank, else `src`): the active
   /// track may have been loaded outside the browse tree (the consumer's own
   /// `load`/`setQueue`) with a `src` that differs textually from the browse
   /// row's (absolute vs relative, extra query params) while being the same
-  /// item. Exact `src` equality remains the fallback for consumers that don't
-  /// assign ids.
-  private func isActiveTrack(id: String?, src: String?) -> Bool {
-    guard let currentTrack = audioBrowser?.getPlayer()?.currentTrack else { return false }
-    if let id, !id.isEmpty, let currentId = currentTrack.id, !currentId.isEmpty {
-      return id == currentId
-    }
-    guard let src else { return false }
-    return currentTrack.src == src
+  /// item. A nil identity on either side never matches.
+  private func isActiveTrack(identity: String?) -> Bool {
+    guard let identity, let currentTrack = audioBrowser?.getPlayer()?.currentTrack else { return false }
+    return currentTrack.identity == identity
   }
 
   // MARK: - Initialization
@@ -118,8 +121,8 @@ public final class RNABCarPlayController: NSObject {
       self?.listItemFactory?.createListItem(for: track, handler: handler)
         ?? CPListItem(text: track.title, detailText: nil)
     }
-    nowPlayingManager.navigateToUrl = { [weak self] url, title in
-      Task { @MainActor in await self?.navigateToUrl(url, title: title) }
+    nowPlayingManager.navigateToPath = { [weak self] path, title in
+      Task { @MainActor in await self?.navigateToPath(path, title: title) }
     }
   }
 
@@ -178,12 +181,13 @@ public final class RNABCarPlayController: NSObject {
 
       // Create list item factory
       let factory = CarPlayListItemFactory(
-        isActiveTrack: { [weak self] id, src in self?.isActiveTrack(id: id, src: src) ?? false },
+        isActiveTrack: { [weak self] identity in self?.isActiveTrack(identity: identity) ?? false },
         onItemSelected: { [weak self] track, completion in
           self?.handleItemSelection(track: track, completion: completion)
         },
       )
       factory.imageLoader = self.imageLoader
+      factory.playingIndicatorLocation = self.playingIndicatorLocation
       self.listItemFactory = factory
 
       self.setupContentSubscriptions()
@@ -261,7 +265,7 @@ public final class RNABCarPlayController: NSObject {
     }
 
     // Subscribe to config changes (for Now Playing buttons and per-track
-    // button state — e.g. resolveAlbumUrl appearing/disappearing)
+    // button state — e.g. resolveAlbumPath appearing/disappearing)
     audioBrowser.browserManager.onConfigChanged = { [weak self] _ in
       Task { @MainActor in
         self?.nowPlayingManager.setupNowPlayingButtons()
@@ -269,13 +273,22 @@ public final class RNABCarPlayController: NSObject {
       }
     }
 
-    // Now-playing buttons + Up Next are runtime-updatable via updateOptions();
-    // refresh them when player options change (configureBrowser is no longer
-    // the only path that can change them).
+    // Now-playing buttons + Up Next + the list playing-indicator location are
+    // runtime-updatable via updateOptions(); refresh them when player options
+    // change (configureBrowser is no longer the only path that can change them).
     let optionsToken = audioBrowser.playerOptionsChangedEmitter.addListener { [weak self] in
       Task { @MainActor in
-        self?.nowPlayingManager.setupNowPlayingButtons()
-        self?.nowPlayingManager.updateNowPlayingButtonStates()
+        guard let self else { return }
+        self.nowPlayingManager.setupNowPlayingButtons()
+        self.nowPlayingManager.updateNowPlayingButtonStates()
+        // The factory's copy doubles as the last-applied value: sweep the
+        // templates only when the location actually changed, not on every
+        // updateOptions() call.
+        let location = self.playingIndicatorLocation
+        if let factory = self.listItemFactory, factory.playingIndicatorLocation != location {
+          factory.playingIndicatorLocation = location
+          self.updatePlayingIndicators()
+        }
       }
     }
     listenerRemovals.append { [weak audioBrowser] in
@@ -409,9 +422,7 @@ public final class RNABCarPlayController: NSObject {
   private func buildInitialInterface() async {
     guard let audioBrowser else {
       logger.error("AudioBrowser not available")
-      await showRootNavigationError(
-        NavigationError(code: .unknownError, message: "", statusCode: nil, statusCodeSuccess: nil),
-      )
+      await showRootNavigationError(.code(.unknownError))
       return
     }
 
@@ -430,16 +441,10 @@ public final class RNABCarPlayController: NSObject {
         showLoadingTemplate()
       }
       do {
+        // An empty query result routes to the .emptyContent error page inside
+        // showTabBar, shared with runtime tab changes.
         let queriedTabs = try await audioBrowser.browserManager.queryTabs()
-        if !queriedTabs.isEmpty {
-          await showTabBar(tabs: queriedTabs)
-        } else {
-          // Empty is a navigation error (.emptyContent) so it formats through
-          // the app's formatNavigationError like every other failure (ADR 0001).
-          await showRootNavigationError(
-            NavigationError(code: .emptyContent, message: "", statusCode: nil, statusCodeSuccess: nil),
-          )
-        }
+        await showTabBar(tabs: queriedTabs)
       } catch {
         logger.error("Failed to query tabs: \(error.localizedDescription)")
         await showRootNavigationError(NavigationError.from(error))
@@ -459,7 +464,13 @@ public final class RNABCarPlayController: NSObject {
   // MARK: - Tab Bar
 
   @MainActor
-  private func showTabBar(tabs: [Track]) async {
+  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 }
+
     // 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
@@ -473,6 +484,17 @@ 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
@@ -501,8 +523,8 @@ public final class RNABCarPlayController: NSObject {
     interfaceController.safeSetRoot(tabBar, animated: true)
 
     // Load content for the first tab only - others load lazily when selected
-    if let firstTemplate = tabTemplates.first, let firstTab = tabs.first, let url = firstTab.url {
-      await loadContent(for: url, into: firstTemplate)
+    if let firstTemplate = tabTemplates.first, let firstTab = tabs.first, let path = firstTab.path {
+      await loadContent(for: path, into: firstTemplate)
     }
   }
 
@@ -540,7 +562,7 @@ public final class RNABCarPlayController: NSObject {
     var templates: [CPListTemplate] = []
     for tab in limitedTabs {
       let outcome = await audioBrowser.gateDecision(
-        for: NativeGateRequest(reason: .browse, path: tab.url, search: nil),
+        for: NativeGateRequest(reason: .browse, path: tab.path, search: nil),
       )
       guard gateBuildGeneration == generation else { return } // superseded by a newer build
       if outcome.gated {
@@ -566,8 +588,8 @@ public final class RNABCarPlayController: NSObject {
     // Eagerly fill any allowed (content) tabs: templateDidAppear isn't
     // guaranteed to re-fire for templates swapped in via updateTemplates.
     for (tab, template) in zip(limitedTabs, templates) {
-      guard getPath(from: template) != nil, let url = tab.url else { continue }
-      await loadContent(for: url, into: template)
+      guard getPath(from: template) != nil, let path = tab.path else { continue }
+      await loadContent(for: path, into: template)
     }
   }
 
@@ -576,7 +598,7 @@ public final class RNABCarPlayController: NSObject {
   /// until its content lazy-loads on first appearance.
   private func createTabTemplate(for track: Track) -> CPListTemplate {
     // The path stored on the template drives lazy loading and refresh.
-    let template = makeLoadingTemplate(title: track.title, path: track.url)
+    let template = makeLoadingTemplate(title: track.title, path: track.path)
     applyTabBarEntry(to: template, for: track)
     return template
   }
@@ -682,14 +704,13 @@ public final class RNABCarPlayController: NSObject {
       // even with no rows — the "Ask Siri to Play" cell IS its content — so it
       // renders rather than falling through to the empty-content state.
       let hasAssistantCell = resolved.carPlaySiriListButton != nil
-      if resolved.children?.isEmpty ?? true, !hasAssistantCell {
+      // A page of empty sections is still empty.
+      let hasChildren = resolved.normalizedSections?.contains { !$0.children.isEmpty } ?? false
+      if !hasChildren, !hasAssistantCell {
         // Empty is modeled as a navigation error (code .emptyContent) so it goes
         // through the same path-aware formatter as failures — letting an app give
         // an empty Favorites tab different copy than an empty search. ADR 0001.
-        let empty = NavigationError(
-          code: .emptyContent, message: "", statusCode: nil, statusCodeSuccess: nil,
-        )
-        await showNavigationErrorView(empty, path: path, on: template)
+        await showNavigationErrorView(.code(.emptyContent), path: path, on: template)
       } else {
         updateTemplate(template, with: resolved)
       }
@@ -749,7 +770,7 @@ public final class RNABCarPlayController: NSObject {
     }
 
     // If this track is already loaded, resume playback and show Now Playing.
-    if track.src != nil, isActiveTrack(id: track.id, src: track.src) {
+    if track.src != nil, isActiveTrack(identity: track.identity) {
       try? audioBrowser.play()
       nowPlayingManager.showNowPlaying()
       completion()
@@ -777,7 +798,7 @@ public final class RNABCarPlayController: NSObject {
 
     // Release CarPlay immediately so the list never locks up. Apple's handler
     // guidance is to finish processing the tap promptly; for a browse we "finish"
-    // by pushing the destination and filling it in (see navigateToUrl), and for
+    // by pushing the destination and filling it in (see navigateToPath), and for
     // playback the Now Playing surface owns its own loading state.
     completion()
 
@@ -790,8 +811,8 @@ public final class RNABCarPlayController: NSObject {
         self.nowPlayingManager.showNowPlaying(popToFront: false)
       case .intercepted:
         self.nowPlayingManager.showNowPlaying(popToFront: false)
-      case let .browse(url):
-        await self.navigateToUrl(url, title: track.title)
+      case let .browse(path):
+        await self.navigateToPath(path, title: track.title)
       case .none:
         break
       }
@@ -809,24 +830,24 @@ public final class RNABCarPlayController: NSObject {
     }
   }
 
-  /// Pushes a browsable URL's destination immediately as an empty, spinning list
+  /// Pushes a browsable path's destination immediately as an empty, spinning list
   /// template — so the list the user tapped from is never blocked. The content is
   /// filled by `templateDidAppear` → `loadContentIfNeeded` → `loadContent`, which
   /// runs once the template is on screen (the timing CarPlay needs: updates made
   /// right after a push are dropped). Backing out and re-tapping retries.
   @MainActor
-  private func navigateToUrl(_ url: String, title: String) async {
+  private func navigateToPath(_ path: String, title: String) async {
     // The gate is resolved per-request: a gated path pushes the gate page
     // (with this request's chrome) instead of browsing into content; this also
     // blocks indirect entries like the Now Playing album line. An allowed path
     // browses normally even while a gate is active.
     if isGated, let audioBrowser {
       let outcome = await audioBrowser.gateDecision(
-        for: NativeGateRequest(reason: .browse, path: url, search: nil),
+        for: NativeGateRequest(reason: .browse, path: path, search: nil),
       )
       if outcome.gated {
         audioBrowser.onGate(GateEvent(reason: .browse))
-        if let top = interfaceController.topTemplate, getPath(from: top) == url { return }
+        if let top = interfaceController.topTemplate, getPath(from: top) == path { return }
         interfaceController.safePush(
           makeGateTemplate(gate: outcome.chrome, tab: nil), animated: true,
         )
@@ -834,24 +855,24 @@ public final class RNABCarPlayController: NSObject {
       }
     }
     // Avoid pushing a duplicate if the top template already shows this path.
-    if let top = interfaceController.topTemplate, getPath(from: top) == url {
+    if let top = interfaceController.topTemplate, getPath(from: top) == path {
       return
     }
     // …and guard a rapid double-tap whose first push hasn't appeared yet (so the
     // check above can't see it). Cleared when the pushed template appears.
-    guard !navigatingPaths.contains(url) else { return }
-    navigatingPaths.insert(url)
+    guard !navigatingPaths.contains(path) else { return }
+    navigatingPaths.insert(path)
 
-    let template = makeLoadingTemplate(title: title, path: url)
+    let template = makeLoadingTemplate(title: title, path: path)
     interfaceController.safePush(template, animated: true) { [weak self] pushed, error in
       guard !pushed else { return }
       // The push can fail (e.g. CarPlay's template stack depth limit). The
       // appear callback that normally clears the guard will never fire, so
       // clear it here — otherwise the destination stays unreachable until
       // CarPlay reconnects.
-      self?.navigatingPaths.remove(url)
+      self?.navigatingPaths.remove(path)
       if let error {
-        self?.logger.error("pushTemplate failed for \(url): \(error.localizedDescription)")
+        self?.logger.error("pushTemplate failed for \(path): \(error.localizedDescription)")
       }
     }
   }
@@ -930,14 +951,14 @@ 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
+    // Same tabs by path while ungated → only the tab-bar entries changed
     // (e.g. titles after a locale switch): restamp them in place. No rebuild,
     // so the selected tab and any pushed navigation stack survive. (Gate
     // templates carry no path, so a gated tab bar never matches here.)
     if !isGated,
        let tabBar = interfaceController.rootTemplate as? CPTabBarTemplate,
        tabBar.templates.count == min(tabs.count, CPTabBarTemplate.maximumTabCount),
-       zip(tabBar.templates, tabs).allSatisfy({ getPath(from: $0) == $1.url })
+       zip(tabBar.templates, tabs).allSatisfy({ getPath(from: $0) == $1.path })
     {
       for (template, tab) in zip(tabBar.templates, tabs) {
         applyTabBarEntry(to: template, for: tab)
@@ -978,7 +999,7 @@ public final class RNABCarPlayController: NSObject {
     // This callback fires when the main browser's content changes.
     // For CarPlay-specific refreshes (e.g., favorites), use notifyContentChanged instead.
     guard let content else { return }
-    refreshTemplatesForPath(content.url, with: content)
+    refreshTemplatesForPath(content.path, with: content)
   }
 
   @MainActor
@@ -990,9 +1011,11 @@ public final class RNABCarPlayController: NSObject {
     nowPlayingManager.handleActiveTrackChanged()
   }
 
-  /// Updates the isPlaying state on all list items based on the current active track.
+  /// Updates the isPlaying state (and indicator location, which options can
+  /// change at runtime) on all list items based on the current active track.
   @MainActor
   fileprivate func updatePlayingIndicators() {
+    let location = playingIndicatorLocation
     var templates: [CPListTemplate] = []
 
     if let tabBar = interfaceController.rootTemplate as? CPTabBarTemplate {
@@ -1015,16 +1038,20 @@ public final class RNABCarPlayController: NSObject {
         for item in section.items {
           guard let listItem = item as? CPListItem,
                 let info = listItem.carPlayItemInfo,
-                info.src != nil
+                info.identity != nil
           else { continue }
 
-          let isPlaying = isActiveTrack(id: info.id, src: info.src)
+          let isPlaying = isActiveTrack(identity: info.identity)
           if listItem.isPlaying != isPlaying {
             logger.debug(
-              "Updating isPlaying for \(info.id ?? info.src ?? ""): \(listItem.isPlaying) → \(isPlaying)")
+              "Updating isPlaying for \(info.identity ?? ""): \(listItem.isPlaying) → \(isPlaying)")
             listItem.isPlaying = isPlaying
             templateChanged = true
           }
+          if listItem.playingIndicatorLocation != location {
+            listItem.playingIndicatorLocation = location
+            templateChanged = true
+          }
         }
       }
       // Setting isPlaying on an already-displayed item does not reliably reach
@@ -1336,12 +1363,23 @@ private extension RNABCarPlayController {
   }
 }
 
+// MARK: - NavigationError Shorthand
+
+extension NavigationError {
+  /// A code-only error: the user-facing copy comes from the app's
+  /// formatNavigationError (ADR 0001), so no message travels with it.
+  static func code(_ code: NavigationErrorType) -> NavigationError {
+    NavigationError(code: code, message: "", statusCode: nil, statusCodeSuccess: nil)
+  }
+}
+
 // MARK: - UIImage Resize
 
 extension UIImage {
-  /// Draws the image centered within the target size, maintaining aspect ratio
-  func resized(to targetSize: CGSize) -> UIImage? {
-    UIGraphicsBeginImageContextWithOptions(targetSize, false, 0.0)
+  /// Draws the image centered within the target size, maintaining aspect
+  /// ratio, at the given display scale (the car screen's, not the phone's).
+  func resized(to targetSize: CGSize, scale: CGFloat) -> UIImage? {
+    UIGraphicsBeginImageContextWithOptions(targetSize, false, scale)
     defer { UIGraphicsEndImageContext() }
 
     // Scale to fit while maintaining aspect ratio