react-native-audio-browser 0.1.1 → 0.2.0-next.1

package/ios/CarPlay/CarPlayImageLoader.swift

@@ -36,10 +36,6 @@ 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
@@ -57,6 +53,16 @@ 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
@@ -69,19 +75,19 @@ final class CarPlayImageLoader {
 
     Task {
       let action = await CarPlayArtworkResolver.resolve(
-        artwork: track.artwork,
+        artwork: track.artwork?.url,
         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 .sfSymbol(let artwork, let width, let height):
+      case let .sfSymbol(artwork, width, height):
         completion(self.sfSymbolImage(forArtwork: artwork, canvasSize: CGSize(width: width, height: height)))
-      case .fetch(let uri, let headers, let shouldTint, let isSvg):
+      case let .fetch(uri, headers, shouldTint, isSvg):
         let image = await self.fetchImage(uri: uri, headers: headers, isSvg: isSvg)
         if let image, shouldTint {
           completion(self.createAdaptiveImage(image, carTraitCollection: self.carTraitCollection))
@@ -96,6 +102,49 @@ 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,6 +7,7 @@ import os.log
 
 /// Typed metadata stored on CPListItems, replacing stringly-typed userInfo dictionaries.
 struct CarPlayItemInfo {
+  let id: String?
   let src: String?
 }
 
@@ -28,12 +29,12 @@ final class CarPlayListItemFactory {
   private let logger = Logger(subsystem: "com.audiobrowser", category: "CarPlayListItemFactory")
 
   var imageLoader: CarPlayImageLoader?
-  private let isActiveTrack: (String) -> Bool
+  private let isActiveTrack: (_ id: String?, _ src: String?) -> Bool
   private let onItemSelected: (Track, @escaping () -> Void) -> Void
 
   init(
-    isActiveTrack: @escaping (String) -> Bool,
-    onItemSelected: @escaping (Track, @escaping () -> Void) -> Void
+    isActiveTrack: @escaping (_ id: String?, _ src: String?) -> Bool,
+    onItemSelected: @escaping (Track, @escaping () -> Void) -> Void,
   ) {
     self.isActiveTrack = isActiveTrack
     self.onItemSelected = onItemSelected
@@ -49,49 +50,44 @@ final class CarPlayListItemFactory {
     let maxSections = CPListTemplate.maximumSectionCount
     let maxTotalItems = CPListTemplate.maximumItemCount
 
-    // Group by groupTitle if present
-    var groups: [String?: [Track]] = [:]
+    // 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])] = []
     for track in children {
-      let groupKey = track.groupTitle
-      groups[groupKey, default: []].append(track)
+      if let last = runs.indices.last, runs[last].title == track.groupTitle {
+        runs[last].tracks.append(track)
+      } else {
+        runs.append((track.groupTitle, [track]))
+      }
     }
 
     // Create sections (respecting both section and total item limits)
     var sections: [CPListSection] = []
     var totalItemCount = 0
 
-    // 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 ?? "") }) {
+    for run in runs {
       guard sections.count < maxSections else { break }
       guard totalItemCount < maxTotalItems else { break }
-      guard groupTitle != nil else { continue }
 
       let availableSlots = maxTotalItems - totalItemCount
-      let items: [CPListTemplateItem] = tracks.prefix(availableSlots).map { track in
-        if track.imageRow != nil {
+      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 {
           return createImageRowItem(for: track)
         }
         return createListItem(for: track)
       }
-      if !items.isEmpty {
-        sections.append(CPListSection(items: items, header: groupTitle, sectionIndexTitle: nil))
-        totalItemCount += items.count
+      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))
       }
+      totalItemCount += items.count
     }
 
     return sections
@@ -105,21 +101,28 @@ 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 ?? track.artist
+      detailText: track.subtitle,
     )
 
     // Store typed info for updatePlayingIndicators()
-    item.setCarPlayItemInfo(CarPlayItemInfo(src: track.src))
+    item.setCarPlayItemInfo(CarPlayItemInfo(id: track.id, 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
-      item.isPlaying = isActiveTrack(src)
+      // 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)
       if item.isPlaying {
         logger.debug("Setting isPlaying=true for: \(track.title) (src: \(src))")
       }
@@ -173,8 +176,14 @@ final class CarPlayListItemFactory {
       CPListImageRowItem(text: track.title, images: placeholders)
     }
 
-    // Handler for row header tap → navigate to track.url if present
+    // 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.
     item.handler = { [onItemSelected] _, completion in
+      guard track.url != nil else {
+        completion()
+        return
+      }
       onItemSelected(track, completion)
     }
 

package/ios/CarPlay/CarPlayNowPlayingManager.swift

@@ -16,19 +16,59 @@ 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()
   }
 
-  /// Gets the current active track's favorited state
+  /// The active track's favorited state, from the authoritative favorite set
+  /// (see `HybridAudioBrowser.isActiveTrackFavorited`).
   private var isActiveTrackFavorited: Bool {
-    (try? audioBrowser?.getActiveTrack())?.favorited ?? false
+    audioBrowser?.isActiveTrackFavorited() ?? false
   }
 
   init(interfaceController: CPInterfaceController) {
@@ -48,6 +88,7 @@ final class CarPlayNowPlayingManager {
       CPNowPlayingTemplate.shared.remove(observer)
       nowPlayingObserver = nil
     }
+    pendingAlbumArtistTrack = nil
     audioBrowser = nil
   }
 
@@ -64,9 +105,30 @@ final class CarPlayNowPlayingManager {
     updateNowPlayingButtonStates()
   }
 
-  /// Sets up custom Now Playing buttons based on configuration
+  /// Sets up custom Now Playing buttons based on configuration and current
+  /// player state, skipping the rebuild when nothing the row renders changed.
   func setupNowPlayingButtons() {
-    let buttons = config.carPlayNowPlayingButtons
+    // 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
     logger.info("Setting up Now Playing buttons: \(buttons.map(\.stringValue))")
 
     guard !buttons.isEmpty else {
@@ -82,17 +144,21 @@ 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: isActiveTrackFavorited)
+          image: favoriteButtonImage(isFavorited: row.favorited ?? false),
         ) { [weak self] _ in
           self?.handleFavoriteButtonTapped()
         }
@@ -112,44 +178,100 @@ final class CarPlayNowPlayingManager {
 
   // MARK: - Show Now Playing
 
-  func showNowPlaying() {
+  /// `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) {
     updateNowPlayingButtonStates()
     let nowPlayingTemplate = CPNowPlayingTemplate.shared
-    // Don't push if already on the template stack
-    guard !interfaceController.templates.contains(where: { $0 === nowPlayingTemplate }) else {
-      return
+    if interfaceController.templates.contains(where: { $0 === nowPlayingTemplate }) {
+      if popToFront {
+        interfaceController.safePop(to: nowPlayingTemplate, animated: true)
+      }
+    } else {
+      interfaceController.safePush(nowPlayingTemplate, animated: true)
     }
-    interfaceController.pushTemplate(nowPlayingTemplate, animated: true, completion: nil)
   }
 
   // MARK: - Button State Updates
 
-  /// Updates the favorite button appearance based on current track's favorite state
+  /// 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.
   func updateFavoriteButtonState() {
-    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()
-        }
-
-        var updatedButtons = buttons
-        updatedButtons[index] = newFavoriteButton
-        CPNowPlayingTemplate.shared.updateNowPlayingButtons(updatedButtons)
-        break
-      }
-    }
+    setupNowPlayingButtons()
   }
 
   /// Updates Now Playing button states based on config and current queue
   func updateNowPlayingButtonStates() {
     updateNowPlayingUpNextButton()
-    updateFavoriteButtonState()
+    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
+
+    // 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
+      }
+      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
+    }
   }
 
   // MARK: - Queue Changes
@@ -231,9 +353,19 @@ 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 = config.carPlayUpNextButton && (audioBrowser?.getPlayer()?.tracks.count ?? 0) > 1
+    template.isUpNextButtonEnabled = (audioBrowser?.carPlayUpNextButton ?? true) && (audioBrowser?.getPlayer()?.tracks.count ?? 0) > 1
   }
 
   fileprivate func handleUpNextButtonTapped() {
@@ -251,18 +383,28 @@ 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: "Up Next",
-      sections: [createUpNextSection(tracks: tracks, player: player)]
+      title: upNextTitle.isEmpty ? "Up Next" : upNextTitle,
+      sections: [createUpNextSection(tracks: tracks, player: player)],
     )
 
     upNextTemplate = template
 
-    interfaceController.pushTemplate(template, animated: true, completion: nil)
+    interfaceController.safePush(template, animated: true)
   }
 
   private func createUpNextSection(tracks: [Track], player: TrackPlayer) -> CPListSection {
-    let items = tracks.enumerated().map { index, track -> CPListItem in
+    // 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
       listItemFactory(track) { [weak self] _, completion in
         self?.logger.info("Skipping to track at index \(index): \(track.title)")
         do {
@@ -297,6 +439,8 @@ private final class NowPlayingObserver: NSObject, CPNowPlayingTemplateObserver,
   }
 
   func nowPlayingTemplateAlbumArtistButtonTapped(_: CPNowPlayingTemplate) {
-    logger.debug("Album/Artist button tapped (not implemented)")
+    Task { @MainActor in
+      manager?.handleAlbumArtistButtonTapped()
+    }
   }
 }

package/ios/CarPlay/ImageRowItem+CarPlay.swift

@@ -0,0 +1,19 @@
+import Foundation
+import NitroModules
+
+// MARK: - ImageRowItem → Track Conversion
+
+extension ImageRowItem {
+  /// Creates a minimal Track from an ImageRowItem for reuse with item selection and artwork loading.
+  /// A `src`-bearing item becomes a playable track (thumbnail tap plays it); otherwise the
+  /// track only navigates via `url`.
+  func toTrack() -> Track {
+    Track(
+      id: id, url: url, src: src, artwork: artwork.map { .first($0) },
+      artworkSource: artworkSource, request: request,
+      artworkCarPlayTinted: nil, title: title, subtitle: nil, artist: artist,
+      albumUrl: albumUrl, album: album, description: nil, genre: nil, duration: nil, style: nil,
+      childrenStyle: nil, favorited: nil, groupTitle: nil, live: live, imageRow: nil,
+    )
+  }
+}

package/ios/CarPlay/RNABAudioBrowser.h

@@ -3,20 +3,25 @@
 
 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.
+@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`.
 ///
-/// 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)
+/// func application(_ application: UIApplication, handlerFor intent: INIntent) -> Any? {
+///     RNABAudioBrowser.handler(for: intent)
 /// }
 /// @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;
+///
+/// A handler must be returned — without one iOS falls back to
+/// `UISIntentForwardingAction` and crashes in
+/// `-[INHandleIntentForwardingActionResponse isSuccess]`.
++ (nullable id)handlerForIntent:(INIntent *)intent;
 
 @end
 

package/ios/CarPlay/RNABAudioBrowser.m

@@ -2,21 +2,22 @@
 
 @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]);
++ (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;
 }
 
 @end