react-native-audio-browser 0.1.0 → 0.2.0-next.1

package/ios/Browser/JsonModels.swift

@@ -1,33 +1,127 @@
 import Foundation
-import NitroModules
+#if canImport(NitroModules)
+  import NitroModules
+#endif
 
 /// JSON serializable models for parsing API responses.
 /// These will be converted to Nitro types after parsing.
 
+/// A track's `artwork` on the wire: a URL string, or `{ light, dark }`.
+///
+/// These models are the browse-response format as well as the persistence
+/// format, so this is what decides whether a payload parses at all — a plain
+/// `String?` here rejects the whole page with a type mismatch, however tolerant
+/// the layers above it are.
+///
+/// Encodes back to whichever shape it came from, so a persisted snapshot
+/// round-trips, and one written before pairs existed still decodes as `.single`.
+enum JsonArtwork: Codable, Equatable {
+  case single(String)
+  case variants(light: String, dark: String)
+
+  private struct Variants: Codable, Equatable {
+    let light: String
+    let dark: String
+  }
+
+  init(from decoder: Decoder) throws {
+    let container = try decoder.singleValueContainer()
+    if let url = try? container.decode(String.self) {
+      self = .single(url)
+    } else {
+      let variants = try container.decode(Variants.self)
+      self = .variants(light: variants.light, dark: variants.dark)
+    }
+  }
+
+  func encode(to encoder: Encoder) throws {
+    var container = encoder.singleValueContainer()
+    switch self {
+    case let .single(url): try container.encode(url)
+    case let .variants(light, dark): try container.encode(Variants(light: light, dark: dark))
+    }
+  }
+}
+
+extension JsonArtwork {
+  /// The Nitro union this maps onto, one case per case.
+  func toNitro() -> Variant_String_ArtworkVariants {
+    switch self {
+    case let .single(url): .first(url)
+    case let .variants(light, dark): .second(ArtworkVariants(light: light, dark: dark))
+    }
+  }
+
+  /// Snapshot a live artwork value back to its JSON model.
+  init?(_ artwork: Variant_String_ArtworkVariants?) {
+    switch artwork {
+    case nil: return nil
+    case let .first(url): self = .single(url)
+    case let .second(variants): self = .variants(light: variants.light, dark: variants.dark)
+    }
+  }
+}
+
 /// 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?
 
   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,
   ) {
+    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
   }
 }
 
