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

package/ios/Tests/RetryLoopTests.swift

@@ -0,0 +1,270 @@
+import AVFoundation
+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("RetryLoop budgets")
+@MainActor
+struct RetryLoopBudgetTests {
+  /// Returns the mock too — `networkMonitor` is weak, the test must keep it alive.
+  private func makeManager(
+    firstConnectMs: Double,
+    maxMs: Double = 120_000,
+    online: Bool,
+  ) -> (RetryLoop, MockNetworkStatus) {
+    let manager = RetryLoop()
+    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)
+  }
+}
+
+// MARK: - handleError
+
+@Suite("RetryLoop.handleError")
+@MainActor
+struct RetryLoopHandleErrorTests {
+  /// What the loop reported and did, in order.
+  final class Record {
+    var retrying: [TrackPlayerError.PlaybackError] = []
+    var errors: [TrackPlayerError.PlaybackError] = []
+    var reloads: [Bool] = []
+  }
+
+  private func makeLoop(retries: Bool = true, delay: TimeInterval = 0) -> (RetryLoop, Record) {
+    let loop = makeRetryLoop(retries: retries, delay: delay)
+    let record = Record()
+    loop.onRetryingError = { record.retrying.append($0) }
+    loop.onError = { record.errors.append($0) }
+    loop.onRetry = { record.reloads.append($0) }
+    return (loop, record)
+  }
+
+  @Test func aNonRetryableErrorSurfacesAtOnce() {
+    let (loop, record) = makeLoop()
+    loop.handleError(URLError(.badURL), context: .playback)
+    #expect(record.errors == [.playbackFailed])
+    #expect(record.retrying.isEmpty)
+    #expect(loop.pendingTask == nil)
+  }
+
+  /// A disabled policy makes every error terminal: no advisory, no retry task, even for a
+  /// retryable failure, which is still classified.
+  @Test func aDisabledPolicySurfacesAtOnce() {
+    let (loop, record) = makeLoop()
+    loop.updatePolicy(from: nil)
+    loop.handleError(URLError(.notConnectedToInternet), context: .mediaLoad)
+    #expect(record.errors == [.notConnectedToInternet])
+    #expect(record.retrying.isEmpty)
+    #expect(loop.pendingTask == nil)
+  }
+
+  /// Also pins that a finished retry clears its handle: session release waits on it.
+  @Test func aRetryableErrorReloadsFromTheContextsPosition() async {
+    let (loop, record) = makeLoop()
+    loop.handleError(URLError(.timedOut), context: .playback)
+    #expect(loop.pendingTask != nil)
+    await loop.pendingTask?.value
+    loop.handleError(URLError(.timedOut), context: .mediaLoad)
+    await loop.pendingTask?.value
+
+    #expect(record.reloads == [true, false])
+    #expect(record.errors.isEmpty)
+    #expect(loop.pendingTask == nil)
+    #expect(loop.attempts == 2)
+  }
+
+  /// The advisory goes out before the backoff, carrying the classification a terminal report
+  /// would.
+  @Test func theAdvisoryPrecedesTheRetry() async {
+    let (loop, record) = makeLoop()
+    loop.handleError(URLError(.cannotConnectToHost), context: .mediaLoad)
+    #expect(record.retrying == [.hostUnreachable])
+    #expect(record.reloads.isEmpty)
+    await loop.pendingTask?.value
+    #expect(record.errors.isEmpty)
+  }
+
+  @Test func givingUpReportsTheAdvisoryThenTheTerminalError() async {
+    let (loop, record) = makeLoop(retries: false)
+    loop.handleError(URLError(.cannotConnectToHost), context: .mediaLoad)
+    await loop.pendingTask?.value
+    #expect(record.retrying == [.hostUnreachable])
+    #expect(record.errors == [.hostUnreachable])
+  }
+
+  /// A cancelled retry stays silent: a track change or a stop cancels it, and surfacing its
+  /// failure would flip the new track or the stop to .error.
+  @Test func aCancelledRetryStaysSilent() async {
+    let (loop, record) = makeLoop(delay: 0.05)
+    loop.handleError(URLError(.timedOut), context: .playback)
+    let task = loop.pendingTask
+    loop.cancel()
+    #expect(loop.pendingTask == nil)
+    await task?.value
+    #expect(record.errors.isEmpty)
+    #expect(record.reloads.isEmpty)
+  }
+
+  /// A second failure replaces the retry in flight, which neither reports nor reloads.
+  @Test func aNewFailureReplacesTheRetryInFlight() async {
+    let (loop, record) = makeLoop(delay: 0.02)
+    loop.handleError(URLError(.timedOut), context: .playback)
+    let first = loop.pendingTask
+    loop.handleError(URLError(.timedOut), context: .playback)
+    let second = loop.pendingTask
+    await first?.value
+    await second?.value
+    #expect(record.reloads == [true])
+    #expect(record.errors.isEmpty)
+  }
+
+  @Test func theHTTPStatusReachesTheReport() async {
+    let (loop, record) = makeLoop(retries: false)
+    loop.handleError(nil, context: .playback, httpStatusCode: 404)
+    loop.handleError(URLError(.badURL), context: .playback, httpStatusCode: 503)
+    await loop.pendingTask?.value
+    #expect(record.errors == [.httpStatus(404), .httpStatus(503)])
+  }
+
+  /// An unclassifiable failure, retried and given up on, reports the context's fallback.
+  @Test func givingUpOnAnOpaqueFailureReportsTheFallback() async {
+    let (loop, record) = makeLoop(retries: false)
+    loop.handleError(NSError(domain: "CoreMediaErrorDomain", code: -12939), context: .mediaLoad)
+    await loop.pendingTask?.value
+    #expect(record.errors == [.failedToLoadKeyValue])
+  }
+
+  @Test func resetRefillsTheBudgets() async {
+    let (loop, _) = makeLoop()
+    loop.handleError(URLError(.timedOut), context: .playback)
+    await loop.pendingTask?.value
+    #expect(loop.attempts == 1)
+    loop.reset()
+    #expect(loop.attempts == 0)
+  }
+
+  @Test func resetDropsTheRetryInFlightSilently() async {
+    let (loop, record) = makeLoop(delay: 0.02)
+    loop.handleError(URLError(.timedOut), context: .playback)
+    let task = loop.pendingTask
+    loop.reset()
+    #expect(loop.pendingTask == nil)
+    await task?.value
+    #expect(record.errors.isEmpty)
+    #expect(record.reloads.isEmpty)
+  }
+
+  /// A loop whose backoff waits until cancelled, reporting when it starts waiting.
+  private func makeWaitingLoop() -> (RetryLoop, Record, () -> Bool) {
+    var waiting = false
+    let loop = RetryLoop(sleep: { _ in
+      await MainActor.run { waiting = true }
+      try await Task.sleep(for: .seconds(60))
+    })
+    loop.updatePolicy(from: .first(true))
+    loop.shouldRetry = { true }
+    let record = Record()
+    loop.onError = { record.errors.append($0) }
+    loop.onRetry = { record.reloads.append($0) }
+    return (loop, record, { waiting })
+  }
+
+  @Test func aCancelDuringTheBackoffStaysSilent() async {
+    let (loop, record, isWaiting) = makeWaitingLoop()
+    loop.handleError(URLError(.timedOut), context: .playback)
+    let task = loop.pendingTask
+    while !isWaiting() {
+      await Task.yield()
+    }
+    loop.cancel()
+    await task?.value
+    #expect(record.errors.isEmpty)
+    #expect(record.reloads.isEmpty)
+  }
+
+  /// A cancel that lands as the backoff completes (the sleep itself returning normally) still
+  /// stops the reload.
+  @Test func aCancelAsTheBackoffEndsStopsTheReload() async {
+    let holder = LoopHolder()
+    let loop = RetryLoop(sleep: { _ in
+      await holder.loop?.cancel()
+    })
+    holder.loop = loop
+    loop.updatePolicy(from: .first(true))
+    loop.shouldRetry = { true }
+    let record = Record()
+    loop.onError = { record.errors.append($0) }
+    loop.onRetry = { record.reloads.append($0) }
+    loop.handleError(URLError(.timedOut), context: .playback)
+    let task = loop.pendingTask
+    await task?.value
+    #expect(record.reloads.isEmpty)
+    #expect(record.errors.isEmpty)
+  }
+}
+
+@MainActor
+private final class LoopHolder {
+  weak var loop: RetryLoop?
+}

