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

package/ios/CarPlay/CarPlayImageLoader.swift

@@ -30,10 +30,29 @@ final class CarPlayImageLoader {
     UIImage(systemName: symbolName)
   }
 
-  /// Renders an SF Symbol from an artwork string (e.g. "sf:heart.fill?bg=#000&fg=#fff").
+  /// 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? {
-    let (symbolName, bg, fg) = SFSymbolRenderer.parseArtwork(artwork)
-    return sfSymbolImageForSize(symbolName, canvasSize: canvasSize, backgroundColor: bg, symbolColor: fg)
+    let (name, background, tint) = SFSymbolRenderer.parseArtwork(artwork)
+    let scale = carTraitCollection.displayScale
+    let lightTile = UIColor(white: 0.92, alpha: 1)
+    let darkTile = UIColor(white: 0.15, alpha: 1)
+    if let tint {
+      return SFSymbolRenderer.image(
+        name: name, canvasSize: canvasSize, scale: scale, tint: tint,
+        background: background ?? (tint == .white ? darkTile : lightTile),
+      )
+    }
+    guard
+      let light = SFSymbolRenderer.image(
+        name: name, canvasSize: canvasSize, scale: scale, tint: .black, background: lightTile,
+      ),
+      let dark = SFSymbolRenderer.image(
+        name: name, canvasSize: canvasSize, scale: scale, tint: .white, background: darkTile,
+      )
+    else { return nil }
+    return .adaptive(light: light, dark: dark, for: carTraitCollection)
   }
 
   /// Cached empty placeholders, keyed by point size — list items and image-row
@@ -72,27 +91,22 @@ final class CarPlayImageLoader {
       return
     }
 
-    // The annotation goes on the closure's return type, not the binding:
-    // @Sendable isn't inferred through `map`, and omitting it fails with
-    // "type of expression is ambiguous" — which doesn't mention @Sendable.
-    let urlResolver = browserManager.map { bm -> @Sendable (Double, Double) async -> ArtworkResolvedImage? in
-      { [weak bm] pixelWidth, pixelHeight in
-        guard let bm else { return nil }
-        let imageContext = ImageContext(width: pixelWidth, height: pixelHeight)
-        guard let source = await bm.resolveArtworkUrl(track: track, perRouteConfig: nil, imageContext: imageContext) else { return nil }
-        return ArtworkResolvedImage(uri: source.uri, headers: source.headers)
-      }
-    }
-
+    let artwork = track.artwork?.url
     Task {
-      let action = await CarPlayArtworkResolver.resolve(
-        artwork: track.artwork?.url,
-        artworkSourceUri: track.artworkSource?.uri,
+      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,
-        targetWidth: Double(size.width),
-        targetHeight: Double(size.height),
-        displayScale: Double(self.carTraitCollection.displayScale),
-        urlResolver: urlResolver,
+        width: Double(size.width),
+        height: Double(size.height),
       )
 
       switch action {
@@ -145,10 +159,7 @@ final class CarPlayImageLoader {
         return
       }
 
-      let asset = UIImageAsset()
-      asset.register(lightImage, with: UITraitCollection(userInterfaceStyle: .light))
-      asset.register(darkImage, with: UITraitCollection(userInterfaceStyle: .dark))
-      completion(asset.image(with: self.carTraitCollection))
+      completion(.adaptive(light: lightImage, dark: darkImage, for: self.carTraitCollection))
     }
   }
 
@@ -174,55 +185,6 @@ final class CarPlayImageLoader {
     return await ArtworkImageFetcher.fetchImage(from: source, downsampleTo: (size, scale))
   }
 
