react-native-audio-browser 0.2.0-next.20 → 0.2.0-next.22

package/README.md

@@ -172,7 +172,7 @@ Full guides and the complete [API Reference](https://audiobrowser.dev/api/) live
 
 **Troubleshooting** — [Networking in native callbacks](https://audiobrowser.dev/guide/native-callback-fetch) · [Android SSL / trust anchors](https://audiobrowser.dev/guide/android-certificates)
 
-The example app in [`apps/example-native`](https://github.com/radio-garden/react-native-audio-browser/tree/main/apps/example-native) browses archive.org's audio collection — in-app, on CarPlay, and on Android Auto — with search, favorites, and the gate.
+The example app in [`apps/example-native`](https://github.com/radio-garden/react-native-audio-browser/tree/main/apps/example-native) browses archive.org's audio collection — in-app, on CarPlay, and on Android Auto — with search, favorites, and the gate. Its **Style Lab** tab renders every CarPlay `style` declaration, each shelf titled with the block it draws ([source](https://github.com/radio-garden/react-native-audio-browser/blob/main/apps/example-native/src/utils/style-lab.ts)).
 
 ### For coding agents
 

package/android/src/main/java/com/audiobrowser/browser/InertStyleDiagnostic.kt

@@ -66,8 +66,8 @@ object InertStyleDiagnostic {
       when (this) {
         GRID_WRAP,
         GRID_TILE -> !context.isGrid
-        IMAGE_SHAPE -> !context.isGrid || context.isCard
-        ACCESSORY_SYMBOL -> context.isCard
+        IMAGE_SHAPE -> !context.isShaped
+        ACCESSORY_SYMBOL -> context.isGrid && !context.isShaped
         CARD_TINT,
         CARD_IMAGE -> !context.isCard
       }
@@ -78,8 +78,9 @@ object InertStyleDiagnostic {
         when (this) {
           GRID_WRAP,
           GRID_TILE -> "`$key` renders only in a grid"
-          IMAGE_SHAPE -> "only plain and condensed tiles have a shape"
-          ACCESSORY_SYMBOL -> "card tiles have no accessory slot"
+          IMAGE_SHAPE -> "only image and condensed tiles have a shape"
+          ACCESSORY_SYMBOL ->
+            "among grid tiles only image and condensed ones have an accessory slot"
           CARD_TINT,
           CARD_IMAGE -> "the card properties render only under `gridTile: 'card'`"
         }
@@ -89,8 +90,9 @@ object InertStyleDiagnostic {
         when (this) {
           GRID_WRAP,
           GRID_TILE -> "Declare `display: 'grid'` on the section or the page, or drop `$key`."
-          IMAGE_SHAPE -> "Render the items as plain or condensed grid tiles, or drop `imageShape`."
-          ACCESSORY_SYMBOL -> "Use `gridTile: 'plain'` or `'condensed'`, or drop `accessorySymbol`."
+          IMAGE_SHAPE -> "Use `gridTile: 'image'` or `'condensed'` in a grid, or drop `imageShape`."
+          ACCESSORY_SYMBOL ->
+            "Use `gridTile: 'image'` or `'condensed'`, or a list, or drop `accessorySymbol`."
           CARD_TINT,
           CARD_IMAGE -> "Declare `display: 'grid'` with `gridTile: 'card'`, or drop `$key`."
         }
@@ -146,9 +148,28 @@ object InertStyleDiagnostic {
 
     /**
      * Whether the card treatment is what this container renders — the `card*` family's condition.
+     * Exhaustive, like [isShaped]: a new tile kind has to be ruled on here.
      */
     val isCard: Boolean
-      get() = isGrid && tile == GridTile.CARD
+      get() =
+        isGrid &&
+          when (tile) {
+            GridTile.CARD -> true
+            GridTile.PLAIN,
+            GridTile.IMAGE,
+            GridTile.CONDENSED -> false
+          }
+
+    /** Whether this container renders a tile family with a shape and an accessory slot. */
+    val isShaped: Boolean
+      get() =
+        isGrid &&
+          when (tile) {
+            GridTile.IMAGE,
+            GridTile.CONDENSED -> true
+            GridTile.PLAIN,
+            GridTile.CARD -> false
+          }
 
     /**
      * The effective style, for the message — in the wire spelling the author types ([toWireString]

package/android/src/main/java/com/audiobrowser/util/StyleWire.kt

@@ -82,6 +82,7 @@ internal fun String?.toImageShape(): ImageShape? =
 internal fun GridTile.toWireString(): String =
   when (this) {
     GridTile.PLAIN -> "plain"
+    GridTile.IMAGE -> "image"
     GridTile.CARD -> "card"
     GridTile.CONDENSED -> "condensed"
   }
@@ -89,6 +90,7 @@ internal fun GridTile.toWireString(): String =
 internal fun String?.toGridTile(): GridTile? =
   when (this?.takeIf { it.isNotEmpty() }?.lowercase()) {
     "plain" -> GridTile.PLAIN
+    "image" -> GridTile.IMAGE
     "card" -> GridTile.CARD
     "condensed" -> GridTile.CONDENSED
     else -> null

package/android/src/test/java/com/audiobrowser/browser/InertStyleDiagnosticTest.kt

@@ -100,6 +100,7 @@ class InertStyleDiagnosticTest {
   @Test
   fun `imageShape needs a shaped tile`() {
     val list = sectionStyle(imageShape = ImageShape.CIRCULAR)
+    val plain = sectionStyle(display = StyleDisplay.GRID, imageShape = ImageShape.CIRCULAR)
     val cards =
       sectionStyle(
         display = StyleDisplay.GRID,
@@ -112,26 +113,49 @@ class InertStyleDiagnosticTest {
         gridTile = GridTile.CONDENSED,
         imageShape = ImageShape.CIRCULAR,
       )
+    val image =
+      sectionStyle(
+        display = StyleDisplay.GRID,
+        gridTile = GridTile.IMAGE,
+        imageShape = ImageShape.CIRCULAR,
+      )
     assertEquals(1, findings(listOf(section(style = list))).size)
+    assertEquals(1, findings(listOf(section(style = plain))).size)
     assertEquals(1, findings(listOf(section(style = cards))).size)
-    // Plain and condensed tiles both take a shape.
     assertTrue(findings(listOf(section(style = condensed))).isEmpty())
+    assertTrue(findings(listOf(section(style = image))).isEmpty())
   }
 
   @Test
-  fun `accessorySymbol is inert only on cards`() {
+  fun `accessorySymbol needs an accessory slot`() {
     val rows = sectionStyle(accessorySymbol = "lock.fill")
+    val condensed =
+      sectionStyle(
+        display = StyleDisplay.GRID,
+        gridTile = GridTile.CONDENSED,
+        accessorySymbol = "lock.fill",
+      )
+    val image =
+      sectionStyle(
+        display = StyleDisplay.GRID,
+        gridTile = GridTile.IMAGE,
+        accessorySymbol = "lock.fill",
+      )
+    val plain = sectionStyle(display = StyleDisplay.GRID, accessorySymbol = "lock.fill")
     val cards =
       sectionStyle(
         display = StyleDisplay.GRID,
         gridTile = GridTile.CARD,
         accessorySymbol = "lock.fill",
       )
-    // List rows draw accessories; card elements have no slot for one.
     assertTrue(findings(listOf(section(style = rows))).isEmpty())
-    val found = findings(listOf(section(style = cards)))
-    assertEquals(1, found.size)
-    assertTrue(found[0], found[0].contains("no accessory slot"))
+    assertTrue(findings(listOf(section(style = condensed))).isEmpty())
+    assertTrue(findings(listOf(section(style = image))).isEmpty())
+    for (style in listOf(plain, cards)) {
+      val found = findings(listOf(section(style = style)))
+      assertEquals(1, found.size)
+      assertTrue(found[0], found[0].contains("accessory slot"))
+    }
   }
 
   @Test
@@ -167,10 +191,10 @@ class InertStyleDiagnosticTest {
   }
 
   @Test
-  fun `a track's own shape is live in a plain grid`() {
+  fun `a track's own shape is live in a shaped grid`() {
     val grid =
       section(
-        style = sectionStyle(display = StyleDisplay.GRID),
+        style = sectionStyle(display = StyleDisplay.GRID, gridTile = GridTile.IMAGE),
         children = arrayOf(track(style = trackStyle(imageShape = ImageShape.CIRCULAR))),
       )
     assertTrue(findings(listOf(grid)).isEmpty())

package/android/src/test/java/com/audiobrowser/browser/JsonStyleTest.kt

@@ -1,5 +1,7 @@
 package com.audiobrowser.browser
 
+import com.audiobrowser.util.toGridTile
+import com.audiobrowser.util.toWireString
 import com.margelo.nitro.audiobrowser.ArtworkRendering
 import com.margelo.nitro.audiobrowser.CardImage
 import com.margelo.nitro.audiobrowser.GridTile
@@ -134,6 +136,25 @@ class JsonStyleTest {
     assertEquals(CardImage.BACKGROUND, style?.cardImage)
   }
 
+  @Test
+  fun `decodes the image family`() {
+    val resolved =
+      json.decodeFromString<JsonResolvedTrack>(
+        """{"path":"/home","title":"Home","sections":[
+          {"style":{"display":"grid","gridTile":"image","imageShape":"circular"},
+           "children":[{"title":"C","src":"s"}]}
+        ]}"""
+      )
+    val style = resolved.toNitro().sections?.first()?.style
+    assertEquals(GridTile.IMAGE, style?.gridTile)
+    assertEquals(ImageShape.CIRCULAR, style?.imageShape)
+  }
+
+  @Test
+  fun `every gridTile survives the wire`() {
+    GridTile.entries.forEach { assertEquals(it, it.toWireString().toGridTile()) }
+  }
+
   @Test
   fun `unknown gridTile decodes as no declaration`() {
     val resolved =

package/android/src/test/java/com/audiobrowser/browser/StyleResolverTest.kt

@@ -132,6 +132,12 @@ class StyleResolverTest {
         page = sectionStyle(gridTile = GridTile.CARD),
       )
     assertEquals(GridTile.PLAIN, overridden.gridTile)
+    val image =
+      StyleResolver.sectionStyle(
+        section = sectionStyle(gridTile = GridTile.IMAGE),
+        page = sectionStyle(gridTile = GridTile.CARD),
+      )
+    assertEquals(GridTile.IMAGE, image.gridTile)
   }
 
   @Test

package/ios/Browser/InertStyleDiagnostic.swift

@@ -69,8 +69,8 @@ enum InertStyleDiagnostic {
     func isInert(in context: Context) -> Bool {
       switch self {
       case .gridWrap, .gridTile: !context.isGrid
-      case .imageShape: !context.isGrid || context.isCard
-      case .accessorySymbol: context.isCard
+      case .imageShape: !context.isShaped
+      case .accessorySymbol: context.isGrid && !context.isShaped
       case .cardTint, .cardImage: !context.isCard
       }
     }
@@ -79,8 +79,8 @@ enum InertStyleDiagnostic {
     var rule: String {
       switch self {
       case .gridWrap, .gridTile: "`\(rawValue)` renders only in a grid"
-      case .imageShape: "only plain and condensed tiles have a shape"
-      case .accessorySymbol: "card tiles have no accessory slot"
+      case .imageShape: "only image and condensed tiles have a shape"
+      case .accessorySymbol: "among grid tiles only image and condensed ones have an accessory slot"
       case .cardTint, .cardImage: "the card properties render only under `gridTile: 'card'`"
       }
     }
@@ -90,9 +90,9 @@ enum InertStyleDiagnostic {
       case .gridWrap, .gridTile:
         "Declare `display: 'grid'` on the section or the page, or drop `\(rawValue)`."
       case .imageShape:
-        "Render the items as plain or condensed grid tiles, or drop `imageShape`."
+        "Use `gridTile: 'image'` or `'condensed'` in a grid, or drop `imageShape`."
       case .accessorySymbol:
-        "Use `gridTile: 'plain'` or `'condensed'`, or drop `accessorySymbol`."
+        "Use `gridTile: 'image'` or `'condensed'`, or a list, or drop `accessorySymbol`."
       case .cardTint, .cardImage:
         "Declare `display: 'grid'` with `gridTile: 'card'`, or drop `\(rawValue)`."
       }
@@ -129,8 +129,25 @@ enum InertStyleDiagnostic {
     }
 
     /// Whether the card treatment is what this container renders — the
-    /// condition the `card*` family is named after.
-    var isCard: Bool { isGrid && tile == .card }
+    /// condition the `card*` family is named after. Exhaustive, like
+    /// `isShaped`: a new tile kind has to be ruled on here.
+    var isCard: Bool {
+      guard isGrid else { return false }
+      return switch tile {
+      case .card: true
+      case .plain, .image, .condensed: false
+      }
+    }
+
+    /// Whether this container renders a tile family with a shape and an
+    /// accessory slot.
+    var isShaped: Bool {
+      guard isGrid else { return false }
+      return switch tile {
+      case .image, .condensed: true
+      case .plain, .card: false
+      }
+    }
 
     /// The effective style, for the message — in the wire spelling the author
     /// types (`stringValue` is the generated enum's own mapping). `gridTile`

package/ios/Browser/SectionPresentation.swift

@@ -41,11 +41,23 @@ enum SectionPresentation: Equatable {
     return symbol
   }
 
+  /// The title a tile shelf draws as the list section's header; nil when
+  /// the image row's own text carries it — here, not in the CarPlay factory,
+  /// so the rule is testable off-device. CarPlay draws a chevron beside an
+  /// image row's text whether or not the row has a handler, so only a shelf
+  /// with a "view all" `path` keeps its title there.
+  ///
+  /// - Parameter supportsElements: whether the platform has the iOS 26
+  ///   element API; the legacy image row's text is not optional.
+  static func tileSectionHeader(_ section: Section, supportsElements: Bool) -> String? {
+    supportsElements && section.path == nil ? section.title : nil
+  }
+
   /// The element family a tile presentation renders on iOS 26+ — here, not
   /// in the CarPlay factory, so the style→family mapping is testable
-  /// off-device. `gridTile` picks the family (plain by default); the plain
-  /// single-line shelf keeps row elements, the one plain element with a
-  /// subtitle slot. Pre-26 has no element API at all: the treatment drops
+  /// off-device. `gridTile` picks the family (plain by default), in either
+  /// wrap mode: a plain tile is a row element (title + subtitle), an image
+  /// tile an image-grid element (title, shape, accessory). Pre-26 has no element API at all: the treatment drops
   /// with the legacy image row (decorations drop before layout).
   enum TileElementFamily: Equatable {
     case rowElements
@@ -54,11 +66,12 @@ enum SectionPresentation: Equatable {
     case condensedElements
   }
 
-  static func tileFamily(for style: SectionStyle?, singleLine: Bool) -> TileElementFamily {
+  static func tileFamily(for style: SectionStyle?) -> TileElementFamily {
     switch style?.gridTile {
+    case .image: .imageGridElements
     case .card: .cardElements
     case .condensed: .condensedElements
-    case .plain, nil: singleLine ? .rowElements : .imageGridElements
+    case .plain, nil: .rowElements
     }
   }
 }

package/ios/CarPlay/CarPlayListItemFactory.swift

@@ -46,22 +46,29 @@ 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 {
+  /// Whether this OS has CarPlay's iOS 26 element API — the wrapping tile
+  /// container and the text-less image row `SectionPresentation` degrades
+  /// against.
+  private static var supportsElements: Bool {
     if #available(iOS 26.0, *) { return true }
     return false
   }
 
+  private static func listSection(_ items: [CPListTemplateItem], header: String?) -> CPListSection {
+    if let header {
+      return CPListSection(items: items, header: header, sectionIndexTitle: nil)
+    }
+    return CPListSection(items: items)
+  }
+
   /// 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).
+  /// - single-line grid (`gridWrap: false`): a section holding one
+  ///   single-line image-row item — 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] {
@@ -84,26 +91,24 @@ final class CarPlayListItemFactory {
       guard !section.children.isEmpty else { continue }
 
       let style = StyleResolver.sectionStyle(section: section.style, page: resolvedTrack.style)
-      let presentation = SectionPresentation(for: style, supportsWrappingGrid: Self.supportsWrappingGrid)
+      let presentation = SectionPresentation(for: style, supportsWrappingGrid: Self.supportsElements)
       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))
         }
-        if let title = section.title {
-          listSections.append(CPListSection(items: items, header: title, sectionIndexTitle: nil))
-        } else {
-          listSections.append(CPListSection(items: items))
-        }
+        listSections.append(Self.listSection(items, header: section.title))
         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]))
+        // Tile presentations render as one image-row item in its own
+        // CPListSection. The title is drawn once: as the section's header
+        // (`SectionPresentation.tileSectionHeader`), or as the item's text.
+        let header = SectionPresentation.tileSectionHeader(section, supportsElements: Self.supportsElements)
+        guard let item = createImageRowItem(
+          for: section, text: header == nil ? section.title : nil, style: style, presentation: presentation,
+        ) else { continue }
+        listSections.append(Self.listSection([item], header: header))
         totalItemCount += 1
       }
     }
@@ -213,16 +218,25 @@ final class CarPlayListItemFactory {
     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 {
+  /// Target artwork size for one tile. Cards, image tiles and plain row
+  /// elements read their own class maximums ('background' selects the larger
+  /// full-height card target); condensed tiles use the shared element size.
+  private static func tileImageSize(
+    family: SectionPresentation.TileElementFamily, cardImage: CardImage?,
+  ) -> CGSize {
+    guard #available(iOS 26.0, *) else { return CPListImageRowItem.maximumImageSize }
+    switch family {
+    case .cardElements:
       return cardImage == .background
         ? CPListImageRowItemCardElement.maximumFullHeightImageSize
         : CPListImageRowItemCardElement.maximumImageSize
+    case .rowElements:
+      return CPListImageRowItemRowElement.maximumImageSize
+    case .imageGridElements:
+      return CPListImageRowItemImageGridElement.maximumImageSize
+    case .condensedElements:
+      return CPListImageRowItemElement.maximumImageSize
     }
-    return rowImageSize
   }
 
   /// Creates the image-row item rendering a tile-presented section: a single
@@ -231,10 +245,14 @@ final class CarPlayListItemFactory {
   ///
   /// Returns nil when nothing is drawable — every child hidden by the
   /// disabled ladder (pre-26 only; the element APIs gray instead).
+  ///
+  /// - Parameter text: the row's own title; nil when the list section's
+  ///   header carries it.
   private func createImageRowItem(
-    for section: Section, style: SectionStyle, presentation: SectionPresentation,
+    for section: Section, text rowText: String?, style: SectionStyle, presentation: SectionPresentation,
   ) -> CPListImageRowItem? {
     let singleLine = presentation == .singleLineRow
+    let family = SectionPresentation.tileFamily(for: style)
     // 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.
@@ -286,14 +304,14 @@ final class CarPlayListItemFactory {
           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) {
+      // 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).
+      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 turns the tint into the color behind the labels).
+        // and fades the tint in behind the labels).
         let elements = makeElements { track, resolved in
           CPListImageRowItemCardElement(
             image: placeholder(),
@@ -304,7 +322,7 @@ final class CarPlayListItemFactory {
           )
         }
         item = CPListImageRowItem(
-          text: section.title, cardElements: elements, allowsMultipleLines: !singleLine,
+          text: rowText, cardElements: elements, allowsMultipleLines: !singleLine,
         )
         applyImage = imageApplier(elements)
       case .condensedElements:
@@ -318,19 +336,9 @@ final class CarPlayListItemFactory {
           )
         }
         item = CPListImageRowItem(
-          text: section.title, condensedElements: elements, allowsMultipleLines: !singleLine,
+          text: rowText, 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).
@@ -342,28 +350,40 @@ final class CarPlayListItemFactory {
             accessorySymbolName: SectionPresentation.effectiveAccessorySymbol(resolved),
           )
         }
-        item = CPListImageRowItem(text: section.title, imageGridElements: elements, allowsMultipleLines: true)
+        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
+          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() }
       // 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))
+        item = CPListImageRowItem(text: rowText ?? "", images: placeholders, imageTitles: tracks.map(\.title))
       } else {
-        item = CPListImageRowItem(text: section.title ?? "", images: placeholders)
+        item = CPListImageRowItem(text: rowText ?? "", images: placeholders)
       }
     }
 
     // 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 let path = section.path else {
-        completion()
-        return
+    // 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)
       }
-      onItemSelected(Self.navigationTrack(path: path, title: section.title), completion)
     }
 
     // Per-tile taps select the child track directly. A disabled tile is
@@ -385,7 +405,7 @@ final class CarPlayListItemFactory {
       imageLoader?.loadArtwork(
         for: track,
         style: resolved,
-        size: Self.tileImageSize(gridTile: style.gridTile, cardImage: resolved.cardImage),
+        size: Self.tileImageSize(family: family, cardImage: resolved.cardImage),
       ) { [weak item, applyImage] image in
         Task { @MainActor in
           guard let item, let image else { return }

package/ios/Model/NitroTypeStubs.swift

@@ -128,12 +128,14 @@
 
   enum GridTile: Equatable {
     case plain
+    case image
     case card
     case condensed
 
     init?(fromString string: String) {
       switch string {
       case "plain": self = .plain
+      case "image": self = .image
       case "card": self = .card
       case "condensed": self = .condensed
       default: return nil
@@ -145,6 +147,7 @@
     var stringValue: String {
       switch self {
       case .plain: "plain"
+      case .image: "image"
       case .card: "card"
       case .condensed: "condensed"
       }

package/ios/Tests/InertStyleDiagnosticTests.swift

@@ -74,22 +74,31 @@ struct InertStyleDiagnosticTests {
 
   @Test func imageShapeNeedsAShapedTile() {
     let list = SectionStyle(imageShape: .circular)
+    let plain = SectionStyle(display: .grid, imageShape: .circular)
     let cards = SectionStyle(gridTile: .card, display: .grid, imageShape: .circular)
     let condensed = SectionStyle(gridTile: .condensed, display: .grid, imageShape: .circular)
+    let image = SectionStyle(gridTile: .image, display: .grid, imageShape: .circular)
     #expect(findings([Section(style: list, children: [])]).count == 1)
+    #expect(findings([Section(style: plain, children: [])]).count == 1)
     #expect(findings([Section(style: cards, children: [])]).count == 1)
-    // Plain and condensed tiles both take a shape.
     #expect(findings([Section(style: condensed, children: [])]).isEmpty)
+    #expect(findings([Section(style: image, children: [])]).isEmpty)
   }
 
-  @Test func accessorySymbolIsInertOnlyOnCards() {
+  @Test func accessorySymbolNeedsAnAccessorySlot() {
     let rows = SectionStyle(accessorySymbol: "lock.fill")
+    let condensed = SectionStyle(gridTile: .condensed, display: .grid, accessorySymbol: "lock.fill")
+    let image = SectionStyle(gridTile: .image, display: .grid, accessorySymbol: "lock.fill")
+    let plain = SectionStyle(display: .grid, accessorySymbol: "lock.fill")
     let cards = SectionStyle(gridTile: .card, display: .grid, accessorySymbol: "lock.fill")
-    // List rows draw accessories; card elements have no slot for one.
     #expect(findings([Section(style: rows, children: [])]).isEmpty)
-    let found = findings([Section(style: cards, children: [])])
-    #expect(found.count == 1)
-    #expect(found[0].contains("no accessory slot"))
+    #expect(findings([Section(style: condensed, children: [])]).isEmpty)
+    #expect(findings([Section(style: image, children: [])]).isEmpty)
+    for style in [plain, cards] {
+      let found = findings([Section(style: style, children: [])])
+      #expect(found.count == 1)
+      #expect(found[0].contains("accessory slot"))
+    }
   }
 
   @Test func artworkRenderingIsNeverInert() {
@@ -114,9 +123,9 @@ struct InertStyleDiagnosticTests {
     #expect(found[0].contains("style.cardTint"))
   }
 
-  @Test func aTracksOwnShapeIsLiveInAPlainGrid() {
+  @Test func aTracksOwnShapeIsLiveInAShapedGrid() {
     let section = Section(
-      style: SectionStyle(display: .grid),
+      style: SectionStyle(gridTile: .image, display: .grid),
       children: [playable(style: TrackStyle(imageShape: .circular))],
     )
     #expect(findings([section]).isEmpty)

package/ios/Tests/JsonModelsTests.swift

@@ -162,6 +162,20 @@ struct JsonStyleTests {
     #expect(style?.cardImage == .background)
   }
 
+  @Test func decodesTheImageFamily() throws {
+    let json = Data(
+      """
+      {"path":"/home","title":"Home","sections":[
+        {"style":{"display":"grid","gridTile":"image","imageShape":"circular"},
+         "children":[{"title":"C","src":"s"}]}
+      ]}
+      """.utf8)
+    let resolved = try JSONDecoder().decode(JsonResolvedTrack.self, from: json).toNitro()
+    let style = resolved.sections?.first?.style
+    #expect(style?.gridTile == .image)
+    #expect(style?.imageShape == .circular)
+  }
+
   @Test func unknownGridTileDecodesAsNoDeclaration() throws {
     let json = Data(
       """

package/ios/Tests/SectionPresentationTests.swift

@@ -59,21 +59,29 @@ struct SectionPresentationTests {
         == .list)
   }
 
-  @Test func tileFamilyFollowsGridTileWithThePlainSplit() {
-    // Card/condensed follow the declaration in either wrap mode; the plain
-    // default splits on the wrap: single-line keeps row elements (the
-    // subtitle slot), wrapping renders the image grid.
+  @Test func tileFamilyFollowsGridTile() {
+    // The family follows the declaration alone; the wrap mode only decides
+    // whether its elements take more than one line.
+    #expect(SectionPresentation.tileFamily(for: SectionStyle(gridTile: .card)) == .cardElements)
     #expect(
-      SectionPresentation.tileFamily(for: SectionStyle(gridTile: .card), singleLine: true)
-        == .cardElements)
+      SectionPresentation.tileFamily(for: SectionStyle(gridTile: .image)) == .imageGridElements)
     #expect(
-      SectionPresentation.tileFamily(for: SectionStyle(gridTile: .condensed), singleLine: false)
-        == .condensedElements)
-    #expect(SectionPresentation.tileFamily(for: nil, singleLine: true) == .rowElements)
-    #expect(SectionPresentation.tileFamily(for: nil, singleLine: false) == .imageGridElements)
-    #expect(
-      SectionPresentation.tileFamily(for: SectionStyle(gridTile: .plain), singleLine: true)
-        == .rowElements)
+      SectionPresentation.tileFamily(for: SectionStyle(gridTile: .condensed)) == .condensedElements)
+    #expect(SectionPresentation.tileFamily(for: nil) == .rowElements)
+    #expect(SectionPresentation.tileFamily(for: SectionStyle(gridTile: .plain)) == .rowElements)
+  }
+
+  @Test func aPathlessShelfTitlesTheSectionHeader() {
+    let viewAll = Section(title: "Popular", path: "/popular", children: [])
+    let preview = Section(title: "Popular", children: [])
+    let untitled = Section(children: [])
+    // The image row's own text carries a chevron, so it is kept for the
+    // shelf that has somewhere to go.
+    #expect(SectionPresentation.tileSectionHeader(viewAll, supportsElements: true) == nil)
+    #expect(SectionPresentation.tileSectionHeader(preview, supportsElements: true) == "Popular")
+    #expect(SectionPresentation.tileSectionHeader(untitled, supportsElements: true) == nil)
+    // The legacy row cannot drop its text.
+    #expect(SectionPresentation.tileSectionHeader(preview, supportsElements: false) == nil)
   }
 
   @Test func effectiveAccessorySymbol_noneAndAbsenceDrawNothing() {

package/ios/Tests/StyleResolverTests.swift

@@ -48,6 +48,11 @@ struct SectionStyleResolutionTests {
       page: SectionStyle(gridTile: .card),
     )
     #expect(overridden.gridTile == .plain)
+    let image = StyleResolver.sectionStyle(
+      section: SectionStyle(gridTile: .image),
+      page: SectionStyle(gridTile: .card),
+    )
+    #expect(image.gridTile == .image)
   }
 }
 

package/lib/typescript/src/types/browser-nodes.d.ts

@@ -23,7 +23,7 @@ export type StyleDisplay = 'list' | 'grid';
  */
 export type ArtworkRendering = 'original' | 'stencil';
 /**
- * The shape a grid tile's artwork is cropped to.
+ * The shape an image or condensed grid tile's artwork is cropped to.
  *
  * - `'rounded-rectangle'` (default) — the standard tile crop.
  * - `'circular'` — the standard presentation for *people* (artists, hosts,
@@ -38,26 +38,31 @@ export type ImageShape = 'circular' | 'rounded-rectangle';
 /**
  * The kind of tile a grid renders.
  *
- * - `'plain'` (default) — artwork tiles with a title.
+ * - `'plain'` (default) — large artwork tiles with a title and subtitle
+ *   below. No shape and no accessory.
+ * - `'image'` — artwork tiles with a title and no subtitle; takes
+ *   {@link TrackStyle.imageShape} and {@link TrackStyle.accessorySymbol}.
+ *   The grid of round tiles for people is `'image'` with
+ *   `imageShape: 'circular'`.
  * - `'card'` — a larger card with title/subtitle and a
  *   {@link TrackStyle.cardTint} color; its image mode is
- *   {@link TrackStyle.cardImage}. Cards have no shape.
- * - `'condensed'` — a denser cell carrying title + subtitle; takes
- *   {@link TrackStyle.imageShape} and {@link TrackStyle.accessorySymbol}
- *   like a plain tile.
+ *   {@link TrackStyle.cardImage}. Cards have no shape and no accessory.
+ * - `'condensed'` — a denser cell carrying title + subtitle beside a small
+ *   image; takes {@link TrackStyle.imageShape} and
+ *   {@link TrackStyle.accessorySymbol}.
  *
  * Element families are mutually exclusive within a container, so this is
  * a container property — hence the enum, and the `grid` prefix.
  */
-export type GridTile = 'plain' | 'card' | 'condensed';
+export type GridTile = 'plain' | 'image' | 'card' | 'condensed';
 /**
  * How a card tile uses its image.
  *
- * - `'normal'` (default) — image above the labels;
- *   {@link TrackStyle.cardTint} colors a gradient behind the labels.
+ * - `'normal'` (default) — a square image inset above the labels;
+ *   {@link TrackStyle.cardTint} colors the whole card.
  * - `'background'` — the image fills the card full-height with the labels
- *   overlaid; `cardTint` becomes the color behind them. Selects the larger
- *   artwork target size.
+ *   overlaid; `cardTint` fades in behind them. Selects the larger artwork
+ *   target size.
  *
  * An enum rather than a boolean: it names the card's image mode and
  * leaves room for future modes.
@@ -120,12 +125,13 @@ export interface TrackStyle {
      */
     artworkRendering?: ArtworkRendering;
     /**
-     * Inherited (`track ?? section ?? page`): the shape a grid tile's
-     * artwork is cropped to — `'circular'` for people, the default
-     * `'rounded-rectangle'` for everything else. Shape follows the item
-     * wherever it travels: a circular artist stays circular in whatever
-     * grid renders it next. Inert where the presentation has no shape
-     * (list rows, pre-26 CarPlay, Android Auto).
+     * Inherited (`track ?? section ?? page`): the shape an image or
+     * condensed grid tile's artwork is cropped to — `'circular'` for people,
+     * the default `'rounded-rectangle'` for everything else. Shape follows
+     * the item wherever it travels: a circular artist stays circular in
+     * whatever shaped grid renders it next. Inert where the presentation has
+     * no shape (list rows, plain and card tiles, pre-26 CarPlay, Android
+     * Auto).
      *
      * @default 'rounded-rectangle'
      *
@@ -135,8 +141,9 @@ export interface TrackStyle {
     /**
      * Inherited (`track ?? section ?? page`): an SF Symbol name drawn as
      * the item's accessory wherever the current presentation supports one —
-     * the trailing edge of a list row, leading the title on an iOS 26 grid
-     * tile (placement is the platform's choice per surface). A resolved
+     * the trailing edge of a list row or an iOS 26 condensed tile, leading
+     * the title on an image tile (placement is the platform's choice per
+     * surface); plain and card tiles have no slot for one. A resolved
      * symbol replaces the derived accessory (the disclosure chevron a
      * browsable row gets); `'none'` clears an inherited value, restoring
      * the derived behavior — inheritance has no other escape, and no SF
@@ -148,8 +155,8 @@ export interface TrackStyle {
     accessorySymbol?: string;
     /**
      * Inherited (`track ?? section ?? page`): the card treatment's tint
-     * color (hex, e.g. `'#1e3a8a'`) — a gradient behind the labels, or the
-     * color behind them when {@link TrackStyle.cardImage} is
+     * color (hex, e.g. `'#1e3a8a'`) — the card's own color, or the color
+     * that fades in behind the labels when {@link TrackStyle.cardImage} is
      * `'background'`. Card-prefixed: inert unless the container renders
      * `gridTile: 'card'`.
      *

package/lib/typescript/src/types/browser-nodes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"browser-nodes.d.ts","sourceRoot":"","sources":["../../../../src/types/browser-nodes.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"browser-nodes.d.ts","sourceRoot":"","sources":["../../../../src/types/browser-nodes.ts"],"names":[],"mappings":"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"}

package/nitrogen/generated/android/c++/JGridTile.hpp

@@ -45,6 +45,9 @@ namespace margelo::nitro::audiobrowser {
         case GridTile::PLAIN:
           static const auto fieldPLAIN = clazz->getStaticField<JGridTile>("PLAIN");
           return clazz->getStaticFieldValue(fieldPLAIN);
+        case GridTile::IMAGE:
+          static const auto fieldIMAGE = clazz->getStaticField<JGridTile>("IMAGE");
+          return clazz->getStaticFieldValue(fieldIMAGE);
         case GridTile::CARD:
           static const auto fieldCARD = clazz->getStaticField<JGridTile>("CARD");
           return clazz->getStaticFieldValue(fieldCARD);

package/nitrogen/generated/android/kotlin/com/margelo/nitro/audiobrowser/GridTile.kt

@@ -17,8 +17,9 @@ import com.facebook.proguard.annotations.DoNotStrip
 @Keep
 enum class GridTile(@DoNotStrip @Keep val value: Int) {
   PLAIN(0),
-  CARD(1),
-  CONDENSED(2);
+  IMAGE(1),
+  CARD(2),
+  CONDENSED(3);
 
   companion object
 }

package/nitrogen/generated/ios/swift/GridTile.swift

@@ -19,6 +19,8 @@ public extension GridTile {
     switch string {
       case "plain":
         self = .plain
+      case "image":
+        self = .image
       case "card":
         self = .card
       case "condensed":
@@ -35,6 +37,8 @@ public extension GridTile {
     switch self {
       case .plain:
         return "plain"
+      case .image:
+        return "image"
       case .card:
         return "card"
       case .condensed:

package/nitrogen/generated/shared/c++/GridTile.hpp

@@ -30,8 +30,9 @@ namespace margelo::nitro::audiobrowser {
    */
   enum class GridTile {
     PLAIN      SWIFT_NAME(plain) = 0,
-    CARD      SWIFT_NAME(card) = 1,
-    CONDENSED      SWIFT_NAME(condensed) = 2,
+    IMAGE      SWIFT_NAME(image) = 1,
+    CARD      SWIFT_NAME(card) = 2,
+    CONDENSED      SWIFT_NAME(condensed) = 3,
   } CLOSED_ENUM;
 
 } // namespace margelo::nitro::audiobrowser
@@ -45,6 +46,7 @@ namespace margelo::nitro {
       std::string unionValue = JSIConverter<std::string>::fromJSI(runtime, arg);
       switch (hashString(unionValue.c_str(), unionValue.size())) {
         case hashString("plain"): return margelo::nitro::audiobrowser::GridTile::PLAIN;
+        case hashString("image"): return margelo::nitro::audiobrowser::GridTile::IMAGE;
         case hashString("card"): return margelo::nitro::audiobrowser::GridTile::CARD;
         case hashString("condensed"): return margelo::nitro::audiobrowser::GridTile::CONDENSED;
         default: [[unlikely]]
@@ -54,6 +56,7 @@ namespace margelo::nitro {
     static inline jsi::Value toJSI(jsi::Runtime& runtime, margelo::nitro::audiobrowser::GridTile arg) {
       switch (arg) {
         case margelo::nitro::audiobrowser::GridTile::PLAIN: return JSIConverter<std::string>::toJSI(runtime, "plain");
+        case margelo::nitro::audiobrowser::GridTile::IMAGE: return JSIConverter<std::string>::toJSI(runtime, "image");
         case margelo::nitro::audiobrowser::GridTile::CARD: return JSIConverter<std::string>::toJSI(runtime, "card");
         case margelo::nitro::audiobrowser::GridTile::CONDENSED: return JSIConverter<std::string>::toJSI(runtime, "condensed");
         default: [[unlikely]]
@@ -68,6 +71,7 @@ namespace margelo::nitro {
       std::string unionValue = JSIConverter<std::string>::fromJSI(runtime, value);
       switch (hashString(unionValue.c_str(), unionValue.size())) {
         case hashString("plain"):
+        case hashString("image"):
         case hashString("card"):
         case hashString("condensed"):
           return true;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-audio-browser",
-  "version": "0.2.0-next.20",
+  "version": "0.2.0-next.22",
   "description": "react-native-audio-browser is a react native package built with Nitro",
   "keywords": [
     "react-native",

package/src/types/browser-nodes.ts

@@ -26,7 +26,7 @@ export type StyleDisplay = 'list' | 'grid'
 export type ArtworkRendering = 'original' | 'stencil'
 
 /**
- * The shape a grid tile's artwork is cropped to.
+ * The shape an image or condensed grid tile's artwork is cropped to.
  *
  * - `'rounded-rectangle'` (default) — the standard tile crop.
  * - `'circular'` — the standard presentation for *people* (artists, hosts,
@@ -42,27 +42,32 @@ export type ImageShape = 'circular' | 'rounded-rectangle'
 /**
  * The kind of tile a grid renders.
  *
- * - `'plain'` (default) — artwork tiles with a title.
+ * - `'plain'` (default) — large artwork tiles with a title and subtitle
+ *   below. No shape and no accessory.
+ * - `'image'` — artwork tiles with a title and no subtitle; takes
+ *   {@link TrackStyle.imageShape} and {@link TrackStyle.accessorySymbol}.
+ *   The grid of round tiles for people is `'image'` with
+ *   `imageShape: 'circular'`.
  * - `'card'` — a larger card with title/subtitle and a
  *   {@link TrackStyle.cardTint} color; its image mode is
- *   {@link TrackStyle.cardImage}. Cards have no shape.
- * - `'condensed'` — a denser cell carrying title + subtitle; takes
- *   {@link TrackStyle.imageShape} and {@link TrackStyle.accessorySymbol}
- *   like a plain tile.
+ *   {@link TrackStyle.cardImage}. Cards have no shape and no accessory.
+ * - `'condensed'` — a denser cell carrying title + subtitle beside a small
+ *   image; takes {@link TrackStyle.imageShape} and
+ *   {@link TrackStyle.accessorySymbol}.
  *
  * Element families are mutually exclusive within a container, so this is
  * a container property — hence the enum, and the `grid` prefix.
  */
-export type GridTile = 'plain' | 'card' | 'condensed'
+export type GridTile = 'plain' | 'image' | 'card' | 'condensed'
 
 /**
  * How a card tile uses its image.
  *
- * - `'normal'` (default) — image above the labels;
- *   {@link TrackStyle.cardTint} colors a gradient behind the labels.
+ * - `'normal'` (default) — a square image inset above the labels;
+ *   {@link TrackStyle.cardTint} colors the whole card.
  * - `'background'` — the image fills the card full-height with the labels
- *   overlaid; `cardTint` becomes the color behind them. Selects the larger
- *   artwork target size.
+ *   overlaid; `cardTint` fades in behind them. Selects the larger artwork
+ *   target size.
  *
  * An enum rather than a boolean: it names the card's image mode and
  * leaves room for future modes.
@@ -128,12 +133,13 @@ export interface TrackStyle {
   artworkRendering?: ArtworkRendering
 
   /**
-   * Inherited (`track ?? section ?? page`): the shape a grid tile's
-   * artwork is cropped to — `'circular'` for people, the default
-   * `'rounded-rectangle'` for everything else. Shape follows the item
-   * wherever it travels: a circular artist stays circular in whatever
-   * grid renders it next. Inert where the presentation has no shape
-   * (list rows, pre-26 CarPlay, Android Auto).
+   * Inherited (`track ?? section ?? page`): the shape an image or
+   * condensed grid tile's artwork is cropped to — `'circular'` for people,
+   * the default `'rounded-rectangle'` for everything else. Shape follows
+   * the item wherever it travels: a circular artist stays circular in
+   * whatever shaped grid renders it next. Inert where the presentation has
+   * no shape (list rows, plain and card tiles, pre-26 CarPlay, Android
+   * Auto).
    *
    * @default 'rounded-rectangle'
    *
@@ -144,8 +150,9 @@ export interface TrackStyle {
   /**
    * Inherited (`track ?? section ?? page`): an SF Symbol name drawn as
    * the item's accessory wherever the current presentation supports one —
-   * the trailing edge of a list row, leading the title on an iOS 26 grid
-   * tile (placement is the platform's choice per surface). A resolved
+   * the trailing edge of a list row or an iOS 26 condensed tile, leading
+   * the title on an image tile (placement is the platform's choice per
+   * surface); plain and card tiles have no slot for one. A resolved
    * symbol replaces the derived accessory (the disclosure chevron a
    * browsable row gets); `'none'` clears an inherited value, restoring
    * the derived behavior — inheritance has no other escape, and no SF
@@ -158,8 +165,8 @@ export interface TrackStyle {
 
   /**
    * Inherited (`track ?? section ?? page`): the card treatment's tint
-   * color (hex, e.g. `'#1e3a8a'`) — a gradient behind the labels, or the
-   * color behind them when {@link TrackStyle.cardImage} is
+   * color (hex, e.g. `'#1e3a8a'`) — the card's own color, or the color
+   * that fades in behind the labels when {@link TrackStyle.cardImage} is
    * `'background'`. Card-prefixed: inert unless the container renders
    * `gridTile: 'card'`.
    *

package/website/guide/artwork.md

@@ -238,7 +238,7 @@ A page's [`Section`](/api/types/browser-nodes/#section) can render its tracks as
 }
 ```
 
-Each tile is an ordinary Track, so its `artwork` runs through the same pipeline as any other. Tile styles presume artwork: a track without any renders as a placeholder tile plus its title — the artwork `resolve` hook is the place to supply fallback art. On CarPlay a single-line grid (`gridWrap: false`) shows the tiles that fit (roughly eight, width-dependent; the rest are truncated) and a wrapping grid takes as many lines as it needs on iOS 26+ (rendering as a list before that); Android Auto's grid always wraps, so it renders both identically. See [Browser → Presentation](/guide/browser#presentation) for the full per-surface rundown.
+Each tile is an ordinary Track, so its `artwork` runs through the same pipeline as any other. Tile styles presume artwork: a track without any renders as a placeholder tile plus its title — the artwork `resolve` hook is the place to supply fallback art. On CarPlay a single-line grid (`gridWrap: false`) shows the tiles that fit on one line (seven on a wide screen, or two condensed cells; the rest are truncated) and a wrapping grid takes as many lines as it needs on iOS 26+ (rendering as a list before that); Android Auto's grid always wraps, so it renders both identically. See [Browser → Presentation](/guide/browser#presentation) for the full per-surface rundown.
 
 ## API summary
 

package/website/guide/browser.md

@@ -521,9 +521,9 @@ Presentation lives in `style` blocks, separate from content, plus a few Track fi
 | `style` (same block)                             | a page                   | declaration for the whole page — a section overrides it for its own children      | all                 |
 | `style: { display: 'grid' }`                     | a browsable track        | the layout of the page it opens — Android Auto reads it from the parent item      | Android Auto / AAOS |
 | `style: { artworkRendering: 'stencil' }`         | a track / section / page | tint monochrome artwork to the surface appearance                                 | CarPlay             |
-| `style: { imageShape: 'circular' }`              | a track / section / page | crop grid-tile artwork circular (people) instead of rounded                       | CarPlay (iOS 26+)   |
-| `style: { accessorySymbol: 'lock.fill' }`        | a track / section / page | SF Symbol accessory on rows and tiles (`'none'` restores the derived one)         | CarPlay             |
-| `style: { gridTile: 'card' }`                    | a section / page         | the grid's tile kind: `'plain'` (default), `'card'`, or `'condensed'`             | CarPlay (iOS 26+)   |
+| `style: { imageShape: 'circular' }`              | a track / section / page | crop `'image'` and `'condensed'` tile artwork circular (people)                   | CarPlay (iOS 26+)   |
+| `style: { accessorySymbol: 'lock.fill' }`        | a track / section / page | SF Symbol accessory on rows and on `'image'` / `'condensed'` tiles                | CarPlay             |
+| `style: { gridTile: 'card' }`                    | a section / page         | the grid's tile kind: `'plain'` (default), `'image'`, `'card'`, or `'condensed'`  | CarPlay (iOS 26+)   |
 | `style: { cardTint: '#1e3a8a' }` (+ `cardImage`) | a track / section / page | card color and image mode (`'background'` fills the card full-height)             | CarPlay (iOS 26+)   |
 | `disabled: true`                                 | a track                  | unavailable: never plays; grayed where drawable, hidden elsewhere                 | all                 |
 | `artwork: 'sf:heart.fill'`                       | any item                 | SF Symbol icon (supports `?bg=…&fg=…`)                                            | iOS                 |
@@ -532,11 +532,11 @@ Presentation lives in `style` blocks, separate from content, plus a few Track fi
 | `albumPath` + `resolveAlbumPath`                 | track + config           | make the now-playing album line tappable                                          | CarPlay             |
 
 ::: info Caveats from the table
-**`albumPath` requires `album`** — CarPlay renders the tappable line from the album metadata, so without an `album` there is no line to tap. **\*Layouts render each platform's nearest supported form** — a single-line grid (`gridWrap: false`) on CarPlay shows the tiles that fit (roughly eight, width-dependent) and truncates the rest; a wrapping grid takes as many lines as it needs on iOS 26+ and renders as a list before that. Android Auto's grid always wraps, so it shows more, never less. No car surface scrolls horizontally; an app UI typically renders `gridWrap: false` as a horizontal scroller. Truncation is visual only: tapping a tile queues the whole section (see [Playback behavior](#playback-behavior)). Item properties like `artworkRendering`, `imageShape`, and `accessorySymbol` are inherited — `track ?? section ?? page`, per property — so a section-wide value can be overridden per item; `accessorySymbol: 'none'` is the per-item escape from an inherited symbol, and where the accessory draws is the platform's choice per surface (trailing on list rows, leading the title on tiles). `display` is never inherited: it always describes the children of whatever it's set on. On a page or section it lays out that page or section; on a browsable track it declares the layout of the page that track opens — Android Auto needs it there, or that page renders as a list. `gridWrap` is inert unless `display` is `'grid'`. One AAOS caveat: AOSP-based Automotive units honor only the parent item's `display`, so a page mixing grid and list sections renders uniformly there — see [Android Auto → Browse display](/guide/android-auto#browse-display).
+**`albumPath` requires `album`** — CarPlay renders the tappable line from the album metadata, so without an `album` there is no line to tap. **\*Layouts render each platform's nearest supported form** — a single-line grid (`gridWrap: false`) on CarPlay shows the tiles that fit on one line (seven on a wide screen, or two condensed cells) and truncates the rest; a wrapping grid takes as many lines as it needs on iOS 26+ and renders as a list before that. Android Auto's grid always wraps, so it shows more, never less. No car surface scrolls horizontally; an app UI typically renders `gridWrap: false` as a horizontal scroller. Truncation is visual only: tapping a tile queues the whole section (see [Playback behavior](#playback-behavior)). Item properties like `artworkRendering`, `imageShape`, and `accessorySymbol` are inherited — `track ?? section ?? page`, per property — so a section-wide value can be overridden per item; `accessorySymbol: 'none'` is the per-item escape from an inherited symbol, and where the accessory draws is the platform's choice per surface (trailing on list rows and condensed tiles, leading the title on image tiles). On an iOS 26 grid, which tile draws what is `gridTile`'s choice: `'plain'` has a subtitle but no shape and no accessory, `'image'` has a shape and an accessory but no subtitle, `'condensed'` has all three beside a small image, and `'card'` has a subtitle, a tint and an image mode. `display` is never inherited: it always describes the children of whatever it's set on. On a page or section it lays out that page or section; on a browsable track it declares the layout of the page that track opens — Android Auto needs it there, or that page renders as a list. `gridWrap` is inert unless `display` is `'grid'`. One AAOS caveat: AOSP-based Automotive units honor only the parent item's `display`, so a page mixing grid and list sections renders uniformly there — see [Android Auto → Browse display](/guide/android-auto#browse-display).
 :::
 
 ::: tip Inert declarations are logged in debug builds
-A combination that can never render — `gridWrap` or `gridTile` outside a grid, `cardTint` with no card treatment in scope, `imageShape` on a list or a card, `accessorySymbol` on a card, `display` on a track that renders playable — is inert, not an error, so nothing breaks. In a **debug build**, each one is logged once per page resolution (`Timber` on Android, `os.log` on iOS) naming the section, the effective style, and the fix:
+A combination that can never render — `gridWrap` or `gridTile` outside a grid, `cardTint` with no card treatment in scope, `imageShape` anywhere but an image or condensed grid, `accessorySymbol` on a plain or card grid, `display` on a track that renders playable — is inert, not an error, so nothing breaks. In a **debug build**, each one is logged once per page resolution (`Timber` on Android, `os.log` on iOS) naming the section, the effective style, and the fix:
 
 ```
 Inert style declaration on page '/home': `style.gridWrap` on section 'Featured'
@@ -557,6 +557,8 @@ A property a _surface_ can't draw is never reported — that's the aspirational
   title: 'Home',
   sections: [
     { title: 'Popular', style: { display: 'grid', gridWrap: false }, path: '/popular', children: [...] },
+    // Round tiles for people: the image tile is the one with a shape.
+    { title: 'Artists', style: { display: 'grid', gridTile: 'image', imageShape: 'circular' }, children: [...] },
     { title: 'All stations', children: [...] }
   ]
 }
@@ -567,6 +569,10 @@ A property a _surface_ can't draw is never reported — that's the aspirational
 }
 ```
 
+::: tip See every style rendered
+The example app's **Style Lab** tab draws each `style` declaration on CarPlay: one page per `gridTile` value, plus pages for section headers and for inheritance from page to section to track. Every shelf is titled with the block it renders, so what you see on screen names what to copy. The pages are plain route data in [`style-lab.ts`](https://github.com/radio-garden/react-native-audio-browser/blob/main/apps/example-native/src/utils/style-lab.ts), with a comment on each example saying what it shows.
+:::
+
 Two config-level platform options round it out: `carPlayLoadingTitle` (localized "Loading…" on older CarPlay) and `androidControllerOfflineError`. The album-line tap needs both `albumPath` on the track and a `resolveAlbumPath` callback in the config that maps it to a browse path — see [CarPlay](/guide/carplay) and [Android Auto](/guide/android-auto) for the platform setup these build on.
 
 ## Where to go next

package/website/guide/track.md

@@ -142,7 +142,7 @@ Optional fields that change how a Track renders on CarPlay / Android Auto. Each
 | ------------------------------------------ | ---------------------------------------------------------------------- | -------------------------- |
 | `style: { display: 'list' \| 'grid' }`     | on a browsable track: the layout of the page it opens                  | Android Auto / AAOS        |
 | `style: { artworkRendering: 'stencil' }`   | tint monochrome artwork to the surface appearance                      | CarPlay                    |
-| `style: { imageShape: 'circular' }`        | crop grid-tile artwork circular (people) instead of rounded            | CarPlay (iOS 26+)          |
+| `style: { imageShape: 'circular' }`        | crop `'image'` and `'condensed'` tile artwork circular (people)        | CarPlay (iOS 26+)          |
 | `style: { accessorySymbol: '…' }`          | SF Symbol accessory; `'none'` restores the derived accessory           | CarPlay                    |
 | `style: { cardTint: '…', cardImage: '…' }` | card color and image mode, when the section renders `gridTile: 'card'` | CarPlay (iOS 26+)          |
 | `disabled`                                 | unavailable: never plays; grayed where drawable, hidden elsewhere      | all                        |