react-native-audio-browser 0.2.0-next.10 → 0.2.0-next.12

package/ios/CarPlay/CarPlayListItemFactory.swift

@@ -7,8 +7,9 @@ import os.log
 
 /// Typed metadata stored on CPListItems, replacing stringly-typed userInfo dictionaries.
 struct CarPlayItemInfo {
-  let id: String?
-  let src: String?
+  /// The track's identity (`id` when non-blank, else `src`) — the comparison
+  /// key for the now-playing indicator repaint sweep.
+  let identity: String?
 }
 
 extension CPListItem {
@@ -29,11 +30,14 @@ final class CarPlayListItemFactory {
   private let logger = Logger(subsystem: "com.audiobrowser", category: "CarPlayListItemFactory")
 
   var imageLoader: CarPlayImageLoader?
-  private let isActiveTrack: (_ id: String?, _ src: String?) -> Bool
+  /// Pushed by the controller (at creation and when options change), like
+  /// `imageLoader` — the factory never reads options itself.
+  var playingIndicatorLocation: CPListItemPlayingIndicatorLocation = .leading
+  private let isActiveTrack: (_ identity: String?) -> Bool
   private let onItemSelected: (Track, @escaping () -> Void) -> Void
 
   init(
-    isActiveTrack: @escaping (_ id: String?, _ src: String?) -> Bool,
+    isActiveTrack: @escaping (_ identity: String?) -> Bool,
     onItemSelected: @escaping (Track, @escaping () -> Void) -> Void,
   ) {
     self.isActiveTrack = isActiveTrack
@@ -42,55 +46,69 @@ final class CarPlayListItemFactory {
 
   // MARK: - Sections
 
+  /// Whether this OS has CarPlay's wrapping tile container (the iOS 26
+  /// element API) — the capability `SectionPresentation` degrades against.
+  private static var supportsWrappingGrid: Bool {
+    if #available(iOS 26.0, *) { return true }
+    return false
+  }
+
+  /// Maps the page's sections 1:1 to CPListSections (ADR 0010), respecting
+  /// CarPlay's section and total-item budgets. Style blocks declare the
+  /// requested presentation (resolved `section ?? page` here — ADR 0011);
+  /// this renders CarPlay's nearest supported form (`SectionPresentation`):
+  /// - list (default): a titled/headerless section of list rows.
+  /// - single-line grid (`gridWrap: false`): a headerless section holding
+  ///   one single-line image-row item whose text is the section title — the
+  ///   tiles that fit render, the rest truncate (the platform doesn't
+  ///   report the fit).
+  /// - wrapping grid: a wrapping, titled tile grid on iOS 26+; a plain list
+  ///   before that.
   func createSections(from resolvedTrack: ResolvedTrack) -> [CPListSection] {
-    guard let children = resolvedTrack.children else {
+    guard let sections = resolvedTrack.normalizedSections else {
       return []
     }
 
     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])] = []
-    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]))
-      }
-    }
-
-    // Create sections (respecting both section and total item limits)
-    var sections: [CPListSection] = []
+    var listSections: [CPListSection] = []
     var totalItemCount = 0
 
