react-native-audio-browser 0.2.0-next.3 → 0.2.0-next.30

package/ios/Extension/UIApplication+ActiveScene.swift

@@ -0,0 +1,27 @@
+import UIKit
+
+extension UIApplication {
+  /// The scene showing the app's own UI: the foreground-active one, else any
+  /// connected window scene. Nil when the app has no UI scene at all (running
+  /// headless for CarPlay), which callers must handle rather than assume.
+  ///
+  /// Replaces the deprecated `UIScreen.main` / `keyWindow` idioms — and exists
+  /// once because the walk was previously written out at each use, so the two
+  /// copies had already drifted apart.
+  var activeWindowScene: UIWindowScene? {
+    let scenes = connectedScenes.compactMap { $0 as? UIWindowScene }
+    return scenes.first { $0.activationState == .foregroundActive } ?? scenes.first
+  }
+}
+
+/// The scale to rasterise at for the app's own screen.
+///
+/// `UITraitCollection.current` rather than the deprecated `UIScreen.main.scale`
+/// (also unavailable on visionOS, which the podspec targets): on the main actor
+/// it already reflects the environment being rendered for. CarPlay surfaces do
+/// NOT use this — they rasterise at `carTraitCollection.displayScale`, the car
+/// screen's own scale.
+@MainActor
+var appDisplayScale: CGFloat {
+  UITraitCollection.current.displayScale
+}

package/ios/Extension/UIImage+Adaptive.swift

@@ -0,0 +1,12 @@
+import UIKit
+
+extension UIImage {
+  /// One image that shows `light` or `dark` by the appearance of the trait collection it is
+  /// displayed in, starting from `traits`; an appearance change re-resolves it in place.
+  static func adaptive(light: UIImage, dark: UIImage, for traits: UITraitCollection) -> UIImage {
+    let asset = UIImageAsset()
+    asset.register(light, with: UITraitCollection(userInterfaceStyle: .light))
+    asset.register(dark, with: UITraitCollection(userInterfaceStyle: .dark))
+    return asset.image(with: traits)
+  }
+}

package/ios/Extension/URLError+Connectivity.swift

@@ -0,0 +1,15 @@
+import Foundation
+
+extension URLError {
+  /// The request failed for want of a connection to the host, so it is worth repeating once one
+  /// is back.
+  var isConnectivity: Bool {
+    switch code {
+    case .timedOut, .networkConnectionLost, .notConnectedToInternet, .cannotConnectToHost, .cannotFindHost,
+         .dnsLookupFailed:
+      true
+    default:
+      false
+    }
+  }
+}

package/ios/Http/HttpClient.swift

@@ -36,174 +36,107 @@ final class HttpClient: @unchecked Sendable {
     }
   }
 
