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

package/ios/Browser/BrowserPathHelper.swift

@@ -0,0 +1,190 @@
+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
+/// 2. Contextual URLs: Embed parent context in track identifiers for playback integration
+///
+/// Contextual URL format: `{parentPath}?__trackId={trackSrc}`
+/// Example: "/library/radio?__trackId=song.mp3"
+///
+/// This allows:
+/// - Playable-only tracks (tracks with `src` but no `url`) 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"
+
+  /// Offline error placeholder media ID
+  static let offlinePath = "/__offline"
+
+  /// Character set for percent-encoding query parameter keys and values.
+  /// Starts from `.urlQueryAllowed` but removes characters that have special
+  /// meaning in query strings (`&`, `=`, `+`) to prevent value corruption.
+  private static let queryComponentAllowed: CharacterSet = {
+    var cs = CharacterSet.urlQueryAllowed
+    cs.remove(charactersIn: "&=+")
+    return cs
+  }()
+
+  /// Query parameter name for contextual track identifiers
+  private static let contextualTrackParam = "__trackId"
+
+  /// 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)?")
+  }
+
+  /// Create a search path for a given query
+  static func createSearchPath(_ query: String) -> String {
+    let encodedQuery =
+      query.addingPercentEncoding(withAllowedCharacters: .urlQueryAllowed) ?? query
+    return "\(searchPathPrefix)?q=\(encodedQuery)"
+  }
+
+  /// Checks if a path contains a contextual track identifier.
+  ///
+  /// - Parameter path: The URL path to check
+  /// - Returns: true if the path contains the contextual track parameter
+  static func isContextual(_ path: String) -> Bool {
+    path.contains("?\(contextualTrackParam)=")
+      || 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.
+  ///
+  /// - Parameter url: The URL to process
+  /// - Returns: The URL without the __trackId parameter
+  ///
+  /// Example: "/library/radio?__trackId=song.mp3" → "/library/radio"
+  /// Example: "/search?q=jazz&__trackId=song.mp3" → "/search?q=jazz"
+  static func stripTrackId(_ url: String) -> String {
+    guard isContextual(url) else {
+      return url
+    }
+
+    guard var components = URLComponents(string: url) else {
+      return url
+    }
+
+    // Filter out __trackId parameter
+    components.queryItems = components.queryItems?.filter { $0.name != contextualTrackParam }
+
+    // If no query items left, clear the query string entirely
+    if components.queryItems?.isEmpty == true {
+      components.queryItems = nil
+    }
+
+    return components.string ?? url
+  }
+
+  /// Builds a contextual URL by appending a track identifier 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
+  ///
+  /// Example: build("/library", "song.mp3") → "/library?__trackId=song.mp3"
+  /// Example: build("/search?q=jazz", "song.mp3") → "/search?q=jazz&__trackId=song.mp3"
+  static func build(parentPath: String, trackId: String) -> String {
+    let encodedTrackId =
+      trackId.addingPercentEncoding(withAllowedCharacters: .urlQueryAllowed) ?? trackId
+    let separator = parentPath.contains("?") ? "&" : "?"
+    return "\(parentPath)\(separator)\(contextualTrackParam)=\(encodedTrackId)"
+  }
+
+  /// Extracts the track ID from a contextual URL.
+  /// Returns nil if the URL is not contextual or doesn't contain the track ID parameter.
+  ///
+  /// - Parameter path: The contextual URL to parse
+  /// - Returns: The extracted track ID, or nil if not found
+  ///
+  /// Example: "/library/radio?__trackId=song.mp3" → "song.mp3"
+  static func extractTrackId(_ path: String) -> String? {
+    guard isContextual(path) else {
+      return nil
+    }
+
+    guard let components = URLComponents(string: path) else {
+      return nil
+    }
+
+    return components.queryItems?.first { $0.name == contextualTrackParam }?.value
+  }
+
+  /// Appends query parameters to a URL, handling `?` vs `&` separator and percent-encoding.
+  ///
+  /// - Parameters:
+  ///   - query: Dictionary of query parameter key-value pairs
+  ///   - url: The URL to append parameters to
+  /// - Returns: The URL with query parameters appended
+  ///
+  /// Examples:
+  /// - appendQuery(["q": "jazz"], to: "/search") → "/search?q=jazz"
+  /// - appendQuery(["page": "2"], to: "/items?sort=new") → "/items?sort=new&page=2"
+  static func appendQuery(_ query: [String: String], to url: String) -> String {
+    guard !query.isEmpty else { return url }
+
+    let queryString = query.keys.sorted()
+      .map { key in
+        let value = query[key]!
+        let encodedKey = key.addingPercentEncoding(withAllowedCharacters: queryComponentAllowed) ?? key
+        let encodedValue = value.addingPercentEncoding(withAllowedCharacters: queryComponentAllowed) ?? value
+        return "\(encodedKey)=\(encodedValue)"
+      }
+      .joined(separator: "&")
+    let separator = url.contains("?") ? "&" : "?"
+    return "\(url)\(separator)\(queryString)"
+  }
+
+  /// Combines a base URL with a path, ensuring proper slash handling.
+  ///
+  /// - Parameters:
+  ///   - baseUrl: The base URL (can be nil)
+  ///   - path: The path to append
+  /// - Returns: The combined URL with proper slash handling
+  ///
+  /// Examples:
+  /// - buildUrl("http://example.com", "api/test") → "http://example.com/api/test"
+  /// - buildUrl("http://example.com/", "/api/test") → "http://example.com/api/test"
+  /// - buildUrl(nil, "/api/test") → "/api/test"
+  /// - buildUrl(nil, "http://full.url") → "http://full.url"
+  static func buildUrl(baseUrl: String?, path: String) -> String {
+    // If path is already a full URL, return it as-is
+    if path.hasPrefix("http://") || path.hasPrefix("https://") {
+      return path
+    }
+
+    // If no baseUrl, return path as-is
+    guard let baseUrl else {
+      return path
+    }
+
+    // Ensure baseUrl ends with / and path doesn't start with /
+    var normalizedBase = baseUrl
+    while normalizedBase.hasSuffix("/") {
+      normalizedBase.removeLast()
+    }
+    normalizedBase += "/"
+
+    var normalizedPath = path
+    while normalizedPath.hasPrefix("/") {
+      normalizedPath.removeFirst()
+    }
+
+    return "\(normalizedBase)\(normalizedPath)"
+  }
+}

