react-native-audio-browser 0.0.1 → 0.1.0-next.2

package/ios/CarPlay/CarPlayImageLoader.swift

@@ -0,0 +1,180 @@
+import CarPlay
+import Foundation
+import NitroModules
+import os.log
+
+/// Handles all image loading and rendering for CarPlay.
+///
+/// Responsibilities:
+/// - SF Symbol rendering (plain and canvas-rendered with light/dark variants)
+/// - Artwork loading via BrowserManager's artwork URL resolution
+/// - Direct artwork loading as fallback
+/// - Adaptive image tinting for monochrome icons
+/// - Placeholder image generation
+@MainActor
+final class CarPlayImageLoader {
+  private let logger = Logger(subsystem: "com.audiobrowser", category: "CarPlayImageLoader")
+
+  private let carTraitCollection: UITraitCollection
+  private weak var browserManager: BrowserManager?
+
+  init(carTraitCollection: UITraitCollection, browserManager: BrowserManager?) {
+    self.carTraitCollection = carTraitCollection
+    self.browserManager = browserManager
+  }
+
+  // MARK: - SF Symbols
+
+  /// Creates an SF Symbol image for tabs - plain systemName, CarPlay handles tinting
+  func sfSymbolImage(_ symbolName: String) -> UIImage? {
+    UIImage(systemName: symbolName)
+  }
+
+  /// Renders an SF Symbol from an artwork string (e.g. "sf:heart.fill?bg=#000&fg=#fff").
+  func sfSymbolImage(forArtwork artwork: String, canvasSize: CGSize) -> UIImage? {
+    let (symbolName, bg, fg) = SFSymbolRenderer.parseArtwork(artwork)
+    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
+    let scale = carTraitCollection.displayScale
+    UIGraphicsBeginImageContextWithOptions(size, false, scale)
+    defer { UIGraphicsEndImageContext() }
+    return UIGraphicsGetImageFromCurrentImageContext()
+  }()
+
+  // MARK: - Artwork Loading
+
+  /// Loads artwork for a track with size context, using the artwork transform if configured.
+  /// - Parameters:
+  ///   - track: The track to load artwork for
+  ///   - 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) {
+    // Build URL resolver closure that wraps BrowserManager
+    let urlResolver: ((Double, Double) async -> ArtworkResolvedImage?)? = browserManager.map { bm in
+      { [weak bm] pixelWidth, pixelHeight in
+        guard let bm else { return nil }
+        let imageContext = ImageContext(width: pixelWidth, height: pixelHeight)
+        guard let source = await bm.resolveArtworkUrl(track: track, perRouteConfig: nil, imageContext: imageContext) else { return nil }
+        return ArtworkResolvedImage(uri: source.uri, headers: source.headers)
+      }
+    }
+
+    Task {
+      let action = await CarPlayArtworkResolver.resolve(
+        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
+      )
+
+      switch action {
+      case .sfSymbol(let artwork, let width, let height):
+        completion(self.sfSymbolImage(forArtwork: artwork, canvasSize: CGSize(width: width, height: height)))
+      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))
+        } else {
+          completion(image)
+        }
+      case .none:
+        completion(nil)
+      }
+    }
+  }
+
+  // MARK: - Private
+
+  /// 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)
+    let svgScale: CGFloat? = isSvg ? carTraitCollection.displayScale : nil
+    return await ArtworkImageFetcher.fetchImage(from: source, svgScale: svgScale)
+  }
+
+  /// 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 = 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 }
+
+    // Explicit colors: single image, no light/dark variants needed
+    if let symbolColor {
+      return renderSymbolInCanvas(symbol, tintColor: symbolColor, backgroundColor: backgroundColor, canvasSize: canvasSize, 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)
+
+    let asset = UIImageAsset()
+    asset.register(lightImage, with: UITraitCollection(userInterfaceStyle: .light))
+    asset.register(darkImage, with: UITraitCollection(userInterfaceStyle: .dark))
+
+    return asset.image(with: carTraitCollection)
+  }
+
+  /// 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)
+  }
+
+  /// Renders an image to a bitmap with the specified tint color (for monochrome icons).
+  private nonisolated func renderImageToBitmap(_ image: UIImage, tintColor: UIColor) -> UIImage {
+    UIGraphicsBeginImageContextWithOptions(image.size, false, image.scale)
+    defer { UIGraphicsEndImageContext() }
+
+    tintColor.set()
+    image.withRenderingMode(.alwaysTemplate).draw(in: CGRect(origin: .zero, size: image.size))
+
+    guard let rendered = UIGraphicsGetImageFromCurrentImageContext() else {
+      return image
+    }
+    return rendered.withRenderingMode(.alwaysOriginal)
+  }
+
+  /// Creates light/dark tinted variants of an image and returns the appropriate one for current appearance
+  private nonisolated func createAdaptiveImage(_ image: UIImage, carTraitCollection: UITraitCollection) -> UIImage {
+    let lightImage = renderImageToBitmap(image, tintColor: .black)
+    let darkImage = renderImageToBitmap(image, tintColor: .white)
+
+    let asset = UIImageAsset()
+    asset.register(lightImage, with: UITraitCollection(userInterfaceStyle: .light))
+    asset.register(darkImage, with: UITraitCollection(userInterfaceStyle: .dark))
+
+    return asset.image(with: carTraitCollection)
+  }
+}

