react-native-audio-browser 0.2.0-next.3 → 0.2.0-next.31

package/ios/CarPlay/RNABMediaAddHandler.swift

@@ -22,30 +22,14 @@ class RNABMediaAddHandler: NSObject, INAddMediaIntentHandling {
   private static let logger = Logger(subsystem: "com.audiobrowser", category: "MediaAddHandler")
 
   func handle(
-    intent: INAddMediaIntent,
-    completion: @escaping @Sendable (INAddMediaIntentResponse) -> Void
+    intent _: INAddMediaIntent,
+    completion: @escaping @Sendable (INAddMediaIntentResponse) -> Void,
   ) {
     Self.logger.info("Add media — favorite current track")
 
     Task { @MainActor in
-      // "Add" targets the current track; if nothing is playing there's nothing
-      // to add, so the assistant reports failure rather than a silent no-op.
-      guard let browser = HybridAudioBrowser.shared,
-            browser.getPlayer()?.currentTrack != nil
-      else {
-        completion(INAddMediaIntentResponse(code: .failure, userActivity: nil))
-        return
-      }
-
-      // Add = favorite the currently-playing track (same path as the CarPlay
-      // favorite button / affinity "like"): flips the now-playing heart and
-      // fires `onFavoriteChanged` so the consumer persists it — no extra handler.
-      do {
-        try browser.setActiveTrackFavorited(favorited: true)
-        completion(INAddMediaIntentResponse(code: .success, userActivity: nil))
-      } catch {
-        completion(INAddMediaIntentResponse(code: .failure, userActivity: nil))
-      }
+      let applied = HybridAudioBrowser.favoriteCurrentTrack(true)
+      completion(INAddMediaIntentResponse(code: applied ? .success : .failure, userActivity: nil))
     }
   }
 
@@ -57,7 +41,7 @@ class RNABMediaAddHandler: NSObject, INAddMediaIntentHandling {
   @objc(resolveMediaItemsForAddMedia:withCompletion:)
   func resolveMediaItems(
     for intent: INAddMediaIntent,
-    with completion: @escaping ([INAddMediaMediaItemResolutionResult]) -> Void
+    with completion: @escaping ([INAddMediaMediaItemResolutionResult]) -> Void,
   ) {
     let name = intent.mediaSearch?.mediaName ?? ""
     let item = INMediaItem(identifier: name, title: name, type: .unknown, artwork: nil)
@@ -66,10 +50,10 @@ class RNABMediaAddHandler: NSObject, INAddMediaIntentHandling {
 
   @objc(resolveMediaDestinationForAddMedia:withCompletion:)
   func resolveMediaDestination(
-    for intent: INAddMediaIntent,
-    with completion: @escaping (INAddMediaMediaDestinationResolutionResult) -> Void
+    for _: INAddMediaIntent,
+    with completion: @escaping (INAddMediaMediaDestinationResolutionResult) -> Void,
   ) {
     // One flat favorites collection — always the user's library, no playlists.
-      completion(.success(with: INMediaDestination.library))
+    completion(.success(with: INMediaDestination.library))
   }
 }

package/ios/CarPlay/RNABMediaAffinityHandler.swift

@@ -21,34 +21,18 @@ class RNABMediaAffinityHandler: NSObject, INUpdateMediaAffinityIntentHandling {
 
   func handle(
     intent: INUpdateMediaAffinityIntent,
-    completion: @escaping @Sendable (INUpdateMediaAffinityIntentResponse) -> Void
+    completion: @escaping @Sendable (INUpdateMediaAffinityIntentResponse) -> Void,
   ) {
     let affinity = intent.affinityType
     Self.logger.info("Update media affinity — type=\(affinity.rawValue)")
 
     Task { @MainActor in
-      // Affinity targets the current track; if nothing is playing there's nothing
-      // to like, so the assistant reports failure rather than a silent no-op.
-      guard let browser = HybridAudioBrowser.shared,
-            browser.getPlayer()?.currentTrack != nil
-      else {
-        completion(INUpdateMediaAffinityIntentResponse(code: .failure, userActivity: nil))
-        return
+      let applied = switch affinity {
+      case .like: HybridAudioBrowser.favoriteCurrentTrack(true)
+      case .dislike: HybridAudioBrowser.favoriteCurrentTrack(false)
+      default: false
       }
-
-      // Map affinity onto the library-managed favorite state (same path as the
-      // CarPlay favorite button): flips the now-playing heart and fires
-      // `onFavoriteChanged` so the consumer persists it — no extra handler.
-      switch affinity {
-      case .like:
-        try? browser.setActiveTrackFavorited(favorited: true)
-      case .dislike:
-        try? browser.setActiveTrackFavorited(favorited: false)
-      default:
-        completion(INUpdateMediaAffinityIntentResponse(code: .failure, userActivity: nil))
-        return
-      }
-      completion(INUpdateMediaAffinityIntentResponse(code: .success, userActivity: nil))
+      completion(INUpdateMediaAffinityIntentResponse(code: applied ? .success : .failure, userActivity: nil))
     }
   }
 
@@ -60,7 +44,7 @@ class RNABMediaAffinityHandler: NSObject, INUpdateMediaAffinityIntentHandling {
   @objc(resolveMediaItemsForUpdateMediaAffinity:withCompletion:)
   func resolveMediaItems(
     for intent: INUpdateMediaAffinityIntent,
-    with completion: @escaping ([INUpdateMediaAffinityMediaItemResolutionResult]) -> Void
+    with completion: @escaping ([INUpdateMediaAffinityMediaItemResolutionResult]) -> Void,
   ) {
     let name = intent.mediaSearch?.mediaName ?? ""
     let item = INMediaItem(identifier: name, title: name, type: .unknown, artwork: nil)

package/ios/CarPlay/RNABMediaIntentHandler.swift

@@ -21,13 +21,12 @@ class RNABMediaIntentHandler: NSObject, INPlayMediaIntentHandling {
       mediaTypeMode: Self.mediaTypeMode(s?.mediaType ?? .unknown),
       reference: Self.reference(s?.reference ?? .unknown),
       hasMediaType: (s?.mediaType ?? .unknown) != .unknown,
-      appName: Self.hostAppName()
+      appName: Self.hostAppName(),
     )
     Self.logger.info("Play media intent — query=\(criteria.query) matchesApp=\(criteria.matchesAppName) resume=\(criteria.isResume)")
 
-    // Static + gate-waiting, so it works even before the shared instance exists
-    // (background intent launch, RN not booted yet).
-    HybridAudioBrowser.handlePlayMediaIntent(criteria: criteria) { success in
+    Task { @MainActor in
+      let success = await MediaIntentPlayback.play(criteria: criteria)
       completion(INPlayMediaIntentResponse(code: success ? .success : .failure, userActivity: nil))
     }
   }
@@ -37,18 +36,18 @@ class RNABMediaIntentHandler: NSObject, INPlayMediaIntentHandling {
   /// `album` are filters, not verticals — they yield no mode.
   private static func mediaTypeMode(_ type: INMediaItemType) -> String? {
     switch type {
-    case .station, .radioStation, .algorithmicRadioStation, .musicStation: return "station"
-    case .podcastShow, .podcastEpisode, .podcastPlaylist, .podcastStation:  return "podcast"
-    case .audioBook:       return "audiobook"
-    case .news:            return "news"
-    case .music:           return "music"
-    case .song:            return "song"
-    case .playlist:        return "playlist"
-    case .musicVideo:      return "music-video"
-    case .movie:           return "movie"
-    case .tvShow:          return "tv-show"
-    case .tvShowEpisode:   return "tv-show-episode"
-    default:               return nil   // album/artist/genre/unknown
+    case .station, .radioStation, .algorithmicRadioStation, .musicStation: "station"
+    case .podcastShow, .podcastEpisode, .podcastPlaylist, .podcastStation: "podcast"
+    case .audioBook: "audiobook"
+    case .news: "news"
+    case .music: "music"
+    case .song: "song"
+    case .playlist: "playlist"
+    case .musicVideo: "music-video"
+    case .movie: "movie"
+    case .tvShow: "tv-show"
+    case .tvShowEpisode: "tv-show-episode"
+    default: nil // album/artist/genre/unknown
     }
   }
 
@@ -56,9 +55,9 @@ class RNABMediaIntentHandler: NSObject, INPlayMediaIntentHandling {
   /// routes to native resume; `.my` to the consumer; everything else is unknown.
   private static func reference(_ ref: INMediaReference) -> MediaIntentCriteria.Reference {
     switch ref {
-    case .currentlyPlaying: return .currentlyPlaying
-    case .my:               return .my
-    default:                return .unknown
+    case .currentlyPlaying: .currentlyPlaying
+    case .my: .my
+    default: .unknown
     }
   }
 

package/ios/CarPlay/SectionPresentation.swift

@@ -0,0 +1,77 @@
+#if canImport(NitroModules)
+  import NitroModules
+#endif
+
+/// The rendered form of a section — the single place where (resolved style,
+/// platform capability) maps to what CarPlay draws. Degradation drops
+/// decorations before layout (ADR 0011): a *wrapping* grid can only reach the
+/// tile path where the platform has a wrapping tile container (CarPlay:
+/// iOS 26+'s element API); without one it becomes a list, where every item
+/// stays reachable instead of truncating at an unknowable width. A
+/// single-line grid (`gridWrap: false`) renders everywhere — the legacy image
+/// row IS the single-line presentation.
+enum SectionPresentation: Equatable {
+  case list
+  case singleLineRow
+  case wrappingGrid
+
+  /// - Parameter supportsWrappingGrid: whether the platform has a wrapping
+  ///   tile container. Injected (rather than read via `#available` here) so
+  ///   the mapping is testable off-device.
+  init(for style: SectionStyle?, supportsWrappingGrid: Bool) {
+    guard style?.display == .grid else {
+      self = .list
+      return
+    }
+    if style?.gridWrap == false {
+      self = .singleLineRow
+    } else if supportsWrappingGrid {
+      self = .wrappingGrid
+    } else {
+      self = .list
+    }
+  }
+
+  /// The accessory symbol a resolved block actually draws: nil when
+  /// undeclared, and nil for the `'none'` sentinel — the inheritance escape
+  /// that restores the derived accessory (a browsable row's chevron). Here,
+  /// not in the CarPlay factory, so the sentinel rule is testable off-device.
+  static func effectiveAccessorySymbol(_ style: TrackStyle?) -> String? {
+    guard let symbol = style?.accessorySymbol, symbol != "none" else { return nil }
+    return symbol
+  }
+
+  /// The title a tile shelf draws as the list section's header; nil when
+  /// the image row's own text carries it — here, not in the CarPlay factory,
+  /// so the rule is testable off-device. CarPlay draws a chevron beside an
+  /// image row's text whether or not the row has a handler, so only a shelf
+  /// with a "view all" `path` keeps its title there.
+  ///
+  /// - Parameter supportsElements: whether the platform has the iOS 26
+  ///   element API; the legacy image row's text is not optional.
+  static func tileSectionHeader(_ section: Section, supportsElements: Bool) -> String? {
+    supportsElements && section.path == nil ? section.title : nil
+  }
+
+  /// The element family a tile presentation renders on iOS 26+ — here, not
+  /// in the CarPlay factory, so the style→family mapping is testable
+  /// off-device. `gridTile` picks the family (plain by default), in either
+  /// wrap mode: a plain tile is a row element (title + subtitle), an image
+  /// tile an image-grid element (title, shape, accessory). Pre-26 has no element API at all: the treatment drops
+  /// with the legacy image row (decorations drop before layout).
+  enum TileElementFamily: Equatable {
+    case rowElements
+    case imageGridElements
+    case cardElements
+    case condensedElements
+  }
+
+  static func tileFamily(for style: SectionStyle?) -> TileElementFamily {
+    switch style?.gridTile {
+    case .image: .imageGridElements
+    case .card: .cardElements
+    case .condensed: .condensedElements
+    case .plain, nil: .rowElements
+    }
+  }
+}

package/ios/CarPlay/TopTemplateReplacer.swift

@@ -0,0 +1,96 @@
+import Foundation
+import os.log
+
+/// The stack mutations a top-template replacement is made of:
+/// `CPInterfaceController` in the app, a fake in tests.
+@MainActor
+protocol TemplateStack {
+  associatedtype Template: AnyObject
+
+  /// Root first.
+  var templates: [Template] { get }
+
+  /// Unanimated.
+  func popTop(completion: @escaping (Bool, Error?) -> Void)
+  func push(_ template: Template, animated: Bool, completion: @escaping (Bool, Error?) -> Void)
+}
+
+/// Pushes onto a full template stack by replacing its top template — an
+/// unanimated pop, then the push — and holds back every other stack mutation
+/// until both have completed. See "Template Depth" in
+/// `website/guide/carplay.md`.
+@MainActor
+final class TopTemplateReplacer {
+  private let logger = Logger(subsystem: "com.audiobrowser", category: "TemplateStack")
+  private var deferred: [() -> Void] = []
+
+  /// True from the pop until the push completes.
+  private(set) var isReplacing = false
+
+  /// Runs `mutation` now, or — while a replacement is in flight — once it has
+  /// settled, after the mutations that arrived before it.
+  func whenSettled(_ mutation: @escaping () -> Void) {
+    guard isReplacing else {
+      mutation()
+      return
+    }
+    deferred.append(mutation)
+  }
+
+  /// Pushes `template` onto `stack` in place of its top template. When the
+  /// push fails, the popped template is pushed back, so the user stays where
+  /// they were. `completion` reports the push of `template` itself.
+  ///
+  /// Refuses a stack with nothing above the root to replace, and a call made
+  /// while a replacement is in flight: route it through `whenSettled`.
+  func push<Stack: TemplateStack>(
+    _ template: Stack.Template,
+    replacingTopOf stack: Stack,
+    animated: Bool,
+    completion: ((Bool, Error?) -> Void)? = nil,
+  ) {
+    let templates = stack.templates
+    guard !isReplacing, templates.count > 1, let top = templates.last else {
+      logger.error("push skipped: \(Self.name(of: template)) has no template to replace (\(templates.count) templates)")
+      completion?(false, nil)
+      return
+    }
+    isReplacing = true
+    logger.info("push at the depth limit: replacing the top, \(Self.name(of: top)), with \(Self.name(of: template))")
+
+    stack.popTop { [self] popped, error in
+      guard popped else {
+        logger.error("replace abandoned: pop failed, \(Self.name(of: template)) not pushed (\(stack.templates.count) templates)")
+        settle(completion, pushed: false, error: error)
+        return
+      }
+      stack.push(template, animated: animated) { [self] pushed, error in
+        guard !pushed else {
+          settle(completion, pushed: true, error: error)
+          return
+        }
+        logger.error("replace failed: \(Self.name(of: template)) not pushed, restoring \(Self.name(of: top))")
+        stack.push(top, animated: false) { [self] restored, _ in
+          if !restored {
+            logger.error("replace failed: \(Self.name(of: top)) not restored (\(stack.templates.count) templates)")
+          }
+          settle(completion, pushed: false, error: error)
+        }
+      }
+    }
+  }
+
+  private func settle(_ completion: ((Bool, Error?) -> Void)?, pushed: Bool, error: Error?) {
+    // Still replacing here, so a mutation the completion issues queues behind
+    // the ones that arrived during the replacement.
+    completion?(pushed, error)
+    isReplacing = false
+    while !isReplacing, !deferred.isEmpty {
+      deferred.removeFirst()()
+    }
+  }
+
+  private static func name(of template: AnyObject) -> String {
+    String(describing: type(of: template))
+  }
+}

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/NavigationError+Conversion.swift

@@ -8,10 +8,6 @@ extension NavigationError {
       switch browserError {
       case .contentNotFound:
         NavigationError(code: .contentNotFound, message: browserError.localizedDescription, statusCode: nil, statusCodeSuccess: nil)
-      case let .httpError(code, _):
-        NavigationError(code: .httpError, message: browserError.localizedDescription, statusCode: Double(code), statusCodeSuccess: (200 ... 299).contains(code))
-      case .networkError:
-        NavigationError(code: .networkError, message: browserError.localizedDescription, statusCode: nil, statusCodeSuccess: nil)
       case .invalidConfiguration:
         NavigationError(code: .unknownError, message: browserError.localizedDescription, statusCode: nil, statusCodeSuccess: nil)
       case .callbackError:
@@ -54,3 +50,17 @@ extension NavigationError {
     return FormattedNavigationError(title: title, message: message.isEmpty ? nil : message)
   }
 }
+
+extension NavigationError {
+  /// A code-only error: the copy comes from the app's `formatNavigationError` (ADR 0001).
+  static func code(_ code: NavigationErrorType) -> NavigationError {
+    NavigationError(code: code, message: "", statusCode: nil, statusCodeSuccess: nil)
+  }
+}
+
+extension NavigationErrorKind {
+  /// The kind of request a navigation error on `path` came from.
+  init(path: String) {
+    self = BrowserPathHelper.isSearchPath(path) ? .search : .browse
+  }
+}

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,23 @@ 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,
+    icyCharset: String?? = 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 +46,18 @@ 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,
+      icyCharset: icyCharset ?? self.icyCharset,
     )
   }
 }

package/ios/Extension/Section+Copying.swift

@@ -0,0 +1,29 @@
+#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,
+    style: SectionStyle?? = nil,
+    path: String?? = nil,
+    children: [Track]? = nil,
+  ) -> Section {
+    Section(
+      title: title ?? self.title,
+      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, style: nil, path: nil, children: children)
+  }
+}

package/ios/Extension/String+IcyCharset.swift

@@ -0,0 +1,21 @@
+import Foundation
+
+extension String {
+  /// Re-decodes an ICY `StreamTitle` that AVFoundation decoded as Latin-1 with the
+  /// charset the track declares. AVFoundation keeps no raw bytes, so the tell is the
+  /// shape: every scalar at or below U+00FF with at least one at or above U+0080. A
+  /// title already decoded to another script contains higher scalars and is returned
+  /// as is, as is pure ASCII, an unknown charset, or bytes the charset cannot decode.
+  func redecodingIcyTitle(charset: String) -> String {
+    var high = false
+    for scalar in unicodeScalars {
+      if scalar.value > 0xFF { return self }
+      if scalar.value >= 0x80 { high = true }
+    }
+    guard high, let data = data(using: .isoLatin1) else { return self }
+    let cfEncoding = CFStringConvertIANACharSetNameToEncoding(charset as CFString)
+    guard cfEncoding != kCFStringEncodingInvalidId else { return self }
+    let encoding = String.Encoding(rawValue: CFStringConvertEncodingToNSStringEncoding(cfEncoding))
+    return String(data: data, encoding: encoding) ?? self
+  }
+}

package/ios/Extension/TimedMetadata+AVFoundation.swift

@@ -6,11 +6,13 @@ import AVFoundation
 
 extension TimedMetadata {
   /// Creates TimedMetadata from AVMetadataItem array, detecting the metadata format.
-  static func from(items: [AVMetadataItem]) -> TimedMetadata? {
+  /// `icyCharset` is the track's declared charset for ICY titles AVFoundation
+  /// decoded as Latin-1; it never touches ID3 or common metadata.
+  static func from(items: [AVMetadataItem], icyCharset: String? = nil) -> TimedMetadata? {
     // Check for ICY metadata (Shoutcast/Icecast streams)
     let icyItems = items.filter { $0.keySpace == .icy }
     if !icyItems.isEmpty {
-      return fromIcy(items: icyItems)
+      return fromIcy(items: icyItems, icyCharset: icyCharset)
     }
 
     // Check for ID3 metadata (MP3)
@@ -24,7 +26,7 @@ extension TimedMetadata {
   }
 
   /// Creates TimedMetadata from ICY (Shoutcast/Icecast) metadata.
-  static func fromIcy(items: [AVMetadataItem]) -> TimedMetadata? {
+  static func fromIcy(items: [AVMetadataItem], icyCharset: String? = nil) -> TimedMetadata? {
     var title: String?
 
     for item in items {
@@ -35,7 +37,7 @@ extension TimedMetadata {
 
     guard let title else { return nil }
     return TimedMetadata(
-      title: title,
+      title: icyCharset.map { title.redecodingIcyTitle(charset: $0) } ?? title,
       artist: nil,
       album: nil,
       date: nil,

package/ios/Extension/Track+Copying.swift

@@ -11,49 +11,45 @@ extension Track {
   /// `title` uses single-optional (`String?`) since it is non-optional on Track.
   func copying(
     id: String?? = nil,
-    url: String?? = nil,
+    path: String?? = nil,
     src: String?? = nil,
     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,
+    icyCharset: String?? = nil,
   ) -> Track {
     Track(
       id: id ?? self.id,
-      url: url ?? self.url,
+      path: path ?? self.path,
       src: src ?? self.src,
       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,
+      icyCharset: icyCharset ?? self.icyCharset,
     )
   }
 }

package/ios/Extension/Track+Identity.swift

@@ -0,0 +1,18 @@
+#if canImport(NitroModules)
+  import NitroModules
+#endif
+
+/// A track's identity: the opaque `id` when present (non-blank), else the
+/// playable `src`. Two tracks refer to the same item iff their identities are
+/// equal. Browsable-only tracks (neither `id` nor `src`) have no identity —
+/// they are addressed by `path` instead.
+///
+/// This is THE comparison rule for favorites matching, section scoping,
+/// skip-in-place, the car now-playing row indicator, and the contextual
+/// `__trackId` — see ADR 0008. Mirrors `trackIdentity` on the TS side.
+extension Track {
+  var identity: String? {
+    if let id, !id.isEmpty { return id }
+    return src
+  }
+}