package/ios/Browser/JsonModels.swift

@@ -0,0 +1,202 @@
+import Foundation
+import NitroModules
+
+/// JSON serializable models for parsing API responses.
+/// These will be converted to Nitro types after parsing.
+
+/// JSON model for image row items (horizontal thumbnail row).
+struct JsonImageRowItem: Codable {
+  let url: String?
+  let artwork: String?
+  let title: String
+
+  init(
+    url: String? = nil,
+    artwork: String? = nil,
+    title: String,
+  ) {
+    self.url = url
+    self.artwork = artwork
+    self.title = title
+  }
+}
+
+/// JSON model for resolved track (container with children).
+struct JsonResolvedTrack: Codable {
+  let url: String
+  let title: String
+  let subtitle: String?
+  let artwork: String?
+  let artist: String?
+  let album: String?
+  let description: String?
+  let genre: String?
+  let duration: Double?
+  let children: [JsonTrack]?
+  let src: String?
+  let style: String?
+  let childrenStyle: String?
+  let groupTitle: String?
+  let live: Bool?
+  let carPlaySiriListButton: String?
+
+  init(
+    url: String,
+    title: String,
+    subtitle: String? = nil,
+    artwork: String? = nil,
+    artist: String? = nil,
+    album: String? = nil,
+    description: String? = nil,
+    genre: String? = nil,
+    duration: Double? = nil,
+    children: [JsonTrack]? = nil,
+    src: String? = nil,
+    style: String? = nil,
+    childrenStyle: String? = nil,
+    groupTitle: String? = nil,
+    live: Bool? = nil,
+    carPlaySiriListButton: String? = nil,
+  ) {
+    self.url = url
+    self.title = title
+    self.subtitle = subtitle
+    self.artwork = artwork
+    self.artist = artist
+    self.album = album
+    self.description = description
+    self.genre = genre
+    self.duration = duration
+    self.children = children
+    self.src = src
+    self.style = style
+    self.childrenStyle = childrenStyle
+    self.groupTitle = groupTitle
+    self.live = live
+    self.carPlaySiriListButton = carPlaySiriListButton
+  }
+}
+
+/// JSON model for individual tracks.
+struct JsonTrack: Codable {
+  let url: String?
+  let title: String
+  let subtitle: String?
+  let artwork: String?
+  let artist: String?
+  let album: String?
+  let description: String?
+  let genre: String?
+  let duration: Double?
+  let src: String?
+  let style: String?
+  let childrenStyle: String?
+  let groupTitle: String?
+  let live: Bool?
+  let imageRow: [JsonImageRowItem]?
+
+  init(
+    url: String? = nil,
+    title: String,
+    subtitle: String? = nil,
+    artwork: String? = nil,
+    artist: String? = nil,
+    album: String? = nil,
+    description: String? = nil,
+    genre: String? = nil,
+    duration: Double? = nil,
+    src: String? = nil,
+    style: String? = nil,
+    childrenStyle: String? = nil,
+    groupTitle: String? = nil,
+    live: Bool? = nil,
+    imageRow: [JsonImageRowItem]? = nil,
+  ) {
+    self.url = url
+    self.title = title
+    self.subtitle = subtitle
+    self.artwork = artwork
+    self.artist = artist
+    self.album = album
+    self.description = description
+    self.genre = genre
+    self.duration = duration
+    self.src = src
+    self.style = style
+    self.childrenStyle = childrenStyle
+    self.groupTitle = groupTitle
+    self.live = live
+    self.imageRow = imageRow
+  }
+}
+
+// MARK: - Convert JSON models to Nitro types
+
+private extension String {
+  func toTrackStyle() -> TrackStyle? {
+    TrackStyle(fromString: lowercased())
+  }
+}
+
+extension JsonImageRowItem {
+  func toNitro() -> ImageRowItem {
+    ImageRowItem(
+      url: url,
+      artwork: artwork,
+      artworkSource: nil,
+      title: title,
+    )
+  }
+}
+
+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 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() },
+    )
+  }
+}

