react-native-audio-browser 0.2.0-next.27 → 0.2.0-next.29

package/ios/CarPlay/CarPlayTemplates.swift

@@ -0,0 +1,63 @@
+import CarPlay
+
+/// What a CarPlay template shows, kept in its `userInfo`.
+struct CarPlayTemplateInfo {
+  enum Kind {
+    /// Content that `path` resolves to; loaded lazily and refreshed.
+    case content
+    /// The Browse Gate's page for `path`, which is never loaded.
+    case gate
+  }
+
+  /// The browse path the template stands for. Nil only for a gate page shown at the root.
+  let path: String?
+  let kind: Kind
+}
+
+extension CPTemplate {
+  var carPlayInfo: CarPlayTemplateInfo? {
+    get { userInfo as? CarPlayTemplateInfo }
+    set { userInfo = newValue }
+  }
+
+  /// The path this template loads content from; nil for gate and message pages.
+  var contentPath: String? {
+    guard let info = carPlayInfo, info.kind == .content else { return nil }
+    return info.path
+  }
+}
+
+extension CPListTemplate {
+  /// A list template whose content is still resolving: the system spinner on iOS 18.4+, and
+  /// the app's `loadingTitle`, when it set one, as the empty-view subtitle. A title-slot hint
+  /// would render at CarPlay's large empty-state size.
+  static func loading(title: String?, path: String?, loadingTitle: String?) -> CPListTemplate {
+    let template = CPListTemplate(title: title, sections: [])
+    if let path { template.carPlayInfo = CarPlayTemplateInfo(path: path, kind: .content) }
+    if let loadingTitle { template.emptyViewSubtitleVariants = [loadingTitle] }
+    if #available(iOS 18.4, *) {
+      template.showsSpinnerWhileEmpty = true
+    }
+    return template
+  }
+
+  /// An empty list template showing a centered message. CarPlay renders an empty view reliably
+  /// only as a template's initial state, so a pushed page's message is a new template.
+  static func message(
+    _ title: String,
+    subtitle: String?,
+    listTitle: String? = nil,
+    info: CarPlayTemplateInfo? = nil,
+  ) -> CPListTemplate {
+    let template = CPListTemplate(title: listTitle, sections: [])
+    template.setMessage(title, subtitle: subtitle)
+    template.carPlayInfo = info
+    return template
+  }
+
+  /// Newlines collapse to spaces: the variants are width alternatives, not lines.
+  func setMessage(_ title: String, subtitle: String?) {
+    emptyViewTitleVariants = [title]
+    emptyViewSubtitleVariants = subtitle.flatMap { $0.isEmpty ? nil : [$0.replacingOccurrences(of: "\n", with: " ")] } ?? []
+  }
+}

package/ios/CarPlay/HybridAudioBrowser+IntentFavorite.swift

@@ -0,0 +1,20 @@
+import Foundation
+import os.log
+
+private let intentLogger = Logger(subsystem: "com.audiobrowser", category: "MediaIntent")
+
+extension HybridAudioBrowser {
+  /// Sets the favorite state of the playing track for a Siri intent, through the same path as
+  /// the CarPlay favorite button. False when nothing is playing, the playing track has no
+  /// identity to favorite, or the change throws.
+  @MainActor
+  static func favoriteCurrentTrack(_ favorited: Bool) -> Bool {
+    guard let browser = shared else { return false }
+    do {
+      return try browser.favoriteActiveTrack(favorited)
+    } catch {
+      intentLogger.error("favoriteCurrentTrack(\(favorited)) failed: \(error.localizedDescription)")
+      return false
+    }
+  }
+}

package/ios/CarPlay/MediaIntentPlayback.swift