-  /// Creates an SF Symbol image rendered at the given canvas size.
-  /// When explicit colors are provided, uses them directly.
-  /// Otherwise falls back to automatic light/dark variants.
-  private func sfSymbolImageForSize(_ symbolName: String, canvasSize: CGSize, backgroundColor: UIColor? = nil, symbolColor: UIColor? = nil) -> UIImage? {
-    let scale = carTraitCollection.displayScale
-    let symbolPointSize = min(canvasSize.width, canvasSize.height) * 0.45
-
-    let config = UIImage.SymbolConfiguration(pointSize: symbolPointSize, weight: .medium)
-    guard let symbol = UIImage(systemName: symbolName, withConfiguration: config) else { return nil }
-
-    // Explicit colors: single image, no light/dark variants needed
-    if let symbolColor {
-      return renderSymbolInCanvas(symbol, tintColor: symbolColor, backgroundColor: backgroundColor, canvasSize: canvasSize, scale: scale)
-    }
-
-    // Auto light/dark variants
-    let lightImage = renderSymbolInCanvas(symbol, tintColor: .black, backgroundColor: nil, canvasSize: canvasSize, scale: scale)
-    let darkImage = renderSymbolInCanvas(symbol, tintColor: .white, backgroundColor: nil, canvasSize: canvasSize, scale: scale)
-
-    let asset = UIImageAsset()
-    asset.register(lightImage, with: UITraitCollection(userInterfaceStyle: .light))
-    asset.register(darkImage, with: UITraitCollection(userInterfaceStyle: .dark))
-
-    return asset.image(with: carTraitCollection)
-  }
-
-  /// Renders an SF Symbol centered in a canvas with a background fill.
-  /// When `backgroundColor` is nil, derives a default from the tint color (light/dark).
-  private nonisolated func renderSymbolInCanvas(_ symbol: UIImage, tintColor: UIColor, backgroundColor: UIColor?, canvasSize: CGSize, scale: CGFloat) -> UIImage {
-    let renderer = UIGraphicsImageRenderer(size: canvasSize, format: {
-      let fmt = UIGraphicsImageRendererFormat()
-      fmt.scale = scale
-      return fmt
-    }())
-
-    return renderer.image { _ in
-      let bgColor = backgroundColor ?? (tintColor == .white ? UIColor(white: 0.15, alpha: 1) : UIColor(white: 0.92, alpha: 1))
-      bgColor.setFill()
-      UIRectFill(CGRect(origin: .zero, size: canvasSize))
-
-      let symbolSize = symbol.size
-      let x = (canvasSize.width - symbolSize.width) / 2
-      let y = (canvasSize.height - symbolSize.height) / 2
-
-      tintColor.set()
-      symbol.withRenderingMode(.alwaysTemplate).draw(in: CGRect(x: x, y: y, width: symbolSize.width, height: symbolSize.height))
-    }.withRenderingMode(.alwaysOriginal)
-  }
-
   /// Renders an image to a bitmap with the specified tint color (for monochrome icons).
   private nonisolated func renderImageToBitmap(_ image: UIImage, tintColor: UIColor) -> UIImage {
     UIGraphicsBeginImageContextWithOptions(image.size, false, image.scale)
@@ -239,13 +201,10 @@ final class CarPlayImageLoader {
 
   /// 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 {
-    let lightImage = renderImageToBitmap(image, tintColor: .black)
-    let darkImage = renderImageToBitmap(image, tintColor: .white)
-
-    let asset = UIImageAsset()
-    asset.register(lightImage, with: UITraitCollection(userInterfaceStyle: .light))
-    asset.register(darkImage, with: UITraitCollection(userInterfaceStyle: .dark))
-
-    return asset.image(with: carTraitCollection)
+    .adaptive(
+      light: renderImageToBitmap(image, tintColor: .black),
+      dark: renderImageToBitmap(image, tintColor: .white),
+      for: carTraitCollection,
+    )
   }
 }

package/ios/CarPlay/CarPlayListItemFactory.swift

