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

package/ios/Browser/SearchDrillIn.swift

@@ -1,18 +1,18 @@
 import Foundation
 
 /// A search result that may or may not be directly playable. `src` is the
-/// playable stream; `url` is a browsable container path. Abstracting these two
+/// playable stream; `path` is a browsable container path. Abstracting these two
 /// fields keeps the drill-in decision free of the Nitro `Track` type so it can
 /// be unit-tested.
 protocol PlayableSearchItem {
   var src: String? { get }
-  var url: String? { get }
+  var path: String? { get }
 }
 
 enum SearchDrillIn {
   /// Picks the playable items for a "play «X»" voice search.
   ///
-  /// If the first result is browsable-only (a `url` container with no `src` — a
+  /// If the first result is browsable-only (a `path` container with no `src` — a
   /// place/genre page), drills into it via `resolveChildren` and uses its
   /// playable children, so we play the first station *inside* the page rather
   /// than skipping the page for a later inline station. Falls back to the flat
@@ -25,8 +25,8 @@ enum SearchDrillIn {
     guard !children.isEmpty else { return nil }
 
     let candidates: [Item]
-    if let first = children.first, first.src == nil, let url = first.url {
-      let drilled = try await resolveChildren(url).filter { $0.src != nil }
+    if let first = children.first, first.src == nil, let path = first.path {
+      let drilled = try await resolveChildren(path).filter { $0.src != nil }
       candidates = drilled.isEmpty ? children : drilled
     } else {
       candidates = children
@@ -37,7 +37,7 @@ enum SearchDrillIn {
   }
 }
 
-// The real Nitro `Track` already carries `src`/`url`; conform it for the app
+// The real Nitro `Track` already carries `src`/`path`; conform it for the app
 // build. (The testable target builds without NitroModules and uses a stub item.)
 #if canImport(NitroModules)
   extension Track: PlayableSearchItem {}

package/ios/Browser/SectionPresentation.swift

@@ -0,0 +1,34 @@
+#if canImport(NitroModules)
+  import NitroModules
+#endif
+
+/// The rendered form of a section — the single place where (resolved style,
+/// platform capability) maps to what CarPlay draws. Degradation drops
+/// decorations before layout (ADR 0011): a *wrapping* grid can only reach the
+/// tile path where the platform has a wrapping tile container (CarPlay:
+/// iOS 26+'s element API); without one it becomes a list, where every item
+/// stays reachable instead of truncating at an unknowable width. A
+/// single-line grid (`gridWrap: false`) renders everywhere — the legacy image
+/// row IS the single-line presentation.
+enum SectionPresentation: Equatable {
+  case list
+  case singleLineRow
+  case wrappingGrid
+
+  /// - Parameter supportsWrappingGrid: whether the platform has a wrapping
+  ///   tile container. Injected (rather than read via `#available` here) so
+  ///   the mapping is testable off-device.
+  init(for style: SectionStyle?, supportsWrappingGrid: Bool) {
+    guard style?.display == .grid else {
+      self = .list
+      return
+    }
+    if style?.gridWrap == false {
+      self = .singleLineRow
+    } else if supportsWrappingGrid {
+      self = .wrappingGrid
+    } else {
+      self = .list
+    }
+  }
+}

package/ios/Browser/SectionScope.swift

@@ -1,35 +1,69 @@
 // Queue scope is the tapped section, not the whole page (ADR 0006): the
 // playback context a listener expects is the list they tapped in — a page
 // aggregating several sections must not leak next/previous across them.
+// Sections are structural (ADR 0010), so scoping is a lookup, not a
+// groupTitle-run derivation.
 enum SectionScope {
-  enum Section {
-    /// The tapped id lives inside an image row's items.
-    case imageRow([ImageRowItem])
-    /// The contiguous `groupTitle` run around the tapped child (items with
-    /// no group title form runs of their own).
-    case run([Track])
+  /// The section containing the tapped identity, plus the tapped child's
+  /// offset within it — non-nil only when the stamped flat index pinned the
+  /// exact copy.
+  struct Scoped {
+    let section: Section
+    let tappedOffset: Int?
   }
 
-  /// The section of `children` containing the playable `trackId`, or nil
-  /// when the id is not found.
-  static func section(of children: [Track], containing trackId: String) -> Section? {
-    for child in children {
-      if let items = child.imageRow, items.contains(where: { $0.src == trackId }) {
-        return .imageRow(items)
+  /// The section of `sections` containing the playable `trackId` (a track
+  /// identity: id when non-blank, else src), or nil when not found.
+  ///
+  /// `tappedIndex` — the flat page position stamped into the contextual URL
+  /// (children concatenated in section order) — is a tie-breaker, never an
+  /// identifier: when the child at that position still carries the tapped
+  /// identity, it pins which section (and which copy) was tapped; when it
+  /// doesn't (the list shifted), resolution falls back to the first section
+  /// containing the identity. A stale index can therefore never select a
+  /// different track — at worst a different copy of the same one.
+  static func scoped(
+    in sections: [Section],
+    containing trackId: String,
+    tappedIndex: Int? = nil,
+  ) -> Scoped? {
+    if let tappedIndex, tappedIndex >= 0 {
+      var start = 0
+      for section in sections {
+        let offset = tappedIndex - start
+        if offset < section.children.count {
+          if section.children[offset].identity == trackId {
+            return Scoped(section: section, tappedOffset: offset)
+          }
+          break
+        }
+        start += section.children.count
       }
     }
-    guard let index = children.firstIndex(where: { $0.src == trackId }) else {
-      return nil
-    }
-    let group = children[index].groupTitle
-    var start = index
-    while start > 0, children[start - 1].groupTitle == group {
-      start -= 1
-    }
-    var end = index
-    while end + 1 < children.count, children[end + 1].groupTitle == group {
-      end += 1
+    for section in sections {
+      if section.children.contains(where: { $0.identity == trackId }) {
+        return Scoped(section: section, tappedOffset: nil)
+      }
     }
-    return .run(Array(children[start ... end]))
+    return nil
+  }
+}
+
+// MARK: - Page shape helpers (ADR 0010)
+
+extension ResolvedTrack {
+  /// The canonical sectioned shape: `sections` wins when present; plain
+  /// `children` is authoring sugar for one untitled section.
+  var normalizedSections: [Section]? {
+    if let sections { return sections }
+    guard let children else { return nil }
+    return [.untitled(children)]
+  }
+
+  /// The page's children concatenated in section order — the flattening
+  /// that defines contextual `__index` positions and the flat views (tabs,
+  /// search) of a sectioned page.
+  var flattenedChildren: [Track]? {
+    normalizedSections.map { $0.flatMap(\.children) }
   }
 }

package/ios/Browser/StyleResolver.swift

@@ -0,0 +1,47 @@
+#if canImport(NitroModules)
+  import NitroModules
+#endif
+
+/// The one place style declarations resolve to effective values (ADR 0011).
+///
+/// Two mechanisms, deliberately distinct:
+/// - **Inherited item properties** resolve `track ?? section ?? page`,
+///   per property — a track's own declaration wins over the blocks that
+///   contain it.
+/// - **Container properties and the positional `display`** resolve by scope
+///   override: `section ?? page` — the page declares for its whole scope, a
+///   section overrides for its own children. `display` is never inherited
+///   item-to-container: each holder describes its own children, and a
+///   track's `display` is the promise for the page *it* opens, not its
+///   rendering inside this section.
+///
+/// Every key of `SectionStyle` must be read by `sectionStyle(section:page:)`
+/// and every inherited key of `TrackStyle` by `trackStyle(track:section:)` —
+/// Nitro flattens the spec's `extends`, so `src/style-resolution.test.ts`
+/// enforces this completeness, not the type system.
+enum StyleResolver {
+  /// Folds the page block into a section's block: every `SectionStyle` key
+  /// resolves `section ?? page`. The result is the section's effective
+  /// block; item resolution then only needs `track ?? section`.
+  static func sectionStyle(section: SectionStyle?, page: SectionStyle?) -> SectionStyle {
+    // Argument order is the generated init's (own properties before inherited
+    // ones — Nitro flattens `extends` own-props-first); the stub mirrors it.
+    SectionStyle(
+      gridWrap: section?.gridWrap ?? page?.gridWrap,
+      display: section?.display ?? page?.display,
+      artworkRendering: section?.artworkRendering ?? page?.artworkRendering,
+    )
+  }
+
+  /// Resolves a track's effective item properties against its (page-folded)
+  /// section block.
+  static func trackStyle(track: TrackStyle?, section: SectionStyle?) -> TrackStyle {
+    TrackStyle(
+      // Positional deny-list: `display` is never inherited onto an item —
+      // resolved nil, so no renderer can mistake the handle's page promise
+      // for this item's own layout.
+      display: nil,
+      artworkRendering: track?.artworkRendering ?? section?.artworkRendering,
+    )
+  }
+}

package/ios/Browser/TabBarEntries.swift

@@ -1,6 +1,6 @@
 /// Compares the tab-list fields the CarPlay tab bar actually renders.
 enum TabBarEntries {
-  /// Whether two tab lists produce identical tab-bar entries — title, url,
+  /// Whether two tab lists produce identical tab-bar entries — title, path,
   /// and the artwork inputs of `applyTabBarEntry`. Used to suppress
   /// `tabsChanged` when a tabs re-query (e.g. from `invalidateAllContent()`)
   /// resolves to the same entries, so an unchanged result never churns the
@@ -8,7 +8,7 @@ enum TabBarEntries {
   static func same(_ old: [Track]?, _ new: [Track]) -> Bool {
     guard let old, old.count == new.count else { return false }
     return zip(old, new).allSatisfy {
-      $0.title == $1.title && $0.url == $1.url && $0.artwork == $1.artwork
+      $0.title == $1.title && $0.path == $1.path && $0.artwork == $1.artwork
         && $0.artworkSource?.uri == $1.artworkSource?.uri
     }
   }

package/ios/Browser/TrackIdTemplate.swift

@@ -0,0 +1,37 @@
+import Foundation
+
+/// `{id}` template-token substitution for request-config string values (path, query values,
+/// header values), used by artwork URL resolution so a `nowPlayingArtwork` like
+/// `{ path: "/artwork/{id}" }` resolves per track.
+///
+/// A track without a non-blank id leaves the token LITERALLY in place — the request then
+/// visibly 404s, which is intended (garbage in, garbage out with a self-describing error
+/// trail; the caller logs a single warning when `containsToken` still matches after
+/// substitution). Mirrors Android's `substituteTrackId` / `configContainsIdToken` in
+/// `BrowserUrlResolution.kt` — keep the two in sync.
+enum TrackIdTemplate {
+  static let token = "{id}"
+
+  /// Replaces the token when `id` is non-blank; otherwise returns the value unchanged
+  /// (token left literal).
+  static func substitute(_ value: String?, id: String?) -> String? {
+    guard let id, !id.isEmpty else { return value }
+    return value?.replacingOccurrences(of: token, with: id)
+  }
+
+  /// Dictionary-value variant of `substitute` (query / header values).
+  static func substitute(_ values: [String: String]?, id: String?) -> [String: String]? {
+    guard let id, !id.isEmpty else { return values }
+    return values?.mapValues { $0.replacingOccurrences(of: token, with: id) }
+  }
+
+  /// Whether the value still carries the token (an unfilled `{id}`).
+  static func containsToken(_ value: String?) -> Bool {
+    value?.contains(token) == true
+  }
+
+  /// Whether any dictionary value still carries the token.
+  static func containsToken(_ values: [String: String]?) -> Bool {
+    values?.values.contains { $0.contains(token) } == true
+  }
+}

package/ios/CarPlay/CarPlayArtworkResolver.swift

@@ -29,7 +29,8 @@ enum CarPlayArtworkResolver {
   /// - Parameters:
   ///   - artwork: The track's `artwork` field (may be an SF Symbol string or URL)
   ///   - artworkSourceUri: The track's `artworkSource?.uri` field
-  ///   - artworkCarPlayTinted: Whether to apply light/dark tinting
+  ///   - stencil: Whether the artwork renders as a monochrome glyph tinted to
+  ///     the surface appearance (`style.artworkRendering: 'stencil'`)
   ///   - targetWidth: Target width in points
   ///   - targetHeight: Target height in points
   ///   - displayScale: The CarPlay display scale factor
@@ -37,7 +38,7 @@ enum CarPlayArtworkResolver {
   static func resolve(
     artwork: String?,
     artworkSourceUri: String?,
-    artworkCarPlayTinted: Bool?,
+    stencil: Bool,
     targetWidth: Double,
     targetHeight: Double,
     displayScale: Double,
@@ -57,7 +58,7 @@ enum CarPlayArtworkResolver {
           return resolveDirectFallback(
             artwork: artwork,
             artworkSourceUri: artworkSourceUri,
-            artworkCarPlayTinted: artworkCarPlayTinted,
+            stencil: stencil,
             targetWidth: targetWidth,
             targetHeight: targetHeight,
           )
@@ -66,7 +67,7 @@ enum CarPlayArtworkResolver {
         return .fetch(
           uri: resolved.uri,
           headers: resolved.headers,
-          shouldTint: artworkCarPlayTinted ?? false,
+          shouldTint: stencil,
           isSvg: isSvg,
         )
       }
@@ -76,7 +77,7 @@ enum CarPlayArtworkResolver {
     return resolveDirectFallback(
       artwork: artwork,
       artworkSourceUri: artworkSourceUri,
-      artworkCarPlayTinted: artworkCarPlayTinted,
+      stencil: stencil,
       targetWidth: targetWidth,
       targetHeight: targetHeight,
     )
@@ -85,7 +86,7 @@ enum CarPlayArtworkResolver {
   private static func resolveDirectFallback(
     artwork: String?,
     artworkSourceUri: String?,
-    artworkCarPlayTinted: Bool?,
+    stencil: Bool,
     targetWidth: Double,
     targetHeight: Double,
   ) -> ArtworkLoadAction {
@@ -100,7 +101,7 @@ enum CarPlayArtworkResolver {
     return .fetch(
       uri: directUri,
       headers: nil,
-      shouldTint: artworkCarPlayTinted ?? false,
+      shouldTint: stencil,
       isSvg: isSvg,
     )
   }