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

package/ios/CarPlay/CarPlayImageLoader.swift

@@ -36,30 +36,39 @@ final class CarPlayImageLoader {
     return sfSymbolImageForSize(symbolName, canvasSize: canvasSize, backgroundColor: bg, symbolColor: fg)
   }
 
-  /// Cached empty placeholder image to reserve space while artwork loads
-  lazy var placeholderImage: UIImage? = {
-    let size = CPListItem.maximumImageSize
-    let scale = carTraitCollection.displayScale
-    UIGraphicsBeginImageContextWithOptions(size, false, scale)
+  /// Cached empty placeholders, keyed by point size — list items and image-row
+  /// cells reserve different footprints.
+  private var placeholders: [String: UIImage] = [:]
+
+  /// Empty placeholder image reserving a `size`-point slot while artwork loads.
+  func placeholderImage(size: CGSize) -> UIImage? {
+    let key = "\(size.width)×\(size.height)"
+    if let cached = placeholders[key] { return cached }
+    UIGraphicsBeginImageContextWithOptions(size, false, carTraitCollection.displayScale)
     defer { UIGraphicsEndImageContext() }
-    return UIGraphicsGetImageFromCurrentImageContext()
-  }()
+    guard let image = UIGraphicsGetImageFromCurrentImageContext() else { return nil }
+    placeholders[key] = image
+    return image
+  }
 
   // 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, size: CGSize, completion: @escaping @Sendable (UIImage?) -> Void) {
+  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.
     if let variants = track.artwork?.variants {
-      loadVariants(for: track, variants: variants, size: size, completion: completion)
+      loadVariants(for: track, style: style, variants: variants, size: size, completion: completion)
       return
     }
 
