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

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/CPInterfaceController+Safe.swift

@@ -12,6 +12,10 @@ import os.log
 /// preconditions are checked up front, the underlying call always gets a
 /// completion, and every failure is logged, with an optional caller completion
 /// for call sites that chain on the result.
+///
+/// A push onto a full stack replaces the top template (`TopTemplateReplacer`).
+/// The stack mutations wait for that replacement to settle before they run,
+/// so none of them lands between its pop and its push.
 @MainActor
 extension CPInterfaceController {
   private static let stackLogger = Logger(subsystem: "com.audiobrowser", category: "TemplateStack")
@@ -26,9 +30,43 @@ extension CPInterfaceController {
   /// push — taking down the whole app, not just the CarPlay scene.
   private static let maximumStackDepth = 5
 
+  private static var topReplacerKey: UInt8 = 0
+
+  private var topReplacer: TopTemplateReplacer {
+    if let replacer = objc_getAssociatedObject(self, &Self.topReplacerKey) as? TopTemplateReplacer {
+      return replacer
+    }
+    let replacer = TopTemplateReplacer()
+    objc_setAssociatedObject(self, &Self.topReplacerKey, replacer, .OBJC_ASSOCIATION_RETAIN_NONATOMIC)
+    return replacer
+  }
+
+  private func whenStackSettled(_ mutation: @escaping (CPInterfaceController) -> Void) {
+    topReplacer.whenSettled { [weak self] in
+      guard let self else { return }
+      mutation(self)
+    }
+  }
+
+  /// Pushes `template`, skipping the raise case (already in the hierarchy). At
+  /// the depth limit it replaces the top template.
+  func safePush(_ template: CPTemplate, animated: Bool, completion: ((Bool, Error?) -> Void)? = nil) {
+    whenStackSettled { controller in
+      let templates = controller.templates
+      guard templates.count >= Self.maximumStackDepth, !templates.contains(where: { $0 === template }) else {
+        controller.guardedPush(template, animated: animated, completion: completion)
+        return
+      }
+      controller.topReplacer.push(
+        template, replacingTopOf: GuardedTemplateStack(controller: controller), animated: animated,
+        completion: completion,
+      )
+    }
+  }
+
   /// Pushes `template`, skipping the raise cases (already in the hierarchy,
   /// stack at the depth limit).
-  func safePush(_ template: CPTemplate, animated: Bool, completion: ((Bool, Error?) -> Void)? = nil) {
+  fileprivate func guardedPush(_ template: CPTemplate, animated: Bool, completion: ((Bool, Error?) -> Void)?) {
     guard !templates.contains(where: { $0 === template }) else {
       Self.stackLogger.warning("push skipped: \(Self.name(of: template)) is already in the stack")
       completion?(false, nil)
@@ -48,7 +86,7 @@ extension CPInterfaceController {
   }
 
   /// Pops the top template, skipping the raise case (nothing above the root).
-  func safePop(animated: Bool, completion: ((Bool, Error?) -> Void)? = nil) {
+  fileprivate func guardedPop(animated: Bool, completion: ((Bool, Error?) -> Void)?) {
     guard templates.count > 1 else {
       Self.stackLogger.warning("pop skipped: already at the root template")
       completion?(false, nil)
@@ -62,41 +100,54 @@ extension CPInterfaceController {
     }
   }
 
+  /// Pops the top template, skipping the raise case (nothing above the root).
+  func safePop(animated: Bool, completion: ((Bool, Error?) -> Void)? = nil) {
+    whenStackSettled { controller in
+      controller.guardedPop(animated: animated, completion: completion)
+    }
+  }
+
   /// Pops back to `template`, skipping the raise case (not in the hierarchy).
   /// A no-op success when it is already the top template.
   func safePop(to template: CPTemplate, animated: Bool, completion: ((Bool, Error?) -> Void)? = nil) {
-    guard templates.contains(where: { $0 === template }) else {
-      Self.stackLogger.warning("pop(to:) skipped: \(Self.name(of: template)) is not in the stack")
-      completion?(false, nil)
-      return
-    }
-    guard topTemplate !== template else {
-      completion?(true, nil)
-      return
-    }
-    pop(to: template, animated: animated) { popped, error in
-      if let error {
-        Self.stackLogger.error("pop(to:) \(Self.name(of: template)) failed: \(error.localizedDescription)")
+    whenStackSettled { controller in
+      guard controller.templates.contains(where: { $0 === template }) else {
+        Self.stackLogger.warning("pop(to:) skipped: \(Self.name(of: template)) is not in the stack")
+        completion?(false, nil)
+        return
+      }
+      guard controller.topTemplate !== template else {
+        completion?(true, nil)
+        return
+      }
+      controller.pop(to: template, animated: animated) { popped, error in
+        if let error {
+          Self.stackLogger.error("pop(to:) \(Self.name(of: template)) failed: \(error.localizedDescription)")
+        }
+        completion?(popped, error)
       }
-      completion?(popped, error)
     }
   }
 
   func safePopToRoot(animated: Bool, completion: ((Bool, Error?) -> Void)? = nil) {
-    popToRootTemplate(animated: animated) { popped, error in
-      if let error {
-        Self.stackLogger.error("popToRootTemplate failed: \(error.localizedDescription)")
+    whenStackSettled { controller in
+      controller.popToRootTemplate(animated: animated) { popped, error in
+        if let error {
+          Self.stackLogger.error("popToRootTemplate failed: \(error.localizedDescription)")
+        }
+        completion?(popped, error)
       }
-      completion?(popped, error)
     }
   }
 
   func safeSetRoot(_ template: CPTemplate, animated: Bool, completion: ((Bool, Error?) -> Void)? = nil) {
-    setRootTemplate(template, animated: animated) { set, error in
-      if let error {
-        Self.stackLogger.error("setRootTemplate \(Self.name(of: template)) failed: \(error.localizedDescription)")
+    whenStackSettled { controller in
+      controller.setRootTemplate(template, animated: animated) { set, error in
+        if let error {
+          Self.stackLogger.error("setRootTemplate \(Self.name(of: template)) failed: \(error.localizedDescription)")
+        }
+        completion?(set, error)
       }
-      completion?(set, error)
     }
   }
 
@@ -124,3 +175,22 @@ extension CPInterfaceController {
     }
   }
 }
+
+/// The guarded pop and push a replacement is made of, so a push that still
+/// cannot fit skips and logs rather than raising.
+@MainActor
+private struct GuardedTemplateStack: TemplateStack {
+  let controller: CPInterfaceController
+
+  var templates: [CPTemplate] {
+    controller.templates
+  }
+
+  func popTop(completion: @escaping (Bool, Error?) -> Void) {
+    controller.guardedPop(animated: false, completion: completion)
+  }
+
+  func push(_ template: CPTemplate, animated: Bool, completion: @escaping (Bool, Error?) -> Void) {
+    controller.guardedPush(template, animated: animated, completion: completion)
+  }
+}