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

package/ios/Tests/PlaybackTimerTests.swift

@@ -0,0 +1,55 @@
+import XCTest
+
+@testable import AudioBrowserTestable
+
+@MainActor
+final class PlaybackTimerTests: XCTestCase {
+  func testNoTicksUntilIntervalSetAndActive() async throws {
+    var ticks = 0
+    let timer = PlaybackTimer(isActive: { $0 == .playing }) { ticks += 1 }
+    timer.onPlaybackStateChanged(.playing) // no interval yet
+    try await Task.sleep(nanoseconds: 1_200_000_000)
+    XCTAssertEqual(ticks, 0)
+  }
+
+  func testTicksWhenIntervalSetAndActive() async throws {
+    var ticks = 0
+    let timer = PlaybackTimer(isActive: { $0 == .playing }) { ticks += 1 }
+    timer.setInterval(1)
+    timer.onPlaybackStateChanged(.playing)
+    try await Task.sleep(nanoseconds: 2_200_000_000)
+    XCTAssertGreaterThanOrEqual(ticks, 1)
+  }
+
+  func testStopsWhenStateLeavesActive() async throws {
+    var ticks = 0
+    let timer = PlaybackTimer(isActive: { $0 == .playing }) { ticks += 1 }
+    timer.setInterval(1)
+    timer.onPlaybackStateChanged(.playing)
+    timer.onPlaybackStateChanged(.paused)
+    let after = ticks
+    try await Task.sleep(nanoseconds: 1_200_000_000)
+    XCTAssertEqual(ticks, after)
+  }
+
+  func testNilIntervalStops() async throws {
+    var ticks = 0
+    let timer = PlaybackTimer(isActive: { $0 == .playing }) { ticks += 1 }
+    timer.setInterval(1)
+    timer.onPlaybackStateChanged(.playing)
+    timer.setInterval(nil) // off-switch
+    let after = ticks
+    try await Task.sleep(nanoseconds: 1_200_000_000)
+    XCTAssertEqual(ticks, after)
+  }
+
+  func testIsActivePredicateGatesState() async throws {
+    // A "playing-only" predicate must not tick while buffering.
+    var ticks = 0
+    let timer = PlaybackTimer(isActive: { $0 == .playing }) { ticks += 1 }
+    timer.setInterval(1)
+    timer.onPlaybackStateChanged(.buffering)
+    try await Task.sleep(nanoseconds: 1_200_000_000)
+    XCTAssertEqual(ticks, 0)
+  }
+}

package/ios/Tests/PlayingStateManagerTests.swift

@@ -0,0 +1,57 @@
+import Foundation
+import Testing
+
+@testable import AudioBrowserTestable
+
+@Suite("PlayingStateManager")
+struct PlayingStateManagerTests {
+  @MainActor
+  private func makeManager() -> (manager: PlayingStateManager, changes: () -> [PlayingState]) {
+    var recorded: [PlayingState] = []
+    let manager = PlayingStateManager { recorded.append($0) }
+    return (manager, { recorded })
+  }
+
+  @Test @MainActor
+  func playing_whenIntentAndActiveState() {
+    let (m, _) = makeManager()
+    m.update(playWhenReady: true, state: .playing)
+    #expect(m.playing == true)
+    #expect(m.buffering == false)
+  }
+
+  @Test @MainActor
+  func buffering_whenIntentAndLoading() {
+    let (m, _) = makeManager()
+    m.update(playWhenReady: true, state: .loading)
+    #expect(m.playing == true)
+    #expect(m.buffering == true)
+  }
+
+  @Test @MainActor
+  func notPlaying_withoutIntent() {
+    let (m, _) = makeManager()
+    m.update(playWhenReady: false, state: .playing)
+    #expect(m.playing == false)
+  }
+
+  /// Terminal states are not playable regardless of intent. .stopped was
+  /// missing from the exclusion list — masked only by stop() clearing
+  /// playWhenReady right after transitioning, which made the gap latent.
+  @Test @MainActor
+  func notPlaying_inTerminalStates_evenWithIntent() {
+    for state in [PlaybackState.none, .stopped, .ended, .error] {
+      let (m, _) = makeManager()
+      m.update(playWhenReady: true, state: state)
+      #expect(m.playing == false, "Expected not playing in \(state) despite intent")
+    }
+  }
+
+  @Test @MainActor
+  func onChange_firesOnlyOnActualChange() {
+    let (m, changes) = makeManager()
+    m.update(playWhenReady: true, state: .playing)
+    m.update(playWhenReady: true, state: .playing)
+    #expect(changes().count == 1)
+  }
+}