-  /// HTTP response data (matches Kotlin HttpClient.HttpResponse).
-  struct HttpResponse {
-    let code: Int
-    let body: String
-    let headers: [String: String]
-
-    var isSuccessful: Bool {
-      (200 ..< 300).contains(code)
-    }
-  }
-
-  /// HTTP exception (matches Kotlin HttpClient.HttpException).
-  final class HttpException: Error, Sendable {
+  /// A non-2xx response (matches Kotlin HttpClient.HttpException).
+  struct HttpException: LocalizedError {
     let code: Int
     let responseBody: String
 
-    init(code: Int, responseBody: String) {
-      self.code = code
-      self.responseBody = responseBody
-    }
-
-    var localizedDescription: String {
-      // Try to extract error message from JSON response: { "error": "message" }
+    /// The API's `{ "error": "message" }`, else the localized HTTP status.
+    var errorDescription: String? {
       if let data = responseBody.data(using: .utf8),
          let json = try? JSONSerialization.jsonObject(with: data) as? [String: Any],
-         let errorMessage = json["error"] as? String
+         let message = json["error"] as? String
       {
-        return errorMessage
+        return message
       }
-      // Fall back to localized HTTP status description
       return HTTPURLResponse.localizedString(forStatusCode: code)
     }
   }
 
-  /// Creates a new HTTP client.
+  enum HttpClientError: LocalizedError {
+    case invalidUrl(String)
+    case unsupportedMethod(String)
+    case notHttp
+    case undecodable(String)
+
+    var errorDescription: String? {
+      switch self {
+      case let .invalidUrl(url): "Invalid URL: \(url)"
+      case let .unsupportedMethod(method): "Unsupported HTTP method: \(method)"
+      case .notHttp: "Invalid response type"
+      case let .undecodable(reason): reason
+      }
+    }
+  }
+
   init(session: URLSession = .shared) {
     self.session = session
   }
 
-  /// Executes an HTTP request (matches Kotlin request() signature).
-  func request(_ httpRequest: HttpRequest) async -> Result<HttpResponse, Error> {
-    guard let url = URL(string: httpRequest.url) else {
-      return .failure(NSError(
-        domain: "HttpClient",
-        code: -1,
-        userInfo: [NSLocalizedDescriptionKey: "Invalid URL: \(httpRequest.url)"],
-      ))
-    }
+  /// Sends `httpRequest` and returns the status code and body, whatever the status.
+  func request(_ httpRequest: HttpRequest) async throws -> (code: Int, data: Data) {
+    guard let url = URL(string: httpRequest.url) else { throw HttpClientError.invalidUrl(httpRequest.url) }
 
     var urlRequest = URLRequest(url: url)
     urlRequest.timeoutInterval = Self.timeoutSeconds
-
-    // Add headers
     httpRequest.headers?.forEach { name, value in
       urlRequest.setValue(value, forHTTPHeaderField: name)
     }
-    // Set User-Agent (userAgent parameter takes precedence over headers)
-    urlRequest.setValue(httpRequest.userAgent, forHTTPHeaderField: "User-Agent")
+    // A `User-Agent` header wins over `userAgent`, as in the media and artwork paths.
+    if httpRequest.headers?["User-Agent"] == nil {
+      urlRequest.setValue(httpRequest.userAgent, forHTTPHeaderField: "User-Agent")
+    }
 
-    // Add body for non-GET requests
-    switch httpRequest.method.uppercased() {
+    let method = httpRequest.method.uppercased()
+    switch method {
     case "GET":
-      urlRequest.httpMethod = "GET"
+      urlRequest.httpMethod = method
     case "POST", "PUT", "PATCH":
-      urlRequest.httpMethod = httpRequest.method.uppercased()
+      urlRequest.httpMethod = method
       urlRequest.setValue(httpRequest.contentType, forHTTPHeaderField: "Content-Type")
-      if let body = httpRequest.body {
-        urlRequest.httpBody = body.data(using: .utf8)
-      }
+      urlRequest.httpBody = httpRequest.body?.data(using: .utf8)
     case "DELETE":
-      urlRequest.httpMethod = "DELETE"
+      urlRequest.httpMethod = method
       if let body = httpRequest.body {
         urlRequest.setValue(httpRequest.contentType, forHTTPHeaderField: "Content-Type")
         urlRequest.httpBody = body.data(using: .utf8)
       }
     default:
-      return .failure(NSError(
-        domain: "HttpClient",
-        code: -1,
-        userInfo: [NSLocalizedDescriptionKey: "Unsupported HTTP method: \(httpRequest.method)"],
-      ))
+      throw HttpClientError.unsupportedMethod(httpRequest.method)
     }
 
-    // Log request
     logRequest(httpRequest)
-
     do {
       let (data, response) = try await session.data(for: urlRequest)
-
-      guard let httpResponse = response as? HTTPURLResponse else {
-        return .failure(NSError(
-          domain: "HttpClient",
-          code: -1,
-          userInfo: [NSLocalizedDescriptionKey: "Invalid response type"],
-        ))
-      }
-
-      let responseBody = String(data: data, encoding: .utf8) ?? ""
-
-      // Extract response headers
-      var headers: [String: String] = [:]
-      for (key, value) in httpResponse.allHeaderFields {
-        if let keyString = key as? String, let valueString = value as? String {
-          headers[keyString] = valueString
-        }
-      }
-
-      let httpResp = HttpResponse(
-        code: httpResponse.statusCode,
-        body: responseBody,
-        headers: headers,
-      )
-
-      // Log response
-      logResponse(httpResp, url: httpRequest.url)
-
-      return .success(httpResp)
+      guard let response = response as? HTTPURLResponse else { throw HttpClientError.notHttp }
+      logResponse(code: response.statusCode, data: data, url: httpRequest.url)
+      return (response.statusCode, data)
     } catch {
-      logError(error, url: httpRequest.url)
-      return .failure(error)
+      logger.error("✗ Error for \(httpRequest.url): \(error.localizedDescription)")
+      throw error
     }
   }
 
-  /// Executes an HTTP request and decodes the JSON response (matches Kotlin requestJson()).
-  func requestJson<T: Decodable>(
-    _ httpRequest: HttpRequest,
-    as type: T.Type,
-  ) async throws -> T {
-    let result = await request(httpRequest)
-
-    switch result {
-    case let .success(response):
-      if !response.isSuccessful {
-        throw HttpException(code: response.code, responseBody: response.body)
-      }
-      guard let data = response.body.data(using: .utf8) else {
-        throw NSError(
-          domain: "HttpClient",
-          code: -1,
-          userInfo: [NSLocalizedDescriptionKey: "Failed to convert response body to data"],
-        )
-      }
-      let decoder = JSONDecoder()
-      do {
-        return try decoder.decode(type, from: data)
-      } catch let DecodingError.keyNotFound(key, context) {
-        throw NSError(
-          domain: "HttpClient",
-          code: -1,
-          userInfo: [NSLocalizedDescriptionKey: "Missing required key '\(key.stringValue)' at path: \(context.codingPath.map(\.stringValue).joined(separator: "."))"],
-        )
-      } catch let DecodingError.typeMismatch(type, context) {
-        throw NSError(
-          domain: "HttpClient",
-          code: -1,
-          userInfo: [NSLocalizedDescriptionKey: "Type mismatch for \(type) at path: \(context.codingPath.map(\.stringValue).joined(separator: "."))"],
-        )
-      } catch let DecodingError.valueNotFound(type, context) {
-        throw NSError(
-          domain: "HttpClient",
-          code: -1,
-          userInfo: [NSLocalizedDescriptionKey: "Value not found for \(type) at path: \(context.codingPath.map(\.stringValue).joined(separator: "."))"],
-        )
-      }
-    case let .failure(error):
-      throw error
+  /// Sends `httpRequest` and decodes a 2xx body as `T`; any other status throws `HttpException`.
+  func requestJson<T: Decodable>(_ httpRequest: HttpRequest, as type: T.Type) async throws -> T {
+    let (code, data) = try await request(httpRequest)
+    guard (200 ..< 300).contains(code) else {
+      throw HttpException(code: code, responseBody: String(decoding: data, as: UTF8.self))
+    }
+    do {
+      return try JSONDecoder().decode(type, from: data)
+    } catch let DecodingError.keyNotFound(key, context) {
+      throw HttpClientError.undecodable("Missing required key '\(key.stringValue)' at path: \(Self.path(context))")
+    } catch let DecodingError.typeMismatch(type, context) {
+      throw HttpClientError.undecodable("Type mismatch for \(type) at path: \(Self.path(context))")
+    } catch let DecodingError.valueNotFound(type, context) {
+      throw HttpClientError.undecodable("Value not found for \(type) at path: \(Self.path(context))")
     }
   }
+
+  private static func path(_ context: DecodingError.Context) -> String {
+    context.codingPath.map(\.stringValue).joined(separator: ".")
+  }
 }
 
 // MARK: - Logging
@@ -211,27 +144,18 @@ final class HttpClient: @unchecked Sendable {
 extension HttpClient {
   private func logRequest(_ request: HttpRequest) {
     logger.debug("→ \(request.method) \(request.url)")
-    if let headers = request.headers, !headers.isEmpty {
-      for (key, value) in headers {
-        logger.debug("  \(key): \(value)")
-      }
+    for (key, value) in request.headers ?? [:] {
+      logger.debug("  \(key): \(value)")
     }
     if let body = request.body {
-      let truncated = body.prefix(500)
-      logger.debug("  Body: \(truncated)\(body.count > 500 ? "..." : "")")
+      logger.debug("  Body: \(body.prefix(500))\(body.count > 500 ? "..." : "")")
     }
   }
 
-  private func logResponse(_ response: HttpResponse, url: String) {
-    let emoji = response.isSuccessful ? "✓" : "✗"
-    logger.debug("← \(emoji) \(response.code) \(url)")
-    if !response.body.isEmpty {
-      let truncated = response.body.prefix(500)
-      logger.debug("  Body: \(truncated)\(response.body.count > 500 ? "..." : "")")
+  private func logResponse(code: Int, data: Data, url: String) {
+    logger.debug("← \((200 ..< 300).contains(code) ? "✓" : "✗") \(code) \(url)")
+    if !data.isEmpty {
+      logger.debug("  Body: \(String(decoding: data.prefix(500), as: UTF8.self))\(data.count > 500 ? "..." : "")")
     }
   }
-
-  private func logError(_ error: Error, url: String) {
-    logger.error("✗ Error for \(url): \(error.localizedDescription)")
-  }
 }

package/ios/HybridAudioBrowser+Browser.swift

@@ -0,0 +1,153 @@
+import AVFoundation
+import AVKit
+import Foundation
+import MediaPlayer
+import NitroModules
+import os.log
+
+public extension HybridAudioBrowser {
+  /// Navigates the in-app browser, reporting a failure as the navigation error. A clear is
+  /// synchronous: JS hears it before the navigation that may set the error again.
+  internal func navigate(_ path: String, clearError: Bool) {
+    if clearError { onMainActor { navigationError.clear() } }
+    Task { @MainActor in
+      do {
+        try await browserManager.load(path)
+      } catch {
+        await reportNavigationError(error, path: path)
+      }
+    }
+  }
+
+  @MainActor
+  private func reportNavigationError(_ error: Error, path: String) async {
+    await navigationError.report(NavigationError.from(error)) { [browserManager] in
+      await browserManager.formatted($0, path: path)
+    }
+  }
+
+  // MARK: - Browser Methods
+
+  func navigatePath(path: String) throws {
+    navigate(path, clearError: true)
+  }
+
+  func navigateTrack(track: Track) throws {
+    // @MainActor: `player` is main-confined, and `trackSelector.select` is
+    // MainActor anyway — a bare Task read the reference off the cooperative
+    // pool, racing the assignment in `setupPlayer`.
+    Task { @MainActor in
+      guard let player else { return }
+      let result = await trackSelector.select(track: track, player: player)
+      switch result {
+      case let .play(intent):
+        player.execute(intent)
+      case .intercepted:
+        break
+      case let .browse(path):
+        navigate(path, clearError: true)
+      case .none:
+        break
+      }
+    }
+  }
+
+  func search(query: String) throws -> Promise<[Track]> {
+    Promise.async { [weak self] in
+      guard let self else { return [] }
+      let resolved = try await browserManager.search(query)
+      return resolved.flattenedChildren ?? []
+    }
+  }
+
+  func getContent() throws -> ResolvedTrack? {
+    onMainActor { browserManager.content }
+  }
+
+  func getNavigationError() throws -> NavigationError? {
+    onMainActor { navigationError.error }
+  }
+
+  func getFormattedNavigationError() throws -> FormattedNavigationError? {
+    onMainActor { navigationError.formatted }
+  }
+
+  /// Internal signal sent on `externalContentChangedEmitter` to tell CarPlay to
+  /// refresh every displayed template. Not a real path (paths are always
+  /// `/…`), so it can't collide with one; kept internal — the public API is
+  /// `invalidateAllContent()`.
+  internal static let invalidateAllSentinel = "__rnab_invalidate_all__"
+
+  func notifyContentChanged(path: String) throws {
+    // Throws on a contextual path (matching Android's `require`) — the caller
+    // must pass the container path, or the invalidation silently hits nothing.
+    try onMainActor { try browserManager.invalidateContentCache(path) }
+
+    // Notify external controllers (CarPlay) that content changed
+    externalContentChangedEmitter.emit(path)
+
+    // Re-resolve the path if it's the current browser path
+    if onMainActor({ browserManager.path }) == path {
+      navigate(path, clearError: false)
+    }
+  }
+
+  func invalidateAllContent() throws {
+    onMainActor { browserManager.clearContentCache() }
+
+    // Tell external controllers (CarPlay) to refresh every displayed template.
+    externalContentChangedEmitter.emit(Self.invalidateAllSentinel)
+
+    // Re-query the tabs source too: a callback source can resolve to new
+    // titles after an invalidation (e.g. a locale switch). BrowserManager
+    // emits tabsChanged only when the result actually differs, and a failed
+    // re-query keeps the current tabs. (Android needs no equivalent — its
+    // root re-query already runs queryTabs(); the web stub re-queries tabs on
+    // the re-navigation.)
+    Task {
+      _ = try? await browserManager.queryTabs()
+    }
+
+    // Re-resolve the JS-facing current path with the cache cleared.
+    Task { @MainActor in
+      do {
+        try await browserManager.load(browserManager.path, bypassCache: true)
+      } catch {
+        await reportNavigationError(error, path: browserManager.path)
+      }
+    }
+  }
+
+  func setFavorites(favorites: [String]) throws {
+    onMainActor { browserManager.setFavorites(favorites) }
+  }
+
+  // MARK: - Gate
+
+  func setGate(gate: Gate?, hasResolver: Bool) throws {
+    onMainActor { browseGate.set(chrome: gate, hasResolver: hasResolver) }
+  }
+
+  func clearGate() throws {
+    onMainActor { browseGate.clear() }
+  }
+
+  // MARK: - Car Connection (CarPlay)
+
+  /// Static because the CarPlay scene can connect before the JS runtime
+  /// creates the shared instance (cold start in the car).
+  internal nonisolated(unsafe) static var carPlayConnected = false
+
+  /// Called by the CarPlay scene delegate (via `RNABCarPlayController`) on
+  /// scene connect/disconnect — not from controller start/stop, which also
+  /// cycle on a JS reload and would emit spurious connection changes.
+  internal static func setCarPlayConnected(_ connected: Bool) {
+    guard carPlayConnected != connected else { return }
+    carPlayConnected = connected
+    shared?.onCarConnectedChanged(connected)
+  }
+
+  func isCarConnected() throws -> Bool {
+    HybridAudioBrowser.carPlayConnected
+  }
+}

package/ios/HybridAudioBrowser+Options.swift

@@ -0,0 +1,144 @@
+import AVFoundation
+import AVKit
+import Foundation
+import MediaPlayer
+import NitroModules
+import os.log
+
+public extension HybridAudioBrowser {
+  // MARK: - Player Setup
+
+  func setupPlayer(options: NativeSetupPlayerOptions) throws -> Promise<Void> {
+    Promise.async {
+      // Create player and configure on main actor
+      await MainActor.run { [weak self] in
+        guard let self else { return }
+        // Set the category now, but activate only when playback produces output.
+        self.audioSession.configure(options.ios)
+
+        // A re-setup REPLACES the player, so the outgoing one has to be torn down
+        // and un-published first. No-op on first setup.
+        destroyPlayer()
+
+        let newEngine = AVPlayerEngine(callbacks: self, resolver: browserManager.requests)
+        if let buffer = options.ios?.buffer { newEngine.bufferDuration = buffer }
+        newEngine.nowPlayingUpdater.enabled = options.autoUpdateNowPlayingMetadata ?? true
+        newEngine.nowPlayingUpdater.formatter = options.nowPlayingMetadataFormatter
+        newEngine.nowPlayingUpdater.isOnline = networkMonitor.isOnline
+        let newPlayer = Player(engine: newEngine)
+        newPlayer.callbacks = self
+        newPlayer.retry.networkMonitor = networkMonitor
+        if let retry = options.retry { newPlayer.retry.updatePolicy(from: retry) }
+        newEngine.nowPlayingUpdater.source = newPlayer
+        engine = newEngine
+        player = newPlayer
+        audioSession.player = newPlayer
+
+        // Connectivity fans out here, whether or not JS subscribes: the JS event, the
+        // now-playing stall line, and reconnecting a stalled stream. The monitor mutates on main.
+        networkMonitor.onChanged = { [weak self] isOnline in
+          MainActor.assumeIsolated {
+            self?.onOnlineChanged(isOnline)
+            self?.engine?.nowPlayingUpdater.isOnline = isOnline
+            if isOnline { self?.player?.networkDidReturn() }
+          }
+        }
+
+        // `options.keepSessionAliveOnError` is deliberately ignored here: iOS needs no masking.
+        // A terminal error keeps the now-playing info (never cleared on error), and next/previous
+        // stay enabled (gated on queue position, not state). So the
+        // session stays controllable through errors by default — the behavior Android achieves via
+        // InterceptingPlayer is already the iOS norm.
+
+        // The bundled runtime options and initial state are part of the atomic launch
+        // description. Stage the state first so setup options and earlier pre-setup setter
+        // calls resolve by strict last-write-wins, then apply everything to the live player.
+        if let bundled = options.options {
+          updateOptions(options: bundled)
+        } else {
+          // updateOptions applies remote commands itself; without bundled options, apply the
+          // defaults (play, pause, next, previous, seekTo) here.
+          applyRemoteCommands()
+        }
+        if let mode = options.repeatMode { pendingRepeatMode = mode }
+        if let intent = options.playWhenReady { pendingPlayWhenReady = intent }
+        applyPendingPlayerState()
+
+        // Push the resolved event cadence unconditionally. `updateOptions` applies
+        // the interval only when it *differs* from the stored one, but the store
+        // outlives the player — so on a re-setup with unchanged options the new
+        // player would come up with no progress timer at all.
+        player?.setProgressUpdateInterval(playerOptions.progressUpdateEventInterval)
+        player?.setPlaybackIntervalEnabled(playbackIntervalEnabled)
+
+        // Notify listeners that player is ready (e.g., CarPlay)
+        playerAndConfiguredBrowser.check()
+      }
+    }
+  }
+
+  /// Applies initial player state staged before the player existed — from setup options or the
+  /// imperative setters called pre-setup. Consumed on apply so a later re-setup doesn't replay
+  /// stale state.
+  @MainActor
+  private func applyPendingPlayerState() {
+    guard let player else { return }
+    if let mode = pendingRepeatMode {
+      player.repeatMode = mode
+      pendingRepeatMode = nil
+    }
+    if let intent = pendingPlayWhenReady {
+      player.setPlayWhenReady(intent)
+      pendingPlayWhenReady = nil
+    }
+  }
+
+  func updateOptions(options: NativeUpdateOptions) {
+    onMainActor {
+      let previousInterval = playerOptions.progressUpdateEventInterval
+
+      // Update stored options
+      playerOptions.update(from: options)
+
+      // Propagate the favorite flag to the browser so it can hydrate
+      // row hearts (the `favorite` capability is the single favoriting switch).
+      browserManager.setFavoriteEnabled(playerOptions.capabilities.favoriteEnabled)
+
+      // Apply remote commands to player
+      applyRemoteCommands()
+
+      // Apply progress update interval if changed
+      if playerOptions.progressUpdateEventInterval != previousInterval {
+        player?.setProgressUpdateInterval(playerOptions.progressUpdateEventInterval)
+      }
+
+      onOptionsChanged(playerOptions.toOptions())
+      playerOptionsChangedEmitter.emit(())
+    }
+  }
+
+  /// Converts capabilities to remote commands and applies them to the player
+  @MainActor
+  private func applyRemoteCommands() {
+    guard let engine else { return }
+
+    let remoteCommands = playerOptions.capabilities.buildRemoteCommands(
+      forwardJumpInterval: NSNumber(value: playerOptions.forwardJumpInterval),
+      backwardJumpInterval: NSNumber(value: playerOptions.backwardJumpInterval),
+      playbackRates: playerOptions.playbackRates,
+    )
+
+    engine.remoteCommands = remoteCommands
+  }
+
+  func getOptions() throws -> Options {
+    onMainActor { playerOptions.toOptions() }
+  }
+
+  func setPlaybackIntervalEnabled(enabled: Bool) {
+    onMainActor {
+      playbackIntervalEnabled = enabled
+      player?.setPlaybackIntervalEnabled(enabled)
+    }
+  }
+}