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

package/ios/Tests/QueueManagerTests.swift

@@ -120,6 +120,41 @@ struct NextTests {
     #expect(q.shuffleOrder.shuffled == order)
   }
 
+  /// A queue reorder permutes positions, not identities, so it must leave the
+  /// shuffled playback order alone. Re-inserting at a random shuffle position
+  /// would silently reshuffle under the listener.
+  @Test func shuffle_moveKeepsThePlaybackOrder() {
+    for target in 0 ..< 5 {
+      let q = QueueManager()
+      q.setQueue(tracks("a", "b", "c", "d", "e"))
+      q.shuffleEnabled = true
+      let before = q.shuffleOrder.shuffled.map { q.tracks[$0].id }
+
+      _ = try? q.move(fromIndex: 0, toIndex: target)
+
+      #expect(q.shuffleOrder.shuffled.map { q.tracks[$0].id } == before)
+    }
+  }
+
+  /// The same hazard as `shuffle_startTrackLeadsTheOrder`, reached by moving the
+  /// *playing* track: a random re-insert can drop it last in the shuffle order,
+  /// which reads as `isLastInPlaybackOrder` and ends the queue at the next track
+  /// boundary with tracks still unplayed.
+  @Test func shuffle_movingCurrentTrackDoesNotEndTheQueue() {
+    for target in 1 ..< 6 {
+      let q = QueueManager()
+      q.setQueue(tracks("a", "b", "c", "d", "e", "f"), initialIndex: 0)
+      q.shuffleEnabled = true // pins "a" first in the order
+      #expect(!q.isLastInPlaybackOrder)
+
+      _ = try? q.move(fromIndex: 0, toIndex: target)
+
+      #expect(q.currentTrack?.id == "a")
+      #expect(!q.isLastInPlaybackOrder)
+      #expect(q.nextTracks.count == 5)
+    }
+  }
+
   @Test func shuffle_visitsAllTracks() {
     let q = QueueManager()
     q.setQueue(tracks("a", "b", "c", "d"))
@@ -382,6 +417,25 @@ struct AddTests {
     #expect(q.tracks[2].id == "c")
     #expect(q.tracks[3].id == "d")
   }
+
+  /// Filling an empty queue must pin the start track to the head of the shuffle
+  /// order, exactly as `setQueue` does — `insert(at:count:)` places new indices
+  /// at random positions, so without the pin the start track can land last and
+  /// the queue reports end-of-queue as soon as it finishes. `shuffleEnabled`'s
+  /// didSet only re-pins on the off→on edge, so shuffle-already-on gets nothing
+  /// from it.
+  @Test func toEmptyQueue_withShuffleAlreadyOn_startTrackLeadsTheOrder() {
+    for start in 0 ..< 6 {
+      let q = QueueManager()
+      q.shuffleEnabled = true
+      q.add(tracks("a", "b", "c", "d", "e", "f"), initialIndex: start)
+
+      #expect(q.shuffleOrder.isFirst(start))
+      #expect(!q.isLastInPlaybackOrder)
+      #expect(q.nextTracks.count == 5)
+      #expect(q.previousTracks.isEmpty)
+    }
+  }
 }
 
 // MARK: - Mutations: addAt()
@@ -414,6 +468,18 @@ struct AddAtTests {
     #expect(q.currentIndex == 0)
   }
 
+  /// Same pinning requirement as `add()` into an empty queue — see its twin.
+  @Test func toEmptyQueue_withShuffleAlreadyOn_startTrackLeadsTheOrder() throws {
+    let q = QueueManager()
+    q.shuffleEnabled = true
+    try q.addAt(tracks("a", "b", "c", "d", "e", "f"), at: 0)
+
+    #expect(q.shuffleOrder.isFirst(0))
+    #expect(!q.isLastInPlaybackOrder)
+    #expect(q.nextTracks.count == 5)
+    #expect(q.previousTracks.isEmpty)
+  }
+
   @Test func invalidIndex_throws() {
     let q = QueueManager()
     q.setQueue(tracks("a"))
@@ -691,10 +757,10 @@ struct ClearTests {
 @Suite("replace & removeUpcomingTracks")
 @MainActor
 struct OtherMutationTests {
-  @Test func replace_updatesTrackAtIndex() {
+  @Test func replace_updatesTrackAtIndex() throws {
     let q = QueueManager()
     q.setQueue(tracks("a", "b", "c"))
-    q.replace(1, Track(id: "B"))
+    try q.replace(1, Track(id: "B"))
     #expect(q.tracks[1].id == "B")
   }
 
@@ -738,10 +804,10 @@ struct OtherMutationTests {
     #expect(q.tracks[0].id == "a")
   }
 
-  @Test func replace_currentTrack_reflectsInCurrentTrack() {
+  @Test func replace_currentTrack_reflectsInCurrentTrack() throws {
     let q = QueueManager()
     q.setQueue(tracks("a", "b", "c"), initialIndex: 1)
-    q.replace(1, Track(id: "B"))
+    try q.replace(1, Track(id: "B"))
     #expect(q.currentTrack?.id == "B")
     #expect(q.currentIndex == 1)
   }
@@ -926,12 +992,12 @@ struct DelegateTests {
     #expect(spy.calls.count == 1)
   }
 
-  @Test func queueDidChangeTracks_firesOnReplace() {
+  @Test func queueDidChangeTracks_firesOnReplace() throws {
     let q = QueueManager()
     q.setQueue(tracks("a", "b"))
     let spy = DelegateSpy()
     q.delegate = spy
-    q.replace(0, Track(id: "A"))
+    try q.replace(0, Track(id: "A"))
     #expect(spy.calls.count == 1)
   }
 

package/ios/Tests/RemoteCommandControllerTests.swift

@@ -136,6 +136,22 @@ struct RemoteCommandControllerTests {
     #expect(center.previousTrackCommand.isEnabled)
   }
 
+  /// The handler properties must not capture the controller strongly. Assigning a
+  /// bare method reference (`= handlePlayCommandDefault`) curries to
+  /// `{ [self] in self.method($0) }`, and storing that back on self is a permanent
+  /// cycle — one leaked controller per player instance, across every JS reload.
+  @Test func doesNotRetainItselfThroughHandlers() {
+    weak var weakController: RemoteCommandController?
+    autoreleasepool {
+      let (controller, _) = makeController()
+      // Forces every lazy handler to initialize, which is what closes the cycle.
+      controller.enable(commands: RemoteCommand.all())
+      controller.disableAll()
+      weakController = controller
+    }
+    #expect(weakController == nil)
+  }
+
   @Test func shuffleAndRepeatStateSurviveCommandCenterSwitch() {
     let (controller, _) = makeController()
     let center = MPRemoteCommandCenter.shared()

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,23 @@ private func makeResolvedTrack(
     description: nil,
     genre: nil,
     duration: nil,
-    style: nil,
-    childrenStyle: nil,
+    disabled: nil,
     favorited: nil,
-    groupTitle: nil,
     live: nil,
-    imageRow: 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", subtitle: nil, 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 +46,9 @@ 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")],
   )
 }
 
@@ -64,12 +60,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 +73,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 +131,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 +159,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", subtitle: nil, 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 +210,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 +234,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/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 let .run(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 let .imageRow(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)
   }
 }