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

package/ios/Browser/BrowserPathHelper.swift

@@ -3,23 +3,24 @@ import Foundation
 /// Utility for handling browser paths and contextual URLs in the media browser system.
 ///
 /// Handles two types of special paths:
-/// 1. System paths (prefixed with `/__`): Root, recent, and search paths
+/// 1. System paths (prefixed with `/__`): root, search, and offline paths
 /// 2. Contextual URLs: Embed parent context in track identifiers for playback integration
 ///
-/// Contextual URL format: `{parentPath}?__trackId={trackSrc}`
-/// Example: "/library/radio?__trackId=song.mp3"
+/// Contextual URL format: `{parentPath}?__trackId={trackIdentity}&__index={childIndex}`
+/// Example: "/library/radio?__trackId=song.mp3&__index=2"
+///
+/// `__trackId` is the identity check; `__index` (the child's position on the
+/// page at stamp time) is only a tie-breaker between surfaces that carry the
+/// same identity — a stale index never selects a different track.
 ///
 /// This allows:
-/// - Playable-only tracks (tracks with `src` but no `url`) to be referenced
+/// - Playable-only tracks (tracks with `src` but no `path`) to be referenced
 /// - Cache lookup to work consistently
 /// - Parent context to be preserved for queue restoration
 enum BrowserPathHelper {
   /// Root path for media browsing
   static let rootPath = "/__root"
 
-  /// Recent media path for playback resumption
-  static let recentPath = "/__recent"
-
   /// Search path prefix (full path is /__search?q=query)
   static let searchPathPrefix = "/__search"
 
@@ -38,10 +39,12 @@ enum BrowserPathHelper {
   /// Query parameter name for contextual track identifiers
   private static let contextualTrackParam = "__trackId"
 
+  /// Query parameter name for the tapped child's page position (tie-breaker)
+  private static let contextualIndexParam = "__index"
+
   /// Check if a path is a special system path (not a regular navigation path)
   static func isSpecialPath(_ path: String) -> Bool {
     path == rootPath ||
-      path == recentPath ||
       path.hasPrefix("\(searchPathPrefix)?")
   }
 
@@ -61,13 +64,13 @@ enum BrowserPathHelper {
       || path.contains("&\(contextualTrackParam)=")
   }
 
-  /// Strips the __trackId parameter from a contextual URL to get the parent path.
-  /// If the URL is not contextual, returns it unchanged.
+  /// Strips the contextual parameters (__trackId and __index) from a contextual
+  /// URL to get the parent path. If the URL is not contextual, returns it unchanged.
   ///
   /// - Parameter url: The URL to process
-  /// - Returns: The URL without the __trackId parameter
+  /// - Returns: The URL without the contextual parameters
   ///
-  /// Example: "/library/radio?__trackId=song.mp3" → "/library/radio"
+  /// Example: "/library/radio?__trackId=song.mp3&__index=2" → "/library/radio"
   /// Example: "/search?q=jazz&__trackId=song.mp3" → "/search?q=jazz"
   static func stripTrackId(_ url: String) -> String {
     guard isContextual(url) else {
@@ -78,8 +81,10 @@ enum BrowserPathHelper {
       return url
     }
 
-    // Filter out __trackId parameter
-    components.queryItems = components.queryItems?.filter { $0.name != contextualTrackParam }
+    // Filter out the contextual parameters
+    components.queryItems = components.queryItems?.filter {
+      $0.name != contextualTrackParam && $0.name != contextualIndexParam
+    }
 
     // If no query items left, clear the query string entirely
     if components.queryItems?.isEmpty == true {
@@ -89,21 +94,24 @@ enum BrowserPathHelper {
     return components.string ?? url
   }
 
-  /// Builds a contextual URL by appending a track identifier to a parent path.
+  /// Builds a contextual URL by appending a track identifier — and optionally
+  /// the tapped child's page position — to a parent path.
   /// Handles existing query parameters correctly.
   ///
   /// - Parameters:
   ///   - parentPath: The parent container path
-  ///   - trackId: The track identifier (typically the `src` value)
-  /// - Returns: A contextual URL combining parent path and track ID
+  ///   - trackId: The track identity (`id` when non-blank, else `src`)
+  ///   - index: The child's position on the page at stamp time (tie-breaker)
+  /// - Returns: A contextual URL combining parent path, track ID, and index
   ///
-  /// Example: build("/library", "song.mp3") → "/library?__trackId=song.mp3"
+  /// Example: build("/library", "song.mp3", index: 2) → "/library?__trackId=song.mp3&__index=2"
   /// Example: build("/search?q=jazz", "song.mp3") → "/search?q=jazz&__trackId=song.mp3"
-  static func build(parentPath: String, trackId: String) -> String {
+  static func build(parentPath: String, trackId: String, index: Int? = nil) -> String {
     let encodedTrackId =
-      trackId.addingPercentEncoding(withAllowedCharacters: .urlQueryAllowed) ?? trackId
+      trackId.addingPercentEncoding(withAllowedCharacters: queryComponentAllowed) ?? trackId
     let separator = parentPath.contains("?") ? "&" : "?"
-    return "\(parentPath)\(separator)\(contextualTrackParam)=\(encodedTrackId)"
+    let indexParam = index.map { "&\(contextualIndexParam)=\($0)" } ?? ""
+    return "\(parentPath)\(separator)\(contextualTrackParam)=\(encodedTrackId)\(indexParam)"
   }
 
   /// Extracts the track ID from a contextual URL.
@@ -125,6 +133,21 @@ enum BrowserPathHelper {
     return components.queryItems?.first { $0.name == contextualTrackParam }?.value
   }
 
+  /// Extracts the stamped page index from a contextual URL, or nil when the
+  /// URL is not contextual or carries no (valid, non-negative) index.
+  ///
+  /// Example: "/library/radio?__trackId=song.mp3&__index=2" → 2
+  static func extractIndex(_ path: String) -> Int? {
+    guard isContextual(path),
+          let components = URLComponents(string: path),
+          let raw = components.queryItems?.first(where: { $0.name == contextualIndexParam })?.value,
+          let index = Int(raw), index >= 0
+    else {
+      return nil
+    }
+    return index
+  }
+
   /// Appends query parameters to a URL, handling `?` vs `&` separator and percent-encoding.
   ///
   /// - Parameters:
@@ -193,27 +216,4 @@ enum BrowserPathHelper {
 
     return "\(normalizedBase)/\(normalizedPath)"
   }
-
-  /// True if `segment` appears in `path` as a complete path segment — bounded on
-  /// the left by the string start or `/`, and on the right by the string end or
-  /// one of `/`, `?`, `#`.
-  static func containsSegment(_ path: String, _ segment: String) -> Bool {
-    guard !segment.isEmpty else { return false }
-    var searchStart = path.startIndex
-    while let range = path.range(of: segment, range: searchStart ..< path.endIndex) {
-      let beforeOk =
-        range.lowerBound == path.startIndex
-          || path[path.index(before: range.lowerBound)] == "/"
-      let afterOk: Bool
-      if range.upperBound == path.endIndex {
-        afterOk = true
-      } else {
-        let next = path[range.upperBound]
-        afterOk = next == "/" || next == "?" || next == "#"
-      }
-      if beforeOk, afterOk { return true }
-      searchStart = range.upperBound
-    }
-    return false
-  }
 }

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