package/ios/Browser/SimpleRouter.swift

@@ -0,0 +1,184 @@
+import Foundation
+
+/// Result of a successful route match.
+struct RouteMatch {
+  /// Extracted parameters from the path (e.g., {id} → "123")
+  /// For tail wildcards, the remaining path is stored in params["tail"]
+  let params: [String: String]
+
+  /// Specificity score (higher = more specific match)
+  let specificity: Int
+
+  init(params: [String: String] = [:], specificity: Int = 0) {
+    self.params = params
+    self.specificity = specificity
+  }
+}
+
+/// Protocol for route entries that can be matched.
+protocol RouteEntry {
+  var path: String { get }
+}
+
+/// Simple route matcher for path patterns with parameter extraction.
+///
+/// Supports patterns like:
+/// - /artists - exact match
+/// - /artists/{id} - parameter extraction
+/// - /artists/{id}/albums - multiple segments with parameters
+/// - /artists/* - wildcard match (matches any single segment)
+/// - /files/** - tail wildcard (matches remaining path segments)
+///
+/// Route specificity rules:
+/// - More path segments = higher specificity
+/// - Constant segments > parameter segments > wildcards > tail wildcards
+/// - Most specific route wins
+final class SimpleRouter {
+  /// Finds the best matching route for the given path.
+  ///
+  /// - Parameters:
+  ///   - path: The incoming path to match (e.g., "/artists/123")
+  ///   - routes: Array of route entries to match against
+  /// - Returns: Tuple of (route, match result) or nil if no match
+  func findBestMatch<T: RouteEntry>(path: String, routes: [T]) -> (route: T, match: RouteMatch)? {
+    var bestMatch: (route: T, match: RouteMatch)?
+
+    for route in routes {
+      if let match = matchPattern(pattern: route.path, path: path) {
+        if bestMatch == nil || match.specificity > bestMatch!.match.specificity {
+          bestMatch = (route, match)
+        }
+      }
+    }
+
+    return bestMatch
+  }
+
+  /// Attempts to match a single pattern against a path.
+  ///
+  /// - Parameters:
+  ///   - pattern: Route pattern (e.g., "/artists/{id}", "/files/*", "/api/**")
+  ///   - path: Incoming path (e.g., "/artists/123")
+  /// - Returns: RouteMatch if successful, nil otherwise
+  private func matchPattern(pattern: String, path: String) -> RouteMatch? {
+    let patternSegments = pattern.split(separator: "/").map(String.init)
+    let pathSegments = path.split(separator: "/").map(String.init)
+
+    var params: [String: String] = [:]
+    var constantSegments = 0
+    var parameterSegments = 0
+    var wildcardSegments = 0
+    var hasTailWildcard = false
+
+    // Check for tail wildcard at end
+    if let lastSegment = patternSegments.last, lastSegment == "**" {
+      hasTailWildcard = true
+
+      // For tail wildcard, pattern must have <= path segments
+      if patternSegments.count - 1 > pathSegments.count {
+        return nil
+      }
+
+      // Match all segments except the tail wildcard
+      for i in 0 ..< (patternSegments.count - 1) {
+        guard
+          matchSingleSegment(
+            patternSegment: patternSegments[i],
+            pathSegment: pathSegments[i],
+            params: &params,
+          )
+        else {
+          return nil
+        }
+
+        updateSegmentCounts(
+          patternSegment: patternSegments[i],
+          constantSegments: &constantSegments,
+          parameterSegments: &parameterSegments,
+          wildcardSegments: &wildcardSegments,
+        )
+      }
+
+      // Capture remaining path segments as "tail" parameter (matches Kotlin behavior)
+      if pathSegments.count > patternSegments.count - 1 {
+        let remainingSegments = pathSegments.dropFirst(patternSegments.count - 1)
+        params["tail"] = remainingSegments.joined(separator: "/")
+      }
+    } else {
+      // Normal matching - must have same number of segments
+      if patternSegments.count != pathSegments.count {
+        return nil
+      }
+
+      for i in patternSegments.indices {
+        guard
+          matchSingleSegment(
+            patternSegment: patternSegments[i],
+            pathSegment: pathSegments[i],
+            params: &params,
+          )
+        else {
+          return nil
+        }
+
+        updateSegmentCounts(
+          patternSegment: patternSegments[i],
+          constantSegments: &constantSegments,
+          parameterSegments: &parameterSegments,
+          wildcardSegments: &wildcardSegments,
+        )
+      }
+    }
+
+    // Specificity calculation (higher = more specific):
+    // - Constants: 1000 points each
+    // - Parameters: 100 points each
+    // - Single wildcards: 10 points each
+    // - Tail wildcard: 1 point
+    // - Base path length: segments count
+    let specificity =
+      (constantSegments * 1000)
+        + (parameterSegments * 100)
+        + (wildcardSegments * 10)
+        + (hasTailWildcard ? 1 : 0)
+        + patternSegments.count
+
+    return RouteMatch(params: params, specificity: specificity)
+  }
+
+  private func matchSingleSegment(
+    patternSegment: String,
+    pathSegment: String,
+    params: inout [String: String],
+  ) -> Bool {
+    // Parameter segment: {paramName}
+    if patternSegment.hasPrefix("{"), patternSegment.hasSuffix("}") {
+      let paramName = String(patternSegment.dropFirst().dropLast())
+      params[paramName] = pathSegment
+      return true
+    }
+
+    // Single wildcard: *
+    if patternSegment == "*" {
+      return true
+    }
+
+    // Constant segment: must match exactly
+    return patternSegment == pathSegment
+  }
+
+  private func updateSegmentCounts(
+    patternSegment: String,
+    constantSegments: inout Int,
+    parameterSegments: inout Int,
+    wildcardSegments: inout Int,
+  ) {
+    if patternSegment.hasPrefix("{"), patternSegment.hasSuffix("}") {
+      parameterSegments += 1
+    } else if patternSegment == "*" {
+      wildcardSegments += 1
+    } else {
+      constantSegments += 1
+    }
+  }
+}

