@5stones/react-native-audio-browser 0.2.0 → 0.3.0

package/ios/CarPlay/CarPlayController.swift

@@ -17,6 +17,9 @@ import os.log
 @MainActor
 @objc(RNABCarPlayController)
 public final class RNABCarPlayController: NSObject {
+  // Force the linker to include RNABMediaIntentHandler so NSClassFromString can find it
+  @objc public static let mediaIntentHandlerClass: AnyClass = RNABMediaIntentHandler.self
+
   private let logger = Logger(subsystem: "com.audiobrowser", category: "CarPlayController")
 
   private let interfaceController: CPInterfaceController
@@ -229,12 +232,8 @@ public final class RNABCarPlayController: NSObject {
 
     let maxTabs = CPTabBarTemplate.maximumTabCount
 
-    // Reserve one slot for search if configured
-    let hasSearch = config.hasSearch
-    let maxContentTabs = hasSearch ? maxTabs - 1 : maxTabs
-
     // Create tab templates synchronously (empty shells) - don't block on content loading
-    let tabTemplates: [CPListTemplate] = tabs.prefix(maxContentTabs).map { tab in
+    let tabTemplates: [CPListTemplate] = tabs.prefix(maxTabs).map { tab in
       createTabTemplate(for: tab)
     }
 
@@ -269,9 +268,8 @@ public final class RNABCarPlayController: NSObject {
     // https://developer.apple.com/download/files/CarPlay-Developer-Guide.pdf
     template.tabImage = defaultTabImage()
 
-    // Support SF Symbols via "sf:" prefix (e.g., "sf:heart.fill")
-    if let artwork = track.artwork, artwork.hasPrefix("sf:") {
-      let symbolName = String(artwork.dropFirst(3))
+    if let artwork = track.artwork, SFSymbolRenderer.isSFSymbol(artwork) {
+      let (symbolName, _, _) = SFSymbolRenderer.parseArtwork(artwork)
       if let image = sfSymbolImage(symbolName) {
         template.tabImage = image
       }
@@ -299,9 +297,9 @@ public final class RNABCarPlayController: NSObject {
   ) -> CPListTemplate {
     let template = CPListTemplate(
       title: resolvedTrack.title,
-      sections: createSections(from: resolvedTrack),
+      sections: [],
     )
-
+    updateTemplate(template, with: resolvedTrack)
     template.userInfo = ["path": path] as [String: Any]
 
     return template
@@ -312,6 +310,29 @@ public final class RNABCarPlayController: NSObject {
     (template.userInfo as? [String: Any])?["path"] as? String
   }
 
+  /// Updates a template's sections and assistant cell from resolved content.
+  private func updateTemplate(_ template: CPListTemplate, with resolvedTrack: ResolvedTrack) {
+    let sections = createSections(from: resolvedTrack)
+    template.updateSections(sections)
+    configureAssistantCell(on: template, from: resolvedTrack)
+  }
+
+  /// Configures the assistant cell ("Ask Siri to Play Audio") on a template
+  /// based on the `carPlaySiriListButton` property of the resolved content.
+  private func configureAssistantCell(on template: CPListTemplate, from resolvedTrack: ResolvedTrack) {
+    guard #available(iOS 15.4, *) else { return }
+    guard let position = resolvedTrack.carPlaySiriListButton else {
+      template.assistantCellConfiguration = nil
+      return
+    }
+    let cellPosition: CPListItem.AssistantCellPosition = position == .top ? .top : .bottom
+    template.assistantCellConfiguration = CPAssistantCellConfiguration(
+      position: cellPosition,
+      visibility: .always,
+      assistantAction: .playMedia,
+    )
+  }
+
   private func createSections(from resolvedTrack: ResolvedTrack) -> [CPListSection] {
     guard let children = resolvedTrack.children else {
       return []
@@ -334,7 +355,12 @@ public final class RNABCarPlayController: NSObject {
     // Ungrouped items first
     if let ungrouped = groups[nil], !ungrouped.isEmpty {
       let availableSlots = maxTotalItems - totalItemCount
-      let items = ungrouped.prefix(availableSlots).map { createListItem(for: $0) }
+      let items: [CPListTemplateItem] = ungrouped.prefix(availableSlots).map { track in
+        if track.imageRow != nil {
+          return createImageRowItem(for: track)
+        }
+        return createListItem(for: track)
+      }
       if !items.isEmpty {
         sections.append(CPListSection(items: items))
         totalItemCount += items.count
@@ -348,7 +374,12 @@ public final class RNABCarPlayController: NSObject {
       guard groupTitle != nil else { continue }
 
       let availableSlots = maxTotalItems - totalItemCount
-      let items = tracks.prefix(availableSlots).map { createListItem(for: $0) }
+      let items: [CPListTemplateItem] = tracks.prefix(availableSlots).map { track in
+        if track.imageRow != nil {
+          return createImageRowItem(for: track)
+        }
+        return createListItem(for: track)
+      }
       if !items.isEmpty {
         sections.append(CPListSection(items: items, header: groupTitle, sectionIndexTitle: nil))
         totalItemCount += items.count
@@ -393,13 +424,7 @@ public final class RNABCarPlayController: NSObject {
     }
 
     // Load artwork with size context for proper CDN optimization
-    // Support SF Symbols via "sf:" prefix (e.g., "sf:heart.fill")
-    if let artwork = track.artwork, artwork.hasPrefix("sf:") {
-      let symbolName = String(artwork.dropFirst(3))
-      if let image = sfSymbolImageForListItem(symbolName) {
-        item.setImage(image)
-      }
-    } else if track.artwork != nil || track.artworkSource != nil {
+    if track.artwork != nil || track.artworkSource != nil {
       // Set empty placeholder to reserve space while loading
       item.setImage(placeholderImage)
       loadArtwork(for: track, size: CPListItem.maximumImageSize) { [weak item] image in
@@ -421,6 +446,111 @@ public final class RNABCarPlayController: NSObject {
     return item
   }
 
+  /// Creates a CPListImageRowItem for a track that has an imageRow.
+  /// Renders as a horizontal row of tappable artwork thumbnails with a header title.
+  private func createImageRowItem(for track: Track) -> CPListImageRowItem {
+    guard let imageRowItems = track.imageRow else {
+      fatalError("createImageRowItem called without imageRow")
+    }
+
+    // CPListImageRowItem requires images at init — start with placeholders
+    let maxImages = CPMaximumNumberOfGridImages
+    let visibleItems = Array(imageRowItems.prefix(maxImages))
+    let placeholders = visibleItems.map { _ in placeholderImage ?? UIImage() }
+    let titles = visibleItems.map(\.title)
+
+    // Use imageTitles variant on iOS 17.4+ to show titles below each thumbnail
+    let item = if #available(iOS 17.4, *) {
+      CPListImageRowItem(text: track.title, images: placeholders, imageTitles: titles)
+    } else {
+      CPListImageRowItem(text: track.title, images: placeholders)
+    }
+
+    // Store track info for identification
+    item.userInfo = [
+      "url": track.url as Any,
+      "src": track.src as Any,
+      "hasSrc": track.src != nil,
+      "hasUrl": track.url != nil,
+    ]
+
+    // Handler for row header tap → navigate to track.url if present
+    item.handler = { [weak self] _, completion in
+      self?.handleItemSelection(track: track, completion: completion)
+    }
+
+    // Handler for individual image taps
+    item.listImageRowHandler = { [weak self] _, index, completion in
+      guard let self, index < visibleItems.count else {
+        completion()
+        return
+      }
+      let tappedItem = visibleItems[index]
+      // Create a minimal Track to reuse handleItemSelection
+      let itemTrack = Track(
+        url: tappedItem.url,
+        src: nil,
+        artwork: tappedItem.artwork,
+        artworkSource: tappedItem.artworkSource,
+        artworkCarPlayTinted: nil,
+        title: tappedItem.title,
+        subtitle: nil,
+        artist: nil,
+        album: nil,
+        description: nil,
+        genre: nil,
+        duration: nil,
+        style: nil,
+        childrenStyle: nil,
+        favorited: nil,
+        groupTitle: nil,
+        live: nil,
+        imageRow: nil,
+      )
+      self.handleItemSelection(track: itemTrack, completion: completion)
+    }
+
+    // Load artwork for each visible image row item asynchronously
+    for (index, imageRowItem) in visibleItems.enumerated() {
+      guard imageRowItem.artwork != nil || imageRowItem.artworkSource != nil else { continue }
+
+      // Create a minimal Track for the artwork loader
+      let itemTrack = Track(
+        url: imageRowItem.url,
+        src: nil,
+        artwork: imageRowItem.artwork,
+        artworkSource: imageRowItem.artworkSource,
+        artworkCarPlayTinted: nil,
+        title: imageRowItem.title,
+        subtitle: nil,
+        artist: nil,
+        album: nil,
+        description: nil,
+        genre: nil,
+        duration: nil,
+        style: nil,
+        childrenStyle: nil,
+        favorited: nil,
+        groupTitle: nil,
+        live: nil,
+        imageRow: nil,
+      )
+
+      loadArtwork(for: itemTrack, size: CPListImageRowItem.maximumImageSize) { [weak item] image in
+        Task { @MainActor in
+          guard let item, let image else { return }
+          var images = item.gridImages
+          if index < images.count {
+            images[index] = image
+            item.update(images)
+          }
+        }
+      }
+    }
+
+    return item
+  }
+
   // MARK: - Content Loading
 
   @MainActor
@@ -429,8 +559,7 @@ public final class RNABCarPlayController: NSObject {
 
     do {
       let resolved = try await audioBrowser.browserManager.resolve(path, useCache: true)
-      let sections = createSections(from: resolved)
-      template.updateSections(sections)
+      updateTemplate(template, with: resolved)
     } catch {
       logger.error("Failed to load content for \(path): \(error.localizedDescription)")
     }
@@ -438,34 +567,11 @@ public final class RNABCarPlayController: NSObject {
 
   // MARK: - Selection Handling
 
-  /// Centralizes handleRemoteLoad interception for synchronous CarPlay selection paths.
-  /// If handleRemoteLoad is set, calls it (intercepted). Otherwise runs defaultBehavior.
-  /// Always fires onRemoteLoad, showNowPlaying, and completion afterward.
-  @discardableResult
-  private func handleLoad(
-    track: Track, queue: [Track], startIndex: Double,
-    audioBrowser: HybridAudioBrowser,
-    completion: @escaping () -> Void,
-    defaultBehavior: () -> Void
-  ) -> Bool {
-    let event = RemoteLoadEvent(track: track, queue: queue, startIndex: startIndex)
-    let handled: Bool
-    if let handler = audioBrowser.handleRemoteLoad {
-      handler(event)
-      handled = true
-    } else {
-      defaultBehavior()
-      handled = false
-    }
-    audioBrowser.onRemoteLoad(event)
-    showNowPlaying()
-    completion()
-    return handled
-  }
-
-  /// Centralizes handleRemoteLoad interception for async CarPlay selection paths (queue expansion).
-  /// If handleRemoteLoad is set, calls it (intercepted). Otherwise runs defaultBehavior.
-  /// Always fires onRemoteLoad, showNowPlaying, and completion afterward.
+  /// Centralizes handleTrackLoad interception for CarPlay selection paths.
+  /// If handleTrackLoad is set on config, awaits it (intercepted). Otherwise runs defaultBehavior.
+  /// Always fires showNowPlaying and completion afterward, even if the handler throws.
+  /// This is intentional: the completion handler must be called to dismiss the CarPlay list
+  /// item spinner, and transitioning to Now Playing avoids leaving the UI in a stuck state.
   @discardableResult
   private func handleLoadAsync(
     track: Track, queue: [Track], startIndex: Double,
@@ -473,18 +579,14 @@ public final class RNABCarPlayController: NSObject {
     completion: @escaping () -> Void,
     defaultBehavior: () async -> Void
   ) async -> Bool {
-    let event = RemoteLoadEvent(track: track, queue: queue, startIndex: startIndex)
-    let handled: Bool
-    if let handler = audioBrowser.handleRemoteLoad {
-      handler(event)
-      handled = true
-    } else {
-      await defaultBehavior()
-      handled = false
+    let event = TrackLoadEvent(track: track, queue: queue, startIndex: startIndex)
+    if await audioBrowser.browserManager.config.awaitTrackLoadHandler(event: event) {
+      await MainActor.run { self.showNowPlaying(); completion() }
+      return true
     }
-    audioBrowser.onRemoteLoad(event)
+    await defaultBehavior()
     await MainActor.run { self.showNowPlaying(); completion() }
-    return handled
+    return false
   }
 
   private func handleItemSelection(track: Track, completion: @escaping () -> Void) {
@@ -515,8 +617,10 @@ public final class RNABCarPlayController: NSObject {
          let index = player?.tracks.firstIndex(where: { $0.src == trackId })
       {
         let queue = player?.tracks ?? []
-        handleLoad(track: track, queue: queue, startIndex: Double(index), audioBrowser: audioBrowser, completion: completion) {
-          try? player?.skipTo(index, playWhenReady: true)
+        Task {
+          await handleLoadAsync(track: track, queue: queue, startIndex: Double(index), audioBrowser: audioBrowser, completion: completion) {
+            try? player?.skipTo(index, playWhenReady: true)
+          }
         }
         return
       }
@@ -881,8 +985,7 @@ public final class RNABCarPlayController: NSObject {
         else { continue }
 
         logger.info("Refreshing tab template for path: \(path)")
-        let sections = createSections(from: content)
-        listTemplate.updateSections(sections)
+        updateTemplate(listTemplate, with: content)
       }
     }
 
@@ -893,8 +996,7 @@ public final class RNABCarPlayController: NSObject {
        templatePath == path
     {
       logger.info("Refreshing top template for path: \(path)")
-      let sections = createSections(from: content)
-      topTemplate.updateSections(sections)
+      updateTemplate(topTemplate, with: content)
     }
   }
 
@@ -1026,18 +1128,31 @@ public final class RNABCarPlayController: NSObject {
     UIImage(systemName: symbolName)
   }
 
-  /// Creates an SF Symbol image for list items with light/dark mode support
-  private func sfSymbolImageForListItem(_ symbolName: String) -> UIImage? {
-    guard let symbol = UIImage(systemName: symbolName) else { return nil }
+  /// Renders an SF Symbol from an artwork string (e.g. "sf:heart.fill?bg=#000&fg=#fff").
+  private func sfSymbolImage(forArtwork artwork: String, canvasSize: CGSize) -> UIImage? {
+    let (symbolName, bg, fg) = SFSymbolRenderer.parseArtwork(artwork)
+    return sfSymbolImageForSize(symbolName, canvasSize: canvasSize, backgroundColor: bg, symbolColor: fg)
+  }
+
+  /// Creates an SF Symbol image rendered at the given canvas size.
+  /// When explicit colors are provided, uses them directly.
+  /// Otherwise falls back to automatic light/dark variants.
+  private func sfSymbolImageForSize(_ symbolName: String, canvasSize: CGSize, backgroundColor: UIColor? = nil, symbolColor: UIColor? = nil) -> UIImage? {
+    let scale = interfaceController.carTraitCollection.displayScale
+    let symbolPointSize = min(canvasSize.width, canvasSize.height) * 0.45
 
-    let size = symbol.size
-    let scale = symbol.scale
+    let config = UIImage.SymbolConfiguration(pointSize: symbolPointSize, weight: .medium)
+    guard let symbol = UIImage(systemName: symbolName, withConfiguration: config) else { return nil }
+
+    // Explicit colors: single image, no light/dark variants needed
+    if let symbolColor {
+      return renderSymbolInCanvas(symbol, tintColor: symbolColor, backgroundColor: backgroundColor, canvasSize: canvasSize, scale: scale)
+    }
 
-    // Create both light and dark bitmap variants
-    let lightImage = renderSymbolToBitmap(symbol, tintColor: .black, size: size, scale: scale)
-    let darkImage = renderSymbolToBitmap(symbol, tintColor: .white, size: size, scale: scale)
+    // Auto light/dark variants
+    let lightImage = renderSymbolInCanvas(symbol, tintColor: .black, backgroundColor: nil, canvasSize: canvasSize, scale: scale)
+    let darkImage = renderSymbolInCanvas(symbol, tintColor: .white, backgroundColor: nil, canvasSize: canvasSize, scale: scale)
 
-    // Combine with UIImageAsset for automatic light/dark switching
     let asset = UIImageAsset()
     asset.register(lightImage, with: UITraitCollection(userInterfaceStyle: .light))
     asset.register(darkImage, with: UITraitCollection(userInterfaceStyle: .dark))
@@ -1045,18 +1160,27 @@ public final class RNABCarPlayController: NSObject {
     return asset.image(with: interfaceController.carTraitCollection)
   }
 
-  /// Renders an SF Symbol to a bitmap with the specified tint color
-  private nonisolated func renderSymbolToBitmap(_ symbol: UIImage, tintColor: UIColor, size: CGSize, scale: CGFloat) -> UIImage {
-    UIGraphicsBeginImageContextWithOptions(size, false, scale)
-    defer { UIGraphicsEndImageContext() }
+  /// Renders an SF Symbol centered in a canvas with a background fill.
+  /// When `backgroundColor` is nil, derives a default from the tint color (light/dark).
+  private nonisolated func renderSymbolInCanvas(_ symbol: UIImage, tintColor: UIColor, backgroundColor: UIColor?, canvasSize: CGSize, scale: CGFloat) -> UIImage {
+    let renderer = UIGraphicsImageRenderer(size: canvasSize, format: {
+      let fmt = UIGraphicsImageRendererFormat()
+      fmt.scale = scale
+      return fmt
+    }())
 
-    tintColor.set()
-    symbol.withRenderingMode(.alwaysTemplate).draw(in: CGRect(origin: .zero, size: size))
+    return renderer.image { _ in
+      let bgColor = backgroundColor ?? (tintColor == .white ? UIColor(white: 0.15, alpha: 1) : UIColor(white: 0.92, alpha: 1))
+      bgColor.setFill()
+      UIRectFill(CGRect(origin: .zero, size: canvasSize))
 
-    guard let rendered = UIGraphicsGetImageFromCurrentImageContext() else {
-      return symbol // Fallback to original if rendering fails
-    }
-    return rendered.withRenderingMode(.alwaysOriginal)
+      let symbolSize = symbol.size
+      let x = (canvasSize.width - symbolSize.width) / 2
+      let y = (canvasSize.height - symbolSize.height) / 2
+
+      tintColor.set()
+      symbol.withRenderingMode(.alwaysTemplate).draw(in: CGRect(x: x, y: y, width: symbolSize.width, height: symbolSize.height))
+    }.withRenderingMode(.alwaysOriginal)
   }
 
   private func defaultTabImage() -> UIImage? {
@@ -1078,9 +1202,14 @@ public final class RNABCarPlayController: NSObject {
   ///   - size: The target size in points (will be multiplied by CarPlay display scale)
   ///   - completion: Called with the loaded image, or nil on failure
   private func loadArtwork(for track: Track, size: CGSize, completion: @escaping @Sendable (UIImage?) -> Void) {
+    if let artwork = track.artwork, SFSymbolRenderer.isSFSymbol(artwork) {
+      completion(sfSymbolImage(forArtwork: artwork, canvasSize: size))
+      return
+    }
+
     guard let browserManager = audioBrowser?.browserManager else {
       // Fall back to direct URL loading
-      loadArtworkDirect(track: track, completion: completion)
+      loadArtworkDirect(track: track, size: size, completion: completion)
       return
     }
 
@@ -1099,16 +1228,9 @@ public final class RNABCarPlayController: NSObject {
 
       await MainActor.run {
         if let imageSource {
-          // Check for SF Symbol URI (e.g., "sf:heart.fill")
-          if imageSource.uri.hasPrefix("sf:") {
-            let symbolName = String(imageSource.uri.dropFirst(3))
-            completion(self.sfSymbolImageForListItem(symbolName))
-            return
-          }
-
           // Parse URL - skip if invalid
           guard let url = URL(string: imageSource.uri) else {
-            self.loadArtworkDirect(track: track, completion: completion)
+            self.loadArtworkDirect(track: track, size: size, completion: completion)
             return
           }
 
@@ -1153,23 +1275,21 @@ public final class RNABCarPlayController: NSObject {
           }
         } else {
           // No resolved URL - try direct loading as fallback
-          self.loadArtworkDirect(track: track, completion: completion)
+          self.loadArtworkDirect(track: track, size: size, completion: completion)
         }
       }
     }
   }
 
   /// Loads artwork directly from track's artwork URL without transform.
-  private func loadArtworkDirect(track: Track, completion: @escaping @Sendable (UIImage?) -> Void) {
+  private func loadArtworkDirect(track: Track, size: CGSize, completion: @escaping @Sendable (UIImage?) -> Void) {
     guard let artworkUrl = track.artwork ?? track.artworkSource?.uri else {
       completion(nil)
       return
     }
 
-    // Check for SF Symbol URI (e.g., "sf:heart.fill")
-    if artworkUrl.hasPrefix("sf:") {
-      let symbolName = String(artworkUrl.dropFirst(3))
-      completion(sfSymbolImageForListItem(symbolName))
+    if SFSymbolRenderer.isSFSymbol(artworkUrl) {
+      completion(sfSymbolImage(forArtwork: artworkUrl, canvasSize: size))
       return
     }
 

package/ios/CarPlay/RNABAudioBrowser.h

@@ -0,0 +1,23 @@
+#import <Foundation/Foundation.h>
+#import <Intents/Intents.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+/// Public entry point for AudioBrowser library functionality that host apps
+/// need to call from their AppDelegate or other Swift/ObjC code.
+///
+/// Usage (add to your bridging header: #import <AudioBrowser/RNABAudioBrowser.h>):
+/// @code
+/// func application(_ application: UIApplication, handle intent: INIntent, completionHandler: @escaping (INIntentResponse) -> Void) {
+///     RNABAudioBrowser.handleMediaIntent(intent, completionHandler: completionHandler)
+/// }
+/// @endcode
+@interface RNABAudioBrowser : NSObject
+
+/// Handle an INPlayMediaIntent forwarded from an Intents Extension via .handleInApp.
+/// Searches using the configured browser search route, queues results, and starts playback.
++ (void)handleMediaIntent:(INIntent *)intent completionHandler:(void (^)(INIntentResponse *))completionHandler;
+
+@end
+
+NS_ASSUME_NONNULL_END

package/ios/CarPlay/RNABAudioBrowser.m

@@ -0,0 +1,22 @@
+#import "RNABAudioBrowser.h"
+
+@implementation RNABAudioBrowser
+
++ (void)handleMediaIntent:(INIntent *)intent completionHandler:(void (^)(INIntentResponse *))completionHandler {
+    Class cls = NSClassFromString(@"RNABMediaIntentHandler");
+    SEL sel = NSSelectorFromString(@"handleMediaIntent:completionHandler:");
+    if (cls && [cls respondsToSelector:sel]) {
+#pragma clang diagnostic push
+#pragma clang diagnostic ignored "-Warc-performSelector-leaks"
+        // RNABMediaIntentHandler.handleMediaIntent(_:completionHandler:) is a static @objc method
+        // that handles INPlayMediaIntent search and playback.
+        typedef void (*HandleFn)(id, SEL, INIntent *, void (^)(INIntentResponse *));
+        HandleFn fn = (HandleFn)[cls methodForSelector:sel];
+        fn(cls, sel, intent, completionHandler);
+#pragma clang diagnostic pop
+    } else {
+        completionHandler([[INPlayMediaIntentResponse alloc] initWithCode:INPlayMediaIntentResponseCodeFailureRequiringAppLaunch userActivity:nil]);
+    }
+}
+
+@end

package/ios/CarPlay/RNABMediaIntentHandler.swift

@@ -0,0 +1,60 @@
+import Foundation
+import Intents
+import os.log
+
+/// Handles INPlayMediaIntent for Siri voice search (e.g. from CarPlay).
+///
+/// The class is internal (not public) to avoid exposing Intents types in the
+/// generated AudioBrowser-Swift.h header, but is registered with the ObjC
+/// runtime via `@objc(RNABMediaIntentHandler)` for NSClassFromString lookup.
+///
+/// Host apps call the static method from `application(_:handle:completionHandler:)`:
+/// ```swift
+/// @objc private protocol RNABMediaIntentHandling {
+///   static func handleMediaIntent(_ intent: INIntent, completionHandler: @escaping (INIntentResponse) -> Void)
+/// }
+///
+/// func application(_ application: UIApplication, handle intent: INIntent, completionHandler: @escaping (INIntentResponse) -> Void) {
+///   (NSClassFromString("RNABMediaIntentHandler") as? RNABMediaIntentHandling.Type)?
+///     .handleMediaIntent(intent, completionHandler: completionHandler)
+/// }
+/// ```
+@objc(RNABMediaIntentHandler)
+class RNABMediaIntentHandler: NSObject, INPlayMediaIntentHandling {
+  private static let logger = Logger(subsystem: "com.audiobrowser", category: "MediaIntentHandler")
+
+  // MARK: - Static Entry Point
+
+  /// Convenience entry point for host apps. Handles the full INPlayMediaIntent flow:
+  /// type checking, search, queue, and playback.
+  @objc static func handleMediaIntent(_ intent: INIntent, completionHandler: @escaping @Sendable (INIntentResponse) -> Void) {
+    guard let playIntent = intent as? INPlayMediaIntent else {
+      completionHandler(INPlayMediaIntentResponse(code: .failure, userActivity: nil))
+      return
+    }
+    let handler = RNABMediaIntentHandler()
+    handler.handle(intent: playIntent) { response in
+      completionHandler(response)
+    }
+  }
+
+  // MARK: - INPlayMediaIntentHandling
+
+  func handle(intent: INPlayMediaIntent, completion: @escaping @Sendable (INPlayMediaIntentResponse) -> Void) {
+    let searchTerm = intent.mediaSearch?.mediaName ?? ""
+    Self.logger.info("Handling play media intent with search term: \(searchTerm)")
+
+    guard let browser = HybridAudioBrowser.shared else {
+      Self.logger.error("HybridAudioBrowser.shared is nil — app may not be initialized yet")
+      completion(INPlayMediaIntentResponse(code: .failureRequiringAppLaunch, userActivity: nil))
+      return
+    }
+
+    browser.handlePlayMediaIntent(searchTerm: searchTerm) { success in
+      completion(INPlayMediaIntentResponse(
+        code: success ? .success : .failure,
+        userActivity: nil,
+      ))
+    }
+  }
+}

package/ios/Extension/ChapterMetadata+AVFoundation.swift

@@ -30,7 +30,7 @@ extension ChapterMetadata {
         startTime: startTime,
         endTime: endTime,
         title: title,
-        url: url
+        url: url,
       )
     }
   }

package/ios/Extension/CxxVectorConformances.swift

@@ -0,0 +1,20 @@
+import NitroModules
+
+// Workaround for a Nitro Modules upstream issue.
+//
+// Nitrogen-generated Swift code (e.g. Func_void_std__vector_Track_.swift) calls
+// .map() on std::vector<T>, which requires CxxRandomAccessCollection conformance.
+// Swift's C++ interop synthesizes this conformance lazily, but in incremental
+// builds the conformance may not be available in the compilation batch that needs
+// it, causing: "Value of type 'std::vector<T>' has no member 'map'"
+//
+// This should be fixed upstream in Nitro Modules. Until then, explicitly
+// declaring the conformance here guarantees it's available regardless of
+// compilation order.
+//
+// To identify which types need conformance, search the generated Swift files for
+// .map() calls on bridge.std__vector_<T>_ types:
+//
+//   grep -r '\.map(' nitrogen/generated/ios/swift/ | grep std__vector
+
+extension margelo.nitro.audiobrowser.bridge.swift.std__vector_Track_: @retroactive CxxRandomAccessCollection {}

package/ios/Extension/TimedMetadata+AVFoundation.swift

@@ -36,7 +36,7 @@ extension TimedMetadata {
       artist: nil,
       album: nil,
       date: nil,
-      genre: nil
+      genre: nil,
     )
   }
 
@@ -57,9 +57,9 @@ extension TimedMetadata {
       case .id3MetadataAlbumTitle, .id3MetadataOriginalAlbumTitle:
         album = item.stringValue
       case .id3MetadataRecordingTime:
-        date = item.stringValue  // TDRC takes precedence (ID3v2.4, more precise)
+        date = item.stringValue // TDRC takes precedence (ID3v2.4, more precise)
       case .id3MetadataYear:
-        date = date ?? item.stringValue  // TYER only if TDRC not found (ID3v2.3)
+        date = date ?? item.stringValue // TYER only if TDRC not found (ID3v2.3)
       case .id3MetadataContentType:
         genre = item.stringValue
       default:
@@ -73,7 +73,7 @@ extension TimedMetadata {
       artist: artist,
       album: album,
       date: date,
-      genre: genre
+      genre: genre,
     )
   }
 
@@ -120,7 +120,7 @@ extension TimedMetadata {
       artist: artist,
       album: album,
       date: date,
-      genre: genre
+      genre: genre,
     )
   }
 }