package/ios/CarPlay/CarPlayListItemFactory.swift

@@ -0,0 +1,209 @@
+import CarPlay
+import Foundation
+import NitroModules
+import os.log
+
+// MARK: - Typed Item Info
+
+/// Typed metadata stored on CPListItems, replacing stringly-typed userInfo dictionaries.
+struct CarPlayItemInfo {
+  let src: String?
+}
+
+extension CPListItem {
+  func setCarPlayItemInfo(_ info: CarPlayItemInfo) {
+    userInfo = ["carPlayItemInfo": info]
+  }
+
+  var carPlayItemInfo: CarPlayItemInfo? {
+    (userInfo as? [String: Any])?["carPlayItemInfo"] as? CarPlayItemInfo
+  }
+}
+
+// MARK: - Factory
+
+/// Creates CPListItems and CPListSections from Track data for CarPlay templates.
+@MainActor
+final class CarPlayListItemFactory {
+  private let logger = Logger(subsystem: "com.audiobrowser", category: "CarPlayListItemFactory")
+
+  var imageLoader: CarPlayImageLoader?
+  private let isActiveTrack: (String) -> Bool
+  private let onItemSelected: (Track, @escaping () -> Void) -> Void
+
+  init(
+    isActiveTrack: @escaping (String) -> Bool,
+    onItemSelected: @escaping (Track, @escaping () -> Void) -> Void
+  ) {
+    self.isActiveTrack = isActiveTrack
+    self.onItemSelected = onItemSelected
+  }
+
+  // MARK: - Sections
+
+  func createSections(from resolvedTrack: ResolvedTrack) -> [CPListSection] {
+    guard let children = resolvedTrack.children else {
+      return []
+    }
+
+    let maxSections = CPListTemplate.maximumSectionCount
+    let maxTotalItems = CPListTemplate.maximumItemCount
+
+    // Group by groupTitle if present
+    var groups: [String?: [Track]] = [:]
+    for track in children {
+      let groupKey = track.groupTitle
+      groups[groupKey, default: []].append(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 ?? "") }) {
+      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 {
+          return createImageRowItem(for: track)
+        }
+        return createListItem(for: track)
+      }
+      if !items.isEmpty {
+        sections.append(CPListSection(items: items, header: groupTitle, sectionIndexTitle: nil))
+        totalItemCount += items.count
+      }
+    }
+
+    return sections
+  }
+
+  // MARK: - List Item
+
+  /// Creates a CPListItem for a track with common setup (typed userInfo, artwork, isPlaying).
+  /// - Parameters:
+  ///   - track: The track to create the item for
+  ///   - handler: Optional custom handler. If nil, uses default browse/play handling.
+  func createListItem(
+    for track: Track,
+    handler: ((CPSelectableListItem, @escaping () -> Void) -> Void)? = nil
+  ) -> CPListItem {
+    let item = CPListItem(
+      text: track.title,
+      detailText: track.subtitle ?? track.artist
+    )
+
+    // Store typed info for updatePlayingIndicators()
+    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
+      item.isPlaying = isActiveTrack(src)
+      if item.isPlaying {
+        logger.debug("Setting isPlaying=true for: \(track.title) (src: \(src))")
+      }
+    } else if track.url != nil {
+      // Browsable only - show disclosure indicator
+      item.accessoryType = .disclosureIndicator
+    }
+
+    // Load artwork with size context for proper CDN optimization
+    if track.artwork != nil || track.artworkSource != nil {
+      // Set empty placeholder to reserve space while loading
+      item.setImage(imageLoader?.placeholderImage)
+      imageLoader?.loadArtwork(for: track, size: CPListItem.maximumImageSize) { [weak item] image in
+        Task { @MainActor in
+          item?.setImage(image)
+        }
+      }
+    }
+
+    // Set selection handler
+    if let handler {
+      item.handler = handler
+    } else {
+      item.handler = { [onItemSelected] _, completion in
+        onItemSelected(track, completion)
+      }
+    }
+
+    return item
+  }
+
+  // MARK: - Image Row Item
+
+  /// Creates a CPListImageRowItem for a track that has an imageRow.
+  /// Renders as a horizontal row of tappable artwork thumbnails with a header title.
+  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 imageLoader?.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)
+    }
+
+    // Handler for row header tap → navigate to track.url if present
+    item.handler = { [onItemSelected] _, completion in
+      onItemSelected(track, completion)
+    }
+
+    // Handler for individual image taps
+    item.listImageRowHandler = { [onItemSelected] _, index, completion in
+      guard index < visibleItems.count else {
+        completion()
+        return
+      }
+      let tappedItem = visibleItems[index]
+      onItemSelected(tappedItem.toTrack(), 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 }
+
+      imageLoader?.loadArtwork(for: imageRowItem.toTrack(), 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
+  }
+}

