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

package/ios/Extension/Track+Copying.swift

@@ -11,49 +11,43 @@ 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,
   ) -> 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,
     )
   }
 }

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
+  }
+}

package/ios/HybridAudioBrowser.swift

@@ -34,6 +34,24 @@ public class HybridAudioBrowser: HybridAudioBrowserSpec, @unchecked Sendable {
   /// silent.
   static let instanceChangedEmitter = Emitter<Void>()
 
+  /// Installed once, on first instance creation. React Native posts this
+  /// notification (from `RCTReloadCommand`) when a JS reload — dev or
+  /// OTA-update restart — is triggered, *before* the old runtime is destroyed:
+  /// the earliest signal that this instance's JS callbacks are about to go
+  /// stale. `init` of the replacement instance drops them too, but only after
+  /// the new runtime is up; this observer closes the window in between.
+  /// Observed by name so the library needs no React-Core dependency (and
+  /// stays inert under SPM tests, where nothing posts it).
+  @MainActor private static let reloadObserver: NSObjectProtocol = NotificationCenter.default.addObserver(
+    forName: Notification.Name("RCTTriggerReloadCommandNotification"),
+    object: nil,
+    queue: .main,
+  ) { _ in
+    MainActor.assumeIsolated {
+      HybridAudioBrowser.shared?.dropStaleJSCallbacks()
+    }
+  }
+
   // MARK: - Private Properties
 
   /// Main-confined by convention, not annotation: `deinit` reads it as a
@@ -70,6 +88,10 @@ public class HybridAudioBrowser: HybridAudioBrowserSpec, @unchecked Sendable {
     playerOptions.carPlayNowPlayingButtons
   }
 
+  @MainActor var carPlayPlayingIndicatorLocation: CarPlayPlayingIndicatorLocation {
+    playerOptions.carPlayPlayingIndicatorLocation
+  }
+
   /// Written from the JS thread, the cooperative pool and MainActor, with a
   /// `didSet` that calls back into Nitro. MainActor-isolated so the compiler
   /// requires an `onMainActor` hop at every access.
@@ -164,7 +186,7 @@ public class HybridAudioBrowser: HybridAudioBrowserSpec, @unchecked Sendable {
   public var configuration: NativeBrowserConfiguration = .init(
     path: nil, request: nil, requestResolver: nil, browse: nil, browseResolver: nil, media: nil, artwork: nil, nowPlayingArtwork: nil, routes: nil,
     singleTrack: nil, handleTrackLoad: nil,
-    androidControllerOfflineError: nil, carPlayLoadingTitle: nil, resolveAlbumUrl: nil, formatNavigationError: nil,
+    androidControllerOfflineError: nil, carPlayLoadingTitle: nil, resolveAlbumPath: nil, formatNavigationError: nil,
   ) {
     didSet {
       // Copied here, on the setter's thread: the Task below outlives this call,
@@ -181,7 +203,7 @@ public class HybridAudioBrowser: HybridAudioBrowserSpec, @unchecked Sendable {
       Task {
         let tabs = try? await browserManager.queryTabs()
         // Navigate to configured path, first tab, or "/"
-        let initialPath = configuredPath ?? tabs?.first?.url ?? "/"
+        let initialPath = configuredPath ?? tabs?.first?.path ?? "/"
         // Clear error before navigation (matches Kotlin clearNavigationError())
         clearNavigationError()
         do {
@@ -213,8 +235,14 @@ public class HybridAudioBrowser: HybridAudioBrowserSpec, @unchecked Sendable {
   /// state, e.g. CarPlay re-seeding `isGated` at scene connect). Serving content
   /// in that window would be a fail-open leak — same direction as the
   /// resolver-error path in `gateDecision`. Matches Android's default.
-  public var resolveGate: (NativeGateRequest) -> Promise<Promise<GateDecision>> = { _ in
-    Promise.resolved(withResult: Promise.resolved(withResult: GateDecision(gated: true, gate: nil)))
+  public var resolveGate: (NativeGateRequest) -> Promise<Promise<GateDecision>> = HybridAudioBrowser.defaultResolveGate
+
+  // Computed, not stored: a nonisolated static holding a non-Sendable closure
+  // is rejected under Swift 6 concurrency checking.
+  static var defaultResolveGate: (NativeGateRequest) -> Promise<Promise<GateDecision>> {
+    { _ in
+      Promise.resolved(withResult: Promise.resolved(withResult: GateDecision(gated: true, gate: nil)))
+    }
   }
 
   /// Fired when a request is gated (served the gate). Set by JS.
@@ -306,7 +334,11 @@ public class HybridAudioBrowser: HybridAudioBrowserSpec, @unchecked Sendable {
     // playerAndConfiguredBrowser OnceValue, so we must explicitly stop
     // its player to prevent two audio streams running simultaneously.
     onMainActor {
+      // Statics are lazy — touch the observer so it's installed from the first
+      // instance onward.
+      _ = HybridAudioBrowser.reloadObserver
       HybridAudioBrowser.shared?.player?.destroy()
+      HybridAudioBrowser.shared?.dropStaleJSCallbacks()
       playerAndConfiguredBrowser.reset()
       HybridAudioBrowser.shared = self
       // Tell connected external controllers (CarPlay) to re-subscribe against
@@ -319,6 +351,38 @@ public class HybridAudioBrowser: HybridAudioBrowserSpec, @unchecked Sendable {
     setupBrowserCallbacks()
   }
 
+  /// Drops every JS-provided callback that native code can invoke on its own
+  /// initiative (browse resolvers, `handleTrackLoad`, `resolveAlbumPath`,
+  /// `formatNavigationError`, `resolveGate`, the now-playing formatter).
+  ///
+  /// Called on the *previous* instance when a new one takes over: its JS runtime
+  /// is gone, and invoking a callback from a dead runtime aborts the process —
+  /// Nitro's `AsyncJSCallback` throws on a destroyed Dispatcher, and the throw
+  /// crosses the generated bridge wrapper's `noexcept` boundary. Native code
+  /// (e.g. a CarPlay controller still bound to this instance mid-reload) keeps
+  /// working off the data-only config with built-in fallbacks; `resolveGate`
+  /// reverts to the fail-closed default it documents for exactly this window.
+  /// One-shot: on a normal reload both triggers hit the same dying instance
+  /// (the reload notification, then the replacement's `init`), and the second
+  /// strip would re-fire the config-setter cascade — another `onConfigChanged`
+  /// → CarPlay now-playing button rebuild — for nothing.
+  @MainActor private var didDropJSCallbacks = false
+
+  @MainActor
+  private func dropStaleJSCallbacks() {
+    guard !didDropJSCallbacks else { return }
+    didDropJSCallbacks = true
+    // Guarded: assigning `config` marks the browser configured (the setter's
+    // didSet), and a never-configured browser must keep cold-start waiters
+    // (CarPlay, Siri) blocked on the readiness gate rather than resolve them
+    // against an empty config.
+    if browserManager.isConfigured {
+      browserManager.config = browserManager.config.strippingJSCallbacks()
+    }
+    resolveGate = Self.defaultResolveGate
+    nowPlayingMetadataFormatter = nil
+  }
+
   deinit {
     // Safety net: ensure the AVPlayer is stopped if this instance is deallocated.
     let player = self.player
@@ -447,8 +511,8 @@ public class HybridAudioBrowser: HybridAudioBrowserSpec, @unchecked Sendable {
         executePlayback(intent)
       case .intercepted:
         break
-      case let .browse(url):
-        navigateToBrowsableUrl(url)
+      case let .browse(path):
+        navigateToBrowsablePath(path)
       case .none:
         break
       }
@@ -472,13 +536,13 @@ public class HybridAudioBrowser: HybridAudioBrowserSpec, @unchecked Sendable {
     }
   }
 
-  private func navigateToBrowsableUrl(_ url: String) {
+  private func navigateToBrowsablePath(_ path: String) {
     clearNavigationError()
     Task {
       do {
-        try await browserManager.navigate(url)
+        try await browserManager.navigate(path)
       } catch {
-        handleNavigationError(error, path: url)
+        handleNavigationError(error, path: path)
       }
     }
   }
@@ -487,7 +551,7 @@ public class HybridAudioBrowser: HybridAudioBrowserSpec, @unchecked Sendable {
     Promise.async { [weak self] in
       guard let self else { return [] }
       let resolved = try await browserManager.search(query)
-      return resolved.children ?? []
+      return resolved.flattenedChildren ?? []
     }
   }
 
@@ -739,11 +803,16 @@ public class HybridAudioBrowser: HybridAudioBrowserSpec, @unchecked Sendable {
           return await browserManager.resolveMediaUrl(src, track: track)
         }
 
-        // Configure artwork URL resolver for Now Playing (with size context)
+        // Configure artwork URL resolver for Now Playing (with size context). The
+        // `nowPlayingArtwork` config runs for EVERY playing track, id or not — an id-less track
+        // leaves any `{id}` token unfilled (resolveArtworkUrl warns and the request visibly
+        // 404s) rather than skipping the config.
         player?.nowPlayingUpdater.artworkUrlResolver = { [weak self] track, imageContext in
           guard let self else { return nil }
-          let perRoute = (track.id?.isEmpty == false) ? browserManager.config.nowPlayingArtwork : nil
-          return await browserManager.resolveArtworkUrl(track: track, perRouteConfig: perRoute, imageContext: imageContext)
+          return await browserManager.resolveArtworkUrl(
+            track: track, perRouteConfig: browserManager.config.nowPlayingArtwork,
+            imageContext: imageContext,
+          )
         }
 
         // Emit the JS `onNowPlayingChanged` event when the rendered text lines change. The updater
@@ -813,9 +882,9 @@ public class HybridAudioBrowser: HybridAudioBrowserSpec, @unchecked Sendable {
       // Update stored options
       playerOptions.update(from: options)
 
-      // Propagate the favorite match mode to the browser so it can hydrate
+      // Propagate the favorite flag to the browser so it can hydrate
       // row hearts (the `favorite` capability is the single favoriting switch).
-      browserManager.setFavoriteMatch(playerOptions.capabilities.favoriteMatch)
+      browserManager.setFavoriteEnabled(playerOptions.capabilities.favoriteEnabled)
 
       // Apply remote commands to player
       applyRemoteCommands()
@@ -1064,23 +1133,24 @@ public class HybridAudioBrowser: HybridAudioBrowserSpec, @unchecked Sendable {
 
   public func setActiveTrackFavorited(favorited: Bool) throws {
     onMainActor {
-      guard let track = player?.currentTrack, let src = track.src else { return }
+      guard let track = player?.currentTrack, let identity = track.identity else { return }
       guard let index = player?.currentIndex, index >= 0 else { return }
-      // Optimistically reflect in the authoritative match set so the now-playing
-      // heart (hydrated from it in getActiveTrack) flips immediately; native
-      // reconciles to its canonical ids on the next setFavorites.
-      browserManager.setFavorited(src: src, favorited: favorited)
+      // Optimistically reflect in the authoritative favorite set so the
+      // now-playing heart (hydrated from it in getActiveTrack) flips
+      // immediately; the consumer reconciles to its canonical identities on
+      // the next setFavorites.
+      browserManager.setFavorited(identity: identity, favorited: favorited)
       let updatedTrack = track.copying(favorited: favorited)
+      // Hydration never overrides a caller-set `favorited`, so the queued
+      // track must itself carry the latest explicit value (as Android's tag
+      // swap and web's replaceTrack do).
+      player?.replace(index, updatedTrack)
+      // The ONLY emit: a favorite toggle is an in-place mutation of the active
+      // track, not a transition — onPlaybackActiveTrackChanged stays
+      // transition-only, and the useActiveTrack / useQueue hooks subscribe to
+      // onFavoriteChanged themselves. Native surfaces (CarPlay heart) observe
+      // favoriteChangedEmitter / onFavoritesChanged directly.
       favoriteChangedEmitter.emit(FavoriteChangedEvent(track: updatedTrack, favorited: favorited))
-      // Fire active track changed so the now-playing heart + useActiveTrack() refresh.
-      let position = player?.currentTime ?? 0
-      activeTrackChangedEmitter.emit(PlaybackActiveTrackChangedEvent(
-        lastIndex: Double(index),
-        lastTrack: track,
-        lastPosition: position,
-        index: Double(index),
-        track: updatedTrack,
-      ))
     }
   }
 
@@ -1220,7 +1290,7 @@ public class HybridAudioBrowser: HybridAudioBrowserSpec, @unchecked Sendable {
       duration: track.duration,
       artwork: nowPlayingArtwork(for: track),
       description: track.description,
-      mediaId: track.src ?? track.url,
+      mediaId: track.src ?? track.path,
       genre: track.genre,
     )
   }
@@ -1809,14 +1879,22 @@ extension HybridAudioBrowser: TrackPlayerCallbacks {
           browser.showNowPlayingRequestedEmitter.emit(())
           completion(true)
         } else if let state = browser.playbackStateStore.load() {
-          browser.logger.info("resume: cold — restoring persisted track")
           let track = state.track.toNitro()
+          // The persisted track can carry `disabled` — it became unavailable
+          // after it was saved. A disabled track never plays, resumption
+          // included (Track.disabled).
+          if track.disabled == true {
+            browser.logger.info("resume: persisted track is disabled — refusing")
+            completion(false)
+            return
+          }
+          browser.logger.info("resume: cold — restoring persisted track")
           let startMs = (track.live == true) ? nil : state.positionMs
           // Match Android resume: re-expand the full queue from the track's contextual
-          // URL (parent container → siblings + selected index). Fall back to the single
-          // track when the url isn't contextual or expansion fails.
-          if let url = state.track.url,
-             let expanded = try? await browser.browserManager.expandQueueFromContextualUrl(url)
+          // path (parent container → siblings + selected index). Fall back to the single
+          // track when the path isn't contextual or expansion fails.
+          if let path = state.track.path,
+             let expanded = try? await browser.browserManager.expandQueueFromContextualPath(path)
           {
             player.setQueue(expanded.tracks, initialIndex: expanded.selectedIndex, startPositionMs: startMs, playWhenReady: true)
           } else {

package/ios/Model/NitroTypeStubs.swift

@@ -5,6 +5,12 @@
   /// These stubs declare `Equatable` for test ergonomics — the generated
   /// Nitro types do NOT. Shared `ios/` sources must not rely on conformances
   /// that exist only here: `swift test` compiles, the app build breaks.
+  ///
+  /// Property names and types ARE checked against `nitrogen/generated/ios/swift`
+  /// by `src/nitro-stub-drift.test.ts`, which runs in the JS CI job — neither
+  /// native job can see both files at once. Declaring fewer properties than the
+  /// real type is fine and deliberate; spelling one differently is what that
+  /// test catches. Conformances and default values are still on you.
 
   struct ArtworkVariants: Equatable {
     var light: String
@@ -23,19 +29,19 @@
   }
 
   struct Track: Equatable {
-    var id: String
-    var url: String?
+    var id: String?
+    var path: String?
     var src: String?
+    var artwork: Variant_String_ArtworkVariants?
+    var artworkSource: ImageSource?
     var request: TrackRequest?
     var title: String = ""
     var artist: String?
-    var albumUrl: String?
+    var albumPath: String?
     var album: String?
+    var style: TrackStyle?
+    var disabled: Bool?
     var live: Bool?
-    var artwork: Variant_String_ArtworkVariants?
-    var artworkSource: ImageSource?
-    var groupTitle: String?
-    var imageRow: [ImageRowItem]?
   }
 
   struct TrackLoadEvent {
@@ -63,14 +69,24 @@
     }
   }
 
+  enum HttpMethod {
+    case get
+    case post
+    case put
+    case patch
+    case delete
+    case head
+    case options
+  }
+
   struct ImageSource: Equatable {
     var uri: String
-    var method: String?
+    var method: HttpMethod?
     var headers: [String: String]?
     var body: String?
   }
 
-  enum TrackStyle {
+  enum StyleDisplay: Equatable {
     case list
     case grid
 
@@ -83,17 +99,46 @@
     }
   }
 
-  struct ImageRowItem: Equatable {
-    var id: String?
-    var url: String?
-    var src: String?
-    var artwork: String?
-    var artworkSource: ImageSource?
-    var title: String
+  enum ArtworkRendering: Equatable {
+    case original
+    case stencil
+
+    init?(fromString string: String) {
+      switch string {
+      case "original": self = .original
+      case "stencil": self = .stencil
+      default: return nil
+      }
+    }
+  }
+
+  struct TrackStyle: Equatable {
+    var display: StyleDisplay?
+    var artworkRendering: ArtworkRendering?
+  }
+
+  // Member order matches the generated init (own properties before inherited
+  // ones — Nitro flattens `extends` own-props-first): the memberwise init this
+  // produces must accept the same argument order as the real type, or
+  // `swift test` passes while the app build breaks on argument order.
+  struct SectionStyle: Equatable {
+    var gridWrap: Bool?
+    var display: StyleDisplay?
+    var artworkRendering: ArtworkRendering?
+  }
+
+  struct Section: Equatable {
+    var title: String?
+    var subtitle: String?
+    var style: SectionStyle?
+    var path: String?
+    var children: [Track]
   }
 
   struct ResolvedTrack: Equatable {
-    var url: String
+    var path: String
+    var style: SectionStyle?
+    var sections: [Section]?
     var children: [Track]?
     var carPlaySiriListButton: CarPlaySiriListButtonPosition?
     var id: String?
@@ -101,21 +146,17 @@
     var artwork: Variant_String_ArtworkVariants?
     var artworkSource: ImageSource?
     var request: TrackRequest?
-    var artworkCarPlayTinted: Bool?
     var title: String
     var subtitle: String?
     var artist: String?
-    var albumUrl: String?
+    var albumPath: String?
     var album: String?
     var description: String?
     var genre: String?
     var duration: Double?
-    var style: TrackStyle?
-    var childrenStyle: TrackStyle?
+    var disabled: Bool?
     var favorited: Bool?
-    var groupTitle: String?
     var live: Bool?
-    var imageRow: [ImageRowItem]?
   }
 
   enum PlaybackState: Equatable {

package/ios/Model/PlayerUpdateOptions.swift

@@ -32,6 +32,9 @@ class PlayerUpdateOptions {
   /// Custom buttons for the CarPlay Now Playing screen
   var carPlayNowPlayingButtons: [CarPlayNowPlayingButton] = []
 
+  /// Where the now-playing indicator draws on CarPlay list rows
+  var carPlayPlayingIndicatorLocation: CarPlayPlayingIndicatorLocation = .leading
+
   // MARK: - Initialization
 
   init() {}
@@ -74,6 +77,9 @@ class PlayerUpdateOptions {
       if let buttons = ios.carPlayNowPlayingButtons {
         carPlayNowPlayingButtons = buttons
       }
+      if let location = ios.carPlayPlayingIndicatorLocation {
+        carPlayPlayingIndicatorLocation = location
+      }
     }
   }
 
@@ -92,6 +98,7 @@ class PlayerUpdateOptions {
         playbackRates: playbackRates,
         carPlayUpNextButton: carPlayUpNextButton,
         carPlayNowPlayingButtons: carPlayNowPlayingButtons,
+        carPlayPlayingIndicatorLocation: carPlayPlayingIndicatorLocation,
       ),
     )
   }

package/ios/Player/NowPlayingUpdater.swift

@@ -130,7 +130,7 @@ final class NowPlayingUpdater {
     let resolvedArtist = artist ?? track.artist
     let resolvedAlbum = album ?? track.album
     let published = Published(
-      trackId: track.src ?? track.url,
+      trackId: track.identity ?? track.path,
       title: resolvedTitle,
       artist: resolvedArtist,
       album: resolvedAlbum,

package/ios/Player/PlaybackCoordinator.swift

@@ -691,14 +691,14 @@ class PlaybackCoordinator {
       guard let src = currentTrack.src else {
         logger.error("Failed to load track - no src")
         logger.error("  track.title: \(currentTrack.title)")
-        logger.error("  track.url: \(currentTrack.url ?? "nil")")
+        logger.error("  track.path: \(currentTrack.path ?? "nil")")
         effectHandler?.clearCurrentItem()
         transition(.errorOccurred(.invalidSourceUrl("nil")))
         return
       }
 
       logger.debug("Loading track: \(currentTrack.title)")
-      logger.debug("  track.url: \(currentTrack.url ?? "nil")")
+      logger.debug("  track.path: \(currentTrack.path ?? "nil")")
       logger.debug("  track.src: \(src)")
 
       effectHandler?.loadTrack(src: src, track: currentTrack)

package/ios/Player/RetryManager.swift

@@ -123,9 +123,10 @@ class RetryManager {
 
   // MARK: - Error Classification
 
-  /// HTTP statuses worth another attempt. Same set as Android's
-  /// `RetryLoadErrorHandlingPolicy.RETRYABLE_HTTP_STATUS_CODES`, so a flaky
-  /// server behaves the same on both platforms.
+  /// HTTP statuses worth another attempt, beyond the 500–599 range checked in
+  /// `isRetryable`. Android's `RetryLoadErrorHandlingPolicy` shares 408/429 but
+  /// enumerates only 500/502/503/504 of the 5xx range, so uncommon 5xx codes
+  /// (501, 505…) retry here and not there.
   private static let retryableHTTPStatusCodes: Set<Int> = [408, 429]
 
   /// AVFoundation failures a retry cannot fix: the media is unusable rather

package/ios/Tests/BrowserPathHelperTests.swift

@@ -74,6 +74,56 @@ import Testing
   #expect(result == "/items?a=1&m=2&z=3")
 }
 
+// MARK: - build
+
+@Test func buildAppendsTrackIdWithQuestionMark() {
+  let result = BrowserPathHelper.build(parentPath: "/library", trackId: "song.mp3")
+  #expect(result == "/library?__trackId=song.mp3")
+}
+
+@Test func buildAppendsTrackIdWithAmpersandWhenParentHasQuery() {
+  let result = BrowserPathHelper.build(parentPath: "/search?q=jazz", trackId: "song.mp3")
+  #expect(result == "/search?q=jazz&__trackId=song.mp3")
+}
+
+@Test func buildRoundTripsSrcWithQueryParams() {
+  // A src carrying its own query string (signed CDN URL) must survive the
+  // build → extract/strip round-trip: an unescaped `&` splits the src into
+  // stray query params, truncating the trackId and polluting the parent path.
+  let src = "https://cdn.example.com/stream.mp3?token=abc&exp=1699999999"
+  let url = BrowserPathHelper.build(parentPath: "/library", trackId: src)
+  #expect(BrowserPathHelper.extractTrackId(url) == src)
+  #expect(BrowserPathHelper.stripTrackId(url) == "/library")
+}
+
+@Test func buildRoundTripsSrcWithEqualsAndPlus() {
+  let src = "https://cdn.example.com/a+b.mp3?sig=x=y"
+  let url = BrowserPathHelper.build(parentPath: "/library", trackId: src)
+  #expect(BrowserPathHelper.extractTrackId(url) == src)
+  #expect(BrowserPathHelper.stripTrackId(url) == "/library")
+}
+
+@Test func buildStampsTheIndexAndRoundTripsIt() {
+  let src = "https://cdn.example.com/stream.mp3?token=abc&exp=1"
+  let url = BrowserPathHelper.build(parentPath: "/library", trackId: src, index: 3)
+  #expect(BrowserPathHelper.extractTrackId(url) == src)
+  #expect(BrowserPathHelper.extractIndex(url) == 3)
+  #expect(BrowserPathHelper.stripTrackId(url) == "/library")
+}
+
+// MARK: - extractIndex
+
+@Test func extractIndexReturnsNilWithoutAStampedIndex() {
+  let url = BrowserPathHelper.build(parentPath: "/library", trackId: "song.mp3")
+  #expect(BrowserPathHelper.extractIndex(url) == nil)
+}
+
+@Test func extractIndexReturnsNilForNonContextualOrMalformedIndex() {
+  #expect(BrowserPathHelper.extractIndex("/library") == nil)
+  #expect(BrowserPathHelper.extractIndex("/library?__trackId=song.mp3&__index=x") == nil)
+  #expect(BrowserPathHelper.extractIndex("/library?__trackId=song.mp3&__index=-1") == nil)
+}
+
 // MARK: - stripTrackId
 
 @Test func stripTrackIdRemovesTrackParam() {
@@ -116,23 +166,3 @@ import Testing
 @Test func isContextualReturnsTrueWithAmpersandSeparator() {
   #expect(BrowserPathHelper.isContextual("/lib?q=1&__trackId=x") == true)
 }
-
-// MARK: - containsSegment
-
-@Test func containsSegmentMatchesFullSegments() {
-  let path = "/listen/amsterdam-funk-channel/Gw0LGB8j"
-  #expect(BrowserPathHelper.containsSegment(path, "Gw0LGB8j"))
-  #expect(BrowserPathHelper.containsSegment(path, "amsterdam-funk-channel"))
-  #expect(BrowserPathHelper.containsSegment(path, "listen"))
-  #expect(BrowserPathHelper.containsSegment("/listen/x/Gw0LGB8j?hl=en", "Gw0LGB8j"))
-  #expect(BrowserPathHelper.containsSegment("/listen/x/Gw0LGB8j#frag", "Gw0LGB8j"))
-}
-
-@Test func containsSegmentRejectsPartialAndMissing() {
-  let path = "/listen/amsterdam-funk-channel/Gw0LGB8j"
-  #expect(!BrowserPathHelper.containsSegment(path, "Gw0LGB8"))
-  #expect(!BrowserPathHelper.containsSegment(path, "funk"))
-  #expect(!BrowserPathHelper.containsSegment(path, "msterdam-funk-channe"))
-  #expect(!BrowserPathHelper.containsSegment(path, "NopeNope"))
-  #expect(!BrowserPathHelper.containsSegment(path, ""))
-}