package/ios/CarPlay/CarPlayArtworkResolver.swift

@@ -0,0 +1,107 @@
+import Foundation
+
+/// Represents a resolved artwork image URL with optional headers.
+struct ArtworkResolvedImage: Equatable, Sendable {
+  let uri: String
+  let headers: [String: String]?
+}
+
+/// Describes what action to take for loading artwork.
+/// Produced by `CarPlayArtworkResolver`, consumed by `CarPlayImageLoader`.
+enum ArtworkLoadAction: Equatable, Sendable {
+  /// Render an SF Symbol from the artwork string at the given canvas size
+  case sfSymbol(artwork: String, width: Double, height: Double)
+  /// Fetch an image from a URL, optionally with headers, tinting, and SVG processing
+  case fetch(uri: String, headers: [String: String]?, shouldTint: Bool, isSvg: Bool)
+  /// No artwork available
+  case none
+}
+
+/// Determines artwork loading strategy without UIKit dependencies.
+///
+/// Encapsulates the decision tree for how to load artwork:
+/// 1. SF Symbol artwork → render directly
+/// 2. URL resolver available → resolve, then fetch from resolved URL
+/// 3. Fallback → fetch directly from artwork/artworkSource URL
+enum CarPlayArtworkResolver {
+  /// Resolves the artwork loading strategy for a track.
+  ///
+  /// - 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
+  ///   - targetWidth: Target width in points
+  ///   - targetHeight: Target height in points
+  ///   - displayScale: The CarPlay display scale factor
+  ///   - urlResolver: Optional closure that resolves artwork URLs (wraps BrowserManager)
+  static func resolve(
+    artwork: String?,
+    artworkSourceUri: String?,
+    artworkCarPlayTinted: Bool?,
+    targetWidth: Double,
+    targetHeight: Double,
+    displayScale: Double,
+    urlResolver: ((Double, Double) async -> ArtworkResolvedImage?)?
+  ) async -> ArtworkLoadAction {
+    // 1. Primary SF symbol check
+    if let artwork, artwork.hasPrefix("sf:") {
+      return .sfSymbol(artwork: artwork, width: targetWidth, height: targetHeight)
+    }
+
+    // 2. Try URL resolution via resolver
+    if let urlResolver {
+      let pixelWidth = targetWidth * displayScale
+      let pixelHeight = targetHeight * displayScale
+      if let resolved = await urlResolver(pixelWidth, pixelHeight) {
+        guard let resolvedUrl = URL(string: resolved.uri) else {
+          return resolveDirectFallback(
+            artwork: artwork,
+            artworkSourceUri: artworkSourceUri,
+            artworkCarPlayTinted: artworkCarPlayTinted,
+            targetWidth: targetWidth,
+            targetHeight: targetHeight
+          )
+        }
+        let isSvg = resolvedUrl.pathExtension.lowercased() == "svg"
+        return .fetch(
+          uri: resolved.uri,
+          headers: resolved.headers,
+          shouldTint: artworkCarPlayTinted ?? false,
+          isSvg: isSvg
+        )
+      }
+    }
+
+    // 3. Direct fallback
+    return resolveDirectFallback(
+      artwork: artwork,
+      artworkSourceUri: artworkSourceUri,
+      artworkCarPlayTinted: artworkCarPlayTinted,
+      targetWidth: targetWidth,
+      targetHeight: targetHeight
+    )
+  }
+
+  private static func resolveDirectFallback(
+    artwork: String?,
+    artworkSourceUri: String?,
+    artworkCarPlayTinted: Bool?,
+    targetWidth: Double,
+    targetHeight: Double
+  ) -> ArtworkLoadAction {
+    guard let directUri = artwork ?? artworkSourceUri else { return .none }
+
+    if directUri.hasPrefix("sf:") {
+      return .sfSymbol(artwork: directUri, width: targetWidth, height: targetHeight)
+    }
+
+    guard let directUrl = URL(string: directUri) else { return .none }
+    let isSvg = directUrl.pathExtension.lowercased() == "svg"
+    return .fetch(
+      uri: directUri,
+      headers: nil,
+      shouldTint: artworkCarPlayTinted ?? false,
+      isSvg: isSvg
+    )
+  }
+}