@@ -77,7 +86,7 @@ final class CarPlayImageLoader {
       let action = await CarPlayArtworkResolver.resolve(
         artwork: track.artwork?.url,
         artworkSourceUri: track.artworkSource?.uri,
-        artworkCarPlayTinted: track.artworkCarPlayTinted,
+        stencil: (style ?? track.style)?.artworkRendering == .stencil,
         targetWidth: Double(size.width),
         targetHeight: Double(size.height),
         displayScale: Double(self.carTraitCollection.displayScale),
@@ -88,7 +97,7 @@ final class CarPlayImageLoader {
       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)
+        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 {
@@ -115,13 +124,18 @@ final class CarPlayImageLoader {
   /// 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))), size: size)
-      async let dark = self.loadArtworkAsync(for: track.copying(artwork: .some(.first(variants.dark))), size: size)
+      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 {
@@ -137,19 +151,25 @@ final class CarPlayImageLoader {
   }
 
   /// `loadArtwork` as an awaitable, so the two variants can load concurrently.
-  private func loadArtworkAsync(for track: Track, size: CGSize) async -> UIImage? {
+  private func loadArtworkAsync(for track: Track, style: TrackStyle?, size: CGSize) async -> UIImage? {
     await withCheckedContinuation { continuation in
-      self.loadArtwork(for: track, size: size) { image in
+      self.loadArtwork(for: track, style: style, size: size) { image in
         continuation.resume(returning: image)
       }
     }
   }
 
   /// Fetches an image from a URL with optional headers and SVG processing.
-  private func fetchImage(uri: String, headers: [String: String]?, isSvg: Bool) async -> UIImage? {
+  /// Rasters are downsampled to `size` points at the car's display scale —
+  /// CPListItem.h: "size them to the display scale of the car screen". SVGs
+  /// already rasterize at car scale via SVGProcessor.
+  private func fetchImage(uri: String, headers: [String: String]?, isSvg: Bool, size: CGSize) async -> UIImage? {
     let source = ImageSource(uri: uri, method: nil, headers: headers, body: nil)
-    let svgScale: CGFloat? = isSvg ? carTraitCollection.displayScale : nil
-    return await ArtworkImageFetcher.fetchImage(from: source, svgScale: svgScale)
+    let scale = carTraitCollection.displayScale
+    if isSvg {
+      return await ArtworkImageFetcher.fetchImage(from: source, svgScale: scale)
+    }
+    return await ArtworkImageFetcher.fetchImage(from: source, downsampleTo: (size, scale))
   }
 
   /// Creates an SF Symbol image rendered at the given canvas size.

package/ios/CarPlay/CarPlayListItemFactory.swift

@@ -7,8 +7,9 @@ import os.log
 
 /// Typed metadata stored on CPListItems, replacing stringly-typed userInfo dictionaries.
 struct CarPlayItemInfo {
-  let id: String?
-  let src: String?
+  /// The track's identity (`id` when non-blank, else `src`) — the comparison
+  /// key for the now-playing indicator repaint sweep.
+  let identity: String?
 }
 
 extension CPListItem {
@@ -29,11 +30,14 @@ final class CarPlayListItemFactory {
   private let logger = Logger(subsystem: "com.audiobrowser", category: "CarPlayListItemFactory")
 
   var imageLoader: CarPlayImageLoader?
-  private let isActiveTrack: (_ id: String?, _ src: String?) -> Bool
+  /// Pushed by the controller (at creation and when options change), like
+  /// `imageLoader` — the factory never reads options itself.
+  var playingIndicatorLocation: CPListItemPlayingIndicatorLocation = .leading
+  private let isActiveTrack: (_ identity: String?) -> Bool
   private let onItemSelected: (Track, @escaping () -> Void) -> Void
 
   init(
-    isActiveTrack: @escaping (_ id: String?, _ src: String?) -> Bool,
+    isActiveTrack: @escaping (_ identity: String?) -> Bool,
     onItemSelected: @escaping (Track, @escaping () -> Void) -> Void,
   ) {
     self.isActiveTrack = isActiveTrack
@@ -42,55 +46,69 @@ final class CarPlayListItemFactory {
 
   // MARK: - Sections
 
+  /// Whether this OS has CarPlay's wrapping tile container (the iOS 26
+  /// element API) — the capability `SectionPresentation` degrades against.
+  private static var supportsWrappingGrid: Bool {
+    if #available(iOS 26.0, *) { return true }
+    return false
+  }
+
+  /// Maps the page's sections 1:1 to CPListSections (ADR 0010), respecting
+  /// CarPlay's section and total-item budgets. Style blocks declare the
+  /// requested presentation (resolved `section ?? page` here — ADR 0011);
+  /// this renders CarPlay's nearest supported form (`SectionPresentation`):
+  /// - list (default): a titled/headerless section of list rows.
+  /// - single-line grid (`gridWrap: false`): a headerless section holding
+  ///   one single-line image-row item whose text is the section title — the
+  ///   tiles that fit render, the rest truncate (the platform doesn't
+  ///   report the fit).
+  /// - wrapping grid: a wrapping, titled tile grid on iOS 26+; a plain list
+  ///   before that.
   func createSections(from resolvedTrack: ResolvedTrack) -> [CPListSection] {
-    guard let children = resolvedTrack.children else {
+    guard let sections = resolvedTrack.normalizedSections else {
       return []
     }
 
     let maxSections = CPListTemplate.maximumSectionCount
     let maxTotalItems = CPListTemplate.maximumItemCount
 
-    // Contiguous runs sharing a groupTitle form a section (the same semantics
-    // Android Auto's GROUP_TITLE hint has), so sections — titled or not —
-    // render in exact source (server) order. Ungrouped runs become headerless
-    // sections in place rather than being hoisted to the top.
-    var runs: [(title: String?, tracks: [Track])] = []
-    for track in children {
-      if let last = runs.indices.last, runs[last].title == track.groupTitle {
-        runs[last].tracks.append(track)
-      } else {
-        runs.append((track.groupTitle, [track]))
-      }
-    }
-
-    // Create sections (respecting both section and total item limits)
-    var sections: [CPListSection] = []
+    var listSections: [CPListSection] = []
     var totalItemCount = 0
 
-    for run in runs {
-      guard sections.count < maxSections else { break }
+    for section in sections {
+      guard listSections.count < maxSections else { break }
       guard totalItemCount < maxTotalItems else { break }
-
-      let availableSlots = maxTotalItems - totalItemCount
-      let items: [CPListTemplateItem] = run.tracks.prefix(availableSlots).map { track in
-        // Empty image rows fall through to a plain list item: zero-image
-        // CPListImageRowItem init is undocumented territory, and a header-only
-        // row is a dead end regardless (a "popular" row with no entries yet).
-        if let imageRow = track.imageRow, !imageRow.isEmpty {
-          return createImageRowItem(for: track)
+      // An empty section is a dead end regardless of style (a "popular"
+      // section with no entries yet) — skip it rather than render a header
+      // with nothing under it.
+      guard !section.children.isEmpty else { continue }
+
+      let style = StyleResolver.sectionStyle(section: section.style, page: resolvedTrack.style)
+      let presentation = SectionPresentation(for: style, supportsWrappingGrid: Self.supportsWrappingGrid)
+      switch presentation {
+      case .list:
+        let availableSlots = maxTotalItems - totalItemCount
+        let items: [CPListTemplateItem] = section.children.prefix(availableSlots).map {
+          createListItem(for: $0, style: StyleResolver.trackStyle(track: $0.style, section: style))
         }
-        return createListItem(for: track)
-      }
-      guard !items.isEmpty else { continue }
-      if let title = run.title {
-        sections.append(CPListSection(items: items, header: title, sectionIndexTitle: nil))
-      } else {
-        sections.append(CPListSection(items: items))
+        if let title = section.title {
+          listSections.append(CPListSection(items: items, header: title, sectionIndexTitle: nil))
+        } else {
+          listSections.append(CPListSection(items: items))
+        }
+        totalItemCount += items.count
+      case .singleLineRow, .wrappingGrid:
+        // Tile presentations render as one image-row item inside a
+        // headerless CPListSection, with the section title as the item's
+        // text — a headed section would render the title twice.
+        guard let item = createImageRowItem(for: section, style: style, presentation: presentation)
+        else { continue }
+        listSections.append(CPListSection(items: [item]))
+        totalItemCount += 1
       }
-      totalItemCount += items.count
     }
 
-    return sections
+    return listSections
   }
 
   // MARK: - List Item
@@ -98,9 +116,14 @@ final class CarPlayListItemFactory {
   /// Creates a CPListItem for a track with common setup (typed userInfo, artwork, isPlaying).
   /// - 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.
   func createListItem(
     for track: Track,
+    style: TrackStyle? = nil,
     handler: ((CPSelectableListItem, @escaping () -> Void) -> Void)? = nil,
   ) -> CPListItem {
     let item = CPListItem(
@@ -109,46 +132,59 @@ final class CarPlayListItemFactory {
     )
 
     // Store typed info for updatePlayingIndicators()
-    item.setCarPlayItemInfo(CarPlayItemInfo(id: track.id, src: track.src))
+    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
-      // Leading (the system default, set explicitly to make the choice
-      // deliberate): the indicator draws in the artwork slot. Note the
+      // 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.
-      item.playingIndicatorLocation = .leading
-      item.isPlaying = isActiveTrack(track.id, src)
+      item.playingIndicatorLocation = playingIndicatorLocation
+      item.isPlaying = isActiveTrack(track.identity)
       if item.isPlaying {
         logger.debug("Setting isPlaying=true for: \(track.title) (src: \(src))")
       }
-    } else if track.url != nil {
+    } else if track.path != nil {
       // Browsable only - show disclosure indicator
       item.accessoryType = .disclosureIndicator
     }
 
+    // An unavailable track grays out and goes inert — list rows are the
+    // surface that CAN draw the fact, so it shows rather than hides
+    // (Track.disabled's rendering ladder).
+    if track.disabled == true {
+      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)
-      imageLoader?.loadArtwork(for: track, size: CPListItem.maximumImageSize) { [weak item] image in
+      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)
         }
       }
     }
 
-    // Set selection handler
-    if let handler {
-      item.handler = handler
-    } else {
-      item.handler = { [onItemSelected] _, completion in
-        onItemSelected(track, completion)
+    // 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.
+    let selection = handler ?? { [onItemSelected] _, completion in
+      onItemSelected(track, completion)
+    }
+    item.handler = { item, completion in
+      guard track.disabled != true else {
+        completion()
+        return
       }
+      selection(item, completion)
     }
 
     return item
@@ -156,58 +192,141 @@ final class CarPlayListItemFactory {
 
   // MARK: - Image Row Item
 
-  /// Creates a CPListImageRowItem for a track that has an imageRow.
-  /// Renders as a horizontal row of tappable artwork thumbnails with a header title.
-  func createImageRowItem(for track: Track) -> CPListImageRowItem {
-    guard let imageRowItems = track.imageRow else {
-      fatalError("createImageRowItem called without imageRow")
+  /// Target size for images inside an image row. The iOS 26 SDK deprecates
+  /// `CPListImageRowItem.maximumImageSize` in favor of the element-based API,
+  /// so read whichever the running OS considers canonical.
+  private static var rowImageSize: CGSize {
+    if #available(iOS 26.0, *) {
+      return CPListImageRowItemElement.maximumImageSize
     }
+    return CPListImageRowItem.maximumImageSize
+  }
 
-    // CPListImageRowItem requires images at init — start with placeholders
-    let maxImages = CPMaximumNumberOfGridImages
-    let visibleItems = Array(imageRowItems.prefix(maxImages))
-    let placeholders = visibleItems.map { _ in imageLoader?.placeholderImage ?? UIImage() }
-    let titles = visibleItems.map(\.title)
+  /// Creates the image-row item rendering a tile-presented section: a single
+  /// truncating line (`.singleLineRow`) or a wrapping multi-line grid
+  /// (`.wrappingGrid` — constructed on iOS 26+ only, by `SectionPresentation`).
+  ///
+  /// Returns nil when nothing is drawable — every child hidden by the
+  /// disabled ladder (pre-26 only; the element APIs gray instead).
+  private func createImageRowItem(
+    for section: Section, style: SectionStyle, presentation: SectionPresentation,
+  ) -> CPListImageRowItem? {
+    let singleLine = presentation == .singleLineRow
+    // Disabled ladder: iOS 26 elements can draw unavailability (grayed +
+    // inert, below); the legacy image row can't, so there a disabled track
+    // hides — never a normal-looking dead tile.
+    let visibleChildren: [Track] = if #available(iOS 26.0, *) {
+      section.children
+    } else {
+      section.children.filter { $0.disabled != true }
+    }
+    guard !visibleChildren.isEmpty else { return nil }
+    // A single line shows at most CPMaximumNumberOfGridImages; the wrapping
+    // grid takes every child (queue scope is declared, never rendered — the
+    // cap here only limits what's drawn, and only where the platform does).
+    let tracks = singleLine
+      ? Array(visibleChildren.prefix(CPMaximumNumberOfGridImages))
+      : visibleChildren
+    let placeholder = { [imageLoader] in
+      imageLoader?.placeholderImage(size: Self.rowImageSize) ?? UIImage()
+    }
 
-    // Use imageTitles variant on iOS 17.4+ to show titles below each thumbnail
-    let item = if #available(iOS 17.4, *) {
-      CPListImageRowItem(text: track.title, images: placeholders, imageTitles: titles)
+    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 (Int, UIImage) -> Void)?
+    if #available(iOS 26.0, *) {
+      if singleLine {
+        // Row elements are the only tile element with a subtitle slot — the
+        // imageGridElements branch below has no equivalent, by SDK design.
+        let rowElements = tracks.map { track in
+          let element = CPListImageRowItemRowElement(
+            image: placeholder(), title: track.title, subtitle: track.subtitle,
+          )
+          if track.disabled == true {
+            element.isEnabled = false
+          }
+          return element
+        }
+        item = CPListImageRowItem(text: section.title, elements: rowElements, allowsMultipleLines: false)
+        applyImage = { index, image in
+          guard index < rowElements.count else { return }
+          rowElements[index].image = image
+        }
+      } else {
+        // imageGridElements, never the title-less gridElements: an
+        // artwork-less track must keep its name on screen (ADR 0010).
+        let gridElements = tracks.map { track in
+          let element = CPListImageRowItemImageGridElement(
+            image: placeholder(), imageShape: .roundedRectangle, title: track.title,
+            accessorySymbolName: nil,
+          )
+          if track.disabled == true {
+            element.isEnabled = false
+          }
+          return element
+        }
+        item = CPListImageRowItem(text: section.title, imageGridElements: gridElements, allowsMultipleLines: true)
+        applyImage = { index, image in
+          guard index < gridElements.count else { return }
+          gridElements[index].image = image
+        }
+      }
     } else {
-      CPListImageRowItem(text: track.title, images: placeholders)
+      let placeholders = tracks.map { _ in placeholder() }
+      // Use imageTitles variant on iOS 17.4+ to show titles below each thumbnail
+      if #available(iOS 17.4, *) {
+        item = CPListImageRowItem(text: section.title ?? "", images: placeholders, imageTitles: tracks.map(\.title))
+      } else {
+        item = CPListImageRowItem(text: section.title ?? "", images: placeholders)
+      }
     }
 
-    // Handler for row header tap → navigate to track.url if present. A row
-    // without a url (pure preview) has nothing to open, so its header tap is
-    // a no-op rather than a selection that can't resolve.
+    // Header tap → navigate to section.path ("view all"). A path-less
+    // section is a pure preview — its header tap is a no-op rather than a
+    // selection that can't resolve.
     item.handler = { [onItemSelected] _, completion in
-      guard track.url != nil else {
+      guard let path = section.path else {
         completion()
         return
       }
-      onItemSelected(track, completion)
+      onItemSelected(Self.navigationTrack(path: path, title: section.title), completion)
     }
 
-    // Handler for individual image taps
+    // 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.
     item.listImageRowHandler = { [onItemSelected] _, index, completion in
-      guard index < visibleItems.count else {
+      guard index < tracks.count, tracks[index].disabled != true else {
         completion()
         return
       }
-      let tappedItem = visibleItems[index]
-      onItemSelected(tappedItem.toTrack(), completion)
+      onItemSelected(tracks[index], completion)
     }
 
-    // Load artwork for each visible image row item asynchronously
-    for (index, imageRowItem) in visibleItems.enumerated() {
-      guard imageRowItem.artwork != nil || imageRowItem.artworkSource != nil else { continue }
+    // Load artwork for each rendered tile asynchronously
+    for (index, track) in tracks.enumerated() {
+      guard track.artwork != nil || track.artworkSource != nil else { continue }
 
-      imageLoader?.loadArtwork(for: imageRowItem.toTrack(), size: CPListImageRowItem.maximumImageSize) { [weak item] image in
+      imageLoader?.loadArtwork(
+        for: track,
+        style: StyleResolver.trackStyle(track: track.style, section: style),
+        size: Self.rowImageSize,
+      ) { [weak item] image in
         Task { @MainActor in
           guard let item, let image else { return }
-          var images = item.gridImages
-          if index < images.count {
-            images[index] = image
-            item.update(images)
+          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)
+            }
           }
         }
       }
@@ -215,4 +334,18 @@ 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,
+    )
+  }
 }

package/ios/CarPlay/CarPlayNowPlayingManager.swift

@@ -16,8 +16,8 @@ final class CarPlayNowPlayingManager {
 
   private let interfaceController: CPInterfaceController
   var listItemFactory: (Track, ((CPSelectableListItem, @escaping () -> Void) -> Void)?) -> CPListItem
-  /// Pushes a browse destination (wired to the controller's navigateToUrl).
-  var navigateToUrl: ((_ url: String, _ title: String) -> Void)?
+  /// Pushes a browse destination (wired to the controller's navigateToPath).
+  var navigateToPath: ((_ path: String, _ title: String) -> Void)?
 
   private weak var audioBrowser: HybridAudioBrowser?
   private var nowPlayingObserver: NowPlayingObserver?
@@ -46,11 +46,11 @@ final class CarPlayNowPlayingManager {
   private var builtRow: BuiltButtonRow?
 
   /// Browse path the album line navigates to for the active track —
-  /// `track.albumUrl`, or the pre-resolved `resolveAlbumUrl` result. Resolved
+  /// `track.albumPath`, or the pre-resolved `resolveAlbumPath` result. Resolved
   /// at track-change time (not at tap) so the album line only surfaces when a
   /// destination actually exists.
   private var albumArtistDestination: String?
-  /// Drops a stale async `resolveAlbumUrl` result when the track changed while
+  /// Drops a stale async `resolveAlbumPath` result when the track changed while
   /// the resolver was in flight (latest-update-wins).
   private var albumArtistGeneration: UInt = 0
   /// The just-tapped track whose load is still in flight. CarPlay reads
@@ -214,7 +214,7 @@ final class CarPlayNowPlayingManager {
 
   /// Re-resolves the album line's destination for the active track and
   /// enables the (tappable) album/artist button only when one exists:
-  /// `track.albumUrl`, or the app's `resolveAlbumUrl` result.
+  /// `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
@@ -242,12 +242,12 @@ final class CarPlayNowPlayingManager {
       setAlbumArtistDestination(nil)
       return
     }
-    logger.info("AlbumArtist: track=\(track.title) albumUrl=\(track.albumUrl ?? "nil") resolver=\(self.config.resolveAlbumUrl != nil)")
-    if let albumUrl = track.albumUrl {
-      setAlbumArtistDestination(albumUrl)
+    logger.info("AlbumArtist: track=\(track.title) albumPath=\(track.albumPath ?? "nil") resolver=\(self.config.resolveAlbumPath != nil)")
+    if let albumPath = track.albumPath {
+      setAlbumArtistDestination(albumPath)
       return
     }
-    guard let resolver = config.resolveAlbumUrl else {
+    guard let resolver = config.resolveAlbumPath else {
       setAlbumArtistDestination(nil)
       return
     }
@@ -256,7 +256,7 @@ final class CarPlayNowPlayingManager {
       do {
         path = try await resolver(track).await()
       } catch {
-        self?.logger.error("resolveAlbumUrl failed: \(error.localizedDescription)")
+        self?.logger.error("resolveAlbumPath failed: \(error.localizedDescription)")
         path = nil
       }
       guard let self, self.albumArtistGeneration == generation else { return }
@@ -295,7 +295,10 @@ 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(to: CPNowPlayingButtonMaximumImageSize) else {
+    guard let image = UIImage(systemName: symbolName)?.resized(
+      to: CPNowPlayingButtonMaximumImageSize,
+      scale: interfaceController.carTraitCollection.displayScale,
+    ) else {
       return UIImage()
     }
     return image
@@ -360,7 +363,7 @@ final class CarPlayNowPlayingManager {
     // 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)")
-    navigateToUrl?(destination, title)
+    navigateToPath?(destination, title)
   }
 
   private func updateNowPlayingUpNextButton() {

package/ios/Extension/Capability+RemoteCommand.swift

@@ -54,7 +54,7 @@ extension PlayerCapabilities {
     // Apple silently removed. On the iOS 16+ target it can never be invoked: CarPlay
     // uses its own CPNowPlayingButton heart, and Siri "I like this" routes through
     // INUpdateMediaAffinityIntent. The `favorite` capability still drives the
-    // favorites-match row indicators via setFavoriteMatch. See issues #67 / #71.
+    // favorite row indicators via setFavoriteEnabled. See issues #67 / #71.
 
     // Mode controls
     if shuffleMode != false {

package/ios/Extension/PlayerCapabilities+Favorite.swift

@@ -1,20 +1,6 @@
 import Foundation
 
 extension PlayerCapabilities {
-  /// Resolved favorite match mode, or `nil` when favoriting is disabled.
-  ///
-  /// `false`/unset → `nil`; `true` → `.exact`; `{ match }` → that match.
-  var favoriteMatch: FavoritesMatchMode? {
-    switch favorite {
-    case .none:
-      nil
-    case let .some(.first(enabled)):
-      enabled ? .exact : nil
-    case let .some(.second(config)):
-      config.match
-    }
-  }
-
   /// Whether the favorite/like control is enabled.
-  var favoriteEnabled: Bool { favoriteMatch != nil }
+  var favoriteEnabled: Bool { favorite ?? false }
 }