react-native-audio-browser 0.2.0-next.34 → 0.2.0-next.35

package/ios/CarPlay/CPInterfaceController+Safe.swift

@@ -111,13 +111,6 @@ extension CPInterfaceController {
     }
   }
 
-  /// Pops the top template, skipping the raise case (nothing above the root).
-  func safePop(animated: Bool, completion: ((Bool, Error?) -> Void)? = nil) {
-    whenStackSettled { controller in
-      controller.guardedPop(animated: animated, completion: completion)
-    }
-  }
-
   /// Pops back to `template`, skipping the raise case (not in the hierarchy).
   /// A no-op success when it is already the top template.
   func safePop(to template: CPTemplate, animated: Bool, completion: ((Bool, Error?) -> Void)? = nil) {

package/ios/CarPlay/CarPlayController.swift

@@ -8,12 +8,6 @@ import os.log
 @MainActor
 @objc(RNABCarPlayController)
 public final class RNABCarPlayController: NSObject {
-  /// The Siri handlers `RNABAudioBrowser.m` looks up by name, referenced so a static link
-  /// keeps them.
-  @objc public static let siriIntentHandlerClasses: [AnyClass] = [
-    RNABMediaIntentHandler.self, RNABMediaAffinityHandler.self, RNABMediaAddHandler.self,
-  ]
-
   private let logger = Logger(subsystem: "com.audiobrowser", category: "CarPlayController")
   private let interfaceController: CPInterfaceController
   private var interfaceDelegate: InterfaceControllerDelegate?

package/ios/CarPlay/CarPlayImageLoader.swift

@@ -6,7 +6,7 @@ import os.log
 /// Handles all image loading and rendering for CarPlay.
 ///
 /// Responsibilities:
-/// - SF Symbol rendering (plain and canvas-rendered with light/dark variants)
+/// - SF Symbol rendering, with light/dark variants
 /// - Artwork loading via BrowserManager's artwork URL resolution
 /// - Direct artwork loading as fallback
 /// - Adaptive image tinting for monochrome icons
@@ -25,15 +25,10 @@ final class CarPlayImageLoader {
 
   // MARK: - SF Symbols
 
-  /// Creates an SF Symbol image for tabs - plain systemName, CarPlay handles tinting
-  func sfSymbolImage(_ symbolName: String) -> UIImage? {
-    UIImage(systemName: symbolName)
-  }
-
   /// Renders an SF Symbol from an artwork string (e.g. "sf:heart.fill?bg=#000&fg=#fff"). With an
   /// `fg` it is drawn in that color; without one it is black or white by appearance, over a grey
   /// tile.
-  func sfSymbolImage(forArtwork artwork: String, canvasSize: CGSize) -> UIImage? {
+  private func sfSymbolImage(forArtwork artwork: String, canvasSize: CGSize) -> UIImage? {
     let (name, background, tint) = SFSymbolRenderer.parseArtwork(artwork)
     let scale = carTraitCollection.displayScale
     let lightTile = UIColor(white: 0.92, alpha: 1)
@@ -72,104 +67,56 @@ final class CarPlayImageLoader {
 
   // MARK: - Artwork Loading
 
-  /// Loads artwork for a track with size context, using the artwork transform if configured.
-  /// - Parameters:
-  ///   - track: The track to load artwork for
-  ///   - style: The track's resolved style block (inherited values folded in).
-  ///     nil = the track's own declaration — callers without a section context
-  ///     (tabs, now-playing) have no inheritance to resolve.
-  ///   - size: The target size in points (will be multiplied by CarPlay display scale)
-  ///   - completion: Called with the loaded image, or nil on failure
-  func loadArtwork(for track: Track, style: TrackStyle? = nil, size: CGSize, completion: @escaping @Sendable (UIImage?) -> Void) {
-    // A track that ships one image per appearance is loaded as two ordinary
-    // single-URL loads and combined below. Recursing rather than branching
-    // inside the loader means each variant still goes through the whole
-    // pipeline — route config, headers, SVG rasterising, the resolve transform
-    // — instead of a second, thinner fetch path that would drift from it.
+  /// A track's artwork at `size` points, through the artwork transform when one is configured;
+  /// nil when it has none or the load fails.
+  /// - Parameter style: the track's resolved style block; nil for the track's own declaration,
+  ///   when there is no section to inherit from (tabs, Up Next).
+  func artwork(for track: Track, style: TrackStyle? = nil, size: CGSize) async -> UIImage? {
+    // Each variant goes through the whole single-URL path (route config, headers, SVG, the
+    // resolve transform), so the pair cannot drift from it.
     if let variants = track.artwork?.variants {
-      loadVariants(for: track, style: style, variants: variants, size: size, completion: completion)
-      return
+      return await artwork(for: track, style: style, variants: variants, size: size)
     }
 
     let artwork = track.artwork?.url
-    Task {
-      var resolved: ArtworkResolvedImage?
-      if CarPlayArtworkResolver.needsResolve(artwork: artwork), let browserManager = self.browserManager {
-        let scale = Double(self.carTraitCollection.displayScale)
-        let context = ImageContext(width: Double(size.width) * scale, height: Double(size.height) * scale)
-        resolved = await browserManager.requests.resolveArtworkUrl(track: track, perRouteConfig: nil, imageContext: context)
-          .map { ArtworkResolvedImage(uri: $0.uri, headers: $0.headers) }
-      }
-      let action = CarPlayArtworkResolver.action(
-        artwork: artwork,
-        artworkSource: track.artworkSource.map { ArtworkResolvedImage(uri: $0.uri, headers: $0.headers) },
-        resolved: resolved,
-        stencil: (style ?? track.style)?.artworkRendering == .stencil,
-        width: Double(size.width),
-        height: Double(size.height),
-      )
+    var resolved: ArtworkResolvedImage?
+    if CarPlayArtworkResolver.needsResolve(artwork: artwork), let browserManager {
+      let scale = Double(carTraitCollection.displayScale)
+      let context = ImageContext(width: Double(size.width) * scale, height: Double(size.height) * scale)
+      resolved = await browserManager.requests.resolveArtworkUrl(track: track, perRouteConfig: nil, imageContext: context)
+        .map { ArtworkResolvedImage(uri: $0.uri, headers: $0.headers) }
+    }
+    let action = CarPlayArtworkResolver.action(
+      artwork: artwork,
+      artworkSource: track.artworkSource.map { ArtworkResolvedImage(uri: $0.uri, headers: $0.headers) },
+      resolved: resolved,
+      stencil: (style ?? track.style)?.artworkRendering == .stencil,
+      width: Double(size.width),
+      height: Double(size.height),
+    )
 
-      switch action {
-      case let .sfSymbol(artwork, width, height):
-        completion(self.sfSymbolImage(forArtwork: artwork, canvasSize: CGSize(width: width, height: height)))
-      case let .fetch(uri, headers, shouldTint, isSvg):
-        let image = await self.fetchImage(uri: uri, headers: headers, isSvg: isSvg, size: size)
-        if let image, shouldTint {
-          completion(self.createAdaptiveImage(image, carTraitCollection: self.carTraitCollection))
-        } else {
-          completion(image)
-        }
-      case .none:
-        completion(nil)
-      }
+    switch action {
+    case let .sfSymbol(artwork, width, height):
+      return sfSymbolImage(forArtwork: artwork, canvasSize: CGSize(width: width, height: height))
+    case let .fetch(uri, headers, shouldTint, isSvg):
+      let image = await fetchImage(uri: uri, headers: headers, isSvg: isSvg, size: size)
+      guard let image, shouldTint else { return image }
+      return tinted(image)
+    case .none:
+      return nil
     }
   }
 
   // MARK: - Private
 
-  /// Loads both images of an `ArtworkVariants` pair and returns them as one
-  /// adaptive image.
-  ///
-  /// The pair is registered on a `UIImageAsset`, which is what makes an
-  /// appearance change mid-drive re-resolve in place: CarPlay re-reads the
-  /// asset against the new trait collection, so the row swaps image without
-  /// another fetch or a re-query of the browse tree.
-  ///
-  /// If either half fails to load, the other is used alone rather than dropping
-  /// the row's image entirely — a glyph that is wrong for one appearance still
-  /// beats an empty slot, and this is usually a transient fetch failure.
-  private func loadVariants(
-    for track: Track,
-    style: TrackStyle?,
-    variants: ArtworkVariants,
-    size: CGSize,
-    completion: @escaping @Sendable (UIImage?) -> Void,
-  ) {
-    Task {
-      async let light = self.loadArtworkAsync(
-        for: track.copying(artwork: .some(.first(variants.light))), style: style, size: size,
-      )
-      async let dark = self.loadArtworkAsync(
-        for: track.copying(artwork: .some(.first(variants.dark))), style: style, size: size,
-      )
-      let (lightImage, darkImage) = await (light, dark)
-
-      guard let lightImage, let darkImage else {
-        completion(lightImage ?? darkImage)
-        return
-      }
-
-      completion(.adaptive(light: lightImage, dark: darkImage, for: self.carTraitCollection))
-    }
-  }
-
-  /// `loadArtwork` as an awaitable, so the two variants can load concurrently.
-  private func loadArtworkAsync(for track: Track, style: TrackStyle?, size: CGSize) async -> UIImage? {
-    await withCheckedContinuation { continuation in
-      self.loadArtwork(for: track, style: style, size: size) { image in
-        continuation.resume(returning: image)
-      }
-    }
+  /// Both images of an `ArtworkVariants` pair as one adaptive image, which CarPlay re-resolves
+  /// in place when the appearance changes. When one half fails, the other is used alone.
+  private func artwork(for track: Track, style: TrackStyle?, variants: ArtworkVariants, size: CGSize) async -> UIImage? {
+    async let light = artwork(for: track.copying(artwork: .some(.first(variants.light))), style: style, size: size)
+    async let dark = artwork(for: track.copying(artwork: .some(.first(variants.dark))), style: style, size: size)
+    let (lightImage, darkImage) = await (light, dark)
+    guard let lightImage, let darkImage else { return lightImage ?? darkImage }
+    return .adaptive(light: lightImage, dark: darkImage, for: carTraitCollection)
   }
 
   /// Fetches an image from a URL with optional headers and SVG processing.
@@ -199,8 +146,8 @@ final class CarPlayImageLoader {
     return rendered.withRenderingMode(.alwaysOriginal)
   }
 
-  /// Creates light/dark tinted variants of an image and returns the appropriate one for current appearance
-  private nonisolated func createAdaptiveImage(_ image: UIImage, carTraitCollection: UITraitCollection) -> UIImage {
+  /// A monochrome image drawn black for light appearance and white for dark.
+  private func tinted(_ image: UIImage) -> UIImage {
     .adaptive(
       light: renderImageToBitmap(image, tintColor: .black),
       dark: renderImageToBitmap(image, tintColor: .white),

package/ios/CarPlay/CarPlayListItemFactory.swift

@@ -29,18 +29,42 @@ extension CPListItem {
 final class CarPlayListItemFactory {
   private let logger = Logger(subsystem: "com.audiobrowser", category: "CarPlayListItemFactory")
 
-  var imageLoader: CarPlayImageLoader?
-  /// Pushed by the controller (at creation and when options change), like
-  /// `imageLoader` — the factory never reads options itself.
-  var playingIndicatorLocation: CPListItemPlayingIndicatorLocation = .leading
+  private let imageLoader: CarPlayImageLoader
+  /// The last-applied location; the factory never reads options itself.
+  var playingIndicatorLocation: CPListItemPlayingIndicatorLocation
   private let isActiveTrack: (_ identity: String?) -> Bool
+  /// Runs an artwork load as a task the session owns, so ending the session cancels it.
+  private let spawn: (@escaping @MainActor () async -> Void) -> Void
   /// A row or tile was tapped; call `completion` once CarPlay may take the next tap.
-  var onItemSelected: (Track, @escaping () -> Void) -> Void = { _, completion in completion() }
+  private let onItemSelected: (Track, @escaping () -> Void) -> Void
   /// A section header's "view all" was tapped.
-  var onNavigate: (_ path: String, _ title: String) -> Void = { _, _ in }
-
-  init(isActiveTrack: @escaping (_ identity: String?) -> Bool) {
+  private let onNavigate: (_ path: String, _ title: String) -> Void
+
+  init(
+    imageLoader: CarPlayImageLoader,
+    playingIndicatorLocation: CPListItemPlayingIndicatorLocation,
+    isActiveTrack: @escaping (_ identity: String?) -> Bool,
+    spawn: @escaping (@escaping @MainActor () async -> Void) -> Void,
+    onItemSelected: @escaping (Track, @escaping () -> Void) -> Void,
+    onNavigate: @escaping (_ path: String, _ title: String) -> Void,
+  ) {
+    self.imageLoader = imageLoader
+    self.playingIndicatorLocation = playingIndicatorLocation
     self.isActiveTrack = isActiveTrack
+    self.spawn = spawn
+    self.onItemSelected = onItemSelected
+    self.onNavigate = onNavigate
+  }
+
+  /// Loads `track`'s artwork and hands it to `apply` unless the session ended meanwhile.
+  private func loadArtwork(
+    for track: Track, style: TrackStyle?, size: CGSize, apply: @escaping @MainActor (UIImage?) -> Void,
+  ) {
+    spawn { [imageLoader] in
+      let image = await imageLoader.artwork(for: track, style: style, size: size)
+      guard !Task.isCancelled else { return }
+      apply(image)
+    }
   }
 
   // MARK: - Sections
@@ -117,14 +141,11 @@ final class CarPlayListItemFactory {
 
   // MARK: - List Item
 
-  /// Creates a CPListItem for a track with common setup (typed userInfo, artwork, isPlaying).
+  /// A list row for `track`: its identity, accessory, playing flag, artwork and tap handler.
   /// - Parameters:
-  ///   - track: The track to create the item for
-  ///   - style: The track's resolved style block (`track ?? section ?? page`,
-  ///     via `StyleResolver`). nil = the track's own declaration — the one
-  ///     genuinely section-less caller (the Up Next queue list) has no
-  ///     inheritance to resolve.
-  ///   - handler: Optional custom handler. If nil, uses default browse/play handling.
+  ///   - style: The track's resolved style block (`track ?? section ?? page`); nil for the
+  ///     track's own declaration, when there is no section (Up Next).
+  ///   - handler: Replaces the default browse or play on tap.
   func createListItem(
     for track: Track,
     style: TrackStyle? = nil,
@@ -135,26 +156,18 @@ final class CarPlayListItemFactory {
       detailText: track.subtitle,
     )
 
-    // Store typed info for updatePlayingIndicators()
     item.setCarPlayItemInfo(CarPlayItemInfo(identity: track.identity))
 
-    // Set accessory type based on whether track is browsable or playable
     if let src = track.src {
-      // Playable track - check if it's currently playing
       item.accessoryType = .none
-      // Consumer-configurable via `ios.carPlayPlayingIndicatorLocation`
-      // (default leading: the indicator draws in the artwork slot). Note the
-      // indicator's rendering is owned by the phone's CarPlay service, and on
-      // some iOS/CarPlay-Simulator combinations it isn't drawn at all — for
-      // ANY third-party app. Verify on a real head unit before assuming a
-      // logic bug here.
+      // The phone's CarPlay service draws the indicator, and some iOS and CarPlay Simulator
+      // combinations draw none for any app: check a real head unit before suspecting this code.
       item.playingIndicatorLocation = playingIndicatorLocation
       item.isPlaying = isActiveTrack(track.identity)
       if item.isPlaying {
         logger.debug("Setting isPlaying=true for: \(track.title) (src: \(src))")
       }
     } else if track.path != nil {
-      // Browsable only - show disclosure indicator
       item.accessoryType = .disclosureIndicator
     }
 
@@ -176,21 +189,15 @@ final class CarPlayListItemFactory {
       item.isEnabled = false
     }
 
-    // Load artwork with size context for proper CDN optimization
     if track.artwork != nil || track.artworkSource != nil {
-      // Set empty placeholder to reserve space while loading
-      item.setImage(imageLoader?.placeholderImage(size: CPListItem.maximumImageSize))
-      imageLoader?.loadArtwork(for: track, style: style, size: CPListItem.maximumImageSize) { [weak item] image in
-        Task { @MainActor in
-          item?.setImage(image)
-        }
+      item.setImage(imageLoader.placeholderImage(size: CPListItem.maximumImageSize))
+      loadArtwork(for: track, style: style, size: CPListItem.maximumImageSize) { [weak item] image in
+        item?.setImage(image)
       }
     }
 
-    // Set selection handler. The disabled guard wraps BOTH handler paths —
-    // custom handlers (Up Next rows skipping the queue, say) included: belt
-    // over the isEnabled braces, so an unavailable track stays inert even if
-    // a surface delivers the tap.
+    // The disabled guard wraps custom handlers too (Up Next rows), so an unavailable track
+    // stays inert even if a surface delivers the tap.
     let selection = handler ?? { [onItemSelected] _, completion in
       onItemSelected(track, completion)
     }
@@ -268,50 +275,40 @@ final class CarPlayListItemFactory {
       ? Array(visibleChildren.prefix(CPMaximumNumberOfGridImages))
       : visibleChildren
     let placeholder = { [imageLoader] in
-      imageLoader?.placeholderImage(size: Self.rowImageSize) ?? UIImage()
+      imageLoader.placeholderImage(size: Self.rowImageSize) ?? UIImage()
     }
 
     let item: CPListImageRowItem
-    // Applies an async-loaded artwork image to a tile on the element-based
-    // API (the elements are captured per availability branch — their type
-    // doesn't exist before iOS 26). nil = the legacy gridImages path.
-    // @MainActor makes the closure Sendable for the artwork completion hop.
-    var applyImage: (@MainActor @Sendable (Int, UIImage) -> Void)?
-    // Resolved once per track, shared by element construction and the
-    // artwork loads below.
+    // Sets a loaded image on its tile's element; nil on the legacy gridImages path, which has
+    // no elements (their types do not exist before iOS 26).
+    var applyImage: (@MainActor (Int, UIImage) -> Void)?
     let resolvedStyles = tracks.map { StyleResolver.trackStyle(track: $0.style, section: style) }
     if #available(iOS 26.0, *) {
-      // Builds a family's elements with the shared per-element tail: the
-      // disabled fact (isEnabled lives on the element base class) applied
-      // once, not per family.
-      func makeElements<Element: CPListImageRowItemElement>(
-        _ make: (Track, TrackStyle) -> Element,
-      ) -> [Element] {
-        zip(tracks, resolvedStyles).map { track, resolved in
+      // One element per track, grayed when disabled, built into the row by the family's
+      // initializer; each tile's image lands on its element.
+      func row<Element: CPListImageRowItemElement>(
+        _ build: (String?, [Element], Bool) -> CPListImageRowItem,
+        element make: (Track, TrackStyle) -> Element,
+      ) -> CPListImageRowItem {
+        let elements = zip(tracks, resolvedStyles).map { track, resolved in
           let element = make(track, resolved)
           if track.disabled == true {
             element.isEnabled = false
           }
           return element
         }
-      }
-      // The image setter every element family shares (`image` is on the base
-      // class); bounds-checked against the elements the row was built with.
-      func imageApplier(_ elements: [some CPListImageRowItemElement]) -> @MainActor @Sendable (Int, UIImage) -> Void {
-        { index, image in
+        applyImage = { index, image in
           guard index < elements.count else { return }
           elements[index].image = image
         }
+        return build(rowText, elements, !singleLine)
       }
-      // The family is style-driven (`SectionPresentation.tileFamily`); every
-      // family takes either wrap mode. Pre-26 the treatment drops and the
-      // layout survives (the legacy branch below).
+      // Pre-26 the family's treatment drops and the layout survives (the legacy branch below).
       switch family {
       case .cardElements:
-        // Cards have no shape and no accessory slot; their knobs are the
-        // tint and the image mode ('background' fills the card full-height
-        // and fades the tint in behind the labels).
-        let elements = makeElements { track, resolved in
+        // Cards have no shape and no accessory slot; 'background' fills the card full-height
+        // and fades the tint in behind the labels.
+        item = row(CPListImageRowItem.init(text:cardElements:allowsMultipleLines:)) { track, resolved in
           CPListImageRowItemCardElement(
             image: placeholder(),
             showsImageFullHeight: resolved.cardImage == .background,
@@ -320,12 +317,8 @@ final class CarPlayListItemFactory {
             tintColor: resolved.cardTint.flatMap { UIColor(declaredHex: $0) },
           )
         }
-        item = CPListImageRowItem(
-          text: rowText, cardElements: elements, allowsMultipleLines: !singleLine,
-        )
-        applyImage = imageApplier(elements)
       case .condensedElements:
-        let elements = makeElements { track, resolved in
+        item = row(CPListImageRowItem.init(text:condensedElements:allowsMultipleLines:)) { track, resolved in
           CPListImageRowItemCondensedElement(
             image: placeholder(),
             imageShape: resolved.imageShape == .circular ? .circular : .roundedRectangle,
@@ -334,14 +327,10 @@ final class CarPlayListItemFactory {
             accessorySymbolName: SectionPresentation.effectiveAccessorySymbol(resolved),
           )
         }
-        item = CPListImageRowItem(
-          text: rowText, condensedElements: elements, allowsMultipleLines: !singleLine,
-        )
-        applyImage = imageApplier(elements)
       case .imageGridElements:
         // imageGridElements, never the title-less gridElements: an
         // artwork-less track must keep its name on screen (ADR 0010).
-        let elements = makeElements { track, resolved in
+        item = row(CPListImageRowItem.init(text:imageGridElements:allowsMultipleLines:)) { track, resolved in
           CPListImageRowItemImageGridElement(
             image: placeholder(),
             imageShape: resolved.imageShape == .circular ? .circular : .roundedRectangle,
@@ -349,22 +338,14 @@ final class CarPlayListItemFactory {
             accessorySymbolName: SectionPresentation.effectiveAccessorySymbol(resolved),
           )
         }
-        item = CPListImageRowItem(
-          text: rowText, imageGridElements: elements, allowsMultipleLines: !singleLine,
-        )
-        applyImage = imageApplier(elements)
       case .rowElements:
         // Titled, so an artwork-less track keeps its name on screen
         // (ADR 0010); no shape and no accessory slot.
-        let elements = makeElements { track, _ in
+        item = row(CPListImageRowItem.init(text:elements:allowsMultipleLines:)) { track, _ in
           CPListImageRowItemRowElement(
             image: placeholder(), title: track.title, subtitle: track.subtitle,
           )
         }
-        item = CPListImageRowItem(
-          text: rowText, elements: elements, allowsMultipleLines: !singleLine,
-        )
-        applyImage = imageApplier(elements)
       }
     } else {
       let placeholders = tracks.map { _ in placeholder() }
@@ -386,9 +367,8 @@ final class CarPlayListItemFactory {
       }
     }
 
-    // Per-tile taps select the child track directly. A disabled tile is
-    // grayed and inert (26+ elements) — the guard keeps it inert even if
-    // the surface delivers the tap anyway.
+    // A disabled tile is grayed and inert (iOS 26 elements); the guard keeps it inert even if
+    // the surface delivers the tap.
     item.listImageRowHandler = { [onItemSelected] _, index, completion in
       guard index < tracks.count, tracks[index].disabled != true else {
         completion()
@@ -397,28 +377,23 @@ final class CarPlayListItemFactory {
       onItemSelected(tracks[index], completion)
     }
 
-    // Load artwork for each rendered tile asynchronously
     for (index, track) in tracks.enumerated() {
       guard track.artwork != nil || track.artworkSource != nil else { continue }
 
       let resolved = resolvedStyles[index]
-      imageLoader?.loadArtwork(
+      loadArtwork(
         for: track,
         style: resolved,
         size: Self.tileImageSize(family: family, cardImage: resolved.cardImage),
       ) { [weak item, applyImage] image in
-        Task { @MainActor in
-          guard let item, let image else { return }
-          if let applyImage {
-            // The element-based API exposes a settable `image`; assigning it
-            // updates the element the row observes.
-            applyImage(index, image)
-          } else {
-            var images = item.gridImages
-            if index < images.count {
-              images[index] = image
-              item.update(images)
-            }
+        guard let item, let image else { return }
+        if let applyImage {
+          applyImage(index, image)
+        } else {
+          var images = item.gridImages
+          if index < images.count {
+            images[index] = image
+            item.update(images)
           }
         }
       }

package/ios/CarPlay/CarPlayNowPlayingManager.swift

@@ -19,20 +19,12 @@ final class CarPlayNowPlayingManager {
   private var subscriptions: [Subscription] = []
   private var nowPlayingObserver: NowPlayingObserver?
   private weak var upNextTemplate: CPListTemplate?
-  /// Everything the built button row renders — button types, the heart's
-  /// favorited state, and the shuffle/repeat `isSelected` state. Rebuilds are
-  /// skipped while this is unchanged (`configChanged` fires on unrelated
-  /// churn, and every `updateNowPlayingButtons` call re-renders ALL buttons).
+  /// What the built button row renders. A rebuild is skipped while it is unchanged: every
+  /// `updateNowPlayingButtons` re-renders all the buttons.
   ///
-  /// shuffle/repeat selected state is part of the snapshot because CarPlay
-  /// SERIALIZES the buttons (NSSecureCoding) to its UI process: whenever the
-  /// now-playing screen re-renders (it does on every metadata change), the
-  /// stateful buttons first draw from their serialized `isSelected`, and only
-  /// then overlay the live state the app reports via the command center. A
-  /// button built with the default `isSelected = false` while repeat/shuffle
-  /// is on therefore flashes background-off → background-on at every
-  /// re-render. Stamping `isSelected` at build time (and rebuilding when the
-  /// mode changes) makes the first-frame render match the live state.
+  /// Shuffle and repeat carry their `isSelected` because CarPlay serializes the buttons to its
+  /// UI process and draws each re-render from the serialized state before the live one: a
+  /// button built unselected while its mode is on flashes off, then on.
   private struct BuiltButtonRow: Equatable {
     let types: [CarPlayNowPlayingButton]
     let favorited: Bool?
@@ -131,16 +123,9 @@ final class CarPlayNowPlayingManager {
   private func refreshButtons() {
     // A gate hides the custom buttons; the transport controls stay, as a gate never blocks
     // playback.
-    let configured = audioBrowser.browseGate.isActive ? [] : audioBrowser.playerOptions.carPlayNowPlayingButtons
-    // The template caps custom buttons at 5 (CPNowPlayingTemplate.h) and says
-    // nothing about overflow — unlike lists (trim) or the tab bar (throw). The
-    // config comes straight from JS, where duplicates and excess are
-    // representable, so dedupe (order preserved) and clamp here.
-    var deduped: [CarPlayNowPlayingButton] = []
-    for button in configured where !deduped.contains(button) {
-      deduped.append(button)
-    }
-    let buttons = Array(deduped.prefix(5))
+    let buttons = NowPlayingButtonRules.buttons(
+      audioBrowser.browseGate.isActive ? [] : audioBrowser.playerOptions.carPlayNowPlayingButtons,
+    )
     let row = BuiltButtonRow(
       types: buttons,
       favorited: buttons.contains(.favorite) ? audioBrowser.isActiveTrackFavorited() : nil,
@@ -296,15 +281,7 @@ final class CarPlayNowPlayingManager {
   private func handleRepeatButtonTapped() {
     guard let player else { return }
     let currentMode = player.repeatMode
-    let newMode: RepeatMode = switch currentMode {
-    case .off:
-      .track
-    case .track:
-      .queue
-    case .queue:
-      .off
-    }
-
+    let newMode = NowPlayingButtonRules.repeatMode(after: currentMode)
     player.repeatMode = newMode
     logger.info("CarPlay repeat mode changed: \(currentMode.stringValue) → \(newMode.stringValue)")
   }
@@ -319,19 +296,9 @@ final class CarPlayNowPlayingManager {
   }
 
   private func handlePlaybackRateButtonTapped() {
-    let rates = audioBrowser.playerOptions.playbackRates
-    guard !rates.isEmpty, let player else { return }
-
+    guard let player else { return }
     let currentRate = Double(player.rate)
-    let nextRate: Double
-
-    if let currentIndex = rates.firstIndex(where: { (currentRate - $0).magnitude < 0.01 }) {
-      let nextIndex = (currentIndex + 1) % rates.count
-      nextRate = rates[nextIndex]
-    } else {
-      nextRate = rates.first { $0 > currentRate } ?? rates[0]
-    }
-
+    guard let nextRate = NowPlayingButtonRules.rate(after: currentRate, in: audioBrowser.playerOptions.playbackRates) else { return }
     player.rate = Float(nextRate)
     logger.info("CarPlay playback rate changed: \(currentRate) → \(nextRate)")
   }

package/ios/CarPlay/CarPlaySession+Navigator.swift

@@ -22,7 +22,7 @@ extension CarPlaySession {
     // 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)
+      player?.previewNowPlaying(track)
       nowPlaying.prepare(for: track)
       nowPlaying.showNowPlaying()
     }
@@ -32,7 +32,7 @@ extension CarPlaySession {
       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() }
+        if track.src != nil { session.player?.endNowPlayingPreview() }
         return
       }
       switch result {
@@ -49,17 +49,6 @@ extension CarPlaySession {
     }
   }
 
-  /// 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 {