@@ -0,0 +1,74 @@
+import Foundation
+import NitroModules
+import os.log
+
+private let logger = Logger(subsystem: "com.audiobrowser", category: "MediaIntentPlayback")
+
+/// Plays a Siri play-media intent through the single voice play funnel (ADR 0002): resume, or
+/// search → queue → play, then surface Now Playing.
+enum MediaIntentPlayback {
+  /// Callable before the bridge exists: it waits, within the assistant's budget, for the player
+  /// and a configured browser, which come up once React Native boots. Each await may outlive the
+  /// bridge or its player (a JS reload or a second setup replaces them), so the player is looked
+  /// up again after one, and the intent fails once the bridge is gone.
+  @MainActor
+  static func play(criteria: MediaIntentCriteria) async -> Bool {
+    guard let (browser, player) = await playerAndConfiguredBrowser.wait(timeout: .seconds(8)) else {
+      logger.error("browser/player not ready within budget")
+      return false
+    }
+    // Resume is not gated: the gate blocks finding content, never hearing the active or
+    // persisted track.
+    if criteria.isResume {
+      if player.currentTrack != nil {
+        logger.info("resume: warm — playing current track")
+        player.play()
+      } else {
+        guard let session = player.persistedSession() else { return false }
+        var expanded: (tracks: [Track], selectedIndex: Int)?
+        if let path = session.track.path {
+          expanded = try? await browser.browserManager.expandQueueFromContextualPath(path)
+        }
+        guard let player = livePlayer(of: browser) else { return false }
+        player.resume(session, queue: expanded)
+      }
+      browser.showNowPlayingRequestedEmitter.emit(())
+      return true
+    }
+
+    // The API still text-searches `q`; the structured fields are forward-compatible, as on
+    // Android.
+    let params = SearchParams(
+      mode: criteria.searchMode.flatMap { SearchMode(fromString: $0) },
+      query: criteria.query,
+      genre: criteria.genre,
+      artist: criteria.artist,
+      album: criteria.album,
+      title: criteria.title,
+      playlist: criteria.playlist,
+      reference: criteria.reference == .my ? .my : .unknown,
+    )
+    guard await browser.browseGate.decide(NativeGateRequest(reason: .search, path: nil, search: params)) == nil else {
+      logger.info("search refused — gated")
+      browser.onGate(GateEvent(reason: .search))
+      return false
+    }
+    do {
+      guard let tracks = try await browser.browserManager.searchPlayable(params),
+            let player = livePlayer(of: browser) else { return false }
+      player.setQueue(tracks, initialIndex: 0, playWhenReady: true)
+      browser.showNowPlayingRequestedEmitter.emit(())
+      return true
+    } catch {
+      logger.error("search failed: \(error.localizedDescription)")
+      return false
+    }
+  }
+
+  /// `browser`'s player while `browser` is still the live bridge; a replaced bridge keeps its
+  /// destroyed player.
+  @MainActor
+  private static func livePlayer(of browser: HybridAudioBrowser) -> Player? {
+    HybridAudioBrowser.shared === browser ? browser.getPlayer() : nil
+  }
+}

package/ios/CarPlay/RNABMediaAddHandler.swift

@@ -28,24 +28,8 @@ class RNABMediaAddHandler: NSObject, INAddMediaIntentHandling {
     Self.logger.info("Add media — favorite current track")
 
     Task { @MainActor in
-      // "Add" targets the current track; if nothing is playing there's nothing
-      // to add, so the assistant reports failure rather than a silent no-op.
-      guard let browser = HybridAudioBrowser.shared,
-            browser.getPlayer()?.currentTrack != nil
-      else {
-        completion(INAddMediaIntentResponse(code: .failure, userActivity: nil))
-        return
-      }
-
-      // Add = favorite the currently-playing track (same path as the CarPlay
-      // favorite button / affinity "like"): flips the now-playing heart and
-      // fires `onFavoriteChanged` so the consumer persists it — no extra handler.
-      do {
-        try browser.setActiveTrackFavorited(favorited: true)
-        completion(INAddMediaIntentResponse(code: .success, userActivity: nil))
-      } catch {
-        completion(INAddMediaIntentResponse(code: .failure, userActivity: nil))
-      }
+      let applied = HybridAudioBrowser.favoriteCurrentTrack(true)
+      completion(INAddMediaIntentResponse(code: applied ? .success : .failure, userActivity: nil))
     }
   }
 

package/ios/CarPlay/RNABMediaAffinityHandler.swift