package/ios/Tests/SearchDrillInTests.swift

@@ -4,14 +4,14 @@ import Testing
 
 private struct Item: PlayableSearchItem {
   let src: String?
-  let url: String?
+  let path: 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))")
+  private func unusedResolver(_ path: String) async throws -> [Item] {
+    Issue.record("resolveChildren should not have been called (path: \(path))")
     return []
   }
 
@@ -22,9 +22,9 @@ struct SearchDrillInTests {
 
   @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),
+      Item(src: "/a.mp3", path: nil),
+      Item(src: nil, path: "/page/x"), // browsable, filtered out
+      Item(src: "/b.mp3", path: nil),
     ]
     let result = try await SearchDrillIn.playable(from: items, resolveChildren: unusedResolver)
     #expect(result?.compactMap(\.src) == ["/a.mp3", "/b.mp3"])
@@ -32,31 +32,31 @@ struct SearchDrillInTests {
 
   @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
+      Item(src: nil, path: "/page/place"), // browsable first result
+      Item(src: "/later.mp3", path: 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)]
+    let result = try await SearchDrillIn.playable(from: items) { path in
+      #expect(path == "/page/place")
+      return [Item(src: "/station1.mp3", path: nil), Item(src: "/station2.mp3", path: 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),
+      Item(src: nil, path: "/page/empty"),
+      Item(src: "/fallback.mp3", path: nil),
     ]
     let result = try await SearchDrillIn.playable(from: items) { _ in
-      [Item(src: nil, url: "/page/nested")] // nothing playable inside
+      [Item(src: nil, path: "/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 items = [Item(src: nil, path: "/page/a"), Item(src: nil, path: "/page/b")]
     let result = try await SearchDrillIn.playable(from: items) { _ in
-      [Item(src: nil, url: "/page/nested")]
+      [Item(src: nil, path: "/page/nested")]
     }
     #expect(result == nil)
   }

package/ios/Tests/SectionPresentationTests.swift

@@ -0,0 +1,98 @@
+import Testing
+
+@testable import AudioBrowserTestable
+
+// The (resolved style, platform capability) → rendered-form mapping (ADR
+// 0011): degradation drops decorations before layout, and the one layout drop
+// is a wrapping grid on a platform without a wrapping tile container.
+
+@Suite("SectionPresentation")
+struct SectionPresentationTests {
+  private func style(display: StyleDisplay?, gridWrap: Bool? = nil) -> SectionStyle {
+    SectionStyle(gridWrap: gridWrap, display: display, artworkRendering: nil)
+  }
+
+  @Test func noStyleRendersAList() {
+    #expect(SectionPresentation(for: nil, supportsWrappingGrid: true) == .list)
+    #expect(SectionPresentation(for: nil, supportsWrappingGrid: false) == .list)
+  }
+
+  @Test func listDisplayRendersAList() {
+    #expect(SectionPresentation(for: style(display: .list), supportsWrappingGrid: true) == .list)
+  }
+
+  @Test func wrappingGridNeedsTheWrappingContainer() {
+    #expect(
+      SectionPresentation(for: style(display: .grid), supportsWrappingGrid: true) == .wrappingGrid)
+    // The one layout drop: a wrapping grid has nowhere to go but a list —
+    // every item stays reachable instead of truncating at an unknowable width.
+    #expect(SectionPresentation(for: style(display: .grid), supportsWrappingGrid: false) == .list)
+  }
+
+  @Test func singleLineGridRendersOnEveryOS() {
+    // gridWrap: false is the legacy image row's own shape, so it never
+    // degrades — declaring it INCREASES pre-26 fidelity.
+    #expect(
+      SectionPresentation(for: style(display: .grid, gridWrap: false), supportsWrappingGrid: true)
+        == .singleLineRow)
+    #expect(
+      SectionPresentation(for: style(display: .grid, gridWrap: false), supportsWrappingGrid: false)
+        == .singleLineRow)
+  }
+
+  @Test func explicitWrapTrueBehavesLikeTheDefault() {
+    #expect(
+      SectionPresentation(for: style(display: .grid, gridWrap: true), supportsWrappingGrid: true)
+        == .wrappingGrid)
+    #expect(
+      SectionPresentation(for: style(display: .grid, gridWrap: true), supportsWrappingGrid: false)
+        == .list)
+  }
+
+  @Test func gridWrapIsInertOnLists() {
+    // Declaring a decoration never changes the layout you'd get without it.
+    #expect(
+      SectionPresentation(for: style(display: .list, gridWrap: false), supportsWrappingGrid: true)
+        == .list)
+    #expect(
+      SectionPresentation(for: style(display: nil, gridWrap: false), supportsWrappingGrid: true)
+        == .list)
+  }
+
+  @Test func tileFamilyFollowsGridTile() {
+    // The family follows the declaration alone; the wrap mode only decides
+    // whether its elements take more than one line.
+    #expect(SectionPresentation.tileFamily(for: SectionStyle(gridTile: .card)) == .cardElements)
+    #expect(
+      SectionPresentation.tileFamily(for: SectionStyle(gridTile: .image)) == .imageGridElements)
+    #expect(
+      SectionPresentation.tileFamily(for: SectionStyle(gridTile: .condensed)) == .condensedElements)
+    #expect(SectionPresentation.tileFamily(for: nil) == .rowElements)
+    #expect(SectionPresentation.tileFamily(for: SectionStyle(gridTile: .plain)) == .rowElements)
+  }
+
+  @Test func aPathlessShelfTitlesTheSectionHeader() {
+    let viewAll = Section(title: "Popular", path: "/popular", children: [])
+    let preview = Section(title: "Popular", children: [])
+    let untitled = Section(children: [])
+    // The image row's own text carries a chevron, so it is kept for the
+    // shelf that has somewhere to go.
+    #expect(SectionPresentation.tileSectionHeader(viewAll, supportsElements: true) == nil)
+    #expect(SectionPresentation.tileSectionHeader(preview, supportsElements: true) == "Popular")
+    #expect(SectionPresentation.tileSectionHeader(untitled, supportsElements: true) == nil)
+    // The legacy row cannot drop its text.
+    #expect(SectionPresentation.tileSectionHeader(preview, supportsElements: false) == nil)
+  }
+
+  @Test func effectiveAccessorySymbol_noneAndAbsenceDrawNothing() {
+    // A declared symbol draws; 'none' (the inheritance escape) and absence
+    // both fall back to the derived accessory.
+    #expect(
+      SectionPresentation.effectiveAccessorySymbol(TrackStyle(accessorySymbol: "lock.fill"))
+        == "lock.fill")
+    #expect(
+      SectionPresentation.effectiveAccessorySymbol(TrackStyle(accessorySymbol: "none")) == nil)
+    #expect(SectionPresentation.effectiveAccessorySymbol(TrackStyle()) == nil)
+    #expect(SectionPresentation.effectiveAccessorySymbol(nil) == nil)
+  }
+}

