react-native-audio-browser 0.2.0-next.11 → 0.2.0-next.13

package/ios/Player/MediaLoader.swift

@@ -38,19 +38,28 @@ final class MediaLoader {
   func resolveAndLoad(src: String, track: Track? = nil) {
     if let resolver = mediaUrlResolver {
       mediaResolverTask?.cancel()
-      mediaResolverTask = Task {
-        self.logger.debug("resolveAndLoad: starting resolution for \(src)")
+      // `[weak self]` like the sibling load tasks below: the resolver is
+      // consumer-supplied and `cancelAll()` cannot force an in-flight `await`
+      // to return, so a strong capture let a resolver that never settles pin
+      // this loader (which also retains the task) indefinitely.
+      // `Logger` is a value type, so capturing it directly keeps the logging
+      // off `self` — and `self` weak, so a consumer resolver that never settles
+      // can't pin the loader (`cancelAll()` can't force an in-flight `await` to
+      // return).
+      let logger = logger
+      mediaResolverTask = Task { [weak self] in
+        logger.debug("resolveAndLoad: starting resolution for \(src)")
 
         guard !Task.isCancelled else {
-          self.logger.debug("resolveAndLoad: cancelled before start")
+          logger.debug("resolveAndLoad: cancelled before start")
           return
         }
 
-        self.logger.debug("resolveAndLoad: calling resolver...")
+        logger.debug("resolveAndLoad: calling resolver...")
         let resolved = await resolver(src, track)
 
-        guard !Task.isCancelled else {
-          self.logger.debug("resolveAndLoad: cancelled after resolver returned")
+        guard !Task.isCancelled, let self else {
+          logger.debug("resolveAndLoad: cancelled after resolver returned")
           return
         }
 
@@ -96,7 +105,7 @@ final class MediaLoader {
         .availableMetadataFormats,
       ) else { return }
 
-      guard !Task.isCancelled, pendingAsset == asset else { return }
+      guard isCurrent(pendingAsset) else { return }
 
       if !commonMetadata.isEmpty {
         delegate?.mediaLoaderDidReceiveCommonMetadata(commonMetadata)
@@ -104,19 +113,21 @@ final class MediaLoader {
 
       if !chapterLocales.isEmpty {
         for locale in chapterLocales {
-          guard !Task.isCancelled else { return }
+          guard isCurrent(pendingAsset) else { return }
           if let chapters = try? await pendingAsset.loadChapterMetadataGroups(
             withTitleLocale: locale,
             containingItemsWithCommonKeys: [],
           ) {
+            guard isCurrent(pendingAsset) else { return }
             delegate?.mediaLoaderDidReceiveChapterMetadata(chapters)
           }
         }
       } else {
         let duration = await (try? pendingAsset.load(.duration)) ?? .zero
         for format in metadataFormats {
-          guard !Task.isCancelled else { return }
+          guard isCurrent(pendingAsset) else { return }
           if let metadata = try? await pendingAsset.loadMetadata(for: format) {
+            guard isCurrent(pendingAsset) else { return }
             let timeRange = CMTimeRange(
               start: CMTime(seconds: 0, preferredTimescale: 1000),
               end: duration,
@@ -159,6 +170,19 @@ final class MediaLoader {
     }
   }
 
+  /// Whether `candidate` is still the load this loader cares about — checked
+  /// after EVERY await, not just once before a loop.
+  ///
+  /// Cancellation alone is not enough: it only sets a flag, and can't abort a
+  /// load already in flight inside AVFoundation (only `cancelLoading()` does,
+  /// and the track-change path deliberately doesn't call it — the old asset
+  /// still backs the playing item at that point). So a load that lands after
+  /// the track changed would otherwise attribute the old asset's metadata to
+  /// the newly loaded track.
+  private func isCurrent(_ candidate: AVURLAsset) -> Bool {
+    !Task.isCancelled && candidate == asset
+  }
+
   func cancelAll() {
     mediaResolverTask?.cancel()
     mediaResolverTask = nil

package/ios/Player/NowPlayingUpdater.swift

@@ -30,17 +30,51 @@ final class NowPlayingUpdater {
     let album: String?
   }
 
+  /// Dedupe baseline for `applyFields`. Only meaningful while it describes the
+  /// controller's current info dict, so the two are cleared together in
+  /// `clearNowPlaying()` — never separately.
   private var lastPublished: Published?
 
+  /// Empties the now-playing surface and the dedupe baseline that describes it.
+  /// One call, because clearing the dict without the baseline makes the next
+  /// publish of the SAME track dedupe against a dict that no longer holds it —
+  /// artwork lands (never deduped) but the text doesn't, and `onChanged`
+  /// never fires.
+  func clearNowPlaying() {
+    nowPlayingInfoController.clear()
+    lastPublished = nil
+    formattedTrackId = nil
+  }
+
   /// Bumped on every `render`; an async formatter result applies only if its render is still the
   /// latest (latest-render-wins — drops a result whose track skipped or whose state moved on while
   /// the formatter was in flight).
   private var renderGeneration: UInt = 0
 
+  /// The track whose *formatted* line is currently on the surface. While this
+  /// matches the rendering track, `render` skips its interim default write — see
+  /// the comment at that site. Cleared whenever the surface stops showing a
+  /// formatter result (a flash overwrites it, `clearNowPlaying` empties it).
+  private var formattedTrackId: String?
+
   init(nowPlayingInfoController: NowPlayingInfoController) {
     self.nowPlayingInfoController = nowPlayingInfoController
   }
 
+  /// Pixel width to request now-playing artwork at: the active scene's screen
+  /// width in pixels, capped at `maxArtworkPixelWidth`. With no foreground
+  /// scene (headless CarPlay) the cap stands in — every current device exceeds
+  /// it anyway, and this only sizes a CDN request.
+  private static var artworkPixelWidth: CGFloat {
+    guard let screen = UIApplication.shared.activeWindowScene?.screen else {
+      return maxArtworkPixelWidth
+    }
+    return min(screen.bounds.width * screen.scale, maxArtworkPixelWidth)
+  }
+
+  /// Mirrored by the Kotlin twin's `artworkSizePx`.
+  private static let maxArtworkPixelWidth: CGFloat = 1200
+
   /// Publishes the static, per-track fields + artwork on a track change. The title/artist/album
   /// lines are owned by `render` (routed through `applyFields` here so it dedupes against later
   /// renders).
@@ -75,6 +109,8 @@ final class NowPlayingUpdater {
     let defaultSecondary = override?.artist ?? track.artist
     let defaultAlbum = override?.album ?? track.album
 
+    let trackId = track.identity ?? track.path
+
     if let flash {
       applyFields(
         track: track,
@@ -82,10 +118,22 @@ final class NowPlayingUpdater {
         artist: flash.artist ?? defaultSecondary,
         album: flash.album ?? defaultAlbum,
       )
+      // The flash replaced the formatter's line, so the surface no longer shows
+      // one: the render that follows the flash reverting must publish the default
+      // immediately rather than sit on stale flash text awaiting the formatter.
+      formattedTrackId = nil
       return
     }
 
-    applyFields(track: track, title: defaultTitle, artist: defaultSecondary, album: defaultAlbum)
+    // Publish the raw default only while no formatter result is on screen for this
+    // track. `render` runs on EVERY playback transition (state change, playing/
+    // buffering flip, timed-metadata tick, connectivity change); writing the
+    // default each time would flash the track title over the formatter's line
+    // until the async result lands, since the two differ by construction on a live
+    // stream (station name vs. song line).
+    if formatter == nil || formattedTrackId != trackId {
+      applyFields(track: track, title: defaultTitle, artist: defaultSecondary, album: defaultAlbum)
+    }
 
     guard let formatter else { return }
     let params = FormatNowPlayingParams(
@@ -111,6 +159,9 @@ final class NowPlayingUpdater {
             artist: formatted.artist ?? defaultSecondary,
             album: formatted.album ?? defaultAlbum,
           )
+          // A formatter result now owns the surface for this track, so later
+          // renders skip the interim default write.
+          self.formattedTrackId = trackId
         }
       }
       .catch { @Sendable [weak self] error in
@@ -130,7 +181,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,
@@ -152,10 +203,7 @@ final class NowPlayingUpdater {
     let artworkUrl = track.artworkSource?.uri ?? track.artwork?.url
     logger.debug("loadArtwork: \(track.title), artworkUrl: \(artworkUrl ?? "nil")")
 
-    // Now Playing artwork: use screen width in pixels, capped at 1200px
-    let screenScale = UIScreen.main.scale
-    let screenWidth = UIScreen.main.bounds.width * screenScale
-    let artworkSize = min(screenWidth, 1200)
+    let artworkSize = Self.artworkPixelWidth
     let nowPlayingSize = ImageContext(width: artworkSize, height: artworkSize)
 
     artworkLoadTask?.cancel()

package/ios/Player/PlaybackCoordinator.swift

@@ -526,14 +526,21 @@ class PlaybackCoordinator {
         let changed = queue.add([track], initialIndex: 0)
         if changed { handleCurrentTrackChanged() }
       } else {
-        queue.replace(queue.currentIndex, track)
-        handleCurrentTrackChanged()
+        // `currentIndex` is invariantly -1 or in bounds, and -1 took the branch
+        // above, so this cannot fail — but surface it rather than reloading the
+        // old track if that invariant is ever broken.
+        do {
+          try queue.replace(queue.currentIndex, track)
+          handleCurrentTrackChanged()
+        } catch {
+          logger.error("load: replace at \(self.queue.currentIndex) failed: \(error)")
+        }
       }
     }
   }
 
-  func replace(_ index: Int, _ track: Track) {
-    queue.replace(index, track)
+  func replace(_ index: Int, _ track: Track) throws {
+    try queue.replace(index, track)
   }
 
   func setQueue(
@@ -691,14 +698,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/PlaybackTimer.swift

@@ -48,10 +48,16 @@ final class PlaybackTimer {
 
   private func start(_ interval: TimeInterval) {
     guard timer == nil else { return }
-    timer = Timer.scheduledTimer(withTimeInterval: interval, repeats: true) {
-      [weak self] _ in
+    // `.common`, not the `.default` mode `Timer.scheduledTimer` installs: UIKit
+    // runs the main run loop in tracking mode while a list is being dragged, and
+    // a default-mode timer does not fire there. Missed repeats are dropped rather
+    // than replayed, so progress events would freeze and interval ticks would be
+    // lost for as long as the user scrolls. (VolumeFader already does this.)
+    let timer = Timer(timeInterval: interval, repeats: true) { [weak self] _ in
       MainActor.assumeIsolated { self?.onTick() }
     }
+    self.timer = timer
+    RunLoop.main.add(timer, forMode: .common)
   }
 
   private func stop() {

package/ios/Player/QueueManager.swift

@@ -225,11 +225,8 @@ class QueueManager {
     let wasEmpty = tracks.isEmpty
     let insertIndex = tracks.count
     tracks.append(contentsOf: newTracks)
+    if wasEmpty { return adoptInitialCurrent(initialIndex) }
     shuffleOrder.insert(at: insertIndex, count: newTracks.count)
-    if wasEmpty {
-      currentIndex = max(0, min(initialIndex, tracks.count - 1))
-      return true
-    }
     return false
   }
 
@@ -250,14 +247,31 @@ class QueueManager {
       currentIndex += newTracks.count
     }
     tracks.insert(contentsOf: newTracks, at: index)
+    if wasEmpty { return adoptInitialCurrent(0) }
     shuffleOrder.insert(at: index, count: newTracks.count)
-    if wasEmpty {
-      currentIndex = 0
-      return true
-    }
     return false
   }
 
+  /// The queue was empty: `index` becomes the current track AND leads the
+  /// shuffle order. One operation because the two must not be separable —
+  /// forgetting the second half is the bug this exists to prevent.
+  ///
+  /// `insert(at:count:)` drops new indices at *random* shuffle positions, so
+  /// without the pin the starting track can land last in the order, which reads
+  /// as `isLastInPlaybackOrder`: the queue "ends" (and fires
+  /// `playerDidEndQueue`) the moment the first track finishes. Pins
+  /// unconditionally, like `setQueue` — the order has to be sane whether or not
+  /// shuffle is on right now, since `shuffleEnabled`'s didSet only re-pins on
+  /// the off→on edge.
+  ///
+  /// Returns true, so callers can `return adoptInitialCurrent(…)` to report the
+  /// current track changed.
+  private func adoptInitialCurrent(_ index: Int) -> Bool {
+    currentIndex = max(0, min(index, tracks.count - 1))
+    shuffleOrder = ShuffleOrder(length: tracks.count, firstIndex: currentIndex)
+    return true
+  }
+
   /// Remove a track from the queue.
   /// Returns `true` if the current track changed.
   @discardableResult
@@ -288,8 +302,18 @@ class QueueManager {
     let insertion = min(newTracks.count, toIndex)
     newTracks.insert(track, at: insertion)
     tracks = newTracks
+    // Carry the moved track's shuffle position across the move. `insert(at:count:)`
+    // would drop it at a RANDOM position instead — reordering the queue would then
+    // silently reorder shuffled playback, and moving the playing track could land it
+    // last in the order, ending the queue at the next track boundary with tracks
+    // still unplayed (the failure `adoptInitialCurrent` guards against elsewhere).
+    // `remove` shifts every later position down by one, so re-inserting at the
+    // captured position restores the exact prior order.
+    let shufflePosition = shuffleOrder.shufflePosition(of: fromIndex)
     shuffleOrder.remove(from: fromIndex, to: fromIndex + 1)
-    shuffleOrder.insert(at: insertion, count: 1)
+    shuffleOrder.insert(
+      at: insertion, atShufflePosition: shufflePosition ?? shuffleOrder.count,
+    )
     // The pointer follows the playing track; its identity never changes on a
     // move, so no caller needs to reload (returning true reloads).
     if currentIndex == fromIndex {
@@ -317,7 +341,9 @@ class QueueManager {
   // MARK: - Other Mutations
 
   /// Replace the track at a specific index.
-  func replace(_ index: Int, _ track: Track) {
+  /// Throws like every other index-taking mutation here, rather than trapping.
+  func replace(_ index: Int, _ track: Track) throws {
+    try throwIfIndexInvalid(index: index)
     tracks[index] = track
   }
 

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/Player/ShuffleOrder.swift

@@ -101,6 +101,13 @@ struct ShuffleOrder {
     return indexInShuffled[index] == 0
   }
 
+  /// The item's position in the shuffle order, or nil when it has none.
+  func shufflePosition(of index: Int) -> Int? {
+    guard index >= 0, index < indexInShuffled.count else { return nil }
+    let position = indexInShuffled[index]
+    return position >= 0 ? position : nil
+  }
+
   // MARK: - Mutation
 
   /// Inserts items at random positions in the shuffle order
@@ -125,6 +132,22 @@ struct ShuffleOrder {
     indexInShuffled = Self.buildIndexInShuffled(from: shuffled)
   }
 
+  /// Inserts one item at `insertionIndex`, placing it at an explicit shuffle
+  /// position rather than a random one.
+  ///
+  /// Used by a queue `move`, which permutes positions but not identities: the
+  /// item already had a place in the playback order, and re-randomising it
+  /// silently reorders playback. For the *playing* track it can drop it at the
+  /// end of the order, which then reads as `isLastInPlaybackOrder` — the queue
+  /// reports itself over at the next track end, with tracks still unplayed.
+  mutating func insert(at insertionIndex: Int, atShufflePosition position: Int) {
+    for i in 0 ..< shuffled.count where shuffled[i] >= insertionIndex {
+      shuffled[i] += 1
+    }
+    shuffled.insert(insertionIndex, at: min(max(0, position), shuffled.count))
+    indexInShuffled = Self.buildIndexInShuffled(from: shuffled)
+  }
+
   /// Removes items in the specified range from the shuffle order
   mutating func remove(from indexFrom: Int, to indexToExclusive: Int) {
     let removeCount = indexToExclusive - indexFrom

package/ios/Player/SleepTimerHandling.swift

@@ -12,4 +12,17 @@ import Foundation
   @discardableResult func clear() -> Bool
   func onTrackChanged()
   func onTrackPlayedToEnd()
+
+  // Consumer-facing surface — HybridAudioBrowser drives these through
+  // TrackPlayer, so they belong here rather than behind a concrete downcast.
+
+  /// Invoked when the timer state changes (set, cleared, completed).
+  var onChanged: ((SleepTimerState) -> Void)? { get set }
+  /// The current timer state, or nil when no timer is active.
+  func get() -> SleepTimerState?
+  /// Sets a time-based timer, optionally fading out over the last
+  /// `fadeDuration` seconds.
+  func set(seconds: TimeInterval, fadeDuration: TimeInterval?)
+  /// Sets the timer to stop playback when the current track ends.
+  func setToEndOfTrack()
 }

package/ios/RemoteCommand/RemoteCommandController.swift

@@ -281,24 +281,59 @@ class RemoteCommandController {
 
   // MARK: - Handlers
 
-  lazy var handlePlayCommand: RemoteCommandHandler = handlePlayCommandDefault
-  lazy var handlePauseCommand: RemoteCommandHandler = handlePauseCommandDefault
-  lazy var handleStopCommand: RemoteCommandHandler = handleStopCommandDefault
-  lazy var handleTogglePlayPauseCommand: RemoteCommandHandler =
-    handleTogglePlayPauseCommandDefault
-  lazy var handleSkipForwardCommand: RemoteCommandHandler = handleSkipForwardCommandDefault
-  lazy var handleSkipBackwardCommand: RemoteCommandHandler = handleSkipBackwardDefault
-  lazy var handleChangePlaybackPositionCommand: RemoteCommandHandler =
-    handleChangePlaybackPositionCommandDefault
-  lazy var handleNextTrackCommand: RemoteCommandHandler = handleNextTrackCommandDefault
-  lazy var handlePreviousTrackCommand: RemoteCommandHandler =
-    handlePreviousTrackCommandDefault
-  lazy var handleChangeRepeatModeCommand: RemoteCommandHandler =
-    handleChangeRepeatModeCommandDefault
-  lazy var handleChangeShuffleModeCommand: RemoteCommandHandler =
-    handleChangeShuffleModeCommandDefault
-  lazy var handleChangePlaybackRateCommand: RemoteCommandHandler =
-    handleChangePlaybackRateCommandDefault
+  // Each default is wrapped in a `[weak self]` closure rather than assigned as a
+  // bare method reference (`= handlePlayCommandDefault`): an unapplied instance
+  // method curries to `{ [self] in self.method($0) }`, which strongly captures
+  // self. Stored back onto self, that is a permanent cycle — `enable(command:)`
+  // forces every lazy init, so the controller would never deallocate, leaking one
+  // per player instance across JS reloads and re-setups.
+  lazy var handlePlayCommand: RemoteCommandHandler = { [weak self] event in
+    self?.handlePlayCommandDefault(event: event) ?? .commandFailed
+  }
+
+  lazy var handlePauseCommand: RemoteCommandHandler = { [weak self] event in
+    self?.handlePauseCommandDefault(event: event) ?? .commandFailed
+  }
+
+  lazy var handleStopCommand: RemoteCommandHandler = { [weak self] event in
+    self?.handleStopCommandDefault(event: event) ?? .commandFailed
+  }
+
+  lazy var handleTogglePlayPauseCommand: RemoteCommandHandler = { [weak self] event in
+    self?.handleTogglePlayPauseCommandDefault(event: event) ?? .commandFailed
+  }
+
+  lazy var handleSkipForwardCommand: RemoteCommandHandler = { [weak self] event in
+    self?.handleSkipForwardCommandDefault(event: event) ?? .commandFailed
+  }
+
+  lazy var handleSkipBackwardCommand: RemoteCommandHandler = { [weak self] event in
+    self?.handleSkipBackwardDefault(event: event) ?? .commandFailed
+  }
+
+  lazy var handleChangePlaybackPositionCommand: RemoteCommandHandler = { [weak self] event in
+    self?.handleChangePlaybackPositionCommandDefault(event: event) ?? .commandFailed
+  }
+
+  lazy var handleNextTrackCommand: RemoteCommandHandler = { [weak self] event in
+    self?.handleNextTrackCommandDefault(event: event) ?? .commandFailed
+  }
+
+  lazy var handlePreviousTrackCommand: RemoteCommandHandler = { [weak self] event in
+    self?.handlePreviousTrackCommandDefault(event: event) ?? .commandFailed
+  }
+
+  lazy var handleChangeRepeatModeCommand: RemoteCommandHandler = { [weak self] event in
+    self?.handleChangeRepeatModeCommandDefault(event: event) ?? .commandFailed
+  }
+
+  lazy var handleChangeShuffleModeCommand: RemoteCommandHandler = { [weak self] event in
+    self?.handleChangeShuffleModeCommandDefault(event: event) ?? .commandFailed
+  }
+
+  lazy var handleChangePlaybackRateCommand: RemoteCommandHandler = { [weak self] event in
+    self?.handleChangePlaybackRateCommandDefault(event: event) ?? .commandFailed
+  }
 
   private func handlePlayCommandDefault(event _: MPRemoteCommandEvent)
     -> MPRemoteCommandHandlerStatus

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, ""))
-}