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

package/ios/Tests/URLErrorConnectivityTests.swift

@@ -0,0 +1,20 @@
+import Foundation
+import Testing
+
+@testable import AudioBrowserTestable
+
+@Suite("URLError.isConnectivity")
+struct URLErrorConnectivityTests {
+  @Test(arguments: [
+    URLError.Code.timedOut, .networkConnectionLost, .notConnectedToInternet, .cannotConnectToHost,
+    .cannotFindHost, .dnsLookupFailed,
+  ])
+  func aMissingConnectionIsWorthRepeating(_ code: URLError.Code) {
+    #expect(URLError(code).isConnectivity)
+  }
+
+  @Test(arguments: [URLError.Code.badServerResponse, .fileDoesNotExist, .badURL, .cancelled, .userAuthenticationRequired])
+  func anyOtherFailureIsNot(_ code: URLError.Code) {
+    #expect(!URLError(code).isConnectivity)
+  }
+}

package/ios/TrackSelector.swift

@@ -14,7 +14,7 @@ import os.log
 }
 
 /// Encapsulates the shared track selection decision tree used by both
-/// HybridAudioBrowser and CarPlayController.
+/// HybridAudioBrowser and CarPlaySession.
 ///
 /// Resolves a track selection to a concrete `SelectionResult` describing
 /// what the caller should do. Each caller then executes the action in its

package/ios/Util/ArtworkImageFetcher.swift

@@ -1,4 +1,5 @@
 import Kingfisher
+import Network
 import NitroModules
 import os.log
 import UIKit
@@ -7,11 +8,14 @@ import UIKit
 enum ArtworkImageFetcher {
   private static let logger = Logger(subsystem: "com.audiobrowser", category: "ArtworkImageFetcher")
 
+  /// - Parameter waitsForConnectivity: A fetch that fails for want of a connection waits for one
+  ///   and tries again. A cancelled fetch that is waiting ends when the connection returns.
   @MainActor
   static func fetchImage(
     from source: ImageSource,
     svgScale: CGFloat? = nil,
     downsampleTo: (size: CGSize, scale: CGFloat)? = nil,
+    waitsForConnectivity: Bool = false,
   ) async -> UIImage? {
     guard let url = URL(string: source.uri) else { return nil }
 
@@ -41,6 +45,10 @@ enum ArtworkImageFetcher {
       options.append(.cacheOriginalImage)
     }
 
+    if waitsForConnectivity {
+      options.append(.retryStrategy(ConnectivityRetry()))
+    }
+
     do {
       let result = try await KingfisherManager.shared.retrieveImage(with: url, options: options)
       return result.image
@@ -50,3 +58,37 @@ enum ArtworkImageFetcher {
     }
   }
 }
+
+/// Repeats a fetch that failed for want of a connection once one is back, a few times at most; any
+/// other failure, a 404 included, stops at once.
+private struct ConnectivityRetry: RetryStrategy {
+  private static let maxRetries = 3
+
+  func retry(context: RetryContext, retryHandler: @escaping @Sendable (RetryDecision) -> Void) {
+    guard context.retriedCount < Self.maxRetries,
+          case let .responseError(reason: .URLSessionError(error)) = context.error,
+          (error as? URLError)?.isConnectivity == true
+    else {
+      retryHandler(.stop)
+      return
+    }
+    Self.whenConnected { retryHandler(.retry(userInfo: nil)) }
+  }
+
+  /// Calls `body` once the device has a usable path, at once when it has one already: a monitor
+  /// reports the current path when it starts, so a reconnect cannot slip past it. The handler
+  /// holds the monitor until it fires.
+  private static func whenConnected(_ body: @escaping @Sendable () -> Void) {
+    let monitor = NWPathMonitor()
+    monitor.pathUpdateHandler = { path in
+      guard path.status == .satisfied, monitor.pathUpdateHandler != nil else { return }
+      monitor.pathUpdateHandler = nil
+      monitor.cancel()
+      body()
+    }
+    monitor.start(queue: queue)
+  }
+
+  /// Serial, so a monitor's handler never runs twice at once.
+  private static let queue = DispatchQueue(label: "com.audiobrowser.artwork-connectivity", qos: .utility)
+}

package/ios/Util/Emitter.swift

@@ -66,3 +66,45 @@ public final class Emitter<T>: @unchecked Sendable {
     return snapshot.count
   }
 }