package/ios/Tests/SectionScopeTests.swift

@@ -2,81 +2,113 @@
 import Testing
 
 struct SectionScopeTests {
-  private func track(_ src: String, group: String? = nil) -> Track {
-    Track(id: src, src: src, groupTitle: group)
+  private func track(_ src: String, id: String? = nil) -> Track {
+    Track(id: id ?? src, src: src)
   }
 
-  private func runSrcs(_ section: SectionScope.Section?) -> [String?]? {
-    guard case .run(let tracks) = section else { return nil }
-    return tracks.map(\.src)
+  private func section(_ title: String? = nil, _ tracks: [Track]) -> Section {
+    Section(title: title, children: tracks)
   }
 
-  private func imageRowSrcs(_ section: SectionScope.Section?) -> [String?]? {
-    guard case .imageRow(let items) = section else { return nil }
-    return items.map(\.src)
+  private func srcs(_ scoped: SectionScope.Scoped?) -> [String?]? {
+    scoped.map { $0.section.children.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"),
+  // Two sections sharing an identity — the duplicate-heavy shape the flat
+  // model had to disambiguate by precedence; sections + the stamped flat
+  // index make it exact.
+  private var sections: [Section] {
+    [
+      section("First", [track("dup"), track("x")]),
+      section("Second", [track("y"), track("dup"), track("z")]),
     ]
-    #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 fallsBackToTheFirstSectionContainingTheIdentity() {
+    let scoped = SectionScope.scoped(in: sections, containing: "dup")
+    #expect(srcs(scoped) == ["dup", "x"])
+    #expect(scoped?.tappedOffset == nil)
   }
 
-  @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 flatIndexPinsTheTappedSection() {
+    // Flat index 3 = second section, offset 1.
+    let scoped = SectionScope.scoped(in: sections, containing: "dup", tappedIndex: 3)
+    #expect(srcs(scoped) == ["y", "dup", "z"])
+    #expect(scoped?.tappedOffset == 1)
   }
 
-  @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 flatIndexPinsTheExactCopyWithinASection() {
+    let playlist = [section(nil, [track("a"), track("b"), track("a"), track("c")])]
+    let scoped = SectionScope.scoped(in: playlist, containing: "a", tappedIndex: 2)
+    #expect(scoped?.tappedOffset == 2)
+  }
+
+  @Test func staleIndexFallsBackToTheFirstIdentityMatch() {
+    // The child at the stamped index no longer carries the tapped identity
+    // (the list shifted) — resolution ignores the index and pins nothing.
+    let scoped = SectionScope.scoped(in: sections, containing: "dup", tappedIndex: 1)
+    #expect(srcs(scoped) == ["dup", "x"])
+    #expect(scoped?.tappedOffset == nil)
   }
 
-  @Test func unknownIdReturnsNil() {
-    #expect(SectionScope.section(of: [track("a")], containing: "zz") == nil)
+  @Test func outOfRangeIndexIsIgnored() {
+    let scoped = SectionScope.scoped(in: sections, containing: "dup", tappedIndex: 99)
+    #expect(srcs(scoped) == ["dup", "x"])
+    #expect(scoped?.tappedOffset == 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 vanishedIdentityReturnsNil() {
+    #expect(SectionScope.scoped(in: sections, containing: "gone") == nil)
   }
 
-  @Test func duplicateSrcAcrossRunsResolvesToTheEarlierRun() {
+  // MARK: - Identity (id when non-blank, else src)
+
+  @Test func matchesChildByIdWhenSrcDiffers() {
     let children = [
-      track("dup", group: "First"),
-      track("x", group: "Second"),
-      track("dup", group: "Second"),
+      Track(id: "stable-a", src: "https://cdn.example/a?token=1"),
+      Track(id: "stable-b", src: "https://cdn.example/b?token=2"),
     ]
-    #expect(runSrcs(SectionScope.section(of: children, containing: "dup")) == ["dup"])
+    let scoped = SectionScope.scoped(in: [section(nil, children)], containing: "stable-b")
+    #expect(srcs(scoped) == ["https://cdn.example/a?token=1", "https://cdn.example/b?token=2"])
+  }
+
+  @Test func blankIdFallsBackToSrc() {
+    let children = [Track(id: "", src: "s1"), Track(id: "", src: "s2")]
+    let scoped = SectionScope.scoped(in: [section(nil, children)], containing: "s2")
+    #expect(srcs(scoped) == ["s1", "s2"])
+  }
+
+  // MARK: - Page shape helpers
+
+  @Test func childrenSugarNormalizesToOneUntitledSection() {
+    let page = ResolvedTrack(path: "/p", children: [track("a"), track("b")], title: "P")
+    let sections = page.normalizedSections
+    #expect(sections?.count == 1)
+    #expect(sections?.first?.title == nil)
+    #expect(sections?.first?.children.map(\.src) == ["a", "b"])
+  }
+
+  @Test func sectionsWinOverChildren() {
+    let page = ResolvedTrack(
+      path: "/p",
+      sections: [section("S", [track("a")])],
+      children: [track("zzz")],
+      title: "P",
+    )
+    #expect(page.normalizedSections?.count == 1)
+    #expect(page.normalizedSections?.first?.title == "S")
+  }
+
+  @Test func flattenedChildrenConcatenateInSectionOrder() {
+    let page = ResolvedTrack(
+      path: "/p",
+      sections: [section("A", [track("a1"), track("a2")]), section(nil, [track("b1")])],
+      title: "P",
+    )
+    #expect(page.flattenedChildren?.map(\.src) == ["a1", "a2", "b1"])
+  }
+
+  @Test func childlessPageHasNoSections() {
+    #expect(ResolvedTrack(path: "/p", title: "P").normalizedSections == nil)
   }
 }