react-native-audio-browser 0.2.0-next.2 → 0.2.0-next.21

package/ios/CarPlay/CarPlayImageLoader.swift

@@ -36,35 +36,46 @@ 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
     }
 
-    // Build URL resolver closure that wraps BrowserManager
-    let urlResolver: ((Double, Double) async -> ArtworkResolvedImage?)? = browserManager.map { bm in
+    // 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)
@@ -77,7 +88,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 +99,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 +126,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 +153,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,70 @@ 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
     }
 
+    // A resolved accessorySymbol replaces the derived accessory above
+    // (accessoryImage outranks accessoryType in the SDK). 'none' — the
+    // inheritance escape — keeps the derived behavior instead.
+    if let symbol = SectionPresentation.effectiveAccessorySymbol(style ?? track.style),
+       let accessory = UIImage(systemName: symbol)
+    {
+      // `accessoryImage` is readonly on CPListItem; post-init updates go
+      // through the setter (which also clears `accessoryType`, per the SDK).
+      item.setAccessoryImage(accessory)
+    }
+
+    // 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 +203,202 @@ 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
+  }
+
+  /// Target artwork size for one tile. Cards read their own class maximums
+  /// ('background' selects the larger full-height target); every other
+  /// family uses the shared element size.
+  private static func tileImageSize(gridTile: GridTile?, cardImage: CardImage?) -> CGSize {
+    if #available(iOS 26.0, *), gridTile == .card {
+      return cardImage == .background
+        ? CPListImageRowItemCardElement.maximumFullHeightImageSize
+        : CPListImageRowItemCardElement.maximumImageSize
     }
+    return rowImageSize
+  }
 
-    // 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 @Sendable (Int, UIImage) -> Void)?
+    // Resolved once per track, shared by element construction and the
+    // artwork loads below.
+    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
+          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
+          guard index < elements.count else { return }
+          elements[index].image = image
+        }
+      }
+      // The family is style-driven (`SectionPresentation.tileFamily`); both
+      // non-plain families take either wrap mode. Pre-26 the treatment drops
+      // and the layout survives (the legacy branch below).
+      switch SectionPresentation.tileFamily(for: style, singleLine: singleLine) {
+      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 turns the tint into the color behind the labels).
+        let elements = makeElements { track, resolved in
+          CPListImageRowItemCardElement(
+            image: placeholder(),
+            showsImageFullHeight: resolved.cardImage == .background,
+            title: track.title,
+            subtitle: track.subtitle,
+            tintColor: resolved.cardTint.flatMap { UIColor(declaredHex: $0) },
+          )
+        }
+        item = CPListImageRowItem(
+          text: section.title, cardElements: elements, allowsMultipleLines: !singleLine,
+        )
+        applyImage = imageApplier(elements)
+      case .condensedElements:
+        let elements = makeElements { track, resolved in
+          CPListImageRowItemCondensedElement(
+            image: placeholder(),
+            imageShape: resolved.imageShape == .circular ? .circular : .roundedRectangle,
+            title: track.title,
+            subtitle: track.subtitle,
+            accessorySymbolName: SectionPresentation.effectiveAccessorySymbol(resolved),
+          )
+        }
+        item = CPListImageRowItem(
+          text: section.title, condensedElements: elements, allowsMultipleLines: !singleLine,
+        )
+        applyImage = imageApplier(elements)
+      case .rowElements:
+        // The only plain tile with a subtitle slot — the imageGridElements
+        // family has no equivalent, by SDK design.
+        let elements = makeElements { track, _ in
+          CPListImageRowItemRowElement(
+            image: placeholder(), title: track.title, subtitle: track.subtitle,
+          )
+        }
+        item = CPListImageRowItem(text: section.title, elements: elements, allowsMultipleLines: false)
+        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
+          CPListImageRowItemImageGridElement(
+            image: placeholder(),
+            imageShape: resolved.imageShape == .circular ? .circular : .roundedRectangle,
+            title: track.title,
+            accessorySymbolName: SectionPresentation.effectiveAccessorySymbol(resolved),
+          )
+        }
+        item = CPListImageRowItem(text: section.title, imageGridElements: elements, allowsMultipleLines: true)
+        applyImage = imageApplier(elements)
+      }
     } 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
+      let resolved = resolvedStyles[index]
+      imageLoader?.loadArtwork(
+        for: track,
+        style: resolved,
+        size: Self.tileImageSize(gridTile: style.gridTile, cardImage: resolved.cardImage),
+      ) { [weak item, applyImage] 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 +406,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, icyCharset: nil,
+    )
+  }
 }