+/// JSON model for per-track HTTP request configuration.
+struct JsonTrackRequest: Codable {
+  let userAgent: String?
+  let headers: [String: String]?
+  let query: [String: String]?
+
+  #if canImport(NitroModules)
+    func toNitro() -> TrackRequest {
+      TrackRequest(userAgent: userAgent, headers: headers, query: query)
+    }
+  #endif
+}
+
 /// JSON model for resolved track (container with children).
 struct JsonResolvedTrack: Codable {
+  let id: String?
   let url: String
   let title: String
   let subtitle: String?
-  let artwork: String?
+  let artwork: JsonArtwork?
   let artist: String?
+  let albumUrl: String?
   let album: String?
   let description: String?
   let genre: String?
@@ -41,11 +135,13 @@ struct JsonResolvedTrack: Codable {
   let carPlaySiriListButton: String?
 
   init(
+    id: String? = nil,
     url: String,
     title: String,
     subtitle: String? = nil,
-    artwork: String? = nil,
+    artwork: JsonArtwork? = nil,
     artist: String? = nil,
+    albumUrl: String? = nil,
     album: String? = nil,
     description: String? = nil,
     genre: String? = nil,
@@ -63,6 +159,7 @@ struct JsonResolvedTrack: Codable {
     self.subtitle = subtitle
     self.artwork = artwork
     self.artist = artist
+    self.albumUrl = albumUrl
     self.album = album
     self.description = description
     self.genre = genre
@@ -74,21 +171,25 @@ struct JsonResolvedTrack: Codable {
     self.groupTitle = groupTitle
     self.live = live
     self.carPlaySiriListButton = carPlaySiriListButton
+    self.id = id
   }
 }
 
 /// JSON model for individual tracks.
 struct JsonTrack: Codable {
+  let id: String?
   let url: String?
   let title: String
   let subtitle: String?
-  let artwork: String?
+  let artwork: JsonArtwork?
   let artist: String?
+  let albumUrl: 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?
@@ -96,16 +197,19 @@ struct JsonTrack: Codable {
   let imageRow: [JsonImageRowItem]?
 
   init(
+    id: String? = nil,
     url: String? = nil,
     title: String,
     subtitle: String? = nil,
-    artwork: String? = nil,
+    artwork: JsonArtwork? = nil,
     artist: String? = nil,
+    albumUrl: 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,
@@ -117,86 +221,203 @@ struct JsonTrack: Codable {
     self.subtitle = subtitle
     self.artwork = artwork
     self.artist = artist
+    self.albumUrl = albumUrl
     self.album = album
     self.description = description
     self.genre = genre
     self.duration = duration
     self.src = src
+    self.request = request
     self.style = style
     self.childrenStyle = childrenStyle
     self.groupTitle = groupTitle
     self.live = live
     self.imageRow = imageRow
+    self.id = id
   }
 }
 
+// MARK: - Snapshot live Nitro types back to JSON models (for persistence)
+
+#if canImport(NitroModules)
+
+  extension JsonTrackRequest {
+    /// Snapshot a live TrackRequest back to its JSON model.
+    init(from request: TrackRequest) {
+      self.init(userAgent: request.userAgent, headers: request.headers, query: request.query)
+    }
+  }
+
+  extension JsonTrack {
+    /// Snapshot the persistable subset of a live Track (inverse of `toNitro()`).
+    init(from track: Track) {
+      self.init(
+        id: track.id,
+        url: track.url,
+        title: track.title,
+        subtitle: track.subtitle,
+        artwork: JsonArtwork(track.artwork),
+        artist: track.artist,
+        albumUrl: track.albumUrl,
+        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,
+        live: track.live,
+        imageRow: nil,
+      )
+    }
+  }
+
+#else
+
+  extension JsonTrackRequest {
+    /// Snapshot a live TrackRequest back to its JSON model (SPM test-target stub).
+    init(from request: TrackRequest) {
+      self.init(userAgent: request.userAgent, headers: request.headers, query: request.query)
+    }
+  }
+
+  extension JsonTrack {
+    /// Snapshot the persistable subset of a live Track (inverse of `toNitro()`).
+    /// SPM test-target stub — only fields present on the minimal `Track` stub.
+    init(from track: Track) {
+      self.init(
+        id: track.id,
+        url: track.url,
+        title: track.title,
+        artwork: JsonArtwork(track.artwork),
+        artist: track.artist,
+        albumUrl: track.albumUrl,
+        album: track.album,
+        src: track.src,
+        request: track.request.map(JsonTrackRequest.init(from:)),
+        live: track.live,
+      )
+    }
+  }
+
+#endif
+
 // MARK: - Convert JSON models to Nitro types
 
-private extension String {
-  func toTrackStyle() -> TrackStyle? {
-    TrackStyle(fromString: lowercased())
+#if canImport(NitroModules)
+
+  private extension String {
+    func toTrackStyle() -> TrackStyle? {
+      TrackStyle(fromString: lowercased())
+    }
   }
-}
 
-extension JsonImageRowItem {
-  func toNitro() -> ImageRowItem {
-    ImageRowItem(
-      url: url,
-      artwork: artwork,
-      artworkSource: nil,
-      title: title,
-    )
+  extension JsonImageRowItem {
+    func toNitro() -> ImageRowItem {
+      ImageRowItem(
+        id: id,
+        url: url,
+        src: src,
+        artwork: artwork,
+        artworkSource: nil,
+        title: title,
+        artist: artist,
+        album: album,
+        albumUrl: albumUrl,
+        live: live,
+        request: request?.toNitro(),
+      )
+    }
   }
-}
 
-extension JsonResolvedTrack {
-  func toNitro() -> ResolvedTrack {
-    ResolvedTrack(
-      url: url,
-      children: children?.map { $0.toNitro() },
-      carPlaySiriListButton: carPlaySiriListButton.flatMap { CarPlaySiriListButtonPosition(fromString: $0) },
-      src: src,
-      artwork: artwork,
-      artworkSource: nil,
-      artworkCarPlayTinted: nil,
-      title: title,
-      subtitle: subtitle,
-      artist: artist,
-      album: album,
-      description: description,
-      genre: genre,
-      duration: duration,
-      style: style?.toTrackStyle(),
-      childrenStyle: childrenStyle?.toTrackStyle(),
-      favorited: nil,
-      groupTitle: groupTitle,
-      live: live,
-      imageRow: nil,
-    )
+  extension JsonResolvedTrack {
+    func toNitro() -> ResolvedTrack {
+      ResolvedTrack(
+        url: url,
+        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,
+        album: album,
+        description: description,
+        genre: genre,
+        duration: duration,
+        style: style?.toTrackStyle(),
+        childrenStyle: childrenStyle?.toTrackStyle(),
+        favorited: nil,
+        groupTitle: groupTitle,
+        live: live,
+        imageRow: nil,
+      )
+    }
   }
-}
 
-extension JsonTrack {
-  func toNitro() -> Track {
-    Track(
-      url: url,
-      src: src,
-      artwork: artwork,
-      artworkSource: nil,
-      artworkCarPlayTinted: nil,
-      title: title,
-      subtitle: subtitle,
-      artist: artist,
-      album: album,
-      description: description,
-      genre: genre,
-      duration: duration,
-      style: style?.toTrackStyle(),
-      childrenStyle: childrenStyle?.toTrackStyle(),
-      favorited: nil,
-      groupTitle: groupTitle,
-      live: live,
-      imageRow: imageRow?.map { $0.toNitro() },
-    )
+  extension JsonTrack {
+    func toNitro() -> Track {
+      Track(
+        id: id,
+        url: url,
+        src: src,
+        artwork: artwork?.toNitro(),
+        artworkSource: nil,
+        request: request?.toNitro(),
+        artworkCarPlayTinted: nil,
+        title: title,
+        subtitle: subtitle,
+        artist: artist,
+        albumUrl: albumUrl,
+        album: album,
+        description: description,
+        genre: genre,
+        duration: duration,
+        style: style?.toTrackStyle(),
+        childrenStyle: childrenStyle?.toTrackStyle(),
+        favorited: nil,
+        groupTitle: groupTitle,
+        live: live,
+        imageRow: imageRow?.map { $0.toNitro() },
+      )
+    }
   }
-}
+
+#else
+
+  // Test-only path: construct minimal stubs for SPM test builds.
+  extension JsonTrack {
+    func toNitro() -> Track {
+      Track(
+        id: id ?? "",
+        url: url,
+        src: src,
+        request: request.map { TrackRequest(userAgent: $0.userAgent, headers: $0.headers, query: $0.query) },
+        title: title,
+        artist: artist,
+        albumUrl: albumUrl,
+        album: album,
+        live: live,
+        artwork: artwork?.toNitro(),
+      )
+    }
+  }
+
+  extension JsonResolvedTrack {
+    func toNitro() -> ResolvedTrack {
+      ResolvedTrack(
+        url: url,
+        children: children?.map { $0.toNitro() },
+        artwork: artwork?.toNitro(),
+        title: title,
+      )
+    }
+  }
+
+#endif

package/ios/Browser/MediaResolveComposer.swift

@@ -0,0 +1,114 @@
+import Foundation
+
+/// Pure, Nitro-free composition logic for the media `resolve` layer.
+///
+/// The two pieces that need testing in isolation from the Nitro bridge are:
+///  1. the variant unwrap — `resolve(track)` returns a `RequestConfig` either
+///     synchronously (`.first`) or via a `Promise` (`.second`); both arms must
+///     yield the same `RequestConfig`; and
+///  2. the merge — the resolved config is layered over the base with
+///     override-wins per field (and per-key dict merge for headers/query).
+///
+/// Production (`BrowserManager+URLResolution.swift`) builds the Nitro
+/// `RequestConfig` values and calls into `MediaResolveComposer.merge` /
+/// `.unwrap`; the SPM test target exercises the same functions against the
+/// stub `RequestConfigLike` value type. Keeping the logic here (rather than in
+/// the Nitro-only extension) is what makes it reachable from tests.
+enum MediaResolveComposer {
+  /// A minimal field set mirroring `RequestConfig`, used so the merge logic can
+  /// be expressed once and shared between the Nitro types and the test stub.
+  struct RequestConfigLike: Equatable {
+    var method: String?
+    var path: String?
+    var baseUrl: String?
+    var headers: [String: String]?
+    var query: [String: String]?
+    var body: String?
+    var contentType: String?
+    var userAgent: String?
+
+    init(
+      method: String? = nil,
+      path: String? = nil,
+      baseUrl: String? = nil,
+      headers: [String: String]? = nil,
+      query: [String: String]? = nil,
+      body: String? = nil,
+      contentType: String? = nil,
+      userAgent: String? = nil,
+    ) {
+      self.method = method
+      self.path = path
+      self.baseUrl = baseUrl
+      self.headers = headers
+      self.query = query
+      self.body = body
+      self.contentType = contentType
+      self.userAgent = userAgent
+    }
+  }
+
+  /// The unwrapped result of a `resolve(track)` variant.
+  enum ResolveVariant<Config> {
+    /// `.first` — a synchronous config.
+    case sync(Config)
+    /// `.second` — a config delivered via an async closure (a Promise in prod).
+    case async(() async throws -> Config)
+  }
+
+  /// Unwraps a sync/async config into a concrete config, awaiting the async arm
+  /// if needed. (Production no longer uses a Nitro variant — `resolve`/`resolveSync`
+  /// are separate fields — but this stays as a pure, testable composition helper.)
+  static func unwrap<Config>(_ variant: ResolveVariant<Config>) async throws -> Config {
+    switch variant {
+    case let .sync(config):
+      config
+    case let .async(makeConfig):
+      try await makeConfig()
+    }
+  }
+
+  /// Run-both resolve composition: the async-resolved config first, then the
+  /// sync-resolved merged over it (sync winning) via `combine`. `nil` when neither
+  /// produced a config. Generic so it is shared verbatim by production (Nitro
+  /// `RequestConfig` + `mergeRequestConfig`) and tests (`RequestConfigLike` +
+  /// `merge`) — one implementation, exercised on both sides.
+  static func composeResolved<C>(
+    async asyncResolved: C?,
+    sync syncResolved: C?,
+    combine: (C, C) -> C,
+  ) -> C? {
+    switch (asyncResolved, syncResolved) {
+    case (nil, nil): nil
+    case let (value?, nil): value
+    case let (nil, value?): value
+    case let (a?, s?): combine(a, s)
+    }
+  }
+
+  /// Override-wins per-field merge. Headers and query merge per-key (override
+  /// key wins). Matches `BrowserManager.mergeRequestConfig`.
+  static func merge(base: RequestConfigLike, override: RequestConfigLike) -> RequestConfigLike {
+    RequestConfigLike(
+      method: override.method ?? base.method,
+      path: override.path ?? base.path,
+      baseUrl: override.baseUrl ?? base.baseUrl,
+      headers: mergeDicts(base.headers, override.headers),
+      query: mergeDicts(base.query, override.query),
+      body: override.body ?? base.body,
+      contentType: override.contentType ?? base.contentType,
+      userAgent: override.userAgent ?? base.userAgent,
+    )
+  }
+
+  /// Per-key dict merge with override-wins; nil-safe (returns the non-nil side,
+  /// or nil when both are nil). Matches `BrowserManager.mergeDicts`.
+  static func mergeDicts(_ base: [String: String]?, _ override: [String: String]?) -> [String: String]? {
+    switch (base, override) {
+    case (nil, nil): nil
+    case let (base?, nil): base
+    case let (nil, override?): override
+    case let (base?, override?): base.merging(override) { _, new in new }
+    }
+  }
+}

package/ios/Browser/SearchDrillIn.swift

@@ -0,0 +1,44 @@
+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
+/// 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 }
+}
+
+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
+  /// 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
+  /// playable results when the first result is already playable or the drill-in
+  /// yields nothing. Returns nil when nothing is playable.
+  static func playable<Item: PlayableSearchItem>(
+    from children: [Item],
+    resolveChildren: sending (String) async throws -> [Item]
+  ) async throws -> [Item]? {
+    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 }
+      candidates = drilled.isEmpty ? children : drilled
+    } else {
+      candidates = children
+    }
+
+    let playable = candidates.filter { $0.src != nil }
+    return playable.isEmpty ? nil : playable
+  }
+}
+
+// The real Nitro `Track` already carries `src`/`url`; conform it for the app
+// build. (The testable target builds without NitroModules and uses a stub item.)
+#if canImport(NitroModules)
+  extension Track: PlayableSearchItem {}
+#endif

package/ios/Browser/SectionScope.swift

@@ -0,0 +1,35 @@
+// 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.
+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 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)
+      }
+    }
+    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
+    }
+    return .run(Array(children[start ... end]))
+  }
+}

package/ios/Browser/TabBarEntries.swift

@@ -0,0 +1,15 @@
+/// Compares the tab-list fields the CarPlay tab bar actually renders.
+enum TabBarEntries {
+  /// Whether two tab lists produce identical tab-bar entries — title, url,
+  /// 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
+  /// tab bar or resets its selection.
+  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.artworkSource?.uri == $1.artworkSource?.uri
+    }
+  }
+}