react-native-audio-browser 0.2.0-next.34 → 0.2.0-next.35

package/ios/CarPlay/CarPlaySession+PageLoader.swift

@@ -26,19 +26,18 @@ extension CarPlaySession {
         NavigationError(code: .timeout, message: "", statusCode: nil, statusCodeSuccess: nil), path: path, on: template,
       )
     }
-    // Cancelled as soon as the resolve settles: formatting its error is a JS round trip the
-    // timeout must not overwrite.
-    defer { watchdog.cancel() }
-
+    let outcome: Result<ResolvedTrack, Error>
     do {
-      let resolved: ResolvedTrack
-      do {
-        resolved = try await audioBrowser.browserManager.resolve(path, useCache: true)
-      } catch {
-        watchdog.cancel()
-        throw error
-      }
-      watchdog.cancel()
+      outcome = try await .success(audioBrowser.browserManager.resolve(path, useCache: true))
+    } catch {
+      outcome = .failure(error)
+    }
+    // As soon as the resolve settles: formatting its error is a JS round trip the timeout must
+    // not overwrite.
+    watchdog.cancel()
+
+    switch outcome {
+    case let .success(resolved):
       guard !Task.isCancelled else { return }
       // An assistant cell is content in itself, even with no rows; a page of empty sections is
       // empty (ADR 0001).
@@ -48,7 +47,7 @@ extension CarPlaySession {
       } else {
         await showNavigationError(.code(.emptyContent), path: path, on: template)
       }
-    } catch {
+    case let .failure(error):
       logger.error("Failed to load content for \(path): \(error.localizedDescription)")
       await showNavigationError(NavigationError.from(error), path: path, on: template)
     }

package/ios/CarPlay/CarPlaySession+Refresher.swift

