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

package/ios/Browser/JsonModels.swift

@@ -4,6 +4,23 @@ import NitroModules
 /// JSON serializable models for parsing API responses.
 /// These will be converted to Nitro types after parsing.
 
+/// JSON model for image row items (horizontal thumbnail row).
+struct JsonImageRowItem: Codable {
+  let url: String?
+  let artwork: String?
+  let title: String
+
+  init(
+    url: String? = nil,
+    artwork: String? = nil,
+    title: String,
+  ) {
+    self.url = url
+    self.artwork = artwork
+    self.title = title
+  }
+}
+
 /// JSON model for resolved track (container with children).
 struct JsonResolvedTrack: Codable {
   let url: String
@@ -21,6 +38,7 @@ struct JsonResolvedTrack: Codable {
   let childrenStyle: String?
   let groupTitle: String?
   let live: Bool?
+  let carPlaySiriListButton: String?
 
   init(
     url: String,
@@ -38,6 +56,7 @@ struct JsonResolvedTrack: Codable {
     childrenStyle: String? = nil,
     groupTitle: String? = nil,
     live: Bool? = nil,
+    carPlaySiriListButton: String? = nil,
   ) {
     self.url = url
     self.title = title
@@ -54,6 +73,7 @@ struct JsonResolvedTrack: Codable {
     self.childrenStyle = childrenStyle
     self.groupTitle = groupTitle
     self.live = live
+    self.carPlaySiriListButton = carPlaySiriListButton
   }
 }
 
@@ -73,6 +93,7 @@ struct JsonTrack: Codable {
   let childrenStyle: String?
   let groupTitle: String?
   let live: Bool?
+  let imageRow: [JsonImageRowItem]?
 
   init(
     url: String? = nil,
@@ -89,6 +110,7 @@ struct JsonTrack: Codable {
     childrenStyle: String? = nil,
     groupTitle: String? = nil,
     live: Bool? = nil,
+    imageRow: [JsonImageRowItem]? = nil,
   ) {
     self.url = url
     self.title = title
@@ -104,6 +126,7 @@ struct JsonTrack: Codable {
     self.childrenStyle = childrenStyle
     self.groupTitle = groupTitle
     self.live = live
+    self.imageRow = imageRow
   }
 }
 
@@ -115,11 +138,23 @@ private extension String {
   }
 }
 
+extension JsonImageRowItem {
+  func toNitro() -> ImageRowItem {
+    ImageRowItem(
+      url: url,
+      artwork: artwork,
+      artworkSource: nil,
+      title: title,
+    )
+  }
+}
+
 extension JsonResolvedTrack {
   func toNitro() -> ResolvedTrack {
     ResolvedTrack(
       url: url,
       children: children?.map { $0.toNitro() },
+      carPlaySiriListButton: carPlaySiriListButton.flatMap { CarPlaySiriListButtonPosition(fromString: $0) },
       src: src,
       artwork: artwork,
       artworkSource: nil,
@@ -136,6 +171,7 @@ extension JsonResolvedTrack {
       favorited: nil,
       groupTitle: groupTitle,
       live: live,
+      imageRow: nil,
     )
   }
 }
@@ -160,6 +196,7 @@ extension JsonTrack {
       favorited: nil,
       groupTitle: groupTitle,
       live: live,
+      imageRow: imageRow?.map { $0.toNitro() },
     )
   }
 }

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,6 +567,28 @@ public final class RNABCarPlayController: NSObject {
 
   // MARK: - Selection Handling
 
+  /// 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,
+    audioBrowser: HybridAudioBrowser,
+    completion: @escaping () -> Void,
+    defaultBehavior: () async -> Void
+  ) async -> Bool {
+    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
+    }
+    await defaultBehavior()
+    await MainActor.run { self.showNowPlaying(); completion() }
+    return false
+  }
+
   private func handleItemSelection(track: Track, completion: @escaping () -> Void) {
     logger.info("Selected track: \(track.title)")
 
@@ -465,10 +616,12 @@ public final class RNABCarPlayController: NSObject {
          parentPath == player?.queueSourcePath,
          let index = player?.tracks.firstIndex(where: { $0.src == trackId })
       {
-        logger.debug("Queue already from \(parentPath), skipping to index \(index)")
-        try? player?.skipTo(index, playWhenReady: true)
-        showNowPlaying()
-        completion()
+        let queue = player?.tracks ?? []
+        Task {
+          await handleLoadAsync(track: track, queue: queue, startIndex: Double(index), audioBrowser: audioBrowser, completion: completion) {
+            try? player?.skipTo(index, playWhenReady: true)
+          }
+        }
         return
       }
 
@@ -477,42 +630,41 @@ public final class RNABCarPlayController: NSObject {
           // Expand the queue from the contextual URL
           if let expanded = try await audioBrowser.browserManager.expandQueueFromContextualUrl(url) {
             let (tracks, startIndex) = expanded
-
-            await MainActor.run {
-              // Replace queue and start at the selected track
-              audioBrowser.getPlayer()?.setQueue(tracks, initialIndex: startIndex, playWhenReady: true, sourcePath: parentPath)
-
-              // Show now playing template
-              self.showNowPlaying()
-              completion()
+            await handleLoadAsync(track: track, queue: tracks, startIndex: Double(startIndex), audioBrowser: audioBrowser, completion: completion) {
+              await MainActor.run {
+                // Replace queue and start at the selected track
+                audioBrowser.getPlayer()?.setQueue(tracks, initialIndex: startIndex, playWhenReady: true, sourcePath: parentPath)
+              }
             }
           } else {
             // Fallback: just load the single track
-            await MainActor.run {
-              try? audioBrowser.load(track: track)
-              try? audioBrowser.play()
-              self.showNowPlaying()
-              completion()
+            await handleLoadAsync(track: track, queue: [track], startIndex: 0, audioBrowser: audioBrowser, completion: completion) {
+              await MainActor.run {
+                try? audioBrowser.load(track: track)
+                try? audioBrowser.play()
+              }
             }
           }
         } catch {
           logger.error("Error expanding queue: \(error.localizedDescription)")
-          await MainActor.run {
-            try? audioBrowser.load(track: track)
-            try? audioBrowser.play()
-            self.showNowPlaying()
-            completion()
+          await handleLoadAsync(track: track, queue: [track], startIndex: 0, audioBrowser: audioBrowser, completion: completion) {
+            await MainActor.run {
+              try? audioBrowser.load(track: track)
+              try? audioBrowser.play()
+            }
           }
         }
       }
     }
     // If track has src, it's playable - load it
     else if track.src != nil {
-      Task { @MainActor in
-        try? audioBrowser.load(track: track)
-        try? audioBrowser.play()
-        showNowPlaying()
-        completion()
+      Task {
+        await handleLoadAsync(track: track, queue: [track], startIndex: 0, audioBrowser: audioBrowser, completion: completion) {
+          await MainActor.run {
+            try? audioBrowser.load(track: track)
+            try? audioBrowser.play()
+          }
+        }
       }
     }
     // If track has url, it's browsable - navigate to it
@@ -833,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)
       }
     }
 
@@ -845,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)
     }
   }
 
@@ -978,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 config = UIImage.SymbolConfiguration(pointSize: symbolPointSize, weight: .medium)
+    guard let symbol = UIImage(systemName: symbolName, withConfiguration: config) else { return nil }
 
-    let size = symbol.size
-    let scale = symbol.scale
+    // 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))
@@ -997,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() }
-
-    tintColor.set()
-    symbol.withRenderingMode(.alwaysTemplate).draw(in: CGRect(origin: .zero, size: size))
-
-    guard let rendered = UIGraphicsGetImageFromCurrentImageContext() else {
-      return symbol // Fallback to original if rendering fails
-    }
-    return rendered.withRenderingMode(.alwaysOriginal)
+  /// 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
+    }())
+
+    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))
+
+      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? {
@@ -1030,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
     }
 
@@ -1051,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
           }
 
@@ -1105,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