react-native-audio-browser 0.2.0-next.2 → 0.2.0-next.20

package/ios/Tests/ResolvedTrackCopyingTests.swift

@@ -3,17 +3,18 @@ import Testing
 @testable import AudioBrowserTestable
 
 private func makeResolvedTrack(
-  url: String = "/test",
+  path: String = "/test",
   title: String = "Test Track",
 ) -> ResolvedTrack {
   ResolvedTrack(
-    url: url,
+    path: path,
+    style: nil,
+    sections: nil,
     children: nil,
     carPlaySiriListButton: nil,
     src: nil,
     artwork: nil,
     artworkSource: nil,
-    artworkCarPlayTinted: nil,
     title: title,
     subtitle: nil,
     artist: nil,
@@ -21,25 +22,24 @@ private func makeResolvedTrack(
     description: nil,
     genre: nil,
     duration: nil,
-    style: nil,
-    childrenStyle: nil,
+    disabled: nil,
     favorited: nil,
-    groupTitle: nil,
     live: nil,
-    imageRow: nil,
+    icyCharset: nil,
   )
 }
 
 private func makeFullResolvedTrack() -> ResolvedTrack {
   ResolvedTrack(
-    url: "/original",
-    children: [Track(id: "t1", url: "/t1")],
+    path: "/original",
+    style: SectionStyle(gridWrap: false, display: .grid, artworkRendering: .stencil),
+    sections: [Section(title: "Group A", style: nil, path: nil, children: [])],
+    children: [Track(id: "t1", path: "/t1")],
     carPlaySiriListButton: .top,
     id: "original-id",
     src: "src.mp3",
     artwork: .first("art.jpg"),
     artworkSource: ImageSource(uri: "resolved-art.jpg"),
-    artworkCarPlayTinted: true,
     title: "Original Title",
     subtitle: "Original Subtitle",
     artist: "Original Artist",
@@ -47,12 +47,10 @@ private func makeFullResolvedTrack() -> ResolvedTrack {
     description: "Original Description",
     genre: "Rock",
     duration: 180.0,
-    style: .list,
-    childrenStyle: .grid,
+    disabled: false,
     favorited: true,
-    groupTitle: "Group A",
     live: false,
-    imageRow: [ImageRowItem(title: "Row 1")],
+    icyCharset: nil,
   )
 }
 
@@ -64,12 +62,12 @@ private func makeFullResolvedTrack() -> ResolvedTrack {
   #expect(copy == original)
 }
 
-// MARK: - non-optional fields (url, title)
+// MARK: - non-optional fields (path, title)
 
-@Test func copyingOverridesUrl() {
-  let original = makeResolvedTrack(url: "/old")
-  let copy = original.copying(url: "/new")
-  #expect(copy.url == "/new")
+@Test func copyingOverridesPath() {
+  let original = makeResolvedTrack(path: "/old")
+  let copy = original.copying(path: "/new")
+  #expect(copy.path == "/new")
   #expect(copy.title == "Test Track")
 }
 
@@ -77,14 +75,14 @@ private func makeFullResolvedTrack() -> ResolvedTrack {
   let original = makeResolvedTrack(title: "Old")
   let copy = original.copying(title: "New")
   #expect(copy.title == "New")
-  #expect(copy.url == "/test")
+  #expect(copy.path == "/test")
 }
 
 // MARK: - optional fields: set value
 
 @Test func copyingOverridesChildren() {
   let original = makeResolvedTrack()
-  let children = [Track(id: "c1", url: "/c1"), Track(id: "c2", url: "/c2")]
+  let children = [Track(id: "c1", path: "/c1"), Track(id: "c2", path: "/c2")]
   let copy = original.copying(children: children)
   #expect(copy.children?.count == 2)
   #expect(copy.children?[0].id == "c1")
@@ -135,8 +133,14 @@ private func makeFullResolvedTrack() -> ResolvedTrack {
 
 @Test func copyingOverridesStyle() {
   let original = makeResolvedTrack()
-  let copy = original.copying(style: .grid)
-  #expect(copy.style == .grid)
+  let copy = original.copying(style: SectionStyle(gridWrap: nil, display: .grid, artworkRendering: nil))
+  #expect(copy.style?.display == .grid)
+}
+
+@Test func copyingOverridesDisabled() {
+  let original = makeResolvedTrack()
+  let copy = original.copying(disabled: true)
+  #expect(copy.disabled == true)
 }
 
 @Test func copyingOverridesFavorited() {
@@ -157,11 +161,13 @@ private func makeFullResolvedTrack() -> ResolvedTrack {
   #expect(copy.carPlaySiriListButton == .bottom)
 }
 
-@Test func copyingOverridesImageRow() {
+@Test func copyingOverridesSections() {
   let original = makeResolvedTrack()
-  let items = [ImageRowItem(title: "Item 1"), ImageRowItem(title: "Item 2")]
-  let copy = original.copying(imageRow: items)
-  #expect(copy.imageRow == items)
+  let sections = [
+    Section(title: "A", style: nil, path: nil, children: [Track(id: "c1", src: "c1")]),
+  ]
+  let copy = original.copying(sections: sections)
+  #expect(copy.sections == sections)
 }
 
 // MARK: - optional fields: set to nil via .some(nil)
@@ -206,13 +212,13 @@ private func makeFullResolvedTrack() -> ResolvedTrack {
 @Test func copyingOverridesMultipleFields() {
   let original = makeResolvedTrack()
   let copy = original.copying(
-    url: "/updated",
+    path: "/updated",
     title: "Updated Title",
     artist: "New Artist",
     duration: 240.0,
     favorited: true,
   )
-  #expect(copy.url == "/updated")
+  #expect(copy.path == "/updated")
   #expect(copy.title == "Updated Title")
   #expect(copy.artist == "New Artist")
   #expect(copy.duration == 240.0)
@@ -230,23 +236,21 @@ private func makeFullResolvedTrack() -> ResolvedTrack {
   let copy = original.copying(title: "Changed Only Title")
   #expect(copy.title == "Changed Only Title")
   // All other fields unchanged
-  #expect(copy.url == "/original")
+  #expect(copy.path == "/original")
   #expect(copy.children?.count == 1)
   #expect(copy.carPlaySiriListButton == .top)
   #expect(copy.src == "src.mp3")
   #expect(copy.artwork?.url == "art.jpg")
   #expect(copy.artworkSource == ImageSource(uri: "resolved-art.jpg"))
-  #expect(copy.artworkCarPlayTinted == true)
   #expect(copy.subtitle == "Original Subtitle")
   #expect(copy.artist == "Original Artist")
   #expect(copy.album == "Original Album")
   #expect(copy.description == "Original Description")
   #expect(copy.genre == "Rock")
   #expect(copy.duration == 180.0)
-  #expect(copy.style == .list)
-  #expect(copy.childrenStyle == .grid)
+  #expect(copy.style == SectionStyle(gridWrap: false, display: .grid, artworkRendering: .stencil))
+  #expect(copy.disabled == false)
   #expect(copy.favorited == true)
-  #expect(copy.groupTitle == "Group A")
+  #expect(copy.sections?.first?.title == "Group A")
   #expect(copy.live == false)
-  #expect(copy.imageRow == [ImageRowItem(title: "Row 1")])
 }

package/ios/Tests/RetryManagerTests.swift

@@ -1,3 +1,4 @@
+import AVFoundation
 import Foundation
 import Testing
 
@@ -87,3 +88,91 @@ struct RetryManagerBudgetTests {
     #expect(manager.hasPlayed == true)
   }
 }
+
+/// Which failures earn another attempt. The reference is Android's
+/// `RetryLoadErrorHandlingPolicy.classifyError`: same HTTP set, and the same
+/// default of treating an unrecognized failure as transient. Defaulting the
+/// other way made `retry: true` largely inert on iOS, since AVFoundation
+/// reports most stream failures as opaque CoreMedia errors, not `URLError`.
+@Suite("RetryManager error classification")
+@MainActor
+struct RetryManagerClassificationTests {
+  private func makeManager() -> RetryManager {
+    let manager = RetryManager()
+    manager.updatePolicy(from: .first(true))
+    return manager
+  }
+
+  /// `AVPlayerItem.error` never carries the status, so the caller reads it off
+  /// the item's error log and passes it in. It outranks the opaque error.
+  @Test(arguments: [408, 429, 500, 502, 503, 504])
+  func retryableHTTPStatus_retries(status: Int) {
+    let opaque = NSError(domain: "CoreMediaErrorDomain", code: -12660)
+    #expect(makeManager().isRetryable(opaque, httpStatusCode: status) == true)
+  }
+
+  /// A retry cannot conjure content that isn't there, whatever the error says.
+  @Test(arguments: [400, 401, 403, 404, 410, 451])
+  func permanentHTTPStatus_doesNotRetry(status: Int) {
+    let transient = URLError(.timedOut)
+    #expect(makeManager().isRetryable(transient, httpStatusCode: status) == false)
+  }
+
+  @Test func transientURLError_retries() {
+    #expect(makeManager().isRetryable(URLError(.networkConnectionLost), httpStatusCode: nil) == true)
+  }
+
+  @Test func fatalURLError_doesNotRetry() {
+    #expect(makeManager().isRetryable(URLError(.badURL), httpStatusCode: nil) == false)
+  }
+
+  /// The regression this suite exists for: an opaque CoreMedia failure with no
+  /// status to read used to be terminal, so a station that dropped mid-song
+  /// never came back on iOS while Android reconnected.
+  @Test func opaqueCoreMediaError_retries() {
+    let error = NSError(domain: "CoreMediaErrorDomain", code: -12939)
+    #expect(makeManager().isRetryable(error, httpStatusCode: nil) == true)
+  }
+
+  /// `AVErrorUnknown` is the wrapper AVFoundation puts around transport
+  /// failures, so it must stay retryable even though it is an AVError.
+  @Test func avErrorUnknown_retries() {
+    let error = NSError(domain: AVFoundationErrorDomain, code: AVError.unknown.rawValue)
+    #expect(makeManager().isRetryable(error, httpStatusCode: nil) == true)
+  }
+
+  @Test(arguments: [
+    AVError.fileFormatNotRecognized.rawValue,
+    AVError.failedToParse.rawValue,
+    AVError.decodeFailed.rawValue,
+  ])
+  func unusableMedia_doesNotRetry(code: Int) {
+    let error = NSError(domain: AVFoundationErrorDomain, code: code)
+    #expect(makeManager().isRetryable(error, httpStatusCode: nil) == false)
+  }
+
+  /// AVFoundation wraps the real cause rather than surfacing it, which is why
+  /// the classifier walks `NSUnderlyingError` instead of inspecting only the
+  /// outermost error.
+  @Test func underlyingURLError_isFound() {
+    let manager = makeManager()
+    let wrapped = NSError(
+      domain: AVFoundationErrorDomain,
+      code: AVError.unknown.rawValue,
+      userInfo: [NSUnderlyingErrorKey: URLError(.badURL)],
+    )
+    #expect(manager.isRetryable(wrapped, httpStatusCode: nil) == false)
+
+    let transient = NSError(
+      domain: AVFoundationErrorDomain,
+      code: AVError.unknown.rawValue,
+      userInfo: [NSUnderlyingErrorKey: URLError(.dnsLookupFailed)],
+    )
+    #expect(manager.isRetryable(transient, httpStatusCode: nil) == true)
+  }
+
+  /// Nothing to classify: no error and no status stays terminal.
+  @Test func nilError_doesNotRetry() {
+    #expect(makeManager().isRetryable(nil, httpStatusCode: nil) == false)
+  }
+}

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,90 @@
+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 tileFamilyFollowsGridTileWithThePlainSplit() {
+    // Card/condensed follow the declaration in either wrap mode; the plain
+    // default splits on the wrap: single-line keeps row elements (the
+    // subtitle slot), wrapping renders the image grid.
+    #expect(
+      SectionPresentation.tileFamily(for: SectionStyle(gridTile: .card), singleLine: true)
+        == .cardElements)
+    #expect(
+      SectionPresentation.tileFamily(for: SectionStyle(gridTile: .condensed), singleLine: false)
+        == .condensedElements)
+    #expect(SectionPresentation.tileFamily(for: nil, singleLine: true) == .rowElements)
+    #expect(SectionPresentation.tileFamily(for: nil, singleLine: false) == .imageGridElements)
+    #expect(
+      SectionPresentation.tileFamily(for: SectionStyle(gridTile: .plain), singleLine: true)
+        == .rowElements)
+  }
+
+  @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)
   }
 }