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

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

@@ -11,7 +11,7 @@ final class CarPlayNowPlayingManager {
   private let interfaceController: CPInterfaceController
   private let audioBrowser: HybridAudioBrowser
   /// Read on each use: a re-setup replaces the bridge's player.
-  private var player: Player? { audioBrowser.getPlayer() }
+  private var player: Player? { audioBrowser.player }
   private let listItem: (Track, ((CPSelectableListItem, @escaping () -> Void) -> Void)?) -> CPListItem
   /// Pushes a browse destination: the album line's.
   private let navigate: (_ path: String, _ title: String) -> Void
@@ -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.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.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)")
   }
@@ -349,7 +316,7 @@ final class CarPlayNowPlayingManager {
   }
 
   private func updateUpNextButton() {
-    CPNowPlayingTemplate.shared.isUpNextButtonEnabled = audioBrowser.carPlayUpNextButton && (player?.tracks.count ?? 0) > 1
+    CPNowPlayingTemplate.shared.isUpNextButtonEnabled = audioBrowser.playerOptions.carPlayUpNextButton && (player?.tracks.count ?? 0) > 1
   }
 
   fileprivate func handleUpNextButtonTapped() {

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 {

package/ios/CarPlay/CarPlaySession+PageLoader.swift

@@ -26,19 +26,18 @@ extension CarPlaySession {
         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() }
-
+    let outcome: Result<ResolvedTrack, Error>
     do {
-      let resolved: ResolvedTrack
-      do {
-        resolved = try await audioBrowser.browserManager.resolve(path, useCache: true)
-      } catch {
-        watchdog.cancel()
-        throw error
-      }
-      watchdog.cancel()
+      outcome = try await .success(audioBrowser.browserManager.resolve(path, useCache: true))
+    } catch {
+      outcome = .failure(error)
+    }
+    // As soon as the resolve settles: formatting its error is a JS round trip the timeout must
+    // not overwrite.
+    watchdog.cancel()
+
+    switch outcome {
+    case let .success(resolved):
       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).
@@ -48,7 +47,7 @@ extension CarPlaySession {
       } else {
         await showNavigationError(.code(.emptyContent), path: path, on: template)
       }
-    } catch {
+    case let .failure(error):
       logger.error("Failed to load content for \(path): \(error.localizedDescription)")
       await showNavigationError(NavigationError.from(error), path: path, on: template)
     }

package/ios/CarPlay/CarPlaySession+Refresher.swift

@@ -23,21 +23,21 @@ extension CarPlaySession {
   /// 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
-          }
-        })
+    let targets = displayedListTemplates().compactMap { template in template.contentPath.map { (template, $0) } }
+    let pages = await targets.map(\.1).concurrentMap { [logger] path -> ResolvedTrack? in
+      do {
+        return try await browserManager.resolve(path, useCache: false)
+      } catch {
+        if !(error is CancellationError || Task.isCancelled) {
+          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)
+    guard !Task.isCancelled else { return }
+    for ((template, _), page) in zip(targets, pages) {
+      guard let page else { continue }
+      updateTemplate(template, with: page)
     }
   }
 }

package/ios/CarPlay/CarPlaySession+TabBar.swift