-    for run in runs {
-      guard sections.count < maxSections else { break }
+    for section in sections {
+      guard listSections.count < maxSections else { break }
       guard totalItemCount < maxTotalItems else { break }
-
-      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 {
-          return createImageRowItem(for: track)
+      // An empty section is a dead end regardless of style (a "popular"
+      // section with no entries yet) — skip it rather than render a header
+      // with nothing under it.
+      guard !section.children.isEmpty else { continue }
+
+      let style = StyleResolver.sectionStyle(section: section.style, page: resolvedTrack.style)
+      let presentation = SectionPresentation(for: style, supportsWrappingGrid: Self.supportsWrappingGrid)
+      switch presentation {
+      case .list:
+        let availableSlots = maxTotalItems - totalItemCount
+        let items: [CPListTemplateItem] = section.children.prefix(availableSlots).map {
+          createListItem(for: $0, style: StyleResolver.trackStyle(track: $0.style, section: style))
         }
-        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 let title = section.title {
+          listSections.append(CPListSection(items: items, header: title, sectionIndexTitle: nil))
+        } else {
+          listSections.append(CPListSection(items: items))
+        }
+        totalItemCount += items.count
+      case .singleLineRow, .wrappingGrid:
+        // Tile presentations render as one image-row item inside a
+        // headerless CPListSection, with the section title as the item's
+        // text — a headed section would render the title twice.
+        guard let item = createImageRowItem(for: section, style: style, presentation: presentation)
+        else { continue }
+        listSections.append(CPListSection(items: [item]))
+        totalItemCount += 1
       }
-      totalItemCount += items.count
     }
 
-    return sections
+    return listSections
   }
 
   // MARK: - List Item
@@ -98,9 +116,14 @@ final class CarPlayListItemFactory {
   /// Creates a CPListItem for a track with common setup (typed userInfo, artwork, isPlaying).
   /// - Parameters:
   ///   - track: The track to create the item for
+  ///   - style: The track's resolved style block (`track ?? section ?? page`,
+  ///     via `StyleResolver`). nil = the track's own declaration — the one
+  ///     genuinely section-less caller (the Up Next queue list) has no
+  ///     inheritance to resolve.
   ///   - handler: Optional custom handler. If nil, uses default browse/play handling.
   func createListItem(
     for track: Track,
+    style: TrackStyle? = nil,
     handler: ((CPSelectableListItem, @escaping () -> Void) -> Void)? = nil,
   ) -> CPListItem {
     let item = CPListItem(
@@ -109,46 +132,59 @@ final class CarPlayListItemFactory {
     )
 
     // Store typed info for updatePlayingIndicators()
-    item.setCarPlayItemInfo(CarPlayItemInfo(id: track.id, src: track.src))
+    item.setCarPlayItemInfo(CarPlayItemInfo(identity: track.identity))
 
     // 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
+      // Consumer-configurable via `ios.carPlayPlayingIndicatorLocation`
+      // (default leading: 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.playingIndicatorLocation = playingIndicatorLocation
+      item.isPlaying = isActiveTrack(track.identity)
       if item.isPlaying {
         logger.debug("Setting isPlaying=true for: \(track.title) (src: \(src))")
       }
-    } else if track.url != nil {
+    } else if track.path != nil {
       // Browsable only - show disclosure indicator
       item.accessoryType = .disclosureIndicator
     }
 
+    // An unavailable track grays out and goes inert — list rows are the
+    // surface that CAN draw the fact, so it shows rather than hides
+    // (Track.disabled's rendering ladder).
+    if track.disabled == true {
+      item.isEnabled = false
+    }
+
     // 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
+      item.setImage(imageLoader?.placeholderImage(size: CPListItem.maximumImageSize))
+      imageLoader?.loadArtwork(for: track, style: style, 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)
+    // Set selection handler. The disabled guard wraps BOTH handler paths —
+    // custom handlers (Up Next rows skipping the queue, say) included: belt
+    // over the isEnabled braces, so an unavailable track stays inert even if
+    // a surface delivers the tap.
+    let selection = handler ?? { [onItemSelected] _, completion in
+      onItemSelected(track, completion)
+    }
+    item.handler = { item, completion in
+      guard track.disabled != true else {
+        completion()
+        return
       }
+      selection(item, completion)
     }
 
     return item
@@ -156,58 +192,141 @@ final class CarPlayListItemFactory {
 
   // 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")
+  /// Target size for images inside an image row. The iOS 26 SDK deprecates
+  /// `CPListImageRowItem.maximumImageSize` in favor of the element-based API,
+  /// so read whichever the running OS considers canonical.
+  private static var rowImageSize: CGSize {
+    if #available(iOS 26.0, *) {
+      return CPListImageRowItemElement.maximumImageSize
     }
+    return CPListImageRowItem.maximumImageSize
+  }
 
-    // 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)
+  /// Creates the image-row item rendering a tile-presented section: a single
+  /// truncating line (`.singleLineRow`) or a wrapping multi-line grid
+  /// (`.wrappingGrid` — constructed on iOS 26+ only, by `SectionPresentation`).
+  ///
+  /// Returns nil when nothing is drawable — every child hidden by the
+  /// disabled ladder (pre-26 only; the element APIs gray instead).
+  private func createImageRowItem(
+    for section: Section, style: SectionStyle, presentation: SectionPresentation,
+  ) -> CPListImageRowItem? {
+    let singleLine = presentation == .singleLineRow
+    // Disabled ladder: iOS 26 elements can draw unavailability (grayed +
+    // inert, below); the legacy image row can't, so there a disabled track
+    // hides — never a normal-looking dead tile.
+    let visibleChildren: [Track] = if #available(iOS 26.0, *) {
+      section.children
+    } else {
+      section.children.filter { $0.disabled != true }
+    }
+    guard !visibleChildren.isEmpty else { return nil }
+    // A single line shows at most CPMaximumNumberOfGridImages; the wrapping
+    // grid takes every child (queue scope is declared, never rendered — the
+    // cap here only limits what's drawn, and only where the platform does).
+    let tracks = singleLine
+      ? Array(visibleChildren.prefix(CPMaximumNumberOfGridImages))
+      : visibleChildren
+    let placeholder = { [imageLoader] in
+      imageLoader?.placeholderImage(size: Self.rowImageSize) ?? UIImage()
+    }
 
-    // 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)
+    let item: CPListImageRowItem
+    // Applies an async-loaded artwork image to a tile on the element-based
+    // API (the elements are captured per availability branch — their type
+    // doesn't exist before iOS 26). nil = the legacy gridImages path.
+    // @MainActor makes the closure Sendable for the artwork completion hop.
+    var applyImage: (@MainActor (Int, UIImage) -> Void)?
+    if #available(iOS 26.0, *) {
+      if singleLine {
+        // Row elements are the only tile element with a subtitle slot — the
+        // imageGridElements branch below has no equivalent, by SDK design.
+        let rowElements = tracks.map { track in
+          let element = CPListImageRowItemRowElement(
+            image: placeholder(), title: track.title, subtitle: track.subtitle,
+          )
+          if track.disabled == true {
+            element.isEnabled = false
+          }
+          return element
+        }
+        item = CPListImageRowItem(text: section.title, elements: rowElements, allowsMultipleLines: false)
+        applyImage = { index, image in
+          guard index < rowElements.count else { return }
+          rowElements[index].image = image
+        }
+      } else {
+        // imageGridElements, never the title-less gridElements: an
+        // artwork-less track must keep its name on screen (ADR 0010).
+        let gridElements = tracks.map { track in
+          let element = CPListImageRowItemImageGridElement(
+            image: placeholder(), imageShape: .roundedRectangle, title: track.title,
+            accessorySymbolName: nil,
+          )
+          if track.disabled == true {
+            element.isEnabled = false
+          }
+          return element
+        }
+        item = CPListImageRowItem(text: section.title, imageGridElements: gridElements, allowsMultipleLines: true)
+        applyImage = { index, image in
+          guard index < gridElements.count else { return }
+          gridElements[index].image = image
+        }
+      }
     } else {
-      CPListImageRowItem(text: track.title, images: placeholders)
+      let placeholders = tracks.map { _ in placeholder() }
+      // Use imageTitles variant on iOS 17.4+ to show titles below each thumbnail
+      if #available(iOS 17.4, *) {
+        item = CPListImageRowItem(text: section.title ?? "", images: placeholders, imageTitles: tracks.map(\.title))
+      } else {
+        item = CPListImageRowItem(text: section.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.
+    // Header tap → navigate to section.path ("view all"). A path-less
+    // section is a pure preview — 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 {
+      guard let path = section.path else {
         completion()
         return
       }
-      onItemSelected(track, completion)
+      onItemSelected(Self.navigationTrack(path: path, title: section.title), completion)
     }
 
-    // Handler for individual image taps
+    // Per-tile taps select the child track directly. A disabled tile is
+    // grayed and inert (26+ elements) — the guard keeps it inert even if
+    // the surface delivers the tap anyway.
     item.listImageRowHandler = { [onItemSelected] _, index, completion in
-      guard index < visibleItems.count else {
+      guard index < tracks.count, tracks[index].disabled != true else {
         completion()
         return
       }
-      let tappedItem = visibleItems[index]
-      onItemSelected(tappedItem.toTrack(), completion)
+      onItemSelected(tracks[index], 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 }
+    // Load artwork for each rendered tile asynchronously
+    for (index, track) in tracks.enumerated() {
+      guard track.artwork != nil || track.artworkSource != nil else { continue }
 
-      imageLoader?.loadArtwork(for: imageRowItem.toTrack(), size: CPListImageRowItem.maximumImageSize) { [weak item] image in
+      imageLoader?.loadArtwork(
+        for: track,
+        style: StyleResolver.trackStyle(track: track.style, section: style),
+        size: Self.rowImageSize,
+      ) { [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)
+          if let applyImage {
+            // The element-based API exposes a settable `image`; assigning it
+            // updates the element the row observes.
+            applyImage(index, image)
+          } else {
+            var images = item.gridImages
+            if index < images.count {
+              images[index] = image
+              item.update(images)
+            }
           }
         }
       }
@@ -215,4 +334,18 @@ final class CarPlayListItemFactory {
 
     return item
   }
+
+  /// A synthetic browsable Track for section-header navigation — the
+  /// section's "view all" surface has a path and a title, but no Track.
+  /// Style-less by design: CarPlay resolves presentation from the page it
+  /// navigates to. (Android's counterpart projects the section's block —
+  /// the promise only exists to feed Android Auto's parent-level hint.)
+  private static func navigationTrack(path: String, title: String?) -> Track {
+    Track(
+      id: nil, path: path, src: nil, artwork: nil, artworkSource: nil,
+      request: nil, title: title ?? "", subtitle: nil,
+      artist: nil, albumPath: nil, album: nil, description: nil, genre: nil,
+      duration: nil, style: nil, disabled: nil, favorited: nil, live: nil,
+    )
+  }
 }

package/ios/CarPlay/CarPlayNowPlayingManager.swift

@@ -16,8 +16,8 @@ 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)?
+  /// Pushes a browse destination (wired to the controller's navigateToPath).
+  var navigateToPath: ((_ path: String, _ title: String) -> Void)?
 
   private weak var audioBrowser: HybridAudioBrowser?
   private var nowPlayingObserver: NowPlayingObserver?
@@ -46,11 +46,11 @@ final class CarPlayNowPlayingManager {
   private var builtRow: BuiltButtonRow?
 
   /// Browse path the album line navigates to for the active track —
-  /// `track.albumUrl`, or the pre-resolved `resolveAlbumUrl` result. Resolved
+  /// `track.albumPath`, or the pre-resolved `resolveAlbumPath` 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
+  /// Drops a stale async `resolveAlbumPath` 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
@@ -214,7 +214,7 @@ final class CarPlayNowPlayingManager {
 
   /// 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.
+  /// `track.albumPath`, or the app's `resolveAlbumPath` 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
@@ -242,12 +242,12 @@ final class CarPlayNowPlayingManager {
       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)
+    logger.info("AlbumArtist: track=\(track.title) albumPath=\(track.albumPath ?? "nil") resolver=\(self.config.resolveAlbumPath != nil)")
+    if let albumPath = track.albumPath {
+      setAlbumArtistDestination(albumPath)
       return
     }
-    guard let resolver = config.resolveAlbumUrl else {
+    guard let resolver = config.resolveAlbumPath else {
       setAlbumArtistDestination(nil)
       return
     }
@@ -256,7 +256,7 @@ final class CarPlayNowPlayingManager {
       do {
         path = try await resolver(track).await()
       } catch {
-        self?.logger.error("resolveAlbumUrl failed: \(error.localizedDescription)")
+        self?.logger.error("resolveAlbumPath failed: \(error.localizedDescription)")
         path = nil
       }
       guard let self, self.albumArtistGeneration == generation else { return }
@@ -295,7 +295,10 @@ final class CarPlayNowPlayingManager {
   /// 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 {
+    guard let image = UIImage(systemName: symbolName)?.resized(
+      to: CPNowPlayingButtonMaximumImageSize,
+      scale: interfaceController.carTraitCollection.displayScale,
+    ) else {
       return UIImage()
     }
     return image
@@ -360,7 +363,7 @@ final class CarPlayNowPlayingManager {
     // 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)
+    navigateToPath?(destination, title)
   }
 
   private func updateNowPlayingUpNextButton() {

package/ios/Extension/Capability+RemoteCommand.swift

@@ -54,7 +54,7 @@ extension PlayerCapabilities {
     // Apple silently removed. On the iOS 16+ target it can never be invoked: CarPlay
     // uses its own CPNowPlayingButton heart, and Siri "I like this" routes through
     // INUpdateMediaAffinityIntent. The `favorite` capability still drives the
-    // favorites-match row indicators via setFavoriteMatch. See issues #67 / #71.
+    // favorite row indicators via setFavoriteEnabled. See issues #67 / #71.
 
     // Mode controls
     if shuffleMode != false {

package/ios/Extension/PlayerCapabilities+Favorite.swift

@@ -1,20 +1,6 @@
 import Foundation
 
 extension PlayerCapabilities {
-  /// Resolved favorite match mode, or `nil` when favoriting is disabled.
-  ///
-  /// `false`/unset → `nil`; `true` → `.exact`; `{ match }` → that match.
-  var favoriteMatch: FavoritesMatchMode? {
-    switch favorite {
-    case .none:
-      nil
-    case let .some(.first(enabled)):
-      enabled ? .exact : nil
-    case let .some(.second(config)):
-      config.match
-    }
-  }
-
   /// Whether the favorite/like control is enabled.
-  var favoriteEnabled: Bool { favoriteMatch != nil }
+  var favoriteEnabled: Bool { favorite ?? false }
 }

package/ios/Extension/ResolvedTrack+Copying.swift

@@ -10,9 +10,11 @@ extension ResolvedTrack {
   /// - `.some(nil)` → set field to nil
   /// - `.some(value)` → set field to value
   ///
-  /// `url` and `title` use single-optional since they are non-optional on ResolvedTrack.
+  /// `path` and `title` use single-optional since they are non-optional on ResolvedTrack.
   func copying(
-    url: String? = nil,
+    path: String? = nil,
+    style: SectionStyle?? = nil,
+    sections: [Section]?? = nil,
     children: [Track]?? = nil,
     carPlaySiriListButton: CarPlaySiriListButtonPosition?? = nil,
     id: String?? = nil,
@@ -20,24 +22,22 @@ extension ResolvedTrack {
     artwork: Variant_String_ArtworkVariants?? = nil,
     artworkSource: ImageSource?? = nil,
     request: TrackRequest?? = nil,
-    artworkCarPlayTinted: Bool?? = nil,
     title: String? = nil,
     subtitle: String?? = nil,
     artist: String?? = nil,
-    albumUrl: String?? = nil,
+    albumPath: String?? = nil,
     album: String?? = nil,
     description: String?? = nil,
     genre: String?? = nil,
     duration: Double?? = nil,
-    style: TrackStyle?? = nil,
-    childrenStyle: TrackStyle?? = nil,
+    disabled: Bool?? = nil,
     favorited: Bool?? = nil,
-    groupTitle: String?? = nil,
     live: Bool?? = nil,
-    imageRow: [ImageRowItem]?? = nil,
   ) -> ResolvedTrack {
     ResolvedTrack(
-      url: url ?? self.url,
+      path: path ?? self.path,
+      style: style ?? self.style,
+      sections: sections ?? self.sections,
       children: children ?? self.children,
       carPlaySiriListButton: carPlaySiriListButton ?? self.carPlaySiriListButton,
       id: id ?? self.id,
@@ -45,21 +45,17 @@ extension ResolvedTrack {
       artwork: artwork ?? self.artwork,
       artworkSource: artworkSource ?? self.artworkSource,
       request: request ?? self.request,
-      artworkCarPlayTinted: artworkCarPlayTinted ?? self.artworkCarPlayTinted,
       title: title ?? self.title,
       subtitle: subtitle ?? self.subtitle,
       artist: artist ?? self.artist,
-      albumUrl: albumUrl ?? self.albumUrl,
+      albumPath: albumPath ?? self.albumPath,
       album: album ?? self.album,
       description: description ?? self.description,
       genre: genre ?? self.genre,
       duration: duration ?? self.duration,
-      style: style ?? self.style,
-      childrenStyle: childrenStyle ?? self.childrenStyle,
+      disabled: disabled ?? self.disabled,
       favorited: favorited ?? self.favorited,
-      groupTitle: groupTitle ?? self.groupTitle,
       live: live ?? self.live,
-      imageRow: imageRow ?? self.imageRow,
     )
   }
 }

package/ios/Extension/Section+Copying.swift

@@ -0,0 +1,31 @@
+#if canImport(NitroModules)
+  import NitroModules
+#endif
+
+extension Section {
+  /// Returns a copy of this Section with only the specified fields changed.
+  ///
+  /// Same double-optional (`T??`) convention as the other copying helpers;
+  /// `children` is single-optional since it is non-optional on Section.
+  func copying(
+    title: String?? = nil,
+    subtitle: String?? = nil,
+    style: SectionStyle?? = nil,
+    path: String?? = nil,
+    children: [Track]? = nil,
+  ) -> Section {
+    Section(
+      title: title ?? self.title,
+      subtitle: subtitle ?? self.subtitle,
+      style: style ?? self.style,
+      path: path ?? self.path,
+      children: children ?? self.children,
+    )
+  }
+
+  /// One untitled section — the canonical wrap of a flat track list
+  /// (`children` authoring sugar, search results — ADR 0010).
+  static func untitled(_ children: [Track]) -> Section {
+    Section(title: nil, subtitle: nil, style: nil, path: nil, children: children)
+  }
+}