+
+/// A listener registration that ends when cancelled or released.
+final class Subscription {
+  private var cancelHandler: (() -> Void)?
+
+  init(cancel: @escaping () -> Void) {
+    cancelHandler = cancel
+  }
+
+  func cancel() {
+    cancelHandler?()
+    cancelHandler = nil
+  }
+
+  deinit {
+    cancelHandler?()
+  }
+}
+
+extension Emitter {
+  /// Adds `listener` until the returned subscription is cancelled or released.
+  func subscribe(_ listener: @escaping (T) -> Void) -> Subscription {
+    let token = addListener(listener)
+    return Subscription { [weak self] in self?.removeListener(token) }
+  }
+}
+
+extension Emitter {
+  /// Like `subscribe`, but `handler` runs on the main actor after the emit returns, whichever
+  /// thread emitted.
+  func subscribeOnMain(_ handler: @escaping @MainActor (T) -> Void) -> Subscription {
+    subscribe { value in
+      let event = MainActorHop(value: value)
+      Task { @MainActor in handler(event.value) }
+    }
+  }
+}
+
+/// Carries an emitted value to the main actor, where it is only read.
+private struct MainActorHop<T>: @unchecked Sendable {
+  let value: T
+}

package/ios/Util/GenerationMemo.swift

@@ -0,0 +1,36 @@
+/// A value computed at most once per generation and shared by every caller of that generation.
+///
+/// `invalidate()` starts a new generation. A caller whose computation finishes or fails after
+/// an invalidation computes again, so `value(_:)` never returns a stale result; `compute` must
+/// therefore read the state it depends on when it runs, not capture it. A failure is not kept:
+/// the next caller of the same generation tries again. A cancelled caller stops retrying.
+@MainActor
+final class GenerationMemo<Value: Sendable> {
+  private var generation = 0
+  private var current: (generation: Int, task: Task<Value, Error>)?
+
+  func invalidate() {
+    generation += 1
+  }
+
+  func value(_ compute: @escaping @MainActor () async throws -> Value) async throws -> Value {
+    while true {
+      try Task.checkCancellation()
+      let generation = generation
+      let task: Task<Value, Error>
+      if let current, current.generation == generation {
+        task = current.task
+      } else {
+        task = Task { try await compute() }
+        current = (generation, task)
+      }
+      do {
+        let value = try await task.value
+        if generation == self.generation { return value }
+      } catch {
+        if current?.task == task { current = nil }
+        if generation == self.generation { throw error }
+      }
+    }
+  }
+}

package/ios/Util/LRUCache.swift

@@ -1,185 +1,46 @@
-import Foundation
-
-/// A thread-safe Least Recently Used (LRU) cache with O(1) operations.
-///
-/// When the cache exceeds its maximum size, the least recently accessed
-/// items are evicted to make room for new entries.
-///
-/// Uses a doubly-linked list + dictionary for O(1) get/set/remove operations.
+/// A cache of at most `maxSize` entries that evicts the least recently used one.
+/// Sized for a handful of entries: a use moves the key within an array.
+@MainActor
 final class LRUCache<Key: Hashable, Value> {
-  /// Doubly-linked list node for O(1) removal and reordering.
-  private final class Node {
-    let key: Key
-    var value: Value
-    /// Weak: with both directions strong, any two adjacent nodes form a reference cycle, so the
-    /// whole chain outlives `clear()` and the cache's own deinit. The list is kept alive from
-    /// `head` forwards.
-    weak var prev: Node?
-    var next: Node?
-
-    init(key: Key, value: Value) {
-      self.key = key
-      self.value = value
-    }
-  }
-
   private let maxSize: Int
-  private var cache: [Key: Node] = [:]
-  private var head: Node? // Most recently used
-  private var tail: Node? // Least recently used
-  private let lock = NSLock()
+  private var entries: [Key: Value] = [:]
+  /// Least recently used first.
+  private var order: [Key] = []
 
-  /// Creates a new LRU cache with the specified maximum size.
-  ///
-  /// - Parameter maxSize: The maximum number of items the cache can hold
-  init(maxSize: Int) {
+  nonisolated init(maxSize: Int) {
     self.maxSize = maxSize
   }
 
-  /// Moves a node to the head (most recently used position).
-  private func moveToHead(_ node: Node) {
-    guard node !== head else { return }
-
-    // Remove from current position
-    node.prev?.next = node.next
-    node.next?.prev = node.prev
-
-    if node === tail {
-      tail = node.prev
-    }
-
-    // Insert at head
-    node.prev = nil
-    node.next = head
-    head?.prev = node
-    head = node
-
-    if tail == nil {
-      tail = node
-    }
-  }
-
-  /// Removes a node from the list.
-  private func removeNode(_ node: Node) {
-    node.prev?.next = node.next
-    node.next?.prev = node.prev
-
-    if node === head {
-      head = node.next
-    }
-    if node === tail {
-      tail = node.prev
-    }
-
-    node.prev = nil
-    node.next = nil
-  }
-
-  /// Adds a node at the head (most recently used position).
-  private func addToHead(_ node: Node) {
-    node.prev = nil
-    node.next = head
-    head?.prev = node
-    head = node
-
-    if tail == nil {
-      tail = node
-    }
-  }
-
-  /// Removes and returns the tail node (least recently used).
-  private func removeTail() -> Node? {
-    guard let tailNode = tail else { return nil }
-    removeNode(tailNode)
-    return tailNode
+  var count: Int {
+    entries.count
   }
 
-  /// Gets a value from the cache, updating its access order.
-  ///
-  /// - Parameter key: The key to look up
-  /// - Returns: The cached value, or nil if not found
   func get(_ key: Key) -> Value? {
-    lock.lock()
-    defer { lock.unlock() }
-
-    guard let node = cache[key] else {
-      return nil
-    }
-
-    // Move to head (most recently used)
-    moveToHead(node)
-    return node.value
+    guard let value = entries[key] else { return nil }
+    touch(key)
+    return value
   }
 
-  /// Sets a value in the cache.
-  ///
-  /// If the cache is full, the least recently used item is evicted.
-  ///
-  /// - Parameters:
-  ///   - key: The key to store
-  ///   - value: The value to store
   func set(_ key: Key, value: Value) {
-    lock.lock()
-    defer { lock.unlock() }
-
-    // If key exists, update value and move to head
-    if let existingNode = cache[key] {
-      existingNode.value = value
-      moveToHead(existingNode)
-      return
+    entries[key] = value
+    touch(key)
+    if order.count > maxSize {
+      entries.removeValue(forKey: order.removeFirst())
     }
-
-    // Evict oldest if at capacity
-    if cache.count >= maxSize, let evicted = removeTail() {
-      cache.removeValue(forKey: evicted.key)
-    }
-
-    // Add new entry at head
-    let newNode = Node(key: key, value: value)
-    cache[key] = newNode
-    addToHead(newNode)
   }
 
-  /// Removes a value from the cache.
-  ///
-  /// - Parameter key: The key to remove
   func remove(_ key: Key) {
-    lock.lock()
-    defer { lock.unlock() }
-
-    guard let node = cache[key] else { return }
-    removeNode(node)
-    cache.removeValue(forKey: key)
+    entries.removeValue(forKey: key)
+    order.removeAll { $0 == key }
   }
 
-  /// Clears all entries from the cache.
   func clear() {
-    lock.lock()
-    defer { lock.unlock() }
-
-    cache.removeAll()
-    head = nil
-    tail = nil
-  }
-
-  /// The current number of items in the cache.
-  var count: Int {
-    lock.lock()
-    defer { lock.unlock() }
-    return cache.count
-  }
-
-  /// Returns all values in the cache (no particular order guaranteed).
-  var values: [Value] {
-    lock.lock()
-    defer { lock.unlock() }
-    return cache.values.map(\.value)
+    entries.removeAll()
+    order.removeAll()
   }
 
-  /// Returns all keys in the cache (no particular order guaranteed).
-  var keys: [Key] {
-    lock.lock()
-    defer { lock.unlock() }
-    return Array(cache.keys)
+  private func touch(_ key: Key) {
+    order.removeAll { $0 == key }
+    order.append(key)
   }
 }

package/ios/Util/NetworkMonitor.swift

@@ -59,7 +59,7 @@ final class NetworkMonitor: @unchecked Sendable {
     // update with a `currentPath` the monitor hasn't finished evaluating. Nothing
     // recovers from that: the handler has already fired, `onChanged` isn't wired
     // until setupPlayer, and the stale value then drives `getOnline()`, the JS
-    // event, and RetryManager's offline parking until the next genuine path
+    // event, and RetryLoop's offline parking until the next genuine path
     // change. Seeding first is a best-effort guess; the handler fires shortly
     // after `start` and is the authoritative last writer.
     let initialStatus = monitor.currentPath.status == .satisfied

package/ios/Util/ReadyValue.swift

@@ -0,0 +1,56 @@
+import Foundation
+
+/// A value that exists once `provider` returns one. `wait` returns it, parking until `check()`
+/// finds it; nothing is cached, so the provider's current answer always wins.
+@MainActor
+final class ReadyValue<T: Sendable> {
+  private let provider: () -> T?
+  private var waiters: [UUID: CheckedContinuation<T?, Never>] = [:]
+
+  init(provider: @escaping () -> T?) {
+    self.provider = provider
+  }
+
+  var waiterCount: Int {
+    waiters.count
+  }
+
+  /// Resumes every parked waiter if the provider now has a value.
+  func check() {
+    guard !waiters.isEmpty, let value = provider() else { return }
+    let pending = waiters
+    waiters = [:]
+    for waiter in pending.values {
+      waiter.resume(returning: value)
+    }
+  }
+
+  /// The provider's value, waiting for it when there is none yet. Nil when the calling task is
+  /// cancelled or `timeout` elapses first.
+  func wait(timeout: Duration? = nil) async -> T? {
+    if let value = provider() { return value }
+    let id = UUID()
+    let timer = timeout.map { timeout in
+      Task { [weak self] in
+        try? await Task.sleep(for: timeout)
+        self?.resume(id, with: nil)
+      }
+    }
+    defer { timer?.cancel() }
+    return await withTaskCancellationHandler {
+      await withCheckedContinuation { continuation in
+        if Task.isCancelled {
+          continuation.resume(returning: nil)
+        } else {
+          waiters[id] = continuation
+        }
+      }
+    } onCancel: {
+      Task { @MainActor [weak self] in self?.resume(id, with: nil) }
+    }
+  }
+
+  private func resume(_ id: UUID, with value: T?) {
+    waiters.removeValue(forKey: id)?.resume(returning: value)
+  }
+}

package/ios/Util/SFSymbolRenderer.swift

@@ -41,15 +41,6 @@ final class SFSymbolRenderer: @unchecked Sendable {
   ///   - canvasSize: The canvas size in points (rendered at device scale)
   /// - Returns: A file URI string, or nil if the symbol doesn't exist or rendering fails
   func render(_ artworkValue: String, canvasSize: CGSize = defaultCanvasSize) -> String? {
-    let (symbolName, backgroundColor, symbolColor) = Self.parseArtwork(artworkValue)
-
-    // Validate symbol exists before any filesystem work
-    let symbolPointSize = min(canvasSize.width, canvasSize.height) * 0.45
-    let config = UIImage.SymbolConfiguration(pointSize: symbolPointSize, weight: .medium)
-    guard let symbol = UIImage(systemName: symbolName, withConfiguration: config) else {
-      return nil
-    }
-
     let safeArtwork = artworkValue.unicodeScalars
       .filter { CharacterSet.alphanumerics.contains($0) || $0 == "_" }
       .map(String.init).joined()
@@ -61,26 +52,11 @@ final class SFSymbolRenderer: @unchecked Sendable {
       return fileURL.absoluteString
     }
 
-    let renderer = UIGraphicsImageRenderer(size: canvasSize, format: {
-      let fmt = UIGraphicsImageRendererFormat()
-      fmt.scale = scale
-      return fmt
-    }())
-
-    let pngData = renderer.pngData { _ in
-      if let backgroundColor {
-        backgroundColor.setFill()
-        UIRectFill(CGRect(origin: .zero, size: canvasSize))
-      }
-
-      let symbolSize = symbol.size
-      let x = (canvasSize.width - symbolSize.width) / 2
-      let y = (canvasSize.height - symbolSize.height) / 2
-
-      (symbolColor ?? .black).set()
-      symbol.withRenderingMode(.alwaysTemplate)
-        .draw(in: CGRect(x: x, y: y, width: symbolSize.width, height: symbolSize.height))
-    }
+    let (symbolName, backgroundColor, symbolColor) = Self.parseArtwork(artworkValue)
+    guard let pngData = Self.image(
+      name: symbolName, canvasSize: canvasSize, scale: scale,
+      tint: symbolColor ?? .black, background: backgroundColor,
+    )?.pngData() else { return nil }
 
     do {
       try pngData.write(to: fileURL, options: .atomic)
@@ -92,6 +68,36 @@ final class SFSymbolRenderer: @unchecked Sendable {
     return fileURL.absoluteString
   }
 
+  /// Draws the symbol at 45% of the canvas, centred and tinted, over `background` (nil leaves it
+  /// transparent). Nil when there is no symbol of that name.
+  static func image(
+    name: String,
+    canvasSize: CGSize,
+    scale: CGFloat,
+    tint: UIColor,
+    background: UIColor?,
+  ) -> UIImage? {
+    let pointSize = min(canvasSize.width, canvasSize.height) * 0.45
+    let config = UIImage.SymbolConfiguration(pointSize: pointSize, weight: .medium)
+    guard let symbol = UIImage(systemName: name, withConfiguration: config) else { return nil }
+    let format = UIGraphicsImageRendererFormat()
+    format.scale = scale
+    return UIGraphicsImageRenderer(size: canvasSize, format: format).image { _ in
+      if let background {
+        background.setFill()
+        UIRectFill(CGRect(origin: .zero, size: canvasSize))
+      }
+      let size = symbol.size
+      tint.set()
+      symbol.withRenderingMode(.alwaysTemplate).draw(in: CGRect(
+        x: (canvasSize.width - size.width) / 2,
+        y: (canvasSize.height - size.height) / 2,
+        width: size.width,
+        height: size.height,
+      ))
+    }.withRenderingMode(.alwaysOriginal)
+  }
+
   /// Whether the given artwork string is an SF Symbol reference.
   static func isSFSymbol(_ artwork: String) -> Bool {
     artwork.hasPrefix("sf:")

package/ios/Util/SVGProcessor.swift

@@ -51,13 +51,3 @@ struct SVGProcessor: ImageProcessor {
     return svg.rasterize(size: renderSize, scale: scale)
   }
 }
-
-// MARK: - Kingfisher Options Extension
-
-extension KingfisherOptionsInfoItem {
-  /// Returns an SVG processor option for Kingfisher.
-  @MainActor
-  static func svgProcessor(size: CGSize? = nil, scale: CGFloat? = nil) -> KingfisherOptionsInfoItem {
-    .processor(SVGProcessor(size: size, scale: scale))
-  }
-}

package/lib/commonjs/web/NativeAudioBrowser.js

@@ -224,7 +224,7 @@ class NativeAudioBrowser extends _TrackPlayer.QueuePlayer {
    * Re-derives the playing state and emits on change. Called from both of its
    * inputs' change points — the state setter and the playWhenReady setter —
    * with a dedupe so identical derivations don't double-emit (parity with
-   * Android's refreshPlayingState / iOS's PlayingStateManager).
+   * Android's refreshPlayingState / iOS's Player.playingState).
    */
   refreshPlayingState() {
     const next = (0, _PlayingStateFactory.derivePlayingState)(this._playWhenReady, this.state.state);

package/lib/commonjs/web/TrackPlayer/PlayingStateFactory.js

@@ -9,7 +9,7 @@ exports.derivePlayingState = derivePlayingState;
  * player's intent (`playWhenReady`) and its current {@link PlaybackState}.
  *
  * A faithful port of the native derivations (android `PlayingStateFactory.derive`,
- * ios `PlayingStateManager.update`) so all platforms agree on what "playing" and
+ * ios `Player.playingState`) so all platforms agree on what "playing" and
  * "buffering" mean for the now-playing UI.
  */
 function derivePlayingState(playWhenReady, state) {

package/lib/module/web/NativeAudioBrowser.js

@@ -221,7 +221,7 @@ export class NativeAudioBrowser extends QueuePlayer {
    * Re-derives the playing state and emits on change. Called from both of its
    * inputs' change points — the state setter and the playWhenReady setter —
    * with a dedupe so identical derivations don't double-emit (parity with
-   * Android's refreshPlayingState / iOS's PlayingStateManager).
+   * Android's refreshPlayingState / iOS's Player.playingState).
    */
   refreshPlayingState() {
     const next = derivePlayingState(this._playWhenReady, this.state.state);

package/lib/module/web/TrackPlayer/PlayingStateFactory.js

@@ -5,7 +5,7 @@
  * player's intent (`playWhenReady`) and its current {@link PlaybackState}.
  *
  * A faithful port of the native derivations (android `PlayingStateFactory.derive`,
- * ios `PlayingStateManager.update`) so all platforms agree on what "playing" and
+ * ios `Player.playingState`) so all platforms agree on what "playing" and
  * "buffering" mean for the now-playing UI.
  */
 export function derivePlayingState(playWhenReady, state) {

package/lib/typescript/src/types/browser.d.ts

@@ -968,7 +968,7 @@ export type CarPlaySiriListButtonPosition = 'top' | 'bottom';
  */
 export type FormattedNavigationError = {
     /**
-     * Title shown in the error action sheet header.
+     * Title of the error.
      *
      * Default values:
      * - `'content-not-found'`: "Content Not Found" (English)
@@ -979,8 +979,8 @@ export type FormattedNavigationError = {
      */
     title: string;
     /**
-     * Optional second line — the body in the error action sheet, the subtitle in
-     * the browse error/empty view. Omit it to show a title only.
+     * Optional second line — the subtitle in the browse error/empty view. Omit it
+     * to show a title only.
      *
      * Default value: `error.message` (omitted when that is empty).
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-audio-browser",
-  "version": "0.2.0-next.27",
+  "version": "0.2.0-next.29",
   "description": "react-native-audio-browser is a react native package built with Nitro",
   "keywords": [
     "react-native",

package/src/types/browser.ts

@@ -1074,7 +1074,7 @@ export type CarPlaySiriListButtonPosition = 'top' | 'bottom'
  */
 export type FormattedNavigationError = {
   /**
-   * Title shown in the error action sheet header.
+   * Title of the error.
    *
    * Default values:
    * - `'content-not-found'`: "Content Not Found" (English)
@@ -1085,8 +1085,8 @@ export type FormattedNavigationError = {
    */
   title: string
   /**
-   * Optional second line — the body in the error action sheet, the subtitle in
-   * the browse error/empty view. Omit it to show a title only.
+   * Optional second line — the subtitle in the browse error/empty view. Omit it
+   * to show a title only.
    *
    * Default value: `error.message` (omitted when that is empty).
    */

package/src/web/NativeAudioBrowser.ts

@@ -328,7 +328,7 @@ export class NativeAudioBrowser
    * Re-derives the playing state and emits on change. Called from both of its
    * inputs' change points — the state setter and the playWhenReady setter —
    * with a dedupe so identical derivations don't double-emit (parity with
-   * Android's refreshPlayingState / iOS's PlayingStateManager).
+   * Android's refreshPlayingState / iOS's Player.playingState).
    */
   private refreshPlayingState(): void {
     const next = derivePlayingState(this._playWhenReady, this.state.state)

package/src/web/TrackPlayer/PlayingStateFactory.test.ts

@@ -3,7 +3,7 @@ import type { PlaybackState } from '../../features'
 import { derivePlayingState } from './PlayingStateFactory'
 
 // Ported from the native truth table (android PlayingStateFactoryTest.kt /
-// ios PlayingStateManager) so web derives PlayingState identically.
+// ios Player.playingState) so web derives PlayingState identically.
 const ALL_STATES: PlaybackState[] = [
   'none',
   'ready',