react-native-audio-browser 0.1.0 → 0.2.0-next.1

package/ios/Player/RetryManager.swift

@@ -1,10 +1,26 @@
 import Foundation
-import NitroModules
+#if canImport(NitroModules)
+  import NitroModules
+#endif
 import os.log
 
+/// Abstracts `NetworkMonitor` so tests can fake connectivity. Sendable because
+/// the network-restore race reads it from a task-group child.
+protocol NetworkStatusProviding: AnyObject, Sendable {
+  var isOnline: Bool { get }
+}
+
 /// Manages retry logic for media load errors with exponential backoff.
 /// Similar to Android's RetryLoadErrorHandlingPolicy.
 ///
+/// Two duration budgets apply, chosen by whether the current load has ever
+/// produced audio (`hasPlayed`): a short first-connect budget — a stream that
+/// fails before ever playing is usually dead, and the listener is actively
+/// waiting for a verdict — and the full recovery budget for a stream that
+/// played and then dropped (tunnels, handovers, encoder restarts). The short
+/// budget counts only online time, so a station tapped in a tunnel still gets
+/// its online seconds once connectivity returns.
+///
 /// When a network monitor is provided and the device is offline, the retry will
 /// trigger immediately when connectivity is restored instead of waiting for the
 /// full backoff delay.
@@ -19,28 +35,53 @@ class RetryManager {
   }
 
   private static let defaultMaxRetryDurationMs: Double = 120_000 // 2 minutes
+  private static let defaultFirstConnectMaxRetryDurationMs: Double = 12_000
 
   /// Prevents surprising playback resumption after long periods offline.
   private var maxRetryDuration: TimeInterval = defaultMaxRetryDurationMs / 1000
 
+  /// Bounds retries of a load that has never produced audio, while online.
+  private var firstConnectMaxRetryDuration: TimeInterval = defaultFirstConnectMaxRetryDurationMs / 1000
+
+  /// True once the current load has produced audio; selects between the
+  /// first-connect and recovery budgets. Set by the owner when audio starts and
+  /// cleared by the owner when a new track loads — deliberately NOT cleared in
+  /// `reset()`, which the healthy-playback budget refill also calls mid-play.
+  var hasPlayed = false
+
+  /// First failure observed while online for the current load — the
+  /// first-connect budget's clock. Never set while offline, and wiped by any
+  /// offline observation, so an offline stretch cannot burn the short budget:
+  /// the clock restarts at the next failure observed online.
+  private var firstOnlineRetryTime: Date?
+
   private var policy: Policy = .disabled
   private var attemptCount = 0
   private var firstRetryTime: Date?
 
-  weak var networkMonitor: NetworkMonitor?
-  private var isWaitingForNetwork = false
+  weak var networkMonitor: (any NetworkStatusProviding)?
+  /// True only while a scheduled retry is parked polling for connectivity to return. Exposed so the
+  /// player's stall-driven reconnect can defer to an in-flight error retry (which owns its own
+  /// reload) and avoid a double load.
+  private(set) var isWaitingForNetwork = false
   /// Invalidates in-flight retries when reset() is called (e.g. track change)
   private var generation: Int = 0
 
   var shouldRetry: () -> Bool = { true }
   var onRetry: ((Bool) -> Void)?
 
+  var isEnabled: Bool {
+    if case .disabled = policy { return false }
+    return true
+  }
+
   // MARK: - Configuration
 
   func updatePolicy(from config: Variant_Bool_RetryConfig?) {
     guard let config else {
       policy = .disabled
       maxRetryDuration = Self.defaultMaxRetryDurationMs / 1000
+      firstConnectMaxRetryDuration = Self.defaultFirstConnectMaxRetryDurationMs / 1000
       logger.debug("Retry policy: disabled")
       return
     }
@@ -49,13 +90,22 @@ class RetryManager {
     case let .first(enabled):
       policy = enabled ? .infinite : .disabled
       maxRetryDuration = Self.defaultMaxRetryDurationMs / 1000
+      firstConnectMaxRetryDuration = Self.defaultFirstConnectMaxRetryDurationMs / 1000
       logger.debug("Retry policy: \(enabled ? "infinite" : "disabled")")
     case let .second(retryConfig):
-      let maxRetries = Int(retryConfig.maxRetries)
-      policy = .limited(maxRetries: maxRetries)
       let durationMs = retryConfig.maxRetryDurationMs ?? Self.defaultMaxRetryDurationMs
       maxRetryDuration = durationMs / 1000
-      logger.debug("Retry policy: limited to \(maxRetries) retries, max duration \(self.maxRetryDuration)s")
+      let firstConnectMs = retryConfig.firstConnectMaxRetryDurationMs
+        ?? Self.defaultFirstConnectMaxRetryDurationMs
+      firstConnectMaxRetryDuration = firstConnectMs / 1000
+      // No attempt cap = retry indefinitely, bounded only by the duration.
+      if let maxRetries = retryConfig.maxRetries.map(Int.init) {
+        policy = .limited(maxRetries: maxRetries)
+        logger.debug("Retry policy: limited to \(maxRetries) retries, max duration \(self.maxRetryDuration)s")
+      } else {
+        policy = .infinite
+        logger.debug("Retry policy: infinite, max duration \(self.maxRetryDuration)s")
+      }
     }
   }
 
