react-native-audio-browser 0.2.0-next.8 → 0.2.0

package/ios/CarPlay/CarPlayImageLoader.swift

@@ -36,6 +36,10 @@ final class CarPlayImageLoader {
     return sfSymbolImageForSize(symbolName, canvasSize: canvasSize, backgroundColor: bg, symbolColor: fg)
   }
 
+  func defaultTabImage() -> UIImage? {
+    sfSymbolImage("music.note.list")
+  }
+
   /// Cached empty placeholder image to reserve space while artwork loads
   lazy var placeholderImage: UIImage? = {
     let size = CPListItem.maximumImageSize
@@ -53,16 +57,6 @@ final class CarPlayImageLoader {
   ///   - size: The target size in points (will be multiplied by CarPlay display scale)
   ///   - completion: Called with the loaded image, or nil on failure
   func loadArtwork(for track: Track, size: CGSize, completion: @escaping @Sendable (UIImage?) -> Void) {
-    // A track that ships one image per appearance is loaded as two ordinary
-    // single-URL loads and combined below. Recursing rather than branching
-    // inside the loader means each variant still goes through the whole
-    // pipeline — route config, headers, SVG rasterising, the resolve transform
-    // — instead of a second, thinner fetch path that would drift from it.
-    if let variants = track.artwork?.variants {
-      loadVariants(for: track, variants: variants, size: size, completion: completion)
-      return
-    }
-
     // Build URL resolver closure that wraps BrowserManager
     let urlResolver: ((Double, Double) async -> ArtworkResolvedImage?)? = browserManager.map { bm in
       { [weak bm] pixelWidth, pixelHeight in
@@ -75,19 +69,19 @@ final class CarPlayImageLoader {
 
     Task {
       let action = await CarPlayArtworkResolver.resolve(
-        artwork: track.artwork?.url,
+        artwork: track.artwork,
         artworkSourceUri: track.artworkSource?.uri,
         artworkCarPlayTinted: track.artworkCarPlayTinted,
         targetWidth: Double(size.width),
         targetHeight: Double(size.height),
         displayScale: Double(self.carTraitCollection.displayScale),
-        urlResolver: urlResolver,
+        urlResolver: urlResolver
       )
 
       switch action {
-      case let .sfSymbol(artwork, width, height):
+      case .sfSymbol(let artwork, let width, let height):
         completion(self.sfSymbolImage(forArtwork: artwork, canvasSize: CGSize(width: width, height: height)))
-      case let .fetch(uri, headers, shouldTint, isSvg):
+      case .fetch(let uri, let headers, let shouldTint, let isSvg):
         let image = await self.fetchImage(uri: uri, headers: headers, isSvg: isSvg)
         if let image, shouldTint {
           completion(self.createAdaptiveImage(image, carTraitCollection: self.carTraitCollection))
@@ -102,49 +96,6 @@ final class CarPlayImageLoader {
 
   // MARK: - Private
 
-  /// Loads both images of an `ArtworkVariants` pair and returns them as one
-  /// adaptive image.
-  ///
-  /// The pair is registered on a `UIImageAsset`, which is what makes an
-  /// appearance change mid-drive re-resolve in place: CarPlay re-reads the
-  /// asset against the new trait collection, so the row swaps image without
-  /// another fetch or a re-query of the browse tree.
-  ///
-  /// If either half fails to load, the other is used alone rather than dropping
-  /// the row's image entirely — a glyph that is wrong for one appearance still
-  /// beats an empty slot, and this is usually a transient fetch failure.
-  private func loadVariants(
-    for track: Track,
-    variants: ArtworkVariants,
-    size: CGSize,
-    completion: @escaping @Sendable (UIImage?) -> Void,
-  ) {
-    Task {
-      async let light = self.loadArtworkAsync(for: track.copying(artwork: .some(.first(variants.light))), size: size)
-      async let dark = self.loadArtworkAsync(for: track.copying(artwork: .some(.first(variants.dark))), size: size)
-      let (lightImage, darkImage) = await (light, dark)
-
-      guard let lightImage, let darkImage else {
-        completion(lightImage ?? darkImage)
-        return
-      }
-
-      let asset = UIImageAsset()
-      asset.register(lightImage, with: UITraitCollection(userInterfaceStyle: .light))
-      asset.register(darkImage, with: UITraitCollection(userInterfaceStyle: .dark))
-      completion(asset.image(with: self.carTraitCollection))
-    }
-  }
-
-  /// `loadArtwork` as an awaitable, so the two variants can load concurrently.
-  private func loadArtworkAsync(for track: Track, size: CGSize) async -> UIImage? {
-    await withCheckedContinuation { continuation in
-      self.loadArtwork(for: track, size: size) { image in
-        continuation.resume(returning: image)
-      }
-    }
-  }
-
   /// Fetches an image from a URL with optional headers and SVG processing.
   private func fetchImage(uri: String, headers: [String: String]?, isSvg: Bool) async -> UIImage? {
     let source = ImageSource(uri: uri, method: nil, headers: headers, body: nil)

package/ios/CarPlay/CarPlayListItemFactory.swift

@@ -7,7 +7,6 @@ import os.log
 
 /// Typed metadata stored on CPListItems, replacing stringly-typed userInfo dictionaries.
 struct CarPlayItemInfo {
-  let id: String?
   let src: String?
 }
 
@@ -29,12 +28,12 @@ final class CarPlayListItemFactory {
   private let logger = Logger(subsystem: "com.audiobrowser", category: "CarPlayListItemFactory")
 
   var imageLoader: CarPlayImageLoader?
-  private let isActiveTrack: (_ id: String?, _ src: String?) -> Bool
+  private let isActiveTrack: (String) -> Bool
   private let onItemSelected: (Track, @escaping () -> Void) -> Void
 
   init(
-    isActiveTrack: @escaping (_ id: String?, _ src: String?) -> Bool,
-    onItemSelected: @escaping (Track, @escaping () -> Void) -> Void,
+    isActiveTrack: @escaping (String) -> Bool,
+    onItemSelected: @escaping (Track, @escaping () -> Void) -> Void
   ) {
     self.isActiveTrack = isActiveTrack
     self.onItemSelected = onItemSelected
@@ -50,44 +49,49 @@ final class CarPlayListItemFactory {
     let maxSections = CPListTemplate.maximumSectionCount
     let maxTotalItems = CPListTemplate.maximumItemCount
 
-    // Contiguous runs sharing a groupTitle form a section (the same semantics
-    // Android Auto's GROUP_TITLE hint has), so sections — titled or not —
-    // render in exact source (server) order. Ungrouped runs become headerless
-    // sections in place rather than being hoisted to the top.
-    var runs: [(title: String?, tracks: [Track])] = []
+    // Group by groupTitle if present
+    var groups: [String?: [Track]] = [:]
     for track in children {
-      if let last = runs.indices.last, runs[last].title == track.groupTitle {
-        runs[last].tracks.append(track)
-      } else {
-        runs.append((track.groupTitle, [track]))
-      }
+      let groupKey = track.groupTitle
+      groups[groupKey, default: []].append(track)
     }
 
     // Create sections (respecting both section and total item limits)
     var sections: [CPListSection] = []
     var totalItemCount = 0
 
-    for run in runs {
+    // Ungrouped items first
+    if let ungrouped = groups[nil], !ungrouped.isEmpty {
+      let availableSlots = maxTotalItems - totalItemCount
+      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
+      }
+    }
+
+    // Then grouped items (respecting section and item limits)
+    for (groupTitle, tracks) in groups.sorted(by: { ($0.key ?? "") < ($1.key ?? "") }) {
       guard sections.count < maxSections else { break }
       guard totalItemCount < maxTotalItems else { break }
+      guard groupTitle != nil else { continue }
 
       let availableSlots = maxTotalItems - totalItemCount
-      let items: [CPListTemplateItem] = run.tracks.prefix(availableSlots).map { track in
-        // Empty image rows fall through to a plain list item: zero-image
-        // CPListImageRowItem init is undocumented territory, and a header-only
-        // row is a dead end regardless (a "popular" row with no entries yet).
-        if let imageRow = track.imageRow, !imageRow.isEmpty {
+      let items: [CPListTemplateItem] = tracks.prefix(availableSlots).map { track in
+        if track.imageRow != nil {
           return createImageRowItem(for: track)
         }
         return createListItem(for: track)
       }
-      guard !items.isEmpty else { continue }
-      if let title = run.title {
-        sections.append(CPListSection(items: items, header: title, sectionIndexTitle: nil))
-      } else {
-        sections.append(CPListSection(items: items))
+      if !items.isEmpty {
+        sections.append(CPListSection(items: items, header: groupTitle, sectionIndexTitle: nil))
+        totalItemCount += items.count
       }
-      totalItemCount += items.count
     }
 
     return sections
@@ -101,28 +105,21 @@ final class CarPlayListItemFactory {
   ///   - handler: Optional custom handler. If nil, uses default browse/play handling.
   func createListItem(
     for track: Track,
-    handler: ((CPSelectableListItem, @escaping () -> Void) -> Void)? = nil,
+    handler: ((CPSelectableListItem, @escaping () -> Void) -> Void)? = nil
   ) -> CPListItem {
     let item = CPListItem(
       text: track.title,
-      detailText: track.subtitle,
+      detailText: track.subtitle ?? track.artist
     )
 
     // Store typed info for updatePlayingIndicators()
-    item.setCarPlayItemInfo(CarPlayItemInfo(id: track.id, src: track.src))
+    item.setCarPlayItemInfo(CarPlayItemInfo(src: track.src))
 
     // Set accessory type based on whether track is browsable or playable
     if let src = track.src {
       // Playable track - check if it's currently playing
       item.accessoryType = .none
-      // Leading (the system default, set explicitly to make the choice
-      // deliberate): the indicator draws in the artwork slot. Note the
-      // indicator's rendering is owned by the phone's CarPlay service, and on
-      // some iOS/CarPlay-Simulator combinations it isn't drawn at all — for
-      // ANY third-party app. Verify on a real head unit before assuming a
-      // logic bug here.
-      item.playingIndicatorLocation = .leading
-      item.isPlaying = isActiveTrack(track.id, src)
+      item.isPlaying = isActiveTrack(src)
       if item.isPlaying {
         logger.debug("Setting isPlaying=true for: \(track.title) (src: \(src))")
       }
@@ -176,14 +173,8 @@ final class CarPlayListItemFactory {
       CPListImageRowItem(text: track.title, images: placeholders)
     }
 
-    // Handler for row header tap → navigate to track.url if present. A row
-    // without a url (pure preview) has nothing to open, so its header tap is
-    // a no-op rather than a selection that can't resolve.
+    // Handler for row header tap → navigate to track.url if present
     item.handler = { [onItemSelected] _, completion in
-      guard track.url != nil else {
-        completion()
-        return
-      }
       onItemSelected(track, completion)
     }
 

package/ios/CarPlay/CarPlayNowPlayingManager.swift

@@ -16,59 +16,19 @@ final class CarPlayNowPlayingManager {
 
   private let interfaceController: CPInterfaceController
   var listItemFactory: (Track, ((CPSelectableListItem, @escaping () -> Void) -> Void)?) -> CPListItem
-  /// Pushes a browse destination (wired to the controller's navigateToUrl).
-  var navigateToUrl: ((_ url: String, _ title: String) -> Void)?
 
   private weak var audioBrowser: HybridAudioBrowser?
   private var nowPlayingObserver: NowPlayingObserver?
   private weak var upNextTemplate: CPListTemplate?
-  /// Everything the built button row renders — button types, the heart's
-  /// favorited state, and the shuffle/repeat `isSelected` state. Rebuilds are
-  /// skipped while this is unchanged (`onConfigChanged` fires on unrelated
-  /// churn, and every `updateNowPlayingButtons` call re-renders ALL buttons).
-  ///
-  /// shuffle/repeat selected state is part of the snapshot because CarPlay
-  /// SERIALIZES the buttons (NSSecureCoding) to its UI process: whenever the
-  /// now-playing screen re-renders (it does on every metadata change), the
-  /// stateful buttons first draw from their serialized `isSelected`, and only
-  /// then overlay the live state the app reports via the command center. A
-  /// button built with the default `isSelected = false` while repeat/shuffle
-  /// is on therefore flashes background-off → background-on at every
-  /// re-render. Stamping `isSelected` at build time (and rebuilding when the
-  /// mode changes) makes the first-frame render match the live state.
-  private struct BuiltButtonRow: Equatable {
-    let types: [CarPlayNowPlayingButton]
-    let favorited: Bool?
-    let shuffleSelected: Bool?
-    let repeatSelected: Bool?
-  }
-
-  private var builtRow: BuiltButtonRow?
-
-  /// Browse path the album line navigates to for the active track —
-  /// `track.albumUrl`, or the pre-resolved `resolveAlbumUrl` result. Resolved
-  /// at track-change time (not at tap) so the album line only surfaces when a
-  /// destination actually exists.
-  private var albumArtistDestination: String?
-  /// Drops a stale async `resolveAlbumUrl` result when the track changed while
-  /// the resolver was in flight (latest-update-wins).
-  private var albumArtistGeneration: UInt = 0
-  /// The just-tapped track whose load is still in flight. CarPlay reads
-  /// `isAlbumArtistButtonEnabled` when the template is displayed (a change while
-  /// visible doesn't re-render), and Now Playing is pushed at tap time — before
-  /// the player's `currentTrack` reflects the tap — so the flag must be derived
-  /// from the tapped track at push time. Cleared when the active track changes.
-  private var pendingAlbumArtistTrack: Track?
 
   /// Convenience accessor for browser config
   private var config: BrowserConfig {
     audioBrowser?.browserManager.config ?? BrowserConfig()
   }
 
-  /// The active track's favorited state, from the authoritative favorite set
-  /// (see `HybridAudioBrowser.isActiveTrackFavorited`).
+  /// Gets the current active track's favorited state
   private var isActiveTrackFavorited: Bool {
-    audioBrowser?.isActiveTrackFavorited() ?? false
+    (try? audioBrowser?.getActiveTrack())?.favorited ?? false
   }
 
   init(interfaceController: CPInterfaceController) {
@@ -88,7 +48,6 @@ final class CarPlayNowPlayingManager {
       CPNowPlayingTemplate.shared.remove(observer)
       nowPlayingObserver = nil
     }
-    pendingAlbumArtistTrack = nil
     audioBrowser = nil
   }
 
@@ -105,30 +64,9 @@ final class CarPlayNowPlayingManager {
     updateNowPlayingButtonStates()
   }
 
-  /// Sets up custom Now Playing buttons based on configuration and current
-  /// player state, skipping the rebuild when nothing the row renders changed.
+  /// Sets up custom Now Playing buttons based on configuration
   func setupNowPlayingButtons() {
-    // While a gate is active, custom buttons (favorite etc.) are hidden;
-    // the system transport controls stay — a gate never blocks playback.
-    let configured = (audioBrowser?.isGateActive ?? false) ? [] : (audioBrowser?.carPlayNowPlayingButtons ?? [])
-    // The template caps custom buttons at 5 (CPNowPlayingTemplate.h) and says
-    // nothing about overflow — unlike lists (trim) or the tab bar (throw). The
-    // config comes straight from JS, where duplicates and excess are
-    // representable, so dedupe (order preserved) and clamp here.
-    var deduped: [CarPlayNowPlayingButton] = []
-    for button in configured where !deduped.contains(button) {
-      deduped.append(button)
-    }
-    let buttons = Array(deduped.prefix(5))
-    let player = audioBrowser?.getPlayer()
-    let row = BuiltButtonRow(
-      types: buttons,
-      favorited: buttons.contains(.favorite) ? isActiveTrackFavorited : nil,
-      shuffleSelected: buttons.contains(.shuffle) ? (player?.shuffleEnabled ?? false) : nil,
-      repeatSelected: buttons.contains(.repeat) ? (player?.getRepeatMode() ?? .off) != .off : nil,
-    )
-    guard row != builtRow else { return }
-    builtRow = row
+    let buttons = config.carPlayNowPlayingButtons
     logger.info("Setting up Now Playing buttons: \(buttons.map(\.stringValue))")
 
     guard !buttons.isEmpty else {
@@ -144,21 +82,17 @@ final class CarPlayNowPlayingManager {
         let shuffleButton = CPNowPlayingShuffleButton { [weak self] _ in
           self?.handleShuffleButtonTapped()
         }
-        // Pre-stamp the serialized selected state — see BuiltButtonRow.
-        shuffleButton.isSelected = row.shuffleSelected ?? false
         nowPlayingButtons.append(shuffleButton)
 
       case .repeat:
         let repeatButton = CPNowPlayingRepeatButton { [weak self] _ in
           self?.handleRepeatButtonTapped()
         }
-        // Pre-stamp the serialized selected state — see BuiltButtonRow.
-        repeatButton.isSelected = row.repeatSelected ?? false
         nowPlayingButtons.append(repeatButton)
 
       case .favorite:
         let favoriteButton = CPNowPlayingImageButton(
-          image: favoriteButtonImage(isFavorited: row.favorited ?? false),
+          image: favoriteButtonImage(isFavorited: isActiveTrackFavorited)
         ) { [weak self] _ in
           self?.handleFavoriteButtonTapped()
         }
@@ -178,100 +112,44 @@ final class CarPlayNowPlayingManager {
 
   // MARK: - Show Now Playing
 
-  /// `popToFront` controls what happens when Now Playing is already on the
-  /// stack but buried under templates pushed on top of it (Up Next, the album
-  /// line's browse destination): a user-initiated surface (tap, voice play)
-  /// pops back to it, while the deferred post-resolve calls in
-  /// `handleItemSelection` pass `false` — they run seconds after the tap, and
-  /// popping then would yank away a screen the user navigated to meanwhile.
-  func showNowPlaying(popToFront: Bool = true) {
+  func showNowPlaying() {
     updateNowPlayingButtonStates()
     let nowPlayingTemplate = CPNowPlayingTemplate.shared
-    if interfaceController.templates.contains(where: { $0 === nowPlayingTemplate }) {
-      if popToFront {
-        interfaceController.safePop(to: nowPlayingTemplate, animated: true)
-      }
-    } else {
-      interfaceController.safePush(nowPlayingTemplate, animated: true)
+    // Don't push if already on the template stack
+    guard !interfaceController.templates.contains(where: { $0 === nowPlayingTemplate }) else {
+      return
     }
+    interfaceController.pushTemplate(nowPlayingTemplate, animated: true, completion: nil)
   }
 
   // MARK: - Button State Updates
 
-  /// Refreshes the row for a favorite/shuffle/repeat state change — the
-  /// snapshot diff in setupNowPlayingButtons makes this a no-op when nothing
-  /// the row renders actually changed.
+  /// Updates the favorite button appearance based on current track's favorite state
   func updateFavoriteButtonState() {
-    setupNowPlayingButtons()
-  }
-
-  /// Updates Now Playing button states based on config and current queue
-  func updateNowPlayingButtonStates() {
-    updateNowPlayingUpNextButton()
-    setupNowPlayingButtons()
-    updateAlbumArtistButtonState()
-  }
-
-  /// Re-resolves the album line's destination for the active track and
-  /// enables the (tappable) album/artist button only when one exists:
-  /// `track.albumUrl`, or the app's `resolveAlbumUrl` result.
-  /// Marks `track` as the just-tapped (still loading) track and derives the
-  /// album line's destination from it. Must run before the Now Playing
-  /// template is pushed — CarPlay reads `isAlbumArtistButtonEnabled` at display
-  /// time, so enabling after the push (when the load lands) renders no chevron.
-  func prepareAlbumArtistButton(for track: Track) {
-    pendingAlbumArtistTrack = track
-    updateAlbumArtistButtonState()
-  }
-
-  /// Clears the tap-time pending track (the player's `currentTrack` is now
-  /// authoritative) and refreshes all button states.
-  func handleActiveTrackChanged() {
-    pendingAlbumArtistTrack = nil
-    updateNowPlayingButtonStates()
-  }
-
-  func updateAlbumArtistButtonState() {
-    albumArtistGeneration &+= 1
-    let generation = albumArtistGeneration
+    guard config.carPlayNowPlayingButtons.contains(.favorite) else { return }
+    let favorited = isActiveTrackFavorited
+    let buttons = CPNowPlayingTemplate.shared.nowPlayingButtons
+
+    for (index, button) in buttons.enumerated() {
+      if button is CPNowPlayingImageButton {
+        let newFavoriteButton = CPNowPlayingImageButton(
+          image: favoriteButtonImage(isFavorited: favorited)
+        ) { [weak self] _ in
+          self?.handleFavoriteButtonTapped()
+        }
 
-    // The just-tapped track wins while its load is in flight: currentTrack
-    // still points at the previous track (or nil) at push time.
-    guard let track = pendingAlbumArtistTrack ?? audioBrowser?.getPlayer()?.currentTrack else {
-      logger.debug("AlbumArtist: no current track → disabled")
-      setAlbumArtistDestination(nil)
-      return
-    }
-    logger.info("AlbumArtist: track=\(track.title) albumUrl=\(track.albumUrl ?? "nil") resolver=\(self.config.resolveAlbumUrl != nil)")
-    if let albumUrl = track.albumUrl {
-      setAlbumArtistDestination(albumUrl)
-      return
-    }
-    guard let resolver = config.resolveAlbumUrl else {
-      setAlbumArtistDestination(nil)
-      return
-    }
-    Task { @MainActor [weak self] in
-      let path: String?
-      do {
-        path = try await resolver(track).await()
-      } catch {
-        self?.logger.error("resolveAlbumUrl failed: \(error.localizedDescription)")
-        path = nil
+        var updatedButtons = buttons
+        updatedButtons[index] = newFavoriteButton
+        CPNowPlayingTemplate.shared.updateNowPlayingButtons(updatedButtons)
+        break
       }
-      guard let self, self.albumArtistGeneration == generation else { return }
-      self.setAlbumArtistDestination(path)
     }
   }
 
-  private func setAlbumArtistDestination(_ path: String?) {
-    albumArtistDestination = path
-    let template = CPNowPlayingTemplate.shared
-    let enabled = path != nil
-    if template.isAlbumArtistButtonEnabled != enabled {
-      logger.info("AlbumArtist: button \(enabled ? "enabled" : "disabled") (destination: \(path ?? "nil"))")
-      template.isAlbumArtistButtonEnabled = enabled
-    }
+  /// Updates Now Playing button states based on config and current queue
+  func updateNowPlayingButtonStates() {
+    updateNowPlayingUpNextButton()
+    updateFavoriteButtonState()
   }
 
   // MARK: - Queue Changes
@@ -353,19 +231,9 @@ final class CarPlayNowPlayingManager {
 
   // MARK: - Private - Up Next
 
-  fileprivate func handleAlbumArtistButtonTapped() {
-    guard let destination = albumArtistDestination else { return }
-    let track = pendingAlbumArtistTrack ?? audioBrowser?.getPlayer()?.currentTrack
-    // The album line is what was tapped, so its text is the natural title for
-    // the pushed destination (artist may be unset, or the live song).
-    let title = track?.album ?? track?.artist ?? track?.title ?? ""
-    logger.info("Album/Artist button tapped, navigating to \(destination)")
-    navigateToUrl?(destination, title)
-  }
-
   private func updateNowPlayingUpNextButton() {
     let template = CPNowPlayingTemplate.shared
-    template.isUpNextButtonEnabled = (audioBrowser?.carPlayUpNextButton ?? true) && (audioBrowser?.getPlayer()?.tracks.count ?? 0) > 1
+    template.isUpNextButtonEnabled = config.carPlayUpNextButton && (audioBrowser?.getPlayer()?.tracks.count ?? 0) > 1
   }
 
   fileprivate func handleUpNextButtonTapped() {
@@ -383,28 +251,18 @@ final class CarPlayNowPlayingManager {
 
     logger.info("Showing Up Next queue with \(tracks.count) tracks")
 
-    // Reuse the now-playing template's button title (system-localized "Up Next"
-    // by default, and whatever the app set otherwise) instead of hardcoding an
-    // un-localized string.
-    let upNextTitle = CPNowPlayingTemplate.shared.upNextTitle
     let template = CPListTemplate(
-      title: upNextTitle.isEmpty ? "Up Next" : upNextTitle,
-      sections: [createUpNextSection(tracks: tracks, player: player)],
+      title: "Up Next",
+      sections: [createUpNextSection(tracks: tracks, player: player)]
     )
 
     upNextTemplate = template
 
-    interfaceController.safePush(template, animated: true)
+    interfaceController.pushTemplate(template, animated: true, completion: nil)
   }
 
   private func createUpNextSection(tracks: [Track], player: TrackPlayer) -> CPListSection {
-    // Clamp to CarPlay's list limit (createSections does the same for browse
-    // lists). Taking the prefix keeps item positions aligned with queue indices.
-    let maxItems = CPListTemplate.maximumItemCount
-    if tracks.count > maxItems {
-      logger.info("Up Next queue has \(tracks.count) tracks, clamping to CarPlay's limit of \(maxItems)")
-    }
-    let items = tracks.prefix(maxItems).enumerated().map { index, track -> CPListItem in
+    let items = tracks.enumerated().map { index, track -> CPListItem in
       listItemFactory(track) { [weak self] _, completion in
         self?.logger.info("Skipping to track at index \(index): \(track.title)")
         do {
@@ -439,8 +297,6 @@ private final class NowPlayingObserver: NSObject, CPNowPlayingTemplateObserver,
   }
 
   func nowPlayingTemplateAlbumArtistButtonTapped(_: CPNowPlayingTemplate) {
-    Task { @MainActor in
-      manager?.handleAlbumArtistButtonTapped()
-    }
+    logger.debug("Album/Artist button tapped (not implemented)")
   }
 }

package/ios/CarPlay/RNABAudioBrowser.h

@@ -3,25 +3,20 @@
 
 NS_ASSUME_NONNULL_BEGIN
 
-@interface RNABAudioBrowser : NSObject
-
-/// Return this from your AppDelegate's `application:handlerForIntent:` (iOS 14+
-/// in-app handling). Vends the library's handler for supported intents —
-/// `INPlayMediaIntent` (search / resume / play), `INUpdateMediaAffinityIntent`
-/// (like / dislike the current track) and `INAddMediaIntent` (add the current
-/// track to favorites) — or nil for unsupported intents. Register the ones you
-/// want in `INIntentsSupported`.
+/// 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, handlerFor intent: INIntent) -> Any? {
-///     RNABAudioBrowser.handler(for: intent)
+/// func application(_ application: UIApplication, handle intent: INIntent, completionHandler: @escaping (INIntentResponse) -> Void) {
+///     RNABAudioBrowser.handleMediaIntent(intent, completionHandler: completionHandler)
 /// }
 /// @endcode
-///
-/// A handler must be returned — without one iOS falls back to
-/// `UISIntentForwardingAction` and crashes in
-/// `-[INHandleIntentForwardingActionResponse isSuccess]`.
-+ (nullable id)handlerForIntent:(INIntent *)intent;
+@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
 

package/ios/CarPlay/RNABAudioBrowser.m

@@ -2,22 +2,21 @@
 
 @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";
++ (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]);
     }
-    if (!handlerClassName) {
-        return nil;
-    }
-    Class cls = NSClassFromString(handlerClassName);
-    return cls ? [[cls alloc] init] : nil;
 }
 
 @end

package/ios/CarPlay/RNABCarPlaySceneDelegate.m

@@ -34,7 +34,6 @@ API_AVAILABLE(ios(14.0))
     }
 
     // Create and start the CarPlay controller
-    [RNABCarPlayController setConnected:YES];
     self.carPlayController = [[RNABCarPlayController alloc] initWithInterfaceController:interfaceController];
     [self.carPlayController start];
 }
@@ -45,7 +44,6 @@ API_AVAILABLE(ios(14.0))
 
     [self.carPlayController stop];
     self.carPlayController = nil;
-    [RNABCarPlayController setConnected:NO];
 }
 
 - (void)templateApplicationScene:(CPTemplateApplicationScene *)templateApplicationScene