@@ -27,28 +27,12 @@ class RNABMediaAffinityHandler: NSObject, INUpdateMediaAffinityIntentHandling {
     Self.logger.info("Update media affinity — type=\(affinity.rawValue)")
 
     Task { @MainActor in
-      // Affinity targets the current track; if nothing is playing there's nothing
-      // to like, so the assistant reports failure rather than a silent no-op.
-      guard let browser = HybridAudioBrowser.shared,
-            browser.getPlayer()?.currentTrack != nil
-      else {
-        completion(INUpdateMediaAffinityIntentResponse(code: .failure, userActivity: nil))
-        return
+      let applied = switch affinity {
+      case .like: HybridAudioBrowser.favoriteCurrentTrack(true)
+      case .dislike: HybridAudioBrowser.favoriteCurrentTrack(false)
+      default: false
       }
-
-      // Map affinity onto the library-managed favorite state (same path as the
-      // CarPlay favorite button): flips the now-playing heart and fires
-      // `onFavoriteChanged` so the consumer persists it — no extra handler.
-      switch affinity {
-      case .like:
-        try? browser.setActiveTrackFavorited(favorited: true)
-      case .dislike:
-        try? browser.setActiveTrackFavorited(favorited: false)
-      default:
-        completion(INUpdateMediaAffinityIntentResponse(code: .failure, userActivity: nil))
-        return
-      }
-      completion(INUpdateMediaAffinityIntentResponse(code: .success, userActivity: nil))
+      completion(INUpdateMediaAffinityIntentResponse(code: applied ? .success : .failure, userActivity: nil))
     }
   }
 

package/ios/CarPlay/RNABMediaIntentHandler.swift

@@ -25,9 +25,8 @@ class RNABMediaIntentHandler: NSObject, INPlayMediaIntentHandling {
     )
     Self.logger.info("Play media intent — query=\(criteria.query) matchesApp=\(criteria.matchesAppName) resume=\(criteria.isResume)")
 
-    // Static + gate-waiting, so it works even before the shared instance exists
-    // (background intent launch, RN not booted yet).
-    HybridAudioBrowser.handlePlayMediaIntent(criteria: criteria) { success in
+    Task { @MainActor in
+      let success = await MediaIntentPlayback.play(criteria: criteria)
       completion(INPlayMediaIntentResponse(code: success ? .success : .failure, userActivity: nil))
     }
   }

package/ios/Extension/NavigationError+Conversion.swift

@@ -8,10 +8,6 @@ extension NavigationError {
       switch browserError {
       case .contentNotFound:
         NavigationError(code: .contentNotFound, message: browserError.localizedDescription, statusCode: nil, statusCodeSuccess: nil)
-      case let .httpError(code, _):
-        NavigationError(code: .httpError, message: browserError.localizedDescription, statusCode: Double(code), statusCodeSuccess: (200 ... 299).contains(code))
-      case .networkError:
-        NavigationError(code: .networkError, message: browserError.localizedDescription, statusCode: nil, statusCodeSuccess: nil)
       case .invalidConfiguration:
         NavigationError(code: .unknownError, message: browserError.localizedDescription, statusCode: nil, statusCodeSuccess: nil)
       case .callbackError:
@@ -55,6 +51,13 @@ extension NavigationError {
   }
 }
 
+extension NavigationError {
+  /// A code-only error: the copy comes from the app's `formatNavigationError` (ADR 0001).
+  static func code(_ code: NavigationErrorType) -> NavigationError {
+    NavigationError(code: code, message: "", statusCode: nil, statusCodeSuccess: nil)
+  }
+}
+
 extension NavigationErrorKind {
   /// The kind of request a navigation error on `path` came from.
   init(path: String) {

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,180 +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)
     }
-    // An explicit `User-Agent` in `headers` wins, matching the two sibling paths
-    // (MediaLoader.buildAssetOptions and the artwork path in
-    // BrowserManager+URLResolution). `userAgent` carries a non-nil default, so
-    // overwriting unconditionally would replace a consumer's header with
-    // "react-native-audio-browser" whenever they set only the header.
+    // 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
@@ -217,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)")
-  }
 }