package/ios/Tests/QueueManagerTests.swift

@@ -390,16 +390,16 @@ struct AddAtTests {
     #expect(try q.addAt([], at: 0) == false)
   }
 
-  @Test func singleExistingTrack_insertBeforeCurrent_doesNotShift() throws {
+  @Test func singleExistingTrack_insertBeforeCurrent_shifts() throws {
     let q = QueueManager()
     q.setQueue(tracks("a"))
-    // guard `tracks.count > 1` is false (count is 1), so currentIndex is NOT shifted.
-    // The original track moves to index 1 but currentIndex stays 0.
     let changed = try q.addAt(tracks("x"), at: 0)
     #expect(changed == false)
-    #expect(q.currentIndex == 0)
-    // currentTrack is now "x" (the inserted track), not "a"
-    #expect(q.currentTrack?.id == "x")
+    // The pointer follows the playing track — the old `tracks.count > 1`
+    // guard silently swapped currentTrack to the inserted track while the
+    // player kept playing the old one.
+    #expect(q.currentIndex == 1)
+    #expect(q.currentTrack?.id == "a")
   }
 
   @Test func atExactCurrentIndex_shiftsCurrentIndex() throws {
@@ -524,13 +524,17 @@ struct RemoveTests {
 @Suite("move()")
 @MainActor
 struct MoveTests {
-  @Test func currentTrack_returnsTrue_updatesIndex() throws {
+  // A move never changes which track is current — the pointer follows the
+  // track, and no move returns true (true triggers a reload at the caller,
+  // which would restart playback on a reorder).
+
+  @Test func currentTrack_pointerFollows() throws {
     let q = QueueManager()
     q.setQueue(tracks("a", "b", "c"), initialIndex: 0)
     let changed = try q.move(fromIndex: 0, toIndex: 2)
-    #expect(changed == true)
+    #expect(changed == false)
     #expect(q.currentIndex == 2)
-    #expect(q.tracks[2].id == "a")
+    #expect(q.currentTrack?.id == "a")
   }
 
   @Test func nonCurrent_returnsFalse() throws {
@@ -548,26 +552,37 @@ struct MoveTests {
     }
   }
 
-  @Test func nonCurrent_acrossCurrent_doesNotAdjustIndex() throws {
+  @Test func nonCurrent_acrossCurrent_keepsPointerOnSameTrack() throws {
     let q = QueueManager()
     q.setQueue(tracks("a", "b", "c"), initialIndex: 1)
-    // Move track from before current to after current.
-    // currentIndex is NOT adjusted (only adjusted when fromIndex == currentIndex).
     let changed = try q.move(fromIndex: 0, toIndex: 2)
     #expect(changed == false)
-    #expect(q.currentIndex == 1)
-    // After remove(0): [b, c], insert at min(2,2)=2: [b, c, a]
-    // currentIndex 1 now points to "c", not "b"
-    #expect(q.currentTrack?.id == "c")
+    // [a,b,c] → [b,c,a]; "b" is now index 0.
+    #expect(q.currentTrack?.id == "b")
+    #expect(q.currentIndex == 0)
+  }
+
+  @Test func nonCurrent_acrossCurrentBackwards_keepsPointerOnSameTrack() throws {
+    let q = QueueManager()
+    q.setQueue(tracks("a", "b", "c"), initialIndex: 1)
+    let changed = try q.move(fromIndex: 2, toIndex: 0)
+    #expect(changed == false)
+    // [a,b,c] → [c,a,b]; "b" is now index 2.
+    #expect(q.currentTrack?.id == "b")
+    #expect(q.currentIndex == 2)
   }
 
-  @Test func toIndexBeyondCount_clampsToEnd() throws {
+  @Test func toIndexBeyondCount_clampsPointerToo() throws {
     let q = QueueManager()
     q.setQueue(tracks("a", "b", "c"), initialIndex: 0)
     let changed = try q.move(fromIndex: 0, toIndex: 99)
-    #expect(changed == true)
+    #expect(changed == false)
     // remove(0): [b, c], insert at min(2, 99)=2: [b, c, a]
     #expect(q.tracks[2].id == "a")
+    // The unclamped assignment left currentIndex at 99 → currentTrack nil →
+    // a reorder unloaded playback.
+    #expect(q.currentIndex == 2)
+    #expect(q.currentTrack?.id == "a")
   }
 
   @Test func invalidFromIndex_throws() {
@@ -606,6 +621,23 @@ struct ClearTests {
     let q = QueueManager()
     #expect(q.clear() == false)
   }
+
+  /// clear() and removeUpcomingTracks() were the only mutations not
+  /// maintaining the shuffle order — a stale order over a rebuilt queue
+  /// navigates to phantom indices, nil-ing currentTrack and unloading
+  /// playback mid-session.
+  @Test func clear_alsoClearsShuffleOrder() {
+    let q = QueueManager()
+    q.shuffleEnabled = true
+    q.setQueue(tracks("a", "b", "c", "d", "e"))
+
+    q.clear()
+
+    #expect(q.shuffleOrder.shuffled.isEmpty)
+
+    _ = try? q.addAt(tracks("x", "y"), at: 0)
+    #expect(q.shuffleOrder.shuffled.count == q.tracks.count)
+  }
 }
 
 // MARK: - Other: replace, removeUpcomingTracks
@@ -620,6 +652,16 @@ struct OtherMutationTests {
     #expect(q.tracks[1].id == "B")
   }
 
+  @Test func removeUpcomingTracks_alsoTrimsShuffleOrder() {
+    let q = QueueManager()
+    q.shuffleEnabled = true
+    q.setQueue(tracks("a", "b", "c", "d", "e"), initialIndex: 1)
+
+    q.removeUpcomingTracks()
+
+    #expect(q.shuffleOrder.shuffled.count == q.tracks.count)
+  }
+
   @Test func removeUpcomingTracks_keepsCurrentAndBefore() {
     let q = QueueManager()
     q.setQueue(tracks("a", "b", "c", "d"), initialIndex: 1)
@@ -878,3 +920,92 @@ struct DelegateTests {
     #expect(spy.calls.isEmpty)
   }
 }
+
+// MARK: - canNext / canPrevious
+
+@Suite("canNext / canPrevious")
+@MainActor
+struct SkipAvailabilityTests {
+  @Test func emptyQueue_bothFalse() {
+    let q = QueueManager()
+    #expect(q.canNext == false)
+    #expect(q.canPrevious == false)
+  }
+
+  @Test func singleTrack_repeatOff_bothFalse() {
+    let q = QueueManager()
+    q.setQueue(tracks("a"))
+    #expect(q.canNext == false)
+    #expect(q.canPrevious == false)
+  }
+
+  @Test func singleTrack_repeatQueue_bothFalse() {
+    let q = QueueManager()
+    q.setQueue(tracks("a"))
+    q.repeatMode = .queue
+    #expect(q.canNext == false)
+    #expect(q.canPrevious == false)
+  }
+
+  @Test func firstOfMany_nextOnly() {
+    let q = QueueManager()
+    q.setQueue(tracks("a", "b", "c"), initialIndex: 0)
+    #expect(q.canNext == true)
+    #expect(q.canPrevious == false)
+  }
+
+  @Test func middleOfMany_both() {
+    let q = QueueManager()
+    q.setQueue(tracks("a", "b", "c"), initialIndex: 1)
+    #expect(q.canNext == true)
+    #expect(q.canPrevious == true)
+  }
+
+  @Test func lastOfMany_repeatOff_previousOnly() {
+    let q = QueueManager()
+    q.setQueue(tracks("a", "b", "c"), initialIndex: 2)
+    #expect(q.canNext == false)
+    #expect(q.canPrevious == true)
+  }
+
+  @Test func lastOfMany_repeatQueue_bothTrue() {
+    let q = QueueManager()
+    q.setQueue(tracks("a", "b", "c"), initialIndex: 2)
+    q.repeatMode = .queue
+    #expect(q.canNext == true) // wraps to first
+    #expect(q.canPrevious == true)
+  }
+
+  @Test func firstOfMany_repeatQueue_bothTrue() {
+    let q = QueueManager()
+    q.setQueue(tracks("a", "b", "c"), initialIndex: 0)
+    q.repeatMode = .queue
+    #expect(q.canNext == true)
+    #expect(q.canPrevious == true) // wraps to last
+  }
+
+  // Shuffle wraps the playback order unconditionally (even with repeat off), so
+  // next()/previous() always move when count > 1 — canNext/canPrevious must
+  // agree at the shuffle-order boundaries, not grey out.
+  @Test func shuffleEnd_repeatOff_canNextTrue() {
+    let q = QueueManager()
+    q.setQueue(tracks("a", "b", "c", "d"))
+    q.shuffleEnabled = true
+    q.repeatMode = .off
+    while !q.isLastInPlaybackOrder {
+      _ = q.next()
+    } // advance to last in shuffle order
+    #expect(q.canNext == true) // next() wraps to the first shuffle position
+  }
+
+  @Test func shuffleStart_repeatOff_canPreviousTrue() {
+    let q = QueueManager()
+    q.setQueue(tracks("a", "b", "c", "d"))
+    q.shuffleEnabled = true
+    q.repeatMode = .off
+    while !q.previousTracks.isEmpty {
+      _ = q.previous()
+    } // back to first in shuffle order
+    #expect(q.canPrevious == true) // previous() wraps to the last shuffle position
+  }
+}

package/ios/Tests/ResolvedTrackCopyingTests.swift

@@ -4,7 +4,7 @@ import Testing
 
 private func makeResolvedTrack(
   url: String = "/test",
-  title: String = "Test Track"
+  title: String = "Test Track",
 ) -> ResolvedTrack {
   ResolvedTrack(
     url: url,
@@ -26,7 +26,7 @@ private func makeResolvedTrack(
     favorited: nil,
     groupTitle: nil,
     live: nil,
-    imageRow: nil
+    imageRow: nil,
   )
 }
 
@@ -35,8 +35,9 @@ private func makeFullResolvedTrack() -> ResolvedTrack {
     url: "/original",
     children: [Track(id: "t1", url: "/t1")],
     carPlaySiriListButton: .top,
+    id: "original-id",
     src: "src.mp3",
-    artwork: "art.jpg",
+    artwork: .first("art.jpg"),
     artworkSource: ImageSource(uri: "resolved-art.jpg"),
     artworkCarPlayTinted: true,
     title: "Original Title",
@@ -51,7 +52,7 @@ private func makeFullResolvedTrack() -> ResolvedTrack {
     favorited: true,
     groupTitle: "Group A",
     live: false,
-    imageRow: [ImageRowItem(title: "Row 1")]
+    imageRow: [ImageRowItem(title: "Row 1")],
   )
 }
 
@@ -95,10 +96,16 @@ private func makeFullResolvedTrack() -> ResolvedTrack {
   #expect(copy.src == "new-src.mp3")
 }
 
+@Test func copyingOverridesId() {
+  let original = makeResolvedTrack()
+  let copy = original.copying(id: "new-id")
+  #expect(copy.id == "new-id")
+}
+
 @Test func copyingOverridesArtwork() {
   let original = makeResolvedTrack()
-  let copy = original.copying(artwork: "new-art.jpg")
-  #expect(copy.artwork == "new-art.jpg")
+  let copy = original.copying(artwork: .some(.first("new-art.jpg")))
+  #expect(copy.artwork?.url == "new-art.jpg")
 }
 
 @Test func copyingOverridesArtworkSource() {
@@ -203,7 +210,7 @@ private func makeFullResolvedTrack() -> ResolvedTrack {
     title: "Updated Title",
     artist: "New Artist",
     duration: 240.0,
-    favorited: true
+    favorited: true,
   )
   #expect(copy.url == "/updated")
   #expect(copy.title == "Updated Title")
@@ -227,7 +234,7 @@ private func makeFullResolvedTrack() -> ResolvedTrack {
   #expect(copy.children?.count == 1)
   #expect(copy.carPlaySiriListButton == .top)
   #expect(copy.src == "src.mp3")
-  #expect(copy.artwork == "art.jpg")
+  #expect(copy.artwork?.url == "art.jpg")
   #expect(copy.artworkSource == ImageSource(uri: "resolved-art.jpg"))
   #expect(copy.artworkCarPlayTinted == true)
   #expect(copy.subtitle == "Original Subtitle")

package/ios/Tests/RetryManagerTests.swift

@@ -0,0 +1,89 @@
+import Foundation
+import Testing
+
+@testable import AudioBrowserTestable
+
+private final class MockNetworkStatus: NetworkStatusProviding, @unchecked Sendable {
+  var isOnline: Bool
+  init(isOnline: Bool) { self.isOnline = isOnline }
+}
+
+/// The two duration budgets: a never-played load gives up fast while online; a
+/// load that produced audio — or a device that is offline — keeps the full
+/// recovery budget. Timing-based: budgets are configured in single-digit
+/// milliseconds so one executed backoff (~1s) exhausts them.
+@Suite("RetryManager budgets")
+@MainActor
+struct RetryManagerBudgetTests {
+  /// Returns the mock too — `networkMonitor` is weak, the test must keep it alive.
+  private func makeManager(
+    firstConnectMs: Double,
+    maxMs: Double = 120_000,
+    online: Bool,
+  ) -> (RetryManager, MockNetworkStatus) {
+    let manager = RetryManager()
+    manager.updatePolicy(from: .second(RetryConfig(
+      maxRetries: nil,
+      maxRetryDurationMs: maxMs,
+      firstConnectMaxRetryDurationMs: firstConnectMs,
+    )))
+    let network = MockNetworkStatus(isOnline: online)
+    manager.networkMonitor = network
+    return (manager, network)
+  }
+
+  /// A dead-on-arrival stream: the first attempt runs, and the budget refuses
+  /// a later one. Budgets are checked before AND after each backoff wait, so
+  /// the test budget must exceed the first backoff (~1s) for attempt one to
+  /// execute, and be exceeded by the cumulative ~2.5s before attempt two ends.
+  /// 1800ms sits ~800ms clear of the first backoff (sleep overshoot on a loaded
+  /// machine only widens the passing margins, never shrinks them into failure).
+  @Test func neverPlayedLoad_givesUpAfterFirstConnectBudget() async {
+    let (manager, network) = makeManager(firstConnectMs: 1800, online: true)
+    _ = network
+
+    #expect(await manager.attemptRetry(startFromCurrentTime: false) == true)
+    #expect(await manager.attemptRetry(startFromCurrentTime: false) == false)
+  }
+
+  /// The same failure timeline on a load that has produced audio keeps
+  /// retrying: only the recovery budget applies.
+  @Test func playedLoad_ignoresTheFirstConnectBudget() async {
+    let (manager, network) = makeManager(firstConnectMs: 500, online: true)
+    _ = network
+    manager.hasPlayed = true
+
+    #expect(await manager.attemptRetry(startFromCurrentTime: false) == true)
+    #expect(await manager.attemptRetry(startFromCurrentTime: false) == true)
+  }
+
+  /// Offline failures must not burn the first-connect budget (a station tapped
+  /// in a tunnel parks for connectivity); the budget's clock starts at the
+  /// first failure observed online, so a dead station still gets a fast
+  /// verdict after restoration.
+  @Test func offlineTime_doesNotBurnTheFirstConnectBudget() async {
+    // 4s: well above the ~2.3s backoff of the first online attempt (the ladder
+    // kept climbing while offline), well below the ~5.6s cumulative after it.
+    let (manager, network) = makeManager(firstConnectMs: 4000, online: false)
+
+    // Offline: the short budget never engages, attempts keep running.
+    #expect(await manager.attemptRetry(startFromCurrentTime: false) == true)
+    #expect(await manager.attemptRetry(startFromCurrentTime: false) == true)
+
+    // Connectivity returns: the short clock starts now — one more attempt
+    // runs, then the budget is spent.
+    network.isOnline = true
+    #expect(await manager.attemptRetry(startFromCurrentTime: false) == true)
+    #expect(await manager.attemptRetry(startFromCurrentTime: false) == false)
+  }
+
+  /// `reset()` (track change / budget refill) restarts the clocks but must NOT
+  /// touch `hasPlayed` — the refill runs mid-play, and clearing the flag there
+  /// would hand a playing stream the short budget on its next drop.
+  @Test func reset_keepsHasPlayed() {
+    let manager = RetryManager()
+    manager.hasPlayed = true
+    manager.reset()
+    #expect(manager.hasPlayed == true)
+  }
+}

package/ios/Tests/SearchDrillInTests.swift

@@ -0,0 +1,63 @@
+import Testing
+
+@testable import AudioBrowserTestable
+
+private struct Item: PlayableSearchItem {
+  let src: String?
+  let url: String?
+}
+
+@Suite("SearchDrillIn.playable")
+struct SearchDrillInTests {
+  /// A resolver that fails the test if the drill-in path calls it.
+  private func unusedResolver(_ url: String) async throws -> [Item] {
+    Issue.record("resolveChildren should not have been called (url: \(url))")
+    return []
+  }
+
+  @Test func noResults_returnsNil() async throws {
+    let result = try await SearchDrillIn.playable(from: [Item](), resolveChildren: unusedResolver)
+    #expect(result == nil)
+  }
+
+  @Test func firstPlayable_returnsFlatPlayable_inOrder_withoutResolving() async throws {
+    let items = [
+      Item(src: "/a.mp3", url: nil),
+      Item(src: nil, url: "/page/x"), // browsable, filtered out
+      Item(src: "/b.mp3", url: nil),
+    ]
+    let result = try await SearchDrillIn.playable(from: items, resolveChildren: unusedResolver)
+    #expect(result?.compactMap(\.src) == ["/a.mp3", "/b.mp3"])
+  }
+
+  @Test func firstBrowsable_drillsIntoIt_andPlaysItsChildren() async throws {
+    let items = [
+      Item(src: nil, url: "/page/place"), // browsable first result
+      Item(src: "/later.mp3", url: nil), // would win without drill-in
+    ]
+    let result = try await SearchDrillIn.playable(from: items) { url in
+      #expect(url == "/page/place")
+      return [Item(src: "/station1.mp3", url: nil), Item(src: "/station2.mp3", url: nil)]
+    }
+    #expect(result?.compactMap(\.src) == ["/station1.mp3", "/station2.mp3"])
+  }
+
+  @Test func browsableDrillYieldsNothing_fallsBackToFlat() async throws {
+    let items = [
+      Item(src: nil, url: "/page/empty"),
+      Item(src: "/fallback.mp3", url: nil),
+    ]
+    let result = try await SearchDrillIn.playable(from: items) { _ in
+      [Item(src: nil, url: "/page/nested")] // nothing playable inside
+    }
+    #expect(result?.compactMap(\.src) == ["/fallback.mp3"])
+  }
+
+  @Test func nothingPlayableAnywhere_returnsNil() async throws {
+    let items = [Item(src: nil, url: "/page/a"), Item(src: nil, url: "/page/b")]
+    let result = try await SearchDrillIn.playable(from: items) { _ in
+      [Item(src: nil, url: "/page/nested")]
+    }
+    #expect(result == nil)
+  }
+}

package/ios/Tests/SectionScopeTests.swift

@@ -0,0 +1,82 @@
+@testable import AudioBrowserTestable
+import Testing
+
+struct SectionScopeTests {
+  private func track(_ src: String, group: String? = nil) -> Track {
+    Track(id: src, src: src, groupTitle: group)
+  }
+
+  private func runSrcs(_ section: SectionScope.Section?) -> [String?]? {
+    guard case .run(let tracks) = section else { return nil }
+    return tracks.map(\.src)
+  }
+
+  private func imageRowSrcs(_ section: SectionScope.Section?) -> [String?]? {
+    guard case .imageRow(let items) = section else { return nil }
+    return items.map(\.src)
+  }
+
+  @Test func scopesToTheContiguousGroupTitleRun() {
+    let children = [
+      track("a", group: "First"),
+      track("b", group: "First"),
+      track("c", group: "Second"),
+      track("d", group: "Second"),
+      track("e"),
+    ]
+    #expect(runSrcs(SectionScope.section(of: children, containing: "c")) == ["c", "d"])
+    #expect(runSrcs(SectionScope.section(of: children, containing: "a")) == ["a", "b"])
+  }
+
+  @Test func ungroupedItemsFormTheirOwnRun() {
+    let children = [
+      track("a", group: "First"),
+      track("b"),
+      track("c"),
+      track("d", group: "Second"),
+    ]
+    #expect(runSrcs(SectionScope.section(of: children, containing: "b")) == ["b", "c"])
+  }
+
+  @Test func identicalTitlesInSeparateRunsStaySeparate() {
+    let children = [
+      track("a", group: "Same"),
+      track("x", group: "Other"),
+      track("b", group: "Same"),
+    ]
+    #expect(runSrcs(SectionScope.section(of: children, containing: "a")) == ["a"])
+  }
+
+  @Test func findsTheIdInsideAnImageRow() {
+    let items = [
+      ImageRowItem(src: "s1", title: "One"),
+      ImageRowItem(src: "s2", title: "Two"),
+    ]
+    var row = Track(id: "row", title: "Most Played")
+    row.imageRow = items
+    let children = [row, track("a")]
+    #expect(imageRowSrcs(SectionScope.section(of: children, containing: "s2")) == ["s1", "s2"])
+  }
+
+  @Test func unknownIdReturnsNil() {
+    #expect(SectionScope.section(of: [track("a")], containing: "zz") == nil)
+  }
+
+  // Pins the documented precedence: sections are located by src, and an id
+  // present in both an image row and the flat list resolves to the row.
+  @Test func imageRowWinsOverAFlatListDuplicate() {
+    var row = Track(id: "row", title: "Row")
+    row.imageRow = [ImageRowItem(src: "dup", title: "Dup")]
+    let children = [row, track("dup"), track("b")]
+    #expect(imageRowSrcs(SectionScope.section(of: children, containing: "dup")) == ["dup"])
+  }
+
+  @Test func duplicateSrcAcrossRunsResolvesToTheEarlierRun() {
+    let children = [
+      track("dup", group: "First"),
+      track("x", group: "Second"),
+      track("dup", group: "Second"),
+    ]
+    #expect(runSrcs(SectionScope.section(of: children, containing: "dup")) == ["dup"])
+  }
+}