package/ios/CarPlay/CarPlayNowPlayingManager.swift

@@ -0,0 +1,302 @@
+import CarPlay
+import Foundation
+import os.log
+
+/// Manages the Now Playing template, buttons, Up Next, and related state for CarPlay.
+///
+/// Responsibilities:
+/// - CPNowPlayingTemplate setup and button configuration
+/// - Button action handlers (shuffle, repeat, favorite, playback rate)
+/// - Button state updates (favorite appearance, Up Next enabled)
+/// - Up Next template creation and queue change handling
+/// - NowPlayingObserver for Up Next button taps
+@MainActor
+final class CarPlayNowPlayingManager {
+  private let logger = Logger(subsystem: "com.audiobrowser", category: "CarPlayNowPlayingManager")
+
+  private let interfaceController: CPInterfaceController
+  var listItemFactory: (Track, ((CPSelectableListItem, @escaping () -> Void) -> Void)?) -> CPListItem
+
+  private weak var audioBrowser: HybridAudioBrowser?
+  private var nowPlayingObserver: NowPlayingObserver?
+  private weak var upNextTemplate: CPListTemplate?
+
+  /// Convenience accessor for browser config
+  private var config: BrowserConfig {
+    audioBrowser?.browserManager.config ?? BrowserConfig()
+  }
+
+  /// Gets the current active track's favorited state
+  private var isActiveTrackFavorited: Bool {
+    (try? audioBrowser?.getActiveTrack())?.favorited ?? false
+  }
+
+  init(interfaceController: CPInterfaceController) {
+    self.interfaceController = interfaceController
+    self.listItemFactory = { track, _ in CPListItem(text: track.title, detailText: nil) }
+  }
+
+  // MARK: - Lifecycle
+
+  func setup(audioBrowser: HybridAudioBrowser) {
+    self.audioBrowser = audioBrowser
+    setupNowPlayingTemplate()
+  }
+
+  func teardown() {
+    if let observer = nowPlayingObserver {
+      CPNowPlayingTemplate.shared.remove(observer)
+      nowPlayingObserver = nil
+    }
+    audioBrowser = nil
+  }
+
+  // MARK: - Now Playing Template
+
+  private func setupNowPlayingTemplate() {
+    let template = CPNowPlayingTemplate.shared
+
+    let observer = NowPlayingObserver(manager: self)
+    nowPlayingObserver = observer
+    template.add(observer)
+
+    setupNowPlayingButtons()
+    updateNowPlayingButtonStates()
+  }
+
+  /// Sets up custom Now Playing buttons based on configuration
+  func setupNowPlayingButtons() {
+    let buttons = config.carPlayNowPlayingButtons
+    logger.info("Setting up Now Playing buttons: \(buttons.map(\.stringValue))")
+
+    guard !buttons.isEmpty else {
+      CPNowPlayingTemplate.shared.updateNowPlayingButtons([])
+      return
+    }
+
+    var nowPlayingButtons: [CPNowPlayingButton] = []
+
+    for buttonType in buttons {
+      switch buttonType {
+      case .shuffle:
+        let shuffleButton = CPNowPlayingShuffleButton { [weak self] _ in
+          self?.handleShuffleButtonTapped()
+        }
+        nowPlayingButtons.append(shuffleButton)
+
+      case .repeat:
+        let repeatButton = CPNowPlayingRepeatButton { [weak self] _ in
+          self?.handleRepeatButtonTapped()
+        }
+        nowPlayingButtons.append(repeatButton)
+
+      case .favorite:
+        let favoriteButton = CPNowPlayingImageButton(
+          image: favoriteButtonImage(isFavorited: isActiveTrackFavorited)
+        ) { [weak self] _ in
+          self?.handleFavoriteButtonTapped()
+        }
+        nowPlayingButtons.append(favoriteButton)
+
+      case .playbackRate:
+        let rateButton = CPNowPlayingPlaybackRateButton { [weak self] _ in
+          self?.handlePlaybackRateButtonTapped()
+        }
+        nowPlayingButtons.append(rateButton)
+      }
+    }
+
+    CPNowPlayingTemplate.shared.updateNowPlayingButtons(nowPlayingButtons)
+    logger.info("Updated Now Playing with \(nowPlayingButtons.count) custom button(s)")
+  }
+
+  // MARK: - Show Now Playing
+
+  func showNowPlaying() {
+    updateNowPlayingButtonStates()
+    let nowPlayingTemplate = CPNowPlayingTemplate.shared
+    // 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
+
+  /// Updates the favorite button appearance based on current track's favorite state
+  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
+      }
+    }
+  }
+
+  /// Updates Now Playing button states based on config and current queue
+  func updateNowPlayingButtonStates() {
+    updateNowPlayingUpNextButton()
+    updateFavoriteButtonState()
+  }
+
+  // MARK: - Queue Changes
+
+  /// Handles queue changes - updates Up Next list if visible
+  func handleQueueChanged(_ tracks: [Track]) {
+    updateNowPlayingUpNextButton()
+
+    guard let template = upNextTemplate,
+          let player = audioBrowser?.getPlayer()
+    else {
+      return
+    }
+
+    logger.debug("Queue changed, updating Up Next list with \(tracks.count) tracks")
+    template.updateSections([createUpNextSection(tracks: tracks, player: player)])
+  }
+
+  // MARK: - Private - Button Handlers
+
+  /// Returns the appropriate image for the favorite button based on state
+  private func favoriteButtonImage(isFavorited: Bool) -> UIImage {
+    let symbolName = isFavorited ? "heart.fill" : "heart"
+    guard let image = UIImage(systemName: symbolName)?.resized(to: CPNowPlayingButtonMaximumImageSize) else {
+      return UIImage()
+    }
+    return image
+  }
+
+  private func handleShuffleButtonTapped() {
+    guard let player = audioBrowser?.getPlayer() else { return }
+
+    let newEnabled = !player.shuffleEnabled
+    player.shuffleEnabled = newEnabled
+    logger.info("CarPlay shuffle mode changed: \(newEnabled)")
+  }
+
+  private func handleRepeatButtonTapped() {
+    guard let player = audioBrowser?.getPlayer() else { return }
+
+    let currentMode = player.getRepeatMode()
+    let newMode: RepeatMode = switch currentMode {
+    case .off:
+      .track
+    case .track:
+      .queue
+    case .queue:
+      .off
+    }
+
+    player.setRepeatMode(newMode)
+    logger.info("CarPlay repeat mode changed: \(currentMode.stringValue) → \(newMode.stringValue)")
+  }
+
+  private func handleFavoriteButtonTapped() {
+    try? audioBrowser?.toggleActiveTrackFavorited()
+    logger.info("CarPlay favorite toggled")
+  }
+
+  private func handlePlaybackRateButtonTapped() {
+    guard let audioBrowser, let player = audioBrowser.getPlayer() else { return }
+
+    let rates = audioBrowser.playbackRates
+    guard !rates.isEmpty else { return }
+
+    let currentRate = Double(player.rate)
+    let nextRate: Double
+
+    if let currentIndex = rates.firstIndex(where: { (currentRate - $0).magnitude < 0.01 }) {
+      let nextIndex = (currentIndex + 1) % rates.count
+      nextRate = rates[nextIndex]
+    } else {
+      nextRate = rates.first { $0 > currentRate } ?? rates[0]
+    }
+
+    player.rate = Float(nextRate)
+    logger.info("CarPlay playback rate changed: \(currentRate) → \(nextRate)")
+  }
+
+  // MARK: - Private - Up Next
+
+  private func updateNowPlayingUpNextButton() {
+    let template = CPNowPlayingTemplate.shared
+    template.isUpNextButtonEnabled = config.carPlayUpNextButton && (audioBrowser?.getPlayer()?.tracks.count ?? 0) > 1
+  }
+
+  fileprivate func handleUpNextButtonTapped() {
+    guard let player = audioBrowser?.getPlayer() else {
+      logger.warning("Player not available for Up Next")
+      return
+    }
+
+    let tracks = player.tracks
+
+    guard !tracks.isEmpty else {
+      logger.debug("No tracks in queue for Up Next")
+      return
+    }
+
+    logger.info("Showing Up Next queue with \(tracks.count) tracks")
+
+    let template = CPListTemplate(
+      title: "Up Next",
+      sections: [createUpNextSection(tracks: tracks, player: player)]
+    )
+
+    upNextTemplate = template
+
+    interfaceController.pushTemplate(template, animated: true, completion: nil)
+  }
+
+  private func createUpNextSection(tracks: [Track], player: TrackPlayer) -> CPListSection {
+    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 {
+          try player.skipTo(index, playWhenReady: true)
+        } catch {
+          self?.logger.error("Failed to skip to track: \(error.localizedDescription)")
+        }
+        completion()
+      }
+    }
+    return CPListSection(items: items)
+  }
+}
+
+// MARK: - Now Playing Observer
+
+/// Private helper class for CPNowPlayingTemplateObserver conformance.
+private final class NowPlayingObserver: NSObject, CPNowPlayingTemplateObserver, @unchecked Sendable {
+  private let logger = Logger(subsystem: "com.audiobrowser", category: "NowPlayingObserver")
+  private weak var manager: CarPlayNowPlayingManager?
+
+  @MainActor
+  init(manager: CarPlayNowPlayingManager) {
+    self.manager = manager
+    super.init()
+  }
+
+  func nowPlayingTemplateUpNextButtonTapped(_: CPNowPlayingTemplate) {
+    Task { @MainActor in
+      manager?.handleUpNextButtonTapped()
+    }
+  }
+
+  func nowPlayingTemplateAlbumArtistButtonTapped(_: CPNowPlayingTemplate) {
+    logger.debug("Album/Artist button tapped (not implemented)")
+  }
+}