@@ -34,14 +34,13 @@ final class CarPlayListItemFactory {
   /// `imageLoader` — the factory never reads options itself.
   var playingIndicatorLocation: CPListItemPlayingIndicatorLocation = .leading
   private let isActiveTrack: (_ identity: String?) -> Bool
-  private let onItemSelected: (Track, @escaping () -> 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() }
+  /// A section header's "view all" was tapped.
+  var onNavigate: (_ path: String, _ title: String) -> Void = { _, _ in }
 
-  init(
-    isActiveTrack: @escaping (_ identity: String?) -> Bool,
-    onItemSelected: @escaping (Track, @escaping () -> Void) -> Void,
-  ) {
+  init(isActiveTrack: @escaping (_ identity: String?) -> Bool) {
     self.isActiveTrack = isActiveTrack
-    self.onItemSelected = onItemSelected
   }
 
   // MARK: - Sections
@@ -380,9 +379,10 @@ final class CarPlayListItemFactory {
     // Header tap → navigate to section.path ("view all"). A path-less
     // section is a pure preview and gets no handler.
     if let path = section.path {
-      let target = Self.navigationTrack(path: path, title: section.title)
-      item.handler = { [onItemSelected] _, completion in
-        onItemSelected(target, completion)
+      let title = section.title ?? ""
+      item.handler = { [onNavigate] _, completion in
+        onNavigate(path, title)
+        completion()
       }
     }
 
@@ -426,18 +426,4 @@ final class CarPlayListItemFactory {
 
     return item
   }
-
-  /// A synthetic browsable Track for section-header navigation — the
-  /// section's "view all" surface has a path and a title, but no Track.
-  /// Style-less by design: CarPlay resolves presentation from the page it
-  /// navigates to. (Android's counterpart projects the section's block —
-  /// the promise only exists to feed Android Auto's parent-level hint.)
-  private static func navigationTrack(path: String, title: String?) -> Track {
-    Track(
-      id: nil, path: path, src: nil, artwork: nil, artworkSource: nil,
-      request: nil, title: title ?? "", subtitle: nil,
-      artist: nil, albumPath: nil, album: nil, description: nil, genre: nil,
-      duration: nil, style: nil, disabled: nil, favorited: nil, live: nil, icyCharset: nil,
-    )
-  }
 }

package/ios/CarPlay/CarPlayNowPlayingManager.swift

@@ -2,29 +2,26 @@ import CarPlay
 import Foundation
 import os.log
 
-/// Manages the Now Playing template, buttons, Up Next, and related state for CarPlay.
-///
-/// Responsibilities:
-/// - CPNowPlayingTemplate setup and button configuration
-/// - Button action handlers (shuffle, repeat, favorite, playback rate)
-/// - Button state updates (favorite appearance, Up Next enabled)
-/// - Up Next template creation and queue change handling
-/// - NowPlayingObserver for Up Next button taps
+/// The CarPlay Now Playing template for one session: its custom buttons, the album line's
+/// destination, Up Next, and the events that refresh them.
 @MainActor
 final class CarPlayNowPlayingManager {
   private let logger = Logger(subsystem: "com.audiobrowser", category: "CarPlayNowPlayingManager")
 
   private let interfaceController: CPInterfaceController
-  var listItemFactory: (Track, ((CPSelectableListItem, @escaping () -> Void) -> Void)?) -> CPListItem
-  /// Pushes a browse destination (wired to the controller's navigateToPath).
-  var navigateToPath: ((_ path: String, _ title: String) -> Void)?
-
-  private weak var audioBrowser: HybridAudioBrowser?
+  private let audioBrowser: HybridAudioBrowser
+  /// Read on each use: a re-setup replaces the bridge's player.
+  private var player: Player? { audioBrowser.getPlayer() }
+  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
+
+  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 (`onConfigChanged` fires on unrelated
+  /// skipped while this is unchanged (`configChanged` fires on unrelated
   /// churn, and every `updateNowPlayingButtons` call re-renders ALL buttons).
   ///
   /// shuffle/repeat selected state is part of the snapshot because CarPlay
@@ -60,57 +57,81 @@ final class CarPlayNowPlayingManager {
   /// from the tapped track at push time. Cleared when the active track changes.
   private var pendingAlbumArtistTrack: Track?
 
-  /// Convenience accessor for browser config
   private var config: BrowserConfig {
-    audioBrowser?.browserManager.config ?? BrowserConfig()
-  }
-
-  /// The active track's favorited state, from the authoritative favorite set
-  /// (see `HybridAudioBrowser.isActiveTrackFavorited`).
-  private var isActiveTrackFavorited: Bool {
-    audioBrowser?.isActiveTrackFavorited() ?? false
+    audioBrowser.browserManager.config
   }
 
-  init(interfaceController: CPInterfaceController) {
+  init(
+    interfaceController: CPInterfaceController,
+    audioBrowser: HybridAudioBrowser,
+    listItem: @escaping (Track, ((CPSelectableListItem, @escaping () -> Void) -> Void)?) -> CPListItem,
+    navigate: @escaping (_ path: String, _ title: String) -> Void,
+  ) {
     self.interfaceController = interfaceController
-    self.listItemFactory = { track, _ in CPListItem(text: track.title, detailText: nil) }
+    self.audioBrowser = audioBrowser
+    self.listItem = listItem
+    self.navigate = navigate
   }
 
   // MARK: - Lifecycle
 
-  func setup(audioBrowser: HybridAudioBrowser) {
-    self.audioBrowser = audioBrowser
-    setupNowPlayingTemplate()
+  func start() {
+    let observer = NowPlayingObserver(manager: self)
+    nowPlayingObserver = observer
+    CPNowPlayingTemplate.shared.add(observer)
+
+    let browserManager = audioBrowser.browserManager
+    subscriptions = [
+      browserManager.configChanged.subscribeOnMain { [weak self] _ in self?.refresh() },
+      audioBrowser.playerOptionsChangedEmitter.subscribeOnMain { [weak self] in self?.refresh() },
+      browserManager.favoritesChanged.subscribeOnMain { [weak self] in self?.refreshButtons() },
+      audioBrowser.favoriteChangedEmitter.subscribeOnMain { [weak self] _ in self?.refreshButtons() },
+      audioBrowser.repeatModeChangedEmitter.subscribeOnMain { [weak self] _ in self?.refreshButtons() },
+      audioBrowser.shuffleChangedEmitter.subscribeOnMain { [weak self] _ in self?.refreshButtons() },
+      audioBrowser.queueChangedEmitter.subscribeOnMain { [weak self] in self?.queueChanged($0) },
+      audioBrowser.showNowPlayingRequestedEmitter.subscribeOnMain { [weak self] in self?.showNowPlaying() },
+      audioBrowser.activeTrackChangedEmitter.subscribeOnMain { [weak self] _ in
+        // The player's current track is authoritative again.
+        self?.pendingAlbumArtistTrack = nil
+        self?.refresh()
+      },
+    ]
+    refresh()
   }
 
-  func teardown() {
-    if let observer = nowPlayingObserver {
-      CPNowPlayingTemplate.shared.remove(observer)
-      nowPlayingObserver = nil
-    }
+  func end() {
+    if let nowPlayingObserver { CPNowPlayingTemplate.shared.remove(nowPlayingObserver) }
+    nowPlayingObserver = nil
+    subscriptions = []
     pendingAlbumArtistTrack = nil
-    audioBrowser = nil
+    // A resolve still in flight must not set the shared template for the next session.
+    albumArtistGeneration &+= 1
   }
 
-  // MARK: - Now Playing Template
-
-  private func setupNowPlayingTemplate() {
-    let template = CPNowPlayingTemplate.shared
-
-    let observer = NowPlayingObserver(manager: self)
-    nowPlayingObserver = observer
-    template.add(observer)
+  /// Re-renders Up Next availability, the custom buttons and the album line's destination.
+  func refresh() {
+    updateUpNextButton()
+    refreshButtons()
+    updateAlbumArtistDestination()
+  }
 
-    setupNowPlayingButtons()
-    updateNowPlayingButtonStates()
+  /// Marks `track` as the just-tapped (still loading) track and derives the album line's
+  /// destination from it. Call before pushing Now Playing: CarPlay reads
+  /// `isAlbumArtistButtonEnabled` at display time, so enabling it after the push renders no
+  /// chevron.
+  func prepare(for track: Track) {
+    pendingAlbumArtistTrack = track
+    updateAlbumArtistDestination()
   }
 
-  /// Sets up custom Now Playing buttons based on configuration and current
-  /// player state, skipping the rebuild when nothing the row renders changed.
-  func setupNowPlayingButtons() {
-    // While a gate is active, custom buttons (favorite etc.) are hidden;
-    // the system transport controls stay — a gate never blocks playback.
-    let configured = (audioBrowser?.isGateActive ?? false) ? [] : (audioBrowser?.carPlayNowPlayingButtons ?? [])
+  // MARK: - Buttons
+
+  /// Builds the custom button row from the configuration and player state, skipping the
+  /// rebuild when nothing the row renders changed.
+  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
@@ -120,12 +141,11 @@ final class CarPlayNowPlayingManager {
       deduped.append(button)
     }
     let buttons = Array(deduped.prefix(5))
-    let player = audioBrowser?.getPlayer()
     let row = BuiltButtonRow(
       types: buttons,
-      favorited: buttons.contains(.favorite) ? isActiveTrackFavorited : nil,
-      shuffleSelected: buttons.contains(.shuffle) ? (player?.shuffleEnabled ?? false) : nil,
-      repeatSelected: buttons.contains(.repeat) ? (player?.getRepeatMode() ?? .off) != .off : nil,
+      favorited: buttons.contains(.favorite) ? audioBrowser.isActiveTrackFavorited() : nil,
+      shuffleSelected: buttons.contains(.shuffle) ? player?.shuffleEnabled ?? false : nil,
+      repeatSelected: buttons.contains(.repeat) ? (player?.repeatMode ?? .off) != .off : nil,
     )
     guard row != builtRow else { return }
     builtRow = row
@@ -182,10 +202,10 @@ final class CarPlayNowPlayingManager {
   /// stack but buried under templates pushed on top of it (Up Next, the album
   /// line's browse destination): a user-initiated surface (tap, voice play)
   /// pops back to it, while the deferred post-resolve calls in
-  /// `handleItemSelection` pass `false` — they run seconds after the tap, and
+  /// `CarPlaySession.select` pass `false` — they run seconds after the tap, and
   /// popping then would yank away a screen the user navigated to meanwhile.
   func showNowPlaying(popToFront: Bool = true) {
-    updateNowPlayingButtonStates()
+    refresh()
     let nowPlayingTemplate = CPNowPlayingTemplate.shared
     if interfaceController.templates.contains(where: { $0 === nowPlayingTemplate }) {
       if popToFront {
@@ -196,48 +216,18 @@ final class CarPlayNowPlayingManager {
     }
   }
 
-  // MARK: - Button State Updates
-
-  /// Refreshes the row for a favorite/shuffle/repeat state change — the
-  /// snapshot diff in setupNowPlayingButtons makes this a no-op when nothing
-  /// the row renders actually changed.
-  func updateFavoriteButtonState() {
-    setupNowPlayingButtons()
-  }
-
-  /// Updates Now Playing button states based on config and current queue
-  func updateNowPlayingButtonStates() {
-    updateNowPlayingUpNextButton()
-    setupNowPlayingButtons()
-    updateAlbumArtistButtonState()
-  }
-
-  /// Re-resolves the album line's destination for the active track and
-  /// enables the (tappable) album/artist button only when one exists:
-  /// `track.albumPath`, or the app's `resolveAlbumPath` result.
-  /// Marks `track` as the just-tapped (still loading) track and derives the
-  /// album line's destination from it. Must run before the Now Playing
-  /// template is pushed — CarPlay reads `isAlbumArtistButtonEnabled` at display
-  /// time, so enabling after the push (when the load lands) renders no chevron.
-  func prepareAlbumArtistButton(for track: Track) {
-    pendingAlbumArtistTrack = track
-    updateAlbumArtistButtonState()
-  }
-
-  /// Clears the tap-time pending track (the player's `currentTrack` is now
-  /// authoritative) and refreshes all button states.
-  func handleActiveTrackChanged() {
-    pendingAlbumArtistTrack = nil
-    updateNowPlayingButtonStates()
-  }
+  // MARK: - Album Line
 
-  func updateAlbumArtistButtonState() {
+  /// Resolves the album line's destination for the active (or just-tapped) track and enables
+  /// the album/artist button only when one exists: `track.albumPath`, or the app's
+  /// `resolveAlbumPath` result.
+  private func updateAlbumArtistDestination() {
     albumArtistGeneration &+= 1
     let generation = albumArtistGeneration
 
     // The just-tapped track wins while its load is in flight: currentTrack
     // still points at the previous track (or nil) at push time.
-    guard let track = pendingAlbumArtistTrack ?? audioBrowser?.getPlayer()?.currentTrack else {
+    guard let track = pendingAlbumArtistTrack ?? player?.currentTrack else {
       logger.debug("AlbumArtist: no current track → disabled")
       setAlbumArtistDestination(nil)
       return
@@ -276,18 +266,10 @@ final class CarPlayNowPlayingManager {
 
   // MARK: - Queue Changes
 
-  /// Handles queue changes - updates Up Next list if visible
-  func handleQueueChanged(_ tracks: [Track]) {
-    updateNowPlayingUpNextButton()
-
-    guard let template = upNextTemplate,
-          let player = audioBrowser?.getPlayer()
-    else {
-      return
-    }
-
-    logger.debug("Queue changed, updating Up Next list with \(tracks.count) tracks")
-    template.updateSections([createUpNextSection(tracks: tracks, player: player)])
+  private func queueChanged(_ tracks: [Track]) {
+    updateUpNextButton()
+    guard let upNextTemplate else { return }
+    upNextTemplate.updateSections([createUpNextSection(tracks: tracks)])
   }
 
   // MARK: - Private - Button Handlers
@@ -295,7 +277,7 @@ final class CarPlayNowPlayingManager {
   /// Returns the appropriate image for the favorite button based on state
   private func favoriteButtonImage(isFavorited: Bool) -> UIImage {
     let symbolName = isFavorited ? "heart.fill" : "heart"
-    guard let image = UIImage(systemName: symbolName)?.resized(
+    guard let image = UIImage(systemName: symbolName)?.fitted(
       to: CPNowPlayingButtonMaximumImageSize,
       scale: interfaceController.carTraitCollection.displayScale,
     ) else {
@@ -305,17 +287,15 @@ final class CarPlayNowPlayingManager {
   }
 
   private func handleShuffleButtonTapped() {
-    guard let player = audioBrowser?.getPlayer() else { return }
-
+    guard let player else { return }
     let newEnabled = !player.shuffleEnabled
     player.shuffleEnabled = newEnabled
     logger.info("CarPlay shuffle mode changed: \(newEnabled)")
   }
 
   private func handleRepeatButtonTapped() {
-    guard let player = audioBrowser?.getPlayer() else { return }
-
-    let currentMode = player.getRepeatMode()
+    guard let player else { return }
+    let currentMode = player.repeatMode
     let newMode: RepeatMode = switch currentMode {
     case .off:
       .track
@@ -325,20 +305,22 @@ final class CarPlayNowPlayingManager {
       .off
     }
 
-    player.setRepeatMode(newMode)
+    player.repeatMode = newMode
     logger.info("CarPlay repeat mode changed: \(currentMode.stringValue) → \(newMode.stringValue)")
   }
 
   private func handleFavoriteButtonTapped() {
-    try? audioBrowser?.toggleActiveTrackFavorited()
+    do {
+      try audioBrowser.toggleActiveTrackFavorited()
+    } catch {
+      logger.error("favorite toggle failed: \(error.localizedDescription)")
+    }
     logger.info("CarPlay favorite toggled")
   }
 
   private func handlePlaybackRateButtonTapped() {
-    guard let audioBrowser, let player = audioBrowser.getPlayer() else { return }
-
     let rates = audioBrowser.playbackRates
-    guard !rates.isEmpty else { return }
+    guard !rates.isEmpty, let player else { return }
 
     let currentRate = Double(player.rate)
     let nextRate: Double
@@ -358,26 +340,20 @@ final class CarPlayNowPlayingManager {
 
   fileprivate func handleAlbumArtistButtonTapped() {
     guard let destination = albumArtistDestination else { return }
-    let track = pendingAlbumArtistTrack ?? audioBrowser?.getPlayer()?.currentTrack
+    let track = pendingAlbumArtistTrack ?? player?.currentTrack
     // The album line is what was tapped, so its text is the natural title for
     // the pushed destination (artist may be unset, or the live song).
     let title = track?.album ?? track?.artist ?? track?.title ?? ""
     logger.info("Album/Artist button tapped, navigating to \(destination)")
-    navigateToPath?(destination, title)
+    navigate(destination, title)
   }
 
-  private func updateNowPlayingUpNextButton() {
-    let template = CPNowPlayingTemplate.shared
-    template.isUpNextButtonEnabled = (audioBrowser?.carPlayUpNextButton ?? true) && (audioBrowser?.getPlayer()?.tracks.count ?? 0) > 1
+  private func updateUpNextButton() {
+    CPNowPlayingTemplate.shared.isUpNextButtonEnabled = audioBrowser.carPlayUpNextButton && (player?.tracks.count ?? 0) > 1
   }
 
   fileprivate func handleUpNextButtonTapped() {
-    guard let player = audioBrowser?.getPlayer() else {
-      logger.warning("Player not available for Up Next")
-      return
-    }
-
-    let tracks = player.tracks
+    let tracks = player?.tracks ?? []
 
     guard !tracks.isEmpty else {
       logger.debug("No tracks in queue for Up Next")
@@ -392,7 +368,7 @@ final class CarPlayNowPlayingManager {
     let upNextTitle = CPNowPlayingTemplate.shared.upNextTitle
     let template = CPListTemplate(
       title: upNextTitle.isEmpty ? "Up Next" : upNextTitle,
-      sections: [createUpNextSection(tracks: tracks, player: player)],
+      sections: [createUpNextSection(tracks: tracks)],
     )
 
     upNextTemplate = template
@@ -400,7 +376,7 @@ final class CarPlayNowPlayingManager {
     interfaceController.safePush(template, animated: true)
   }
 
-  private func createUpNextSection(tracks: [Track], player: TrackPlayer) -> CPListSection {
+  private func createUpNextSection(tracks: [Track]) -> CPListSection {
     // Clamp to CarPlay's list limit (createSections does the same for browse
     // lists). Taking the prefix keeps item positions aligned with queue indices.
     let maxItems = CPListTemplate.maximumItemCount
@@ -408,10 +384,10 @@ final class CarPlayNowPlayingManager {
       logger.info("Up Next queue has \(tracks.count) tracks, clamping to CarPlay's limit of \(maxItems)")
     }
     let items = tracks.prefix(maxItems).enumerated().map { index, track -> CPListItem in
-      listItemFactory(track) { [weak self] _, completion in
+      listItem(track) { [weak self] _, completion in
         self?.logger.info("Skipping to track at index \(index): \(track.title)")
         do {
-          try player.skipTo(index, playWhenReady: true)
+          try self?.player?.skipTo(index, playWhenReady: true)
         } catch {
           self?.logger.error("Failed to skip to track: \(error.localizedDescription)")
         }
@@ -447,3 +423,17 @@ private final class NowPlayingObserver: NSObject, CPNowPlayingTemplateObserver,
     }
   }
 }
+
+private extension UIImage {
+  /// Draws the image centered in `targetSize`, keeping its aspect ratio, at the car screen's
+  /// display scale.
+  func fitted(to targetSize: CGSize, scale: CGFloat) -> UIImage? {
+    UIGraphicsBeginImageContextWithOptions(targetSize, false, scale)
+    defer { UIGraphicsEndImageContext() }
+    let fitScale = min(targetSize.width / size.width, targetSize.height / size.height)
+    let scaledSize = CGSize(width: size.width * fitScale, height: size.height * fitScale)
+    let origin = CGPoint(x: (targetSize.width - scaledSize.width) / 2, y: (targetSize.height - scaledSize.height) / 2)
+    draw(in: CGRect(origin: origin, size: scaledSize))
+    return UIGraphicsGetImageFromCurrentImageContext()?.withRenderingMode(.alwaysTemplate)
+  }
+}