@@ -39,9 +39,9 @@ extension CarPlaySession {
     // 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)) {
+      if gated, let chrome = await browseGates(for: [nil])[0] {
         guard isCurrent(build) else { return }
-        audioBrowser.onGate(GateEvent(reason: .browse))
+        reportGates([chrome], reason: .browse)
         interfaceController.safeSetRoot(makeGatePage(chrome, path: nil, tab: nil), animated: true)
       } else {
         await showRootError(.code(.emptyContent), build: build)
@@ -49,11 +49,9 @@ extension CarPlaySession {
       return
     }
 
-    let chromes = gated ? await gates(for: tabs) : tabs.map { _ in nil }
+    let chromes = gated ? await browseGates(for: tabs.map(\.path)) : tabs.map { _ in nil }
     guard isCurrent(build) else { return }
-    for _ in chromes.compactMap(\.self) {
-      audioBrowser.onGate(GateEvent(reason: .browse))
-    }
+    reportGates(chromes, reason: .browse)
     let templates = zip(tabs, chromes).map { tab, chrome in
       chrome.map { makeGatePage($0, path: tab.path, tab: tab) } ?? makeTabTemplate(for: tab)
     }
@@ -123,24 +121,24 @@ extension CarPlaySession {
   /// 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)) }
+    reportGates([chrome], 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?] {
+  /// One browse decision per path, made concurrently and returned in path order. Reports
+  /// nothing: the caller reports once it knows its build is still current.
+  private func browseGates(for paths: [String?]) 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))
-      }
+    return await paths.concurrentMap { path in
+      await browseGate.decide(NativeGateRequest(reason: .browse, path: path, search: nil))
     }
-    var chromes: [Gate?] = []
-    for decision in decisions {
-      await chromes.append(decision.value)
+  }
+
+  /// Fires `onGate` once for each request the gate gated.
+  private func reportGates(_ chromes: [Gate?], reason: GateReason) {
+    for _ in chromes.compactMap(\.self) {
+      audioBrowser.onGate(GateEvent(reason: reason))
     }
-    return chromes
   }
 
   /// A tab's content shell, which loads when it first appears.
@@ -168,15 +166,16 @@ extension CarPlaySession {
   func applyTabBarEntry(to template: CPTemplate, for track: Track) {
     template.tabTitle = track.title
     if let artwork = track.artwork?.url, SFSymbolRenderer.isSFSymbol(artwork) {
+      // A plain symbol: CarPlay tints the tab image itself.
       let (symbolName, _, _) = SFSymbolRenderer.parseArtwork(artwork)
-      if let image = imageLoader.sfSymbolImage(symbolName) {
+      if let image = UIImage(systemName: 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 }
-        }
+      spawn { [weak template] session in
+        let image = await session.imageLoader.artwork(for: track, size: CGSize(width: 24, height: 24))
+        guard !Task.isCancelled, let image else { return }
+        template?.tabImage = image
       }
     } else {
       // A restamp must not leave an old icon on a now title-only tab.

package/ios/CarPlay/CarPlaySession.swift

@@ -12,10 +12,17 @@ final class CarPlaySession {
   let interfaceController: CPInterfaceController
   let audioBrowser: HybridAudioBrowser
   /// Read on each use: a re-setup replaces the bridge's player.
-  var player: Player? { audioBrowser.getPlayer() }
+  var player: Player? { audioBrowser.player }
   let trackSelector: TrackSelector
   let imageLoader: CarPlayImageLoader
-  let listItemFactory: CarPlayListItemFactory
+  private(set) lazy var listItemFactory = CarPlayListItemFactory(
+    imageLoader: imageLoader,
+    playingIndicatorLocation: playingIndicatorLocation,
+    isActiveTrack: { [weak self] identity in identity != nil && self?.player?.currentTrack?.identity == identity },
+    spawn: { [weak self] work in self?.spawn { _ in await work() } },
+    onItemSelected: { [weak self] track, completion in self?.select(track, completion: completion) },
+    onNavigate: { [weak self] path, title in self?.spawn { await $0.navigate(to: path, title: title) } },
+  )
   private(set) var nowPlaying: CarPlayNowPlayingManager!
 
   private var subscriptions: [Subscription] = []
@@ -56,12 +63,6 @@ final class CarPlaySession {
       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,
@@ -70,9 +71,6 @@ final class CarPlaySession {
       },
       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() {
@@ -156,7 +154,7 @@ final class CarPlaySession {
   // MARK: - Playing Indicators
 
   var playingIndicatorLocation: CPListItemPlayingIndicatorLocation {
-    switch audioBrowser.carPlayPlayingIndicatorLocation {
+    switch audioBrowser.playerOptions.carPlayPlayingIndicatorLocation {
     case .trailing: .trailing
     case .leading: .leading
     }