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

package/ios/Browser/JsonModels.swift

@@ -62,41 +62,125 @@ extension JsonArtwork {
   }
 }
 
-/// JSON model for image row items (horizontal thumbnail row).
-struct JsonImageRowItem: Codable {
-  let id: String?
-  let url: String?
-  let src: String?
-  let artwork: String?
-  let title: String
-  let artist: String?
-  let album: String?
-  let albumUrl: String?
-  let live: Bool?
-  let request: JsonTrackRequest?
+/// A style declaration block on the wire (ADR 0011):
+/// `{ display?, gridWrap?, artworkRendering? }`.
+///
+/// One JSON model serves both the `TrackStyle` and `SectionStyle` positions —
+/// keys that don't exist at the narrower position simply don't map.
+///
+/// Decoding is tolerant by design: a stale payload — the retired string
+/// styles, a wrong-typed field, an unknown enum value — must degrade to "no
+/// declaration", never fail the page or the persisted playback state (the
+/// decoders above this are strict, so a throw here would kill the whole
+/// payload). `init(from:)` therefore never throws, and unknown enum values
+/// map to nil at `toNitro` time.
+struct JsonStyle: Codable, Equatable {
+  let display: String?
+  let gridWrap: Bool?
+  let artworkRendering: String?
 
   init(
-    id: String? = nil,
-    url: String? = nil,
-    src: String? = nil,
-    artwork: String? = nil,
-    title: String,
-    artist: String? = nil,
-    album: String? = nil,
-    albumUrl: String? = nil,
-    live: Bool? = nil,
-    request: JsonTrackRequest? = nil,
+    display: String? = nil,
+    gridWrap: Bool? = nil,
+    artworkRendering: String? = nil,
+  ) {
+    self.display = display
+    self.gridWrap = gridWrap
+    self.artworkRendering = artworkRendering
+  }
+
+  init(from decoder: Decoder) throws {
+    // A non-object value (the retired `style: 'grid'` string) decodes as an
+    // empty block rather than failing the parent.
+    guard let container = try? decoder.container(keyedBy: CodingKeys.self) else {
+      display = nil
+      gridWrap = nil
+      artworkRendering = nil
+      return
+    }
+    display = (try? container.decodeIfPresent(String.self, forKey: .display)) ?? nil
+    gridWrap = (try? container.decodeIfPresent(Bool.self, forKey: .gridWrap)) ?? nil
+    artworkRendering = (try? container.decodeIfPresent(String.self, forKey: .artworkRendering)) ?? nil
+  }
+}
+
+extension JsonStyle {
+  /// The wire strings map to Nitro enums here, tolerantly: an unknown value
+  /// (a future `display` mode, say) is no declaration, not an error. A block
+  /// that resolves to no declarations at all — `{}`, the tolerant decoder's
+  /// empty result for the retired string vocabulary, or all-unknown values —
+  /// maps to nil, so "no declaration" has one shape on every platform
+  /// (Android's lenient mapper makes the same collapse).
+  func toTrackStyle() -> TrackStyle? {
+    let display = display.flatMap { StyleDisplay(fromString: $0.lowercased()) }
+    let artworkRendering = artworkRendering.flatMap { ArtworkRendering(fromString: $0.lowercased()) }
+    guard display != nil || artworkRendering != nil else { return nil }
+    return TrackStyle(display: display, artworkRendering: artworkRendering)
+  }
+
+  func toSectionStyle() -> SectionStyle? {
+    let display = display.flatMap { StyleDisplay(fromString: $0.lowercased()) }
+    let artworkRendering = artworkRendering.flatMap { ArtworkRendering(fromString: $0.lowercased()) }
+    guard display != nil || artworkRendering != nil || gridWrap != nil else { return nil }
+    // Argument order is the generated init's (own properties before
+    // inherited ones — Nitro flattens `extends` own-props-first).
+    return SectionStyle(
+      gridWrap: gridWrap,
+      display: display,
+      artworkRendering: artworkRendering,
+    )
+  }
+
+  /// Snapshot a live track block back to its JSON model (for persistence).
+  /// An all-nil block snapshots as no block — the decoders collapse it to
+  /// "no declaration" anyway, so never persist the distinction.
+  init?(_ style: TrackStyle?) {
+    guard let style, style.display != nil || style.artworkRendering != nil else { return nil }
+    self.init(
+      display: Self.string(style.display),
+      artworkRendering: Self.string(style.artworkRendering),
+    )
+  }
+
+  private static func string(_ display: StyleDisplay?) -> String? {
+    switch display {
+    case .list: "list"
+    case .grid: "grid"
+    case nil: nil
+    }
+  }
+
+  private static func string(_ rendering: ArtworkRendering?) -> String? {
+    switch rendering {
+    case .original: "original"
+    case .stencil: "stencil"
+    case nil: nil
+    }
+  }
+}
+
+/// JSON model for a page section (ADR 0010). Legacy `groupTitle`/`imageRow`
+/// keys in payloads are simply unknown to these models and decode as
+/// ignored dead weight.
+struct JsonSection: Codable {
+  let title: String?
+  let subtitle: String?
+  let style: JsonStyle?
+  let path: String?
+  let children: [JsonTrack]
+
+  init(
+    title: String? = nil,
+    subtitle: String? = nil,
+    style: JsonStyle? = nil,
+    path: String? = nil,
+    children: [JsonTrack],
   ) {
-    self.id = id
-    self.url = url
-    self.src = src
-    self.artwork = artwork
     self.title = title
-    self.artist = artist
-    self.album = album
-    self.albumUrl = albumUrl
-    self.live = live
-    self.request = request
+    self.subtitle = subtitle
+    self.style = style
+    self.path = path
+    self.children = children
   }
 }
 
@@ -116,59 +200,59 @@ struct JsonTrackRequest: Codable {
 /// JSON model for resolved track (container with children).
 struct JsonResolvedTrack: Codable {
   let id: String?
-  let url: String
+  let path: String
   let title: String
   let subtitle: String?
   let artwork: JsonArtwork?
   let artist: String?
-  let albumUrl: String?
+  let albumPath: String?
   let album: String?
   let description: String?
   let genre: String?
   let duration: Double?
+  let sections: [JsonSection]?
   let children: [JsonTrack]?
   let src: String?
-  let style: String?
-  let childrenStyle: String?
-  let groupTitle: String?
+  let style: JsonStyle?
+  let disabled: Bool?
   let live: Bool?
   let carPlaySiriListButton: String?
 
   init(
     id: String? = nil,
-    url: String,
+    path: String,
     title: String,
     subtitle: String? = nil,
     artwork: JsonArtwork? = nil,
     artist: String? = nil,
-    albumUrl: String? = nil,
+    albumPath: String? = nil,
     album: String? = nil,
     description: String? = nil,
     genre: String? = nil,
     duration: Double? = nil,
+    sections: [JsonSection]? = nil,
     children: [JsonTrack]? = nil,
     src: String? = nil,
-    style: String? = nil,
-    childrenStyle: String? = nil,
-    groupTitle: String? = nil,
+    style: JsonStyle? = nil,
+    disabled: Bool? = nil,
     live: Bool? = nil,
     carPlaySiriListButton: String? = nil,
   ) {
-    self.url = url
+    self.path = path
     self.title = title
     self.subtitle = subtitle
     self.artwork = artwork
     self.artist = artist
-    self.albumUrl = albumUrl
+    self.albumPath = albumPath
     self.album = album
     self.description = description
     self.genre = genre
     self.duration = duration
+    self.sections = sections
     self.children = children
     self.src = src
     self.style = style
-    self.childrenStyle = childrenStyle
-    self.groupTitle = groupTitle
+    self.disabled = disabled
     self.live = live
     self.carPlaySiriListButton = carPlaySiriListButton
     self.id = id
@@ -178,50 +262,46 @@ struct JsonResolvedTrack: Codable {
 /// JSON model for individual tracks.
 struct JsonTrack: Codable {
   let id: String?
-  let url: String?
+  let path: String?
   let title: String
   let subtitle: String?
   let artwork: JsonArtwork?
   let artist: String?
-  let albumUrl: String?
+  let albumPath: String?
   let album: String?
   let description: String?
   let genre: String?
   let duration: Double?
   let src: String?
   let request: JsonTrackRequest?
-  let style: String?
-  let childrenStyle: String?
-  let groupTitle: String?
+  let style: JsonStyle?
+  let disabled: Bool?
   let live: Bool?
-  let imageRow: [JsonImageRowItem]?
 
   init(
     id: String? = nil,
-    url: String? = nil,
+    path: String? = nil,
     title: String,
     subtitle: String? = nil,
     artwork: JsonArtwork? = nil,
     artist: String? = nil,
-    albumUrl: String? = nil,
+    albumPath: String? = nil,
     album: String? = nil,
     description: String? = nil,
     genre: String? = nil,
     duration: Double? = nil,
     src: String? = nil,
     request: JsonTrackRequest? = nil,
-    style: String? = nil,
-    childrenStyle: String? = nil,
-    groupTitle: String? = nil,
+    style: JsonStyle? = nil,
+    disabled: Bool? = nil,
     live: Bool? = nil,
-    imageRow: [JsonImageRowItem]? = nil,
   ) {
-    self.url = url
+    self.path = path
     self.title = title
     self.subtitle = subtitle
     self.artwork = artwork
     self.artist = artist
-    self.albumUrl = albumUrl
+    self.albumPath = albumPath
     self.album = album
     self.description = description
     self.genre = genre
@@ -229,10 +309,8 @@ struct JsonTrack: Codable {
     self.src = src
     self.request = request
     self.style = style
-    self.childrenStyle = childrenStyle
-    self.groupTitle = groupTitle
+    self.disabled = disabled
     self.live = live
-    self.imageRow = imageRow
     self.id = id
   }
 }
@@ -250,26 +328,27 @@ struct JsonTrack: Codable {
 
   extension JsonTrack {
     /// Snapshot the persistable subset of a live Track (inverse of `toNitro()`).
+    /// The track's own declared style block and `disabled` persist (ADR 0011);
+    /// section/page-inherited values are never stamped onto tracks and
+    /// re-resolve at render, exactly as they do live.
     init(from track: Track) {
       self.init(
         id: track.id,
-        url: track.url,
+        path: track.path,
         title: track.title,
         subtitle: track.subtitle,
         artwork: JsonArtwork(track.artwork),
         artist: track.artist,
-        albumUrl: track.albumUrl,
+        albumPath: track.albumPath,
         album: track.album,
         description: track.description,
         genre: track.genre,
         duration: track.duration,
         src: track.src,
         request: track.request.map(JsonTrackRequest.init(from:)),
-        style: nil,
-        childrenStyle: nil,
-        groupTitle: track.groupTitle,
+        style: JsonStyle(track.style),
+        disabled: track.disabled,
         live: track.live,
-        imageRow: nil,
       )
     }
   }
@@ -289,14 +368,16 @@ struct JsonTrack: Codable {
     init(from track: Track) {
       self.init(
         id: track.id,
-        url: track.url,
+        path: track.path,
         title: track.title,
         artwork: JsonArtwork(track.artwork),
         artist: track.artist,
-        albumUrl: track.albumUrl,
+        albumPath: track.albumPath,
         album: track.album,
         src: track.src,
         request: track.request.map(JsonTrackRequest.init(from:)),
+        style: JsonStyle(track.style),
+        disabled: track.disabled,
         live: track.live,
       )
     }
@@ -308,26 +389,14 @@ struct JsonTrack: Codable {
 
 #if canImport(NitroModules)
 
-  private extension String {
-    func toTrackStyle() -> TrackStyle? {
-      TrackStyle(fromString: lowercased())
-    }
-  }
-
-  extension JsonImageRowItem {
-    func toNitro() -> ImageRowItem {
-      ImageRowItem(
-        id: id,
-        url: url,
-        src: src,
-        artwork: artwork,
-        artworkSource: nil,
+  extension JsonSection {
+    func toNitro() -> Section {
+      Section(
         title: title,
-        artist: artist,
-        album: album,
-        albumUrl: albumUrl,
-        live: live,
-        request: request?.toNitro(),
+        subtitle: subtitle,
+        style: style?.toSectionStyle(),
+        path: path,
+        children: children.map { $0.toNitro() },
       )
     }
   }
@@ -335,28 +404,26 @@ struct JsonTrack: Codable {
   extension JsonResolvedTrack {
     func toNitro() -> ResolvedTrack {
       ResolvedTrack(
-        url: url,
+        path: path,
+        style: style?.toSectionStyle(),
+        sections: sections?.map { $0.toNitro() },
         children: children?.map { $0.toNitro() },
         carPlaySiriListButton: carPlaySiriListButton.flatMap { CarPlaySiriListButtonPosition(fromString: $0) },
         id: id,
         src: src,
         artwork: artwork?.toNitro(),
         artworkSource: nil, request: nil,
-        artworkCarPlayTinted: nil,
         title: title,
         subtitle: subtitle,
         artist: artist,
-        albumUrl: albumUrl,
+        albumPath: albumPath,
         album: album,
         description: description,
         genre: genre,
         duration: duration,
-        style: style?.toTrackStyle(),
-        childrenStyle: childrenStyle?.toTrackStyle(),
+        disabled: disabled,
         favorited: nil,
-        groupTitle: groupTitle,
         live: live,
-        imageRow: nil,
       )
     }
   }
@@ -365,26 +432,23 @@ struct JsonTrack: Codable {
     func toNitro() -> Track {
       Track(
         id: id,
-        url: url,
+        path: path,
         src: src,
         artwork: artwork?.toNitro(),
         artworkSource: nil,
         request: request?.toNitro(),
-        artworkCarPlayTinted: nil,
         title: title,
         subtitle: subtitle,
         artist: artist,
-        albumUrl: albumUrl,
+        albumPath: albumPath,
         album: album,
         description: description,
         genre: genre,
         duration: duration,
         style: style?.toTrackStyle(),
-        childrenStyle: childrenStyle?.toTrackStyle(),
+        disabled: disabled,
         favorited: nil,
-        groupTitle: groupTitle,
         live: live,
-        imageRow: imageRow?.map { $0.toNitro() },
       )
     }
   }
@@ -396,15 +460,29 @@ struct JsonTrack: Codable {
     func toNitro() -> Track {
       Track(
         id: id ?? "",
-        url: url,
+        path: path,
         src: src,
+        artwork: artwork?.toNitro(),
         request: request.map { TrackRequest(userAgent: $0.userAgent, headers: $0.headers, query: $0.query) },
         title: title,
         artist: artist,
-        albumUrl: albumUrl,
+        albumPath: albumPath,
         album: album,
+        style: style?.toTrackStyle(),
+        disabled: disabled,
         live: live,
-        artwork: artwork?.toNitro(),
+      )
+    }
+  }
+
+  extension JsonSection {
+    func toNitro() -> Section {
+      Section(
+        title: title,
+        subtitle: subtitle,
+        style: style?.toSectionStyle(),
+        path: path,
+        children: children.map { $0.toNitro() },
       )
     }
   }
@@ -412,10 +490,13 @@ struct JsonTrack: Codable {
   extension JsonResolvedTrack {
     func toNitro() -> ResolvedTrack {
       ResolvedTrack(
-        url: url,
+        path: path,
+        style: style?.toSectionStyle(),
+        sections: sections?.map { $0.toNitro() },
         children: children?.map { $0.toNitro() },
         artwork: artwork?.toNitro(),
         title: title,
+        disabled: disabled,
       )
     }
   }

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) }
   }
 }