@@ -23,21 +23,21 @@ extension CarPlaySession {
   /// invalidated (e.g. a locale change).
   func refreshAllDisplayedTemplates() async {
     let browserManager = audioBrowser.browserManager
-    let loads = displayedListTemplates().compactMap { template in
-      template.contentPath.map { path in
-        (template, Task<ResolvedTrack?, Never> { @MainActor [logger] in
-          do {
-            return try await browserManager.resolve(path, useCache: false)
-          } catch {
-            logger.error("invalidateAllContent: failed to refresh \(path): \(error.localizedDescription)")
-            return nil
-          }
-        })
+    let targets = displayedListTemplates().compactMap { template in template.contentPath.map { (template, $0) } }
+    let pages = await targets.map(\.1).concurrentMap { [logger] path -> ResolvedTrack? in
+      do {
+        return try await browserManager.resolve(path, useCache: false)
+      } catch {
+        if !(error is CancellationError || Task.isCancelled) {
+          logger.error("invalidateAllContent: failed to refresh \(path): \(error.localizedDescription)")
+        }
+        return nil
       }
     }
-    for load in loads {
-      guard let resolved = await load.1.value, !Task.isCancelled else { continue }
-      updateTemplate(load.0, with: resolved)
+    guard !Task.isCancelled else { return }
+    for ((template, _), page) in zip(targets, pages) {
+      guard let page else { continue }
+      updateTemplate(template, with: page)
     }
   }
 }

package/ios/CarPlay/CarPlaySession+TabBar.swift

@@ -39,9 +39,9 @@ extension CarPlaySession {
     // A tab bar with no tabs renders blank. A gate shows one full-screen page instead;
     // otherwise it is the empty-content error, like any other failure (ADR 0001).
     guard !tabs.isEmpty else {
-      if gated, let chrome = await audioBrowser.browseGate.decide(NativeGateRequest(reason: .browse, path: nil, search: nil)) {
+      if gated, let chrome = await browseGates(for: [nil])[0] {
         guard isCurrent(build) else { return }
-        audioBrowser.onGate(GateEvent(reason: .browse))
+        reportGates([chrome], reason: .browse)
         interfaceController.safeSetRoot(makeGatePage(chrome, path: nil, tab: nil), animated: true)
       } else {
         await showRootError(.code(.emptyContent), build: build)
@@ -49,11 +49,9 @@ extension CarPlaySession {
       return
     }
 
-    let chromes = gated ? await gates(for: tabs) : tabs.map { _ in nil }
+    let chromes = gated ? await browseGates(for: tabs.map(\.path)) : tabs.map { _ in nil }
     guard isCurrent(build) else { return }
-    for _ in chromes.compactMap(\.self) {
-      audioBrowser.onGate(GateEvent(reason: .browse))
-    }
+    reportGates(chromes, reason: .browse)
     let templates = zip(tabs, chromes).map { tab, chrome in
       chrome.map { makeGatePage($0, path: tab.path, tab: tab) } ?? makeTabTemplate(for: tab)
     }
@@ -123,24 +121,24 @@ extension CarPlaySession {
   /// request is allowed.
   func gate(_ reason: GateReason, path: String?, search: SearchParams? = nil) async -> Gate? {
     let chrome = await audioBrowser.browseGate.decide(NativeGateRequest(reason: reason, path: path, search: search))
-    if chrome != nil { audioBrowser.onGate(GateEvent(reason: reason)) }
+    reportGates([chrome], reason: reason)
     return chrome
   }
 
-  /// One decision per tab, made concurrently and returned in tab order. Reports nothing: the
-  /// caller fires `onGate` once it knows its build is still current.
-  private func gates(for tabs: [Track]) async -> [Gate?] {
+  /// One browse decision per path, made concurrently and returned in path order. Reports
+  /// nothing: the caller reports once it knows its build is still current.
+  private func browseGates(for paths: [String?]) async -> [Gate?] {
     let browseGate = audioBrowser.browseGate
-    let decisions = tabs.map { tab in
-      Task<Gate?, Never> { @MainActor in
-        await browseGate.decide(NativeGateRequest(reason: .browse, path: tab.path, search: nil))
-      }
+    return await paths.concurrentMap { path in
+      await browseGate.decide(NativeGateRequest(reason: .browse, path: path, search: nil))
     }
-    var chromes: [Gate?] = []
-    for decision in decisions {
-      await chromes.append(decision.value)
+  }
+
+  /// Fires `onGate` once for each request the gate gated.
+  private func reportGates(_ chromes: [Gate?], reason: GateReason) {
+    for _ in chromes.compactMap(\.self) {
+      audioBrowser.onGate(GateEvent(reason: reason))
     }
-    return chromes
   }
 
   /// A tab's content shell, which loads when it first appears.
@@ -168,15 +166,16 @@ extension CarPlaySession {
   func applyTabBarEntry(to template: CPTemplate, for track: Track) {
     template.tabTitle = track.title
     if let artwork = track.artwork?.url, SFSymbolRenderer.isSFSymbol(artwork) {
+      // A plain symbol: CarPlay tints the tab image itself.
       let (symbolName, _, _) = SFSymbolRenderer.parseArtwork(artwork)
-      if let image = imageLoader.sfSymbolImage(symbolName) {
+      if let image = UIImage(systemName: symbolName) {
         template.tabImage = image
       }
     } else if track.artwork != nil || track.artworkSource != nil {
-      imageLoader.loadArtwork(for: track, size: CGSize(width: 24, height: 24)) { [weak template] image in
-        Task { @MainActor in
-          if let image { template?.tabImage = image }
-        }
+      spawn { [weak template] session in
+        let image = await session.imageLoader.artwork(for: track, size: CGSize(width: 24, height: 24))
+        guard !Task.isCancelled, let image else { return }
+        template?.tabImage = image
       }
     } else {
       // A restamp must not leave an old icon on a now title-only tab.

package/ios/CarPlay/CarPlaySession.swift

@@ -15,7 +15,14 @@ final class CarPlaySession {
   var player: Player? { audioBrowser.player }
   let trackSelector: TrackSelector
   let imageLoader: CarPlayImageLoader
-  let listItemFactory: CarPlayListItemFactory
+  private(set) lazy var listItemFactory = CarPlayListItemFactory(
+    imageLoader: imageLoader,
+    playingIndicatorLocation: playingIndicatorLocation,
+    isActiveTrack: { [weak self] identity in identity != nil && self?.player?.currentTrack?.identity == identity },
+    spawn: { [weak self] work in self?.spawn { _ in await work() } },
+    onItemSelected: { [weak self] track, completion in self?.select(track, completion: completion) },
+    onNavigate: { [weak self] path, title in self?.spawn { await $0.navigate(to: path, title: title) } },
+  )
   private(set) var nowPlaying: CarPlayNowPlayingManager!
 
   private var subscriptions: [Subscription] = []
@@ -56,12 +63,6 @@ final class CarPlaySession {
       carTraitCollection: interfaceController.carTraitCollection,
       browserManager: audioBrowser.browserManager,
     )
-    listItemFactory = CarPlayListItemFactory(
-      isActiveTrack: { [weak audioBrowser] identity in
-        identity != nil && audioBrowser?.player?.currentTrack?.identity == identity
-      },
-    )
-    listItemFactory.imageLoader = imageLoader
     nowPlaying = CarPlayNowPlayingManager(
       interfaceController: interfaceController,
       audioBrowser: audioBrowser,
@@ -70,9 +71,6 @@ final class CarPlaySession {
       },
       navigate: { [weak self] path, title in self?.spawn { await $0.navigate(to: path, title: title) } },
     )
-    listItemFactory.onItemSelected = { [weak self] track, completion in self?.select(track, completion: completion) }
-    listItemFactory.onNavigate = { [weak self] path, title in self?.spawn { await $0.navigate(to: path, title: title) } }
-    listItemFactory.playingIndicatorLocation = playingIndicatorLocation
   }
 
   func start() {

package/ios/CarPlay/IntentHandlers.swift

@@ -0,0 +1,96 @@
+import Foundation
+import Intents
+import os.log
+
+/// The library's Siri handlers, vended to the host app through `RNABAudioBrowser.handlerForIntent:`.
+@objc(RNABIntentHandlers)
+public final class IntentHandlers: NSObject {
+  /// A handler for `INPlayMediaIntent`, `INUpdateMediaAffinityIntent` and `INAddMediaIntent`;
+  /// nil for any other intent.
+  @objc(handlerForIntent:)
+  public static func handler(for intent: INIntent) -> Any? {
+    switch intent {
+    case is INPlayMediaIntent: MediaIntentHandler()
+    case is INUpdateMediaAffinityIntent, is INAddMediaIntent: FavoriteIntentHandler()
+    default: nil
+    }
+  }
+}
+
+/// "Add this to my favorites" and "I like / don't like this": sets the favorite state of the
+/// playing track, through the same path as the CarPlay favorite button. A named item that is
+/// not playing is out of scope.
+final class FavoriteIntentHandler: NSObject, INAddMediaIntentHandling, INUpdateMediaAffinityIntentHandling {
+  private static let logger = Logger(subsystem: "com.audiobrowser", category: "FavoriteIntentHandler")
+
+  func handle(intent _: INAddMediaIntent, completion: @escaping @Sendable (INAddMediaIntentResponse) -> Void) {
+    Self.logger.info("Add media — favorite current track")
+    Task { @MainActor in
+      let applied = Self.favoriteCurrentTrack(true)
+      completion(INAddMediaIntentResponse(code: applied ? .success : .failure, userActivity: nil))
+    }
+  }
+
+  func handle(
+    intent: INUpdateMediaAffinityIntent,
+    completion: @escaping @Sendable (INUpdateMediaAffinityIntentResponse) -> Void,
+  ) {
+    let affinity = intent.affinityType
+    Self.logger.info("Update media affinity — type=\(affinity.rawValue)")
+    Task { @MainActor in
+      let applied = switch affinity {
+      case .like: Self.favoriteCurrentTrack(true)
+      case .dislike: Self.favoriteCurrentTrack(false)
+      default: false
+      }
+      completion(INUpdateMediaAffinityIntentResponse(code: applied ? .success : .failure, userActivity: nil))
+    }
+  }
+
+  // Siri fails an intent whose handler has no resolution method. They are optional @objc
+  // requirements, so each is pinned to the selector SiriKit calls. The handlers act on the
+  // playing track, so the spoken item passes through.
+
+  @objc(resolveMediaItemsForAddMedia:withCompletion:)
+  func resolveMediaItems(
+    for intent: INAddMediaIntent,
+    with completion: @escaping ([INAddMediaMediaItemResolutionResult]) -> Void,
+  ) {
+    completion([.success(with: Self.spokenItem(intent.mediaSearch))])
+  }
+
+  /// One flat favorites collection: always the user's library.
+  @objc(resolveMediaDestinationForAddMedia:withCompletion:)
+  func resolveMediaDestination(
+    for _: INAddMediaIntent,
+    with completion: @escaping (INAddMediaMediaDestinationResolutionResult) -> Void,
+  ) {
+    completion(.success(with: INMediaDestination.library))
+  }
+
+  @objc(resolveMediaItemsForUpdateMediaAffinity:withCompletion:)
+  func resolveMediaItems(
+    for intent: INUpdateMediaAffinityIntent,
+    with completion: @escaping ([INUpdateMediaAffinityMediaItemResolutionResult]) -> Void,
+  ) {
+    completion([.success(with: Self.spokenItem(intent.mediaSearch))])
+  }
+
+  private static func spokenItem(_ search: INMediaSearch?) -> INMediaItem {
+    let name = search?.mediaName ?? ""
+    return INMediaItem(identifier: name, title: name, type: .unknown, artwork: nil)
+  }
+
+  /// False when nothing is playing, the playing track has no identity to favorite, or the
+  /// change throws.
+  @MainActor
+  private static func favoriteCurrentTrack(_ favorited: Bool) -> Bool {
+    guard let browser = HybridAudioBrowser.shared else { return false }
+    do {
+      return try browser.favoriteActiveTrack(favorited)
+    } catch {
+      logger.error("favoriteCurrentTrack(\(favorited)) failed: \(error.localizedDescription)")
+      return false
+    }
+  }
+}

package/ios/CarPlay/MediaIntentCriteria.swift

@@ -3,7 +3,7 @@ import Foundation
 /// Normalized "what did the user ask to play", derived from a media intent.
 /// Deliberately free of `Intents` types so the core (`HybridAudioBrowser`)
 /// never imports the Intents framework — the mapping lives in the
-/// `Intents`-aware `RNABMediaIntentHandler`.
+/// `Intents`-aware `MediaIntentHandler`.
 public struct MediaIntentCriteria: Sendable {
   /// Media-reference axis (mirrors `INMediaReference`). `currentlyPlaying`
   /// routes to native resume and never reaches the consumer; `my` routes to
@@ -12,19 +12,16 @@ public struct MediaIntentCriteria: Sendable {
 
   let query: String
   let reference: Reference
-  let hasGenres: Bool
   let hasMediaType: Bool
-  /// True when `query` is effectively the host app's own name. Siri turns
-  /// "Play «app»" into a search for a word in the app name — e.g. "Play Radio
-  /// Garden" arrives as mediaName "Garden" (+ radio mediaType). That's an
-  /// app-open/resume, not a station search.
+  /// True when `query` is effectively the host app's own name. Siri turns "Play «App Name»"
+  /// into a search for a word of it ("Name", with a radio media type): an app-open or resume,
+  /// not a search.
   let matchesAppName: Bool
 
-  // Structured search payload, mirroring the shared `SearchParams`. Plain
-  // Sendable strings so this type stays in the unit-testable target; the Nitro
-  // `SearchParams` is assembled in the funnel.
-  /// The container-vertical `SearchMode` name, or nil. Comes ONLY from the
-  /// intent's media type — never derived from which filter field is set.
+  // Structured search payload, mirroring `SearchParams` in plain strings so this type stays in
+  // the SwiftPM target; the funnel builds the Nitro `SearchParams`.
+  /// The container-vertical `SearchMode` name, or nil. Comes only from the intent's media type,
+  /// never from which filter field is set.
   let searchMode: String?
   let genre: String?
   let artist: String?
@@ -32,30 +29,40 @@ public struct MediaIntentCriteria: Sendable {
   let title: String?
   let playlist: String?
 
+  /// Builds criteria from the raw fields of a media-search intent.
+  ///
+  /// `mediaTypeMode` is the `SearchMode` string for the intent's container vertical ("station",
+  /// "podcast", "song", …), or nil for a filter-only or unclassified type.
   init(
-    query: String,
+    mediaName: String?,
+    genreNames: [String],
+    artistName: String?,
+    albumName: String?,
+    mediaTypeMode: String?,
     reference: Reference,
-    hasGenres: Bool,
     hasMediaType: Bool,
-    matchesAppName: Bool,
-    searchMode: String? = nil,
-    genre: String? = nil,
-    artist: String? = nil,
-    album: String? = nil,
-    title: String? = nil,
-    playlist: String? = nil,
+    appName: String?,
   ) {
-    self.query = query
+    let name = (mediaName ?? "").trimmingCharacters(in: .whitespacesAndNewlines)
+    let trimmedNonEmpty: (String?) -> String? = {
+      let t = ($0 ?? "").trimmingCharacters(in: .whitespacesAndNewlines)
+      return t.isEmpty ? nil : t
+    }
+
+    genre = genreNames.isEmpty ? nil : genreNames.joined(separator: " ")
+    artist = trimmedNonEmpty(artistName)
+    album = trimmedNonEmpty(albumName)
+    // song/playlist carry their spoken name into a dedicated field.
+    title = mediaTypeMode == "song" ? (name.isEmpty ? nil : name) : nil
+    playlist = mediaTypeMode == "playlist" ? (name.isEmpty ? nil : name) : nil
+
+    // Always populated, so search works before the API honours `mode`: the spoken name, else a
+    // structured value.
+    query = name.isEmpty ? (genre ?? artist ?? album ?? title ?? playlist ?? "") : name
     self.reference = reference
-    self.hasGenres = hasGenres
     self.hasMediaType = hasMediaType
-    self.matchesAppName = matchesAppName
-    self.searchMode = searchMode
-    self.genre = genre
-    self.artist = artist
-    self.album = album
-    self.title = title
-    self.playlist = playlist
+    matchesAppName = Self.queryMatchesAppName(query, appName: appName)
+    searchMode = mediaTypeMode
   }
 
   /// Resume vs search, by reference:
@@ -69,61 +76,12 @@ public struct MediaIntentCriteria: Sendable {
     case .unknown:
       let q = query.trimmingCharacters(in: .whitespacesAndNewlines)
       // "Play «app»": no search term and no other filter → resume.
-      if q.isEmpty { return !hasGenres && !hasMediaType }
+      if q.isEmpty { return genre == nil && !hasMediaType }
       // "Play «app-name»": resume — unless a real filter signals a search.
-      return matchesAppName && !hasGenres
+      return matchesAppName && genre == nil
     }
   }
 
-  /// Builds criteria from the raw fields of a media-search intent. Pure (no
-  /// `Intents`/`Bundle` dependency) so the whole Siri-phrase → search decision
-  /// is unit-testable.
-  ///
-  /// `mediaTypeMode` is the already-collapsed `SearchMode` string for the
-  /// intent's container vertical (e.g. "station"/"podcast"/"song"), or nil for
-  /// a filter-only / unclassified type. `reference` is the mapped axis.
-  static func from(
-    mediaName: String?,
-    genreNames: [String],
-    artistName: String?,
-    albumName: String?,
-    mediaTypeMode: String?,
-    reference: Reference,
-    hasMediaType: Bool,
-    appName: String?,
-  ) -> MediaIntentCriteria {
-    let name = (mediaName ?? "").trimmingCharacters(in: .whitespacesAndNewlines)
-    let trimmedNonEmpty: (String?) -> String? = {
-      let t = ($0 ?? "").trimmingCharacters(in: .whitespacesAndNewlines)
-      return t.isEmpty ? nil : t
-    }
-
-    let genre = genreNames.isEmpty ? nil : genreNames.joined(separator: " ")
-    let artist = trimmedNonEmpty(artistName)
-    let album = trimmedNonEmpty(albumName)
-    // song/playlist carry their spoken name into a dedicated field.
-    let title = mediaTypeMode == "song" ? (name.isEmpty ? nil : name) : nil
-    let playlist = mediaTypeMode == "playlist" ? (name.isEmpty ? nil : name) : nil
-
-    // `query` is always populated so search works even before the API honours
-    // `mode`: prefer the spoken name, else fall back to a structured value.
-    let query = name.isEmpty ? (genre ?? artist ?? album ?? title ?? playlist ?? "") : name
-
-    return MediaIntentCriteria(
-      query: query,
-      reference: reference,
-      hasGenres: !genreNames.isEmpty,
-      hasMediaType: hasMediaType,
-      matchesAppName: queryMatchesAppName(query, appName: appName),
-      searchMode: mediaTypeMode, // mode is the vertical, verbatim — no derivation
-      genre: genre,
-      artist: artist,
-      album: album,
-      title: title,
-      playlist: playlist,
-    )
-  }
-
   /// Whether `query` is effectively the host app's own name. Case- and
   /// diacritic-insensitive.
   ///

package/ios/CarPlay/{RNABMediaIntentHandler.swift → MediaIntentHandler.swift}

@@ -2,18 +2,15 @@ import Foundation
 import Intents
 import os.log
 
-/// In-app INPlayMediaIntent handler (Siri / CarPlay voice). Internal so Intents
-/// types stay out of the generated header; exposed to the ObjC runtime via
-/// `@objc(RNABMediaIntentHandler)` and vended from `RNABAudioBrowser.handlerForIntent(_:)`.
-@objc(RNABMediaIntentHandler)
-class RNABMediaIntentHandler: NSObject, INPlayMediaIntentHandling {
+/// Siri's play-media intent, from the phone or CarPlay voice: plays through `MediaIntentPlayback`.
+final class MediaIntentHandler: NSObject, INPlayMediaIntentHandling {
   private static let logger = Logger(subsystem: "com.audiobrowser", category: "MediaIntentHandler")
 
   // MARK: - INPlayMediaIntentHandling
 
   func handle(intent: INPlayMediaIntent, completion: @escaping @Sendable (INPlayMediaIntentResponse) -> Void) {
     let s = intent.mediaSearch
-    let criteria = MediaIntentCriteria.from(
+    let criteria = MediaIntentCriteria(
       mediaName: s?.mediaName,
       genreNames: s?.genreNames ?? [],
       artistName: s?.artistName,

package/ios/CarPlay/NowPlayingButtonRules.swift

@@ -0,0 +1,35 @@
+/// What CarPlay's Now Playing custom buttons show and do.
+enum NowPlayingButtonRules {
+  /// `CPNowPlayingTemplate` takes at most five custom buttons and does not say what happens to
+  /// more.
+  static let maximumButtonCount = 5
+
+  /// The configured buttons, first occurrence of each kept, capped at `maximumButtonCount`:
+  /// the configuration comes from JS, where duplicates and excess are representable.
+  static func buttons<Button: Equatable>(_ configured: [Button]) -> [Button] {
+    var buttons: [Button] = []
+    for button in configured where !buttons.contains(button) {
+      buttons.append(button)
+    }
+    return Array(buttons.prefix(maximumButtonCount))
+  }
+
+  /// The repeat button cycles off → track → queue → off.
+  static func repeatMode(after mode: RepeatMode) -> RepeatMode {
+    switch mode {
+    case .off: .track
+    case .track: .queue
+    case .queue: .off
+    }
+  }
+
+  /// The rate after `current` in `rates`: the next one, wrapping, when `current` is one of them;
+  /// else the first rate above it, else the first. Nil when there are no rates.
+  static func rate(after current: Double, in rates: [Double]) -> Double? {
+    guard !rates.isEmpty else { return nil }
+    if let index = rates.firstIndex(where: { (current - $0).magnitude < 0.01 }) {
+      return rates[(index + 1) % rates.count]
+    }
+    return rates.first { $0 > current } ?? rates[0]
+  }
+}

package/ios/CarPlay/RNABAudioBrowser.m

@@ -1,23 +1,15 @@
 #import "RNABAudioBrowser.h"
 
+#if __has_include(<AudioBrowser/AudioBrowser-Swift.h>)
+#import <AudioBrowser/AudioBrowser-Swift.h>
+#elif __has_include("AudioBrowser-Swift.h")
+#import "AudioBrowser-Swift.h"
+#endif
+
 @implementation RNABAudioBrowser
 
 + (nullable id)handlerForIntent:(INIntent *)intent {
-    // The handlers are internal Swift classes exposed to the ObjC runtime via
-    // @objc(...); each conforms to the matching INIntentHandling protocol.
-    NSString *handlerClassName = nil;
-    if ([intent isKindOfClass:[INPlayMediaIntent class]]) {
-        handlerClassName = @"RNABMediaIntentHandler";
-    } else if ([intent isKindOfClass:[INUpdateMediaAffinityIntent class]]) {
-        handlerClassName = @"RNABMediaAffinityHandler";
-    } else if ([intent isKindOfClass:[INAddMediaIntent class]]) {
-        handlerClassName = @"RNABMediaAddHandler";
-    }
-    if (!handlerClassName) {
-        return nil;
-    }
-    Class cls = NSClassFromString(handlerClassName);
-    return cls ? [[cls alloc] init] : nil;
+    return [RNABIntentHandlers handlerForIntent:intent];
 }
 
 @end

package/ios/Player/Player.swift

@@ -927,6 +927,25 @@ final class Player {
     }
   }
 
+  // MARK: - Now Playing Preview
+
+  /// Shows `track` on the now-playing surface before it is current, so a tapped track shows at
+  /// once while its queue and media resolve.
+  func previewNowPlaying(_ track: Track) {
+    engine.loadNowPlayingMetadata(for: track)
+  }
+
+  /// Puts the current track back over a preview that will not play, or clears the surface when
+  /// nothing is current.
+  func endNowPlayingPreview() {
+    guard let currentTrack else {
+      engine.clearNowPlaying()
+      return
+    }
+    engine.loadNowPlayingMetadata(for: currentTrack)
+    engine.renderNowPlaying()
+  }
+
   // MARK: - Progress Updates
 
   func setProgressUpdateInterval(_ interval: TimeInterval?) {

package/ios/Tests/ConcurrentMapTests.swift

@@ -0,0 +1,42 @@
+@testable import AudioBrowserTestable
+import Testing
+
+@Suite("concurrentMap")
+struct ConcurrentMapTests {
+  @Test @MainActor
+  func keepsElementOrder_whenLaterElementsFinishFirst() async {
+    let results = await [30, 20, 10].concurrentMap { delayMs in
+      try? await Task.sleep(for: .milliseconds(delayMs))
+      return delayMs * 2
+    }
+    #expect(results == [60, 40, 20])
+  }
+
+  @Test @MainActor
+  func keepsNilResults_inPlace() async {
+    let results = await ["a", "", "c"].concurrentMap { $0.isEmpty ? nil : $0 }
+    #expect(results == ["a", nil, "c"])
+  }
+
+  @Test @MainActor
+  func empty_returnsEmpty() async {
+    let results = await [Int]().concurrentMap { $0 }
+    #expect(results.isEmpty)
+  }
+
+  @Test @MainActor
+  func cancellingTheCaller_cancelsEveryTransform() async {
+    let task = Task { @MainActor in
+      await [1, 2].concurrentMap { _ in
+        do {
+          try await Task.sleep(for: .seconds(10))
+          return false
+        } catch {
+          return Task.isCancelled
+        }
+      }
+    }
+    task.cancel()
+    #expect(await task.value == [true, true])
+  }
+}