@@ -103,11 +153,29 @@ class RetryManager {
   func reset() {
     attemptCount = 0
     firstRetryTime = nil
+    firstOnlineRetryTime = nil
     isWaitingForNetwork = false
     generation += 1
     logger.debug("Retry count reset (generation \(self.generation))")
   }
 
+  private var isOnline: Bool { networkMonitor?.isOnline ?? true }
+
+  /// A description of the exhausted budget, or nil while budget remains.
+  /// The recovery duration bounds everything (including offline waits); the
+  /// first-connect duration additionally bounds never-played loads, online only.
+  private func exhaustedBudget() -> String? {
+    let now = Date()
+    if let start = firstRetryTime, now.timeIntervalSince(start) >= maxRetryDuration {
+      return "max retry duration (\(maxRetryDuration)s)"
+    }
+    if !hasPlayed, isOnline, let start = firstOnlineRetryTime,
+       now.timeIntervalSince(start) >= firstConnectMaxRetryDuration {
+      return "first-connect retry duration (\(firstConnectMaxRetryDuration)s)"
+    }
+    return nil
+  }
+
   func attemptRetry(startFromCurrentTime: Bool) async -> Bool {
     if case .disabled = policy {
       logger.debug("Retry disabled, not retrying")
@@ -129,14 +197,20 @@ class RetryManager {
     if firstRetryTime == nil {
       firstRetryTime = Date()
     }
+    if isOnline {
+      if firstOnlineRetryTime == nil { firstOnlineRetryTime = Date() }
+    } else {
+      // Seeing the device offline restarts the first-connect clock: a station
+      // that lost connectivity mid-budget gets its full online seconds again
+      // after restoration, instead of the offline gap counting against it.
+      firstOnlineRetryTime = nil
+    }
 
-    // Check if we've been retrying too long (prevents surprising resumption after long offline periods)
-    if let startTime = firstRetryTime {
-      let elapsed = Date().timeIntervalSince(startTime)
-      if elapsed >= maxRetryDuration {
-        logger.info("Max retry duration (\(self.maxRetryDuration)s) exceeded after \(elapsed)s, giving up")
-        return false
-      }
+    // Check if we've been retrying too long (prevents surprising resumption
+    // after long offline periods, and grants dead-on-arrival streams a fast verdict)
+    if let budget = exhaustedBudget() {
+      logger.info("\(budget) exceeded, giving up")
+      return false
     }
 
     let delaySeconds = calculateDelaySeconds()
@@ -157,18 +231,20 @@ class RetryManager {
       return false
     }
 
+    // Cancellation can land after the sleep completed — without this check a
+    // replaced retry (new error right as the old backoff expires) still fires
+    // onRetry, double-reloading and burning the attempt count twice.
+    guard !Task.isCancelled else { return false }
+
     guard shouldRetry() else {
       logger.debug("shouldRetry returned false after delay, cancelling retry")
       return false
     }
 
-    // Re-check duration — we may have waited a long time for network restoration
-    if let startTime = firstRetryTime {
-      let elapsed = Date().timeIntervalSince(startTime)
-      if elapsed >= maxRetryDuration {
-        logger.info("Max retry duration (\(self.maxRetryDuration)s) exceeded after waiting (\(elapsed)s), giving up")
-        return false
-      }
+    // Re-check the budgets — we may have waited a long time for network restoration
+    if let budget = exhaustedBudget() {
+      logger.info("\(budget) exceeded after waiting, giving up")
+      return false
     }
 
     attemptCount += 1
@@ -218,7 +294,7 @@ class RetryManager {
 
   /// Returns false when network is restored, true if cancelled.
   @MainActor
-  private func waitForNetworkRestored(monitor: NetworkMonitor) async -> Bool {
+  private func waitForNetworkRestored(monitor: any NetworkStatusProviding) async -> Bool {
     if monitor.isOnline {
       return false
     }

package/ios/Player/SleepTimerHandling.swift

@@ -1,7 +1,15 @@
+import Foundation
+
 /// Protocol abstracting sleep timer for testability.
 /// PlaybackCoordinator uses this instead of SleepTimerManager directly.
 @MainActor protocol SleepTimerHandling: AnyObject {
   var onComplete: (() -> Void)? { get set }
+  /// Invoked when the fade-out window of a time-based timer begins.
+  var onFadeStart: ((_ duration: TimeInterval) -> Void)? { get set }
+  /// Invoked when a timer is cancelled/replaced while its fade may be running —
+  /// the listener restores the pre-fade volume.
+  var onFadeCancel: (() -> Void)? { get set }
+  @discardableResult func clear() -> Bool
   func onTrackChanged()
   func onTrackPlayedToEnd()
 }

package/ios/Player/SleepTimerManager.swift

@@ -1,5 +1,8 @@
 import Foundation
-import NitroModules
+
+#if canImport(NitroModules)
+  import NitroModules
+#endif
 
 /// Type alias for the Nitro SleepTimer variant type
 typealias SleepTimerState = SleepTimer
@@ -11,7 +14,8 @@ class SleepTimerManager: SleepTimerHandling {
   // MARK: - Properties
 
   // nonisolated(unsafe) for deinit cleanup — deinit is always nonisolated in Swift 6.
-  nonisolated(unsafe) private var sleepTimerJob: DispatchWorkItem?
+  private nonisolated(unsafe) var sleepTimerJob: DispatchWorkItem?
+  private nonisolated(unsafe) var fadeJob: DispatchWorkItem?
 
   /// The time when playback should stop (seconds since epoch), or -1 if inactive
   private(set) var sleepTimerTime: TimeInterval = -1 {
@@ -36,6 +40,14 @@ class SleepTimerManager: SleepTimerHandling {
   /// Callback invoked when the sleep timer fires
   var onComplete: (() -> Void)?
 
+  /// Callback invoked when the fade-out window of a time-based timer begins
+  var onFadeStart: ((_ duration: TimeInterval) -> Void)?
+
+  /// Callback invoked when a timer is cancelled/replaced while its fade may be
+  /// running — the listener restores the pre-fade volume. Not invoked on
+  /// completion: there the pause lands first, then the volume is restored.
+  var onFadeCancel: (() -> Void)?
+
   /// Callback invoked when the sleep timer state changes
   var onChanged: ((SleepTimerState) -> Void)?
 
@@ -49,6 +61,7 @@ class SleepTimerManager: SleepTimerHandling {
     if !hasSleepTimer { return false }
     sleepTimerTime = -1
     willSleepWhenCurrentItemReachesEnd = false
+    onFadeCancel?()
     onChanged?(.first(NullType.null))
     return true
   }
@@ -74,9 +87,13 @@ class SleepTimerManager: SleepTimerHandling {
   }
 
   /// Sets a time-based sleep timer.
-  /// - Parameter seconds: Number of seconds until playback stops
-  func set(seconds: TimeInterval) {
+  /// - Parameters:
+  ///   - seconds: Number of seconds until playback stops
+  ///   - fadeDuration: Seconds over which to fade the volume out before the
+  ///     deadline (clamped to `seconds`); silence lands exactly at the deadline
+  func set(seconds: TimeInterval, fadeDuration: TimeInterval? = nil) {
     cancelSleepTimerJob()
+    onFadeCancel?()
     let job = DispatchWorkItem { [weak self] in
       MainActor.assumeIsolated {
         self?.complete()
@@ -85,6 +102,16 @@ class SleepTimerManager: SleepTimerHandling {
     sleepTimerJob = job
     sleepTimerTime = Date().timeIntervalSince1970 + seconds
     DispatchQueue.main.asyncAfter(deadline: .now() + seconds, execute: job)
+    if let fadeDuration, fadeDuration > 0 {
+      let fade = min(fadeDuration, seconds)
+      let fadeJob = DispatchWorkItem { [weak self] in
+        MainActor.assumeIsolated {
+          self?.onFadeStart?(fade)
+        }
+      }
+      self.fadeJob = fadeJob
+      DispatchQueue.main.asyncAfter(deadline: .now() + (seconds - fade), execute: fadeJob)
+    }
     if let state = get() { onChanged?(state) }
   }
 
@@ -92,7 +119,10 @@ class SleepTimerManager: SleepTimerHandling {
   func setToEndOfTrack() {
     let changed = !willSleepWhenCurrentItemReachesEnd
     willSleepWhenCurrentItemReachesEnd = true
-    if changed, let state = get() { onChanged?(state) }
+    if changed {
+      onFadeCancel?()
+      if let state = get() { onChanged?(state) }
+    }
   }
 
   /// Called when the current track changes. Resets end-of-track timer.
@@ -116,6 +146,8 @@ class SleepTimerManager: SleepTimerHandling {
   private func cancelSleepTimerJob() {
     sleepTimerJob?.cancel()
     sleepTimerJob = nil
+    fadeJob?.cancel()
+    fadeJob = nil
   }
 
   private func complete() {
@@ -127,5 +159,6 @@ class SleepTimerManager: SleepTimerHandling {
 
   deinit {
     sleepTimerJob?.cancel()
+    fadeJob?.cancel()
   }
 }

package/ios/Player/VolumeFader.swift

@@ -0,0 +1,77 @@
+import Foundation
+
+/// Ramps the player volume down over a duration (sleep-timer fade).
+/// The gain follows a squared curve: loudness perception is logarithmic, so a
+/// linear gain ramp sounds like a late cutoff rather than a fade.
+@MainActor
+final class VolumeFader {
+  private static let stepInterval: TimeInterval = 0.05
+
+  private let getVolume: () -> Float
+  private let setVolume: (Float) -> Void
+  // nonisolated(unsafe) for deinit cleanup — deinit is always nonisolated in Swift 6.
+  private nonisolated(unsafe) var timer: Timer?
+
+  /// Volume captured when the fade started; restored after the fade resolves.
+  /// Non-nil from fade start until cancel/completion, even once the ramp has
+  /// reached silence.
+  private(set) var originalVolume: Float?
+
+  var isActive: Bool { originalVolume != nil }
+
+  init(getVolume: @escaping () -> Float, setVolume: @escaping (Float) -> Void) {
+    self.getVolume = getVolume
+    self.setVolume = setVolume
+  }
+
+  func start(duration: TimeInterval) {
+    // If a fade is already running, keep its captured volume as the baseline —
+    // the current (partially faded) volume is not the value to restore.
+    let baseVolume = originalVolume ?? getVolume()
+    cancel(restoringVolume: false)
+    originalVolume = baseVolume
+    guard duration > 0 else { return }
+
+    let startDate = Date()
+    let timer = Timer(timeInterval: Self.stepInterval, repeats: true) { [weak self] _ in
+      MainActor.assumeIsolated {
+        guard let self else { return }
+        let progress = min(1, Date().timeIntervalSince(startDate) / duration)
+        let remaining = Float(1 - progress)
+        self.setVolume(baseVolume * remaining * remaining)
+        if progress >= 1 {
+          self.timer?.invalidate()
+          self.timer = nil
+        }
+      }
+    }
+    self.timer = timer
+    RunLoop.main.add(timer, forMode: .common)
+  }
+
+  /// Stops the ramp. With `restoringVolume` the pre-fade volume is put back
+  /// immediately (cancellation); without it the caller restores after pausing
+  /// (completion path — restoring first would let full-volume audio slip out).
+  func cancel(restoringVolume: Bool) {
+    timer?.invalidate()
+    timer = nil
+    guard let originalVolume else { return }
+    self.originalVolume = nil
+    if restoringVolume { setVolume(originalVolume) }
+  }
+
+  /// Resolves the fade around a halting action: stops the ramp, runs `halt`,
+  /// then restores the pre-fade volume — in that order, because restoring
+  /// before halting would let full-volume audio slip out. The restore is
+  /// skipped when no fade was running.
+  func resolve(around halt: () -> Void) {
+    let preFadeVolume = originalVolume
+    cancel(restoringVolume: false)
+    halt()
+    if let preFadeVolume { setVolume(preFadeVolume) }
+  }
+
+  deinit {
+    timer?.invalidate()
+  }
+}

package/ios/RemoteCommand/RemoteCommandController.swift

@@ -51,6 +51,19 @@ class RemoteCommandController {
   var commandTargetPointers: [String: Any] = [:]
   private var enabledCommands: [RemoteCommand] = []
 
+  /// Whether there's a next/previous track to skip to. Stored so it survives
+  /// command (re)enable and iOS-16 command-center switches; the next/previous
+  /// commands are enabled in this state rather than unconditionally.
+  private var canNext = true
+  private var canPrevious = true
+
+  /// Shuffle/repeat display state, stored so it survives a command-center switch
+  /// (iOS-16 MPNowPlayingSession re-creation). A new center defaults these to
+  /// off; without re-applying, the CarPlay/lock-screen shuffle & repeat buttons
+  /// flash off on every switch.
+  private var shuffleEnabled = false
+  private var repeatMode: RepeatMode = .off
+
   /**
    Create a new RemoteCommandController.
 
@@ -90,6 +103,11 @@ class RemoteCommandController {
     // Re-enable commands on the new center
     enable(commands: commandsToReEnable)
 
+    // Restore shuffle/repeat display state — the new center defaults them to off,
+    // so without this the shuffle & repeat buttons flash off on every switch.
+    center.changeShuffleModeCommand.currentShuffleType = shuffleEnabled.mpShuffleType
+    center.changeRepeatModeCommand.currentRepeatType = repeatMode.mpRepeatType
+
     logger.info("Switched command center, re-enabled \(commandsToReEnable.count) commands")
   }
 
@@ -156,12 +174,14 @@ class RemoteCommandController {
         key: command.key,
         handler: handleNextTrackCommand,
       )
+      center.nextTrackCommand.isEnabled = canNext
     case .previous:
       enableRemoteCommand(
         center.previousTrackCommand,
         key: command.key,
         handler: handlePreviousTrackCommand,
       )
+      center.previousTrackCommand.isEnabled = canPrevious
     case .changePlaybackPosition:
       enableRemoteCommand(
         center.changePlaybackPositionCommand,
@@ -182,11 +202,6 @@ class RemoteCommandController {
         key: command.key,
         handler: handleSkipBackwardCommand,
       )
-    case let .like(isActive, localizedTitle, localizedShortTitle):
-      center.likeCommand.isActive = isActive
-      center.likeCommand.localizedTitle = localizedTitle
-      center.likeCommand.localizedShortTitle = localizedShortTitle
-      enableRemoteCommand(center.likeCommand, key: command.key, handler: handleLikeCommand)
     case .changeRepeatMode:
       enableRemoteCommand(
         center.changeRepeatModeCommand,
@@ -229,8 +244,6 @@ class RemoteCommandController {
       disableRemoteCommand(center.skipForwardCommand, key: command.key)
     case .skipBackward:
       disableRemoteCommand(center.skipBackwardCommand, key: command.key)
-    case .like:
-      disableRemoteCommand(center.likeCommand, key: command.key)
     case .changeRepeatMode:
       disableRemoteCommand(center.changeRepeatModeCommand, key: command.key)
     case .changeShuffleMode:
@@ -244,14 +257,25 @@ class RemoteCommandController {
 
   /// Updates the repeat mode state shown on CarPlay and lock screen
   func updateRepeatMode(_ mode: RepeatMode) {
+    repeatMode = mode
     center.changeRepeatModeCommand.currentRepeatType = mode.mpRepeatType
   }
 
   /// Updates the shuffle mode state shown on CarPlay and lock screen
   func updateShuffleMode(_ enabled: Bool) {
+    shuffleEnabled = enabled
     center.changeShuffleModeCommand.currentShuffleType = enabled.mpShuffleType
   }
 
+  /// Greys out next/previous (lock screen / Control Center / CarPlay) when the
+  /// queue has nowhere to skip. Applied live when those commands are configured.
+  func setSkipAvailability(canNext: Bool, canPrevious: Bool) {
+    self.canNext = canNext
+    self.canPrevious = canPrevious
+    if enabledCommands.contains(.next) { center.nextTrackCommand.isEnabled = canNext }
+    if enabledCommands.contains(.previous) { center.previousTrackCommand.isEnabled = canPrevious }
+  }
+
   // MARK: - Handlers
 
   lazy var handlePlayCommand: RemoteCommandHandler = handlePlayCommandDefault
@@ -266,7 +290,6 @@ class RemoteCommandController {
   lazy var handleNextTrackCommand: RemoteCommandHandler = handleNextTrackCommandDefault
   lazy var handlePreviousTrackCommand: RemoteCommandHandler =
     handlePreviousTrackCommandDefault
-  lazy var handleLikeCommand: RemoteCommandHandler = handleLikeCommandDefault
   lazy var handleChangeRepeatModeCommand: RemoteCommandHandler =
     handleChangeRepeatModeCommandDefault
   lazy var handleChangeShuffleModeCommand: RemoteCommandHandler =
@@ -352,13 +375,6 @@ class RemoteCommandController {
     return MPRemoteCommandHandlerStatus.success
   }
 
-  private func handleLikeCommandDefault(event _: MPRemoteCommandEvent)
-    -> MPRemoteCommandHandlerStatus
-  {
-    callbacks?.remoteLike()
-    return MPRemoteCommandHandlerStatus.success
-  }
-
   private func handleChangeRepeatModeCommandDefault(event: MPRemoteCommandEvent)
     -> MPRemoteCommandHandlerStatus
   {

package/ios/Tests/AirPlayStallJudgementTests.swift

@@ -0,0 +1,52 @@
+import Testing
+
+@testable import AudioBrowserTestable
+
+@Suite("AirPlayStallJudgement")
+struct AirPlayStallJudgementTests {
+  /// The exact transition Pocket Casts recovers from: over AirPlay, AVPlayer
+  /// drops .waitingToPlayAtSpecifiedRate(.noItemToPlay) → .paused while still
+  /// meant to play. That, and only that, should nudge.
+  private func judge(
+    previous: PlayerTimeControlStatus? = .waitingToPlayAtSpecifiedRate,
+    current: PlayerTimeControlStatus = .paused,
+    reasonWasNoItemToPlay: Bool = true,
+    isAirPlay: Bool = true,
+    playWhenReady: Bool = true,
+  ) -> AirPlayStallJudgement {
+    AirPlayStallJudgement(
+      previous: previous,
+      current: current,
+      previousWaitingReasonWasNoItemToPlay: reasonWasNoItemToPlay,
+      isAirPlay: isAirPlay,
+      playWhenReady: playWhenReady,
+    )
+  }
+
+  @Test func exactTransition_nudges() {
+    #expect(judge().shouldNudge)
+  }
+
+  @Test func notAirPlay_doesNotNudge() {
+    #expect(!judge(isAirPlay: false).shouldNudge)
+  }
+
+  @Test func notPlayWhenReady_doesNotNudge() {
+    #expect(!judge(playWhenReady: false).shouldNudge)
+  }
+
+  @Test func previousNotWaiting_doesNotNudge() {
+    #expect(!judge(previous: .playing).shouldNudge)
+    #expect(!judge(previous: nil).shouldNudge)
+  }
+
+  @Test func currentNotPaused_doesNotNudge() {
+    #expect(!judge(current: .playing).shouldNudge)
+    #expect(!judge(current: .waitingToPlayAtSpecifiedRate).shouldNudge)
+  }
+
+  @Test func reasonNotNoItemToPlay_doesNotNudge() {
+    // A normal stall (.toMinimizeStalls etc.) landing in paused isn't the bug.
+    #expect(!judge(reasonWasNoItemToPlay: false).shouldNudge)
+  }
+}

package/ios/Tests/BrowserPathHelperTests.swift

@@ -29,6 +29,14 @@ import Testing
   #expect(result == "http://example.com/api")
 }
 
+@Test func buildUrlEmptyPathReturnsBaseWithoutTrailingSlash() {
+  // An endpoint whose baseUrl already includes the full path (e.g. search,
+  // `https://host/api/search`) passes an empty path — the base IS the URL, and
+  // must not gain a dangling trailing slash.
+  let result = BrowserPathHelper.buildUrl(baseUrl: "http://example.com/api/search", path: "")
+  #expect(result == "http://example.com/api/search")
+}
+
 // MARK: - appendQuery
 
 @Test func appendQueryAddsParamsWithQuestionMark() {
@@ -108,3 +116,23 @@ 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, ""))
+}