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

package/ios/TrackSelector.swift

@@ -5,7 +5,7 @@ import os.log
 
 @MainActor protocol TrackSelectionBrowser {
   func awaitTrackLoadHandler(event: TrackLoadEvent) async -> Bool
-  func expandQueueFromContextualUrl(_ url: String) async throws -> (tracks: [Track], selectedIndex: Int)?
+  func expandQueueFromContextualPath(_ path: String) async throws -> (tracks: [Track], selectedIndex: Int)?
 }
 
 @MainActor protocol TrackSelectionPlayer {
@@ -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
@@ -36,9 +36,9 @@ class TrackSelector {
     case play(PlaybackIntent)
     /// JS handleTrackLoad handler intercepted — caller should not play.
     case intercepted
-    /// Track is browsable — caller should navigate to this URL.
-    case browse(url: String)
-    /// Nothing to do (no src, no url).
+    /// Track is browsable — caller should navigate to this path.
+    case browse(path: String)
+    /// Nothing to do (no src, no path).
     case none
   }
 
@@ -54,16 +54,22 @@ class TrackSelector {
   // MARK: - Selection
 
   /// Resolves a track selection to a concrete action.
-  /// Handles contextual URL expansion, queue reuse, and handler interception.
+  /// Handles contextual path expansion, queue reuse, and handler interception.
   func select(
     track: Track,
     player: some TrackSelectionPlayer,
   ) async -> SelectionResult {
-    let url = track.url
+    // A disabled track is unavailable — it never plays, whichever surface or
+    // stale resume path delivered the selection (Track.disabled).
+    if track.disabled == true {
+      return .none
+    }
+
+    let path = track.path
 
-    // 1. Contextual URL (playable-only track with queue context)
-    if let url, BrowserPathHelper.isContextual(url) {
-      return await handleContextualUrl(url, track: track, player: player)
+    // 1. Contextual path (playable-only track with queue context)
+    if let path, BrowserPathHelper.isContextual(path) {
+      return await handleContextualPath(path, track: track, player: player)
     }
 
     // 2. Has src — single playable track
@@ -71,9 +77,9 @@ class TrackSelector {
       return await handlePlayableTrack(track, player: player)
     }
 
-    // 3. Has url — browsable
-    if let url {
-      return .browse(url: url)
+    // 3. Has path — browsable
+    if let path {
+      return .browse(path: path)
     }
 
     // 4. Neither
@@ -82,31 +88,40 @@ class TrackSelector {
 
   // MARK: - Private Helpers
 
-  private func handleContextualUrl(
-    _ url: String,
+  private func handleContextualPath(
+    _ path: String,
     track: Track,
     player: some TrackSelectionPlayer,
   ) async -> SelectionResult {
-    let parentPath = BrowserPathHelper.stripTrackId(url)
-    let trackId = BrowserPathHelper.extractTrackId(url)
-
-    // Check if queue already came from this parent path — just skip to the track
-    if let trackId,
-       parentPath == player.queueSourcePath,
-       let index = player.tracks.firstIndex(where: { $0.src == trackId })
-    {
-      logger.debug("Queue already from \(parentPath), skipping to index \(index)")
-      let queue = player.tracks
-      let event = TrackLoadEvent(track: track, queue: queue, startIndex: Double(index))
-      if await browserManager.awaitTrackLoadHandler(event: event) {
-        return .intercepted
+    let parentPath = BrowserPathHelper.stripTrackId(path)
+    let trackId = BrowserPathHelper.extractTrackId(path)
+
+    // Check if queue already came from this parent path — just skip to the
+    // track. Exact-surface match first: a contextual path carries the tapped
+    // page position (`__index`), so path equality pins the exact copy when
+    // the page holds the same identity more than once. The identity match
+    // remains for index-less paths (e.g. pre-stamp persisted state); an
+    // index-stamped path with no exact match falls through to expansion,
+    // which re-scopes the queue to the tapped section.
+    if parentPath == player.queueSourcePath {
+      var skipIndex = player.tracks.firstIndex(where: { $0.path == path })
+      if skipIndex == nil, BrowserPathHelper.extractIndex(path) == nil, let trackId {
+        skipIndex = player.tracks.firstIndex(where: { $0.identity == trackId })
+      }
+      if let index = skipIndex {
+        logger.debug("Queue already from \(parentPath), skipping to index \(index)")
+        let queue = player.tracks
+        let event = TrackLoadEvent(track: track, queue: queue, startIndex: Double(index))
+        if await browserManager.awaitTrackLoadHandler(event: event) {
+          return .intercepted
+        }
+        return .play(.skipTo(index: index))
       }
-      return .play(.skipTo(index: index))
     }
 
-    // Expand the queue from the contextual URL
+    // Expand the queue from the contextual path
     do {
-      if let expanded = try await browserManager.expandQueueFromContextualUrl(url) {
+      if let expanded = try await browserManager.expandQueueFromContextualPath(path) {
         let (tracks, startIndex) = expanded
         let event = TrackLoadEvent(track: track, queue: tracks, startIndex: Double(startIndex))
         if await browserManager.awaitTrackLoadHandler(event: event) {

package/ios/Util/ArtworkImageFetcher.swift

@@ -1,4 +1,5 @@
 import Kingfisher
+import Network
 import NitroModules
 import os.log
 import UIKit
@@ -7,8 +8,15 @@ 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) async -> UIImage? {
+  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 }
 
     var options: KingfisherOptionsInfo = []
@@ -24,6 +32,21 @@ enum ArtworkImageFetcher {
     }
     if let svgScale {
       options.append(.processor(SVGProcessor(size: nil, scale: svgScale)))
+    } else if let downsampleTo {
+      // Downsample rasters at decode time. Any size hint passed upstream (the
+      // resolver's ImageContext) is advisory — a CDN can ignore it and return
+      // the original — so this is the only sizing that is guaranteed to
+      // happen. The processed image is cached under a size-qualified key;
+      // cacheOriginalImage keeps the untouched original in the disk cache so
+      // the same URL at another target size re-processes instead of
+      // re-downloading.
+      options.append(.processor(DownsamplingImageProcessor(size: downsampleTo.size)))
+      options.append(.scaleFactor(downsampleTo.scale))
+      options.append(.cacheOriginalImage)
+    }
+
+    if waitsForConnectivity {
+      options.append(.retryStrategy(ConnectivityRetry()))
     }
 
     do {
@@ -35,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,182 +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
-    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

@@ -11,13 +11,36 @@ final class NetworkMonitor: @unchecked Sendable {
   private let monitor: NWPathMonitor
   private let queue = DispatchQueue(label: "com.audiobrowser.networkmonitor")
 
-  /// Current network connectivity state. Must only be set on main thread.
-  private(set) var isOnline: Bool = false {
-    didSet {
-      if oldValue != isOnline {
-        logger.notice("Network status changed: \(oldValue) -> \(self.isOnline)")
-        onChanged?(isOnline)
-      }
+  /// Guards `_isOnline` only. Never held across `onChanged` — see `apply`.
+  private let lock = NSLock()
+  private var _isOnline = false
+
+  /// Current network connectivity state. Readable from any thread: the value is
+  /// lock-protected rather than confined, so callers on the JS thread (Nitro's
+  /// `getOnline`) don't have to block on a main-queue hop to read a Bool.
+  ///
+  /// The broadcast is main-confined even though the value isn't — `onChanged`
+  /// fans out to the JS bridge, a now-playing re-render and a player reload, so
+  /// it must not run under the lock (reentrancy) or off the main actor.
+  var isOnline: Bool {
+    lock.lock()
+    defer { lock.unlock() }
+    return _isOnline
+  }
+
+  /// Stores a new status and, if it actually changed, broadcasts on main —
+  /// outside the lock.
+  private func apply(_ newStatus: Bool) {
+    lock.lock()
+    let changed = _isOnline != newStatus
+    let oldValue = _isOnline
+    _isOnline = newStatus
+    lock.unlock()
+
+    guard changed else { return }
+    logger.notice("Network status changed: \(oldValue) -> \(newStatus)")
+    DispatchQueue.main.async { [weak self] in
+      self?.onChanged?(newStatus)
     }
   }
 
@@ -31,29 +54,23 @@ final class NetworkMonitor: @unchecked Sendable {
   init() {
     monitor = NWPathMonitor()
 
-    // Set up handler before starting
-    monitor.pathUpdateHandler = { [weak self] path in
-      let newStatus = path.status == .satisfied
-      DispatchQueue.main.async { [weak self] in
-        self?.isOnline = newStatus
-      }
-    }
-
-    // Start monitoring
-    monitor.start(queue: queue)
-
-    // Read initial state after starting (currentPath is now valid)
+    // Seed BEFORE `start`. `start` publishes `self` to the monitor queue, so any
+    // write after it races the handler's locked write — and would clobber a real
+    // 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 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
     logger.notice("NetworkMonitor initialized, initial isOnline=\(initialStatus)")
-    isOnline = initialStatus
-  }
+    _isOnline = initialStatus
 
-  // MARK: - Public Methods
+    monitor.pathUpdateHandler = { [weak self] path in
+      self?.apply(path.status == .satisfied)
+    }
 
-  /// Gets the current network connectivity state.
-  /// - Returns: true if device is online, false otherwise
-  func getOnline() -> Bool {
-    isOnline
+    monitor.start(queue: queue)
   }
 
   /// Stops monitoring and cleans up resources.

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