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

package/ios/Tests/StyleResolverTests.swift

@@ -0,0 +1,127 @@
+import Testing
+
+@testable import AudioBrowserTestable
+
+// Resolution semantics (ADR 0011): container properties and `display` resolve
+// by scope override (`section ?? page`), inherited item properties resolve
+// `track ?? section ?? page` — and `display` never inherits onto an item.
+
+@Suite("StyleResolver.sectionStyle")
+struct SectionStyleResolutionTests {
+  @Test func sectionOverridesThePagePerProperty() {
+    let resolved = StyleResolver.sectionStyle(
+      section: SectionStyle(gridWrap: nil, display: .list, artworkRendering: nil),
+      page: SectionStyle(gridWrap: false, display: .grid, artworkRendering: .stencil),
+    )
+    // Declared on the section: wins. Undeclared: the page's scope-wide value.
+    #expect(resolved.display == .list)
+    #expect(resolved.artworkRendering == .stencil)
+    #expect(resolved.gridWrap == false)
+  }
+
+  @Test func aStylelessSectionTakesThePageBlock() {
+    let resolved = StyleResolver.sectionStyle(
+      section: nil,
+      page: SectionStyle(gridWrap: true, display: .grid, artworkRendering: nil),
+    )
+    #expect(resolved.display == .grid)
+    #expect(resolved.gridWrap == true)
+  }
+
+  @Test func noDeclarationsResolveToAnEmptyBlock() {
+    let resolved = StyleResolver.sectionStyle(section: nil, page: nil)
+    #expect(resolved.display == nil)
+    #expect(resolved.artworkRendering == nil)
+    #expect(resolved.gridWrap == nil)
+    #expect(resolved.gridTile == nil)
+  }
+
+  @Test func gridTileResolvesByScopeOverride() {
+    // A page-wide card treatment; one section opts back to plain tiles.
+    let inherited = StyleResolver.sectionStyle(
+      section: nil,
+      page: SectionStyle(gridTile: .card),
+    )
+    #expect(inherited.gridTile == .card)
+    let overridden = StyleResolver.sectionStyle(
+      section: SectionStyle(gridTile: .plain),
+      page: SectionStyle(gridTile: .card),
+    )
+    #expect(overridden.gridTile == .plain)
+  }
+}
+
+@Suite("StyleResolver.trackStyle")
+struct TrackStyleResolutionTests {
+  @Test func trackOverridesTheSectionPerProperty() {
+    let resolved = StyleResolver.trackStyle(
+      track: TrackStyle(display: nil, artworkRendering: .original),
+      section: SectionStyle(gridWrap: nil, display: .grid, artworkRendering: .stencil),
+    )
+    #expect(resolved.artworkRendering == .original)
+  }
+
+  @Test func aStylelessTrackInheritsTheSectionValue() {
+    let resolved = StyleResolver.trackStyle(
+      track: nil,
+      section: SectionStyle(gridWrap: nil, display: nil, artworkRendering: .stencil),
+    )
+    #expect(resolved.artworkRendering == .stencil)
+  }
+
+  @Test func displayNeverInheritsOntoAnItem() {
+    // The track's own `display` is the page promise for the page IT opens;
+    // the section's describes its children's layout. Neither may surface as
+    // the item's resolved display.
+    let resolved = StyleResolver.trackStyle(
+      track: TrackStyle(display: .grid, artworkRendering: nil),
+      section: SectionStyle(gridWrap: nil, display: .grid, artworkRendering: nil),
+    )
+    #expect(resolved.display == nil)
+  }
+
+  @Test func imageShapeInheritsAndOverridesPerItem() {
+    // Section-wide circular (an artists shelf); one album overrides.
+    let inherited = StyleResolver.trackStyle(
+      track: nil,
+      section: SectionStyle(imageShape: .circular),
+    )
+    #expect(inherited.imageShape == .circular)
+    let overridden = StyleResolver.trackStyle(
+      track: TrackStyle(imageShape: .roundedRectangle),
+      section: SectionStyle(imageShape: .circular),
+    )
+    #expect(overridden.imageShape == .roundedRectangle)
+  }
+
+  @Test func accessorySymbolInheritsAndNoneResolvesAsAValue() {
+    let inherited = StyleResolver.trackStyle(
+      track: nil,
+      section: SectionStyle(accessorySymbol: "lock.fill"),
+    )
+    #expect(inherited.accessorySymbol == "lock.fill")
+    // 'none' is the inheritance escape — it must survive resolution intact
+    // (the renderer, not the resolver, maps it to "no accessory").
+    let escaped = StyleResolver.trackStyle(
+      track: TrackStyle(accessorySymbol: "none"),
+      section: SectionStyle(accessorySymbol: "lock.fill"),
+    )
+    #expect(escaped.accessorySymbol == "none")
+  }
+
+  @Test func cardPropertiesInheritAndOverridePerItem() {
+    // Section-wide tint/mode; one card overrides its image mode.
+    let inherited = StyleResolver.trackStyle(
+      track: nil,
+      section: SectionStyle(accessorySymbol: nil, cardTint: "#1e3a8a", cardImage: .background),
+    )
+    #expect(inherited.cardTint == "#1e3a8a")
+    #expect(inherited.cardImage == .background)
+    let overridden = StyleResolver.trackStyle(
+      track: TrackStyle(cardImage: .normal),
+      section: SectionStyle(cardTint: "#1e3a8a", cardImage: .background),
+    )
+    #expect(overridden.cardImage == .normal)
+    #expect(overridden.cardTint == "#1e3a8a")
+  }
+}

package/ios/Tests/Support/TestTypes.swift

@@ -185,6 +185,7 @@ final class MockSleepTimerHandling: SleepTimerHandling {
   var onComplete: (() -> Void)?
   var onFadeStart: ((_ duration: TimeInterval) -> Void)?
   var onFadeCancel: (() -> Void)?
+  var onChanged: ((SleepTimerState) -> Void)?
   var trackChangedCallCount = 0
   var trackPlayedToEndCallCount = 0
   var clearCallCount = 0
@@ -196,6 +197,12 @@ final class MockSleepTimerHandling: SleepTimerHandling {
 
   func onTrackChanged() { trackChangedCallCount += 1 }
   func onTrackPlayedToEnd() { trackPlayedToEndCallCount += 1 }
+
+  // Consumer-facing surface — unused by the coordinator tests, present only to
+  // satisfy the protocol. Add recorders alongside the tests that need them.
+  func get() -> SleepTimerState? { nil }
+  func set(seconds _: TimeInterval, fadeDuration _: TimeInterval?) {}
+  func setToEndOfTrack() {}
 }
 
 // MARK: - Mock RetryHandling

package/ios/Tests/TabBarEntriesTests.swift

@@ -4,59 +4,59 @@ import Testing
 
 struct TabBarEntriesTests {
   private func tab(
-    _ title: String, url: String, artwork: String? = nil,
+    _ title: String, path: String, artwork: String? = nil,
     artworkSource: ImageSource? = nil, artist: String? = nil,
   ) -> Track {
     Track(
-      id: url, url: url, title: title, artist: artist, artwork: artwork.map { .first($0) },
-      artworkSource: artworkSource,
+      id: path, path: path, artwork: artwork.map { .first($0) },
+      artworkSource: artworkSource, title: title, artist: artist,
     )
   }
 
   @Test func identicalListsAreSame() {
-    let tabs = [tab("Explore", url: "/explore"), tab("Browse", url: "/browse")]
+    let tabs = [tab("Explore", path: "/explore"), tab("Browse", path: "/browse")]
     #expect(TabBarEntries.same(tabs, tabs))
   }
 
   @Test func titleChangeDiffers() {
     #expect(
       !TabBarEntries.same(
-        [tab("Explore", url: "/explore")],
-        [tab("Verkennen", url: "/explore")],
+        [tab("Explore", path: "/explore")],
+        [tab("Verkennen", path: "/explore")],
       ))
   }
 
-  @Test func urlChangeDiffers() {
+  @Test func pathChangeDiffers() {
     #expect(
       !TabBarEntries.same(
-        [tab("Explore", url: "/explore")],
-        [tab("Explore", url: "/discover")],
+        [tab("Explore", path: "/explore")],
+        [tab("Explore", path: "/discover")],
       ))
   }
 
   @Test func artworkChangeDiffers() {
     #expect(
       !TabBarEntries.same(
-        [tab("Explore", url: "/explore", artwork: "sf:globe")],
-        [tab("Explore", url: "/explore", artwork: "sf:map")],
+        [tab("Explore", path: "/explore", artwork: "sf:globe")],
+        [tab("Explore", path: "/explore", artwork: "sf:map")],
       ))
   }
 
   @Test func artworkSourceUriChangeDiffers() {
     #expect(
       !TabBarEntries.same(
-        [tab("Explore", url: "/explore", artworkSource: ImageSource(uri: "https://a/1.png"))],
-        [tab("Explore", url: "/explore", artworkSource: ImageSource(uri: "https://a/2.png"))],
+        [tab("Explore", path: "/explore", artworkSource: ImageSource(uri: "https://a/1.png"))],
+        [tab("Explore", path: "/explore", artworkSource: ImageSource(uri: "https://a/2.png"))],
       ))
   }
 
   @Test func countChangeDiffers() {
-    let tabs = [tab("Explore", url: "/explore")]
-    #expect(!TabBarEntries.same(tabs, tabs + [tab("Browse", url: "/browse")]))
+    let tabs = [tab("Explore", path: "/explore")]
+    #expect(!TabBarEntries.same(tabs, tabs + [tab("Browse", path: "/browse")]))
   }
 
   @Test func nilOldDiffers() {
-    #expect(!TabBarEntries.same(nil, [tab("Explore", url: "/explore")]))
+    #expect(!TabBarEntries.same(nil, [tab("Explore", path: "/explore")]))
   }
 
   @Test func nonRenderedFieldChangeIsSame() {
@@ -64,8 +64,8 @@ struct TabBarEntriesTests {
     // drift without churning the tab bar.
     #expect(
       TabBarEntries.same(
-        [tab("Explore", url: "/explore", artist: "a")],
-        [tab("Explore", url: "/explore", artist: "b")],
+        [tab("Explore", path: "/explore", artist: "a")],
+        [tab("Explore", path: "/explore", artist: "b")],
       ))
   }
 }

package/ios/Tests/TrackIdTemplateTests.swift

@@ -0,0 +1,67 @@
+@testable import AudioBrowserTestable
+import Testing
+
+/// `{id}` template substitution used by artwork URL resolution
+/// (BrowserManager+URLResolution.substituteTrackId). A track without a non-blank id must leave
+/// the token LITERALLY in place — never substitute an empty string, never skip — so the
+/// resulting request 404s with a self-describing URL (the resolver logs a warning keyed off
+/// `containsToken`). Mirrors Android's `substituteTrackId` / `configContainsIdToken`.
+struct TrackIdTemplateTests {
+  // MARK: substitution with an id
+
+  @Test func substitutesTokenInString() {
+    #expect(TrackIdTemplate.substitute("/artwork/{id}", id: "abc") == "/artwork/abc")
+  }
+
+  @Test func substitutesEveryOccurrence() {
+    #expect(TrackIdTemplate.substitute("/{id}/art/{id}.png", id: "x") == "/x/art/x.png")
+  }
+
+  @Test func substitutesTokenInDictionaryValues() {
+    let subbed = TrackIdTemplate.substitute(["x-track": "{id}", "plain": "v"], id: "abc")
+    #expect(subbed == ["x-track": "abc", "plain": "v"])
+  }
+
+  @Test func valueWithoutTokenIsUnchanged() {
+    #expect(TrackIdTemplate.substitute("/artwork/static.png", id: "abc") == "/artwork/static.png")
+  }
+
+  // MARK: token left literal without an id
+
+  @Test func nilIdLeavesTokenLiteral() {
+    #expect(TrackIdTemplate.substitute("/artwork/{id}", id: nil) == "/artwork/{id}")
+  }
+
+  @Test func blankIdLeavesTokenLiteral() {
+    #expect(TrackIdTemplate.substitute("/artwork/{id}", id: "") == "/artwork/{id}")
+  }
+
+  @Test func nilIdLeavesDictionaryValuesLiteral() {
+    #expect(TrackIdTemplate.substitute(["x-track": "{id}"], id: nil) == ["x-track": "{id}"])
+  }
+
+  @Test func nilValuePassesThrough() {
+    #expect(TrackIdTemplate.substitute(String?.none, id: "abc") == nil)
+    #expect(TrackIdTemplate.substitute([String: String]?.none, id: nil) == nil)
+  }
+
+  // MARK: unfilled-token detection (drives the single warning)
+
+  @Test func detectsUnfilledTokenInString() {
+    #expect(TrackIdTemplate.containsToken("/artwork/{id}"))
+    #expect(!TrackIdTemplate.containsToken("/artwork/abc"))
+    #expect(!TrackIdTemplate.containsToken(String?.none))
+  }
+
+  @Test func detectsUnfilledTokenInDictionaryValues() {
+    #expect(TrackIdTemplate.containsToken(["x-track": "{id}"]))
+    #expect(!TrackIdTemplate.containsToken(["x-track": "abc"]))
+    #expect(!TrackIdTemplate.containsToken([String: String]?.none))
+  }
+
+  @Test func substitutionThenDetectionNeverBothMatch() {
+    // With an id, substitution clears the token, so no warning fires.
+    let subbed = TrackIdTemplate.substitute("/artwork/{id}", id: "abc")
+    #expect(!TrackIdTemplate.containsToken(subbed))
+  }
+}

package/ios/Tests/TrackIdentityTests.swift

@@ -0,0 +1,20 @@
+@testable import AudioBrowserTestable
+import Testing
+
+struct TrackIdentityTests {
+  @Test func idWinsOverSrc() {
+    #expect(Track(id: "stable", src: "https://cdn.example/stream").identity == "stable")
+  }
+
+  @Test func blankIdFallsBackToSrc() {
+    #expect(Track(id: "", src: "https://cdn.example/stream").identity == "https://cdn.example/stream")
+  }
+
+  @Test func nilIdFallsBackToSrc() {
+    #expect(Track(src: "https://cdn.example/stream").identity == "https://cdn.example/stream")
+  }
+
+  @Test func neitherIdNorSrcHasNoIdentity() {
+    #expect(Track(path: "/browse/only").identity == nil)
+  }
+}

package/ios/Tests/TrackSelectorTests.swift

@@ -12,15 +12,15 @@ private final class BrowserMock: TrackSelectionBrowser {
 
   // Record calls for verification
   var trackLoadEvents: [TrackLoadEvent] = []
-  var expandedUrls: [String] = []
+  var expandedPaths: [String] = []
 
   func awaitTrackLoadHandler(event: TrackLoadEvent) async -> Bool {
     trackLoadEvents.append(event)
     return trackLoadHandlerResult
   }
 
-  func expandQueueFromContextualUrl(_ url: String) async throws -> (tracks: [Track], selectedIndex: Int)? {
-    expandedUrls.append(url)
+  func expandQueueFromContextualPath(_ path: String) async throws -> (tracks: [Track], selectedIndex: Int)? {
+    expandedPaths.append(path)
     if let error = expandQueueError {
       throw error
     }
@@ -53,23 +53,23 @@ private func makeSelector() -> (TrackSelector, BrowserMock, PlayerMock) {
 @Suite("browsable track")
 @MainActor
 struct BrowsableTrackTests {
-  @Test func urlOnly_returnsBrowse() async {
+  @Test func pathOnly_returnsBrowse() async {
     let (selector, _, player) = makeSelector()
-    let track = Track(id: "t1", url: "/some/path")
+    let track = Track(id: "t1", path: "/some/path")
     let result = await selector.select(track: track, player: player)
-    guard case let .browse(url) = result else {
+    guard case let .browse(path) = result else {
       Issue.record("expected .browse, got \(result)")
       return
     }
-    #expect(url == "/some/path")
+    #expect(path == "/some/path")
   }
 }
 
-// MARK: - No src or url
+// MARK: - No src or path
 
-@Suite("no src or url")
+@Suite("no src or path")
 @MainActor
-struct NoSrcOrUrlTests {
+struct NoSrcOrPathTests {
   @Test func returnsNone() async {
     let (selector, _, player) = makeSelector()
     let track = Track(id: "t1")
@@ -115,25 +115,56 @@ struct PlayableTrackTests {
   }
 }
 
-// MARK: - Contextual URL Queue Reuse
+// MARK: - Contextual path Queue Reuse
 
-@Suite("contextual URL queue reuse")
+@Suite("contextual path queue reuse")
 @MainActor
-struct ContextualUrlQueueReuseTests {
+struct ContextualPathQueueReuseTests {
   @Test func matchingQueueSourcePath_returnsSkipTo() async {
     let (selector, browser, player) = makeSelector()
     let parentPath = "/library/radio"
     let trackSrc = "song.mp3"
-    let contextualUrl = BrowserPathHelper.build(parentPath: parentPath, trackId: trackSrc)
+    let contextualPath = BrowserPathHelper.build(parentPath: parentPath, trackId: trackSrc)
+
+    // Id-less queue tracks: identity falls back to src.
+    player.queueSourcePath = parentPath
+    player.tracks = [
+      Track(src: "other.mp3"),
+      Track(src: "song.mp3"),
+      Track(src: "another.mp3"),
+    ]
+
+    let track = Track(path: contextualPath, src: trackSrc)
+    let result = await selector.select(track: track, player: player)
+    guard case let .play(intent) = result else {
+      Issue.record("expected .play, got \(result)")
+      return
+    }
+    guard case let .skipTo(index) = intent else {
+      Issue.record("expected .skipTo, got \(intent)")
+      return
+    }
+    #expect(index == 1)
+    #expect(browser.trackLoadEvents.count == 1)
+    #expect(browser.expandedPaths.isEmpty)
+  }
+
+  // Skip-in-place matches by id when queue tracks carry ids: the contextual
+  // trackId is the row's identity (its id), and the queue row is found even
+  // though its src differs textually from the tapped track's.
+  @Test func matchingQueueSourcePath_skipsToTrackByIdWhenSrcDiffers() async {
+    let (selector, browser, player) = makeSelector()
+    let parentPath = "/library/radio"
+    let contextualPath = BrowserPathHelper.build(parentPath: parentPath, trackId: "b")
 
     player.queueSourcePath = parentPath
     player.tracks = [
       Track(id: "a", src: "other.mp3"),
-      Track(id: "b", src: "song.mp3"),
+      Track(id: "b", src: "https://cdn.example/song.mp3?token=queue"),
       Track(id: "c", src: "another.mp3"),
     ]
 
-    let track = Track(id: "t1", url: contextualUrl, src: trackSrc)
+    let track = Track(id: "b", path: contextualPath, src: "song.mp3")
     let result = await selector.select(track: track, player: player)
     guard case let .play(intent) = result else {
       Issue.record("expected .play, got \(result)")
@@ -144,8 +175,7 @@ struct ContextualUrlQueueReuseTests {
       return
     }
     #expect(index == 1)
-    #expect(browser.trackLoadEvents.count == 1)
-    #expect(browser.expandedUrls.isEmpty)
+    #expect(browser.expandedPaths.isEmpty)
   }
 
   @Test func handlerIntercepts_returnsIntercepted() async {
@@ -153,32 +183,93 @@ struct ContextualUrlQueueReuseTests {
     browser.trackLoadHandlerResult = true
     let parentPath = "/library/radio"
     let trackSrc = "song.mp3"
-    let contextualUrl = BrowserPathHelper.build(parentPath: parentPath, trackId: trackSrc)
+    let contextualPath = BrowserPathHelper.build(parentPath: parentPath, trackId: trackSrc)
 
     player.queueSourcePath = parentPath
     player.tracks = [
-      Track(id: "a", src: "song.mp3"),
+      Track(src: "song.mp3"),
     ]
 
-    let track = Track(id: "t1", url: contextualUrl, src: trackSrc)
+    let track = Track(path: contextualPath, src: trackSrc)
     let result = await selector.select(track: track, player: player)
     guard case .intercepted = result else {
       Issue.record("expected .intercepted, got \(result)")
       return
     }
+    #expect(browser.expandedPaths.isEmpty)
+  }
+
+  // A queue holding the same identity twice (normal for music playlists):
+  // exact contextual-path equality — which carries the stamped page index —
+  // pins the tapped copy instead of the first one.
+  @Test func duplicateIdentityInQueue_pathMatchPinsTheTappedCopy() async {
+    let (selector, browser, player) = makeSelector()
+    let parentPath = "/playlist"
+    func stamped(_ id: String, _ index: Int) -> String {
+      BrowserPathHelper.build(parentPath: parentPath, trackId: id, index: index)
+    }
+
+    player.queueSourcePath = parentPath
+    player.tracks = [
+      Track(path: stamped("a", 0), src: "a"),
+      Track(path: stamped("b", 1), src: "b"),
+      Track(path: stamped("a", 2), src: "a"),
+    ]
+
+    let track = Track(path: stamped("a", 2), src: "a")
+    let result = await selector.select(track: track, player: player)
+    guard case let .play(.skipTo(index)) = result else {
+      Issue.record("expected .play(.skipTo), got \(result)")
+      return
+    }
+    #expect(index == 2)
+    #expect(browser.expandedPaths.isEmpty)
+  }
+
+  // A tap in section B whose identity also sits in the active section-A
+  // queue: the exact surface is not in the queue, so the selection
+  // re-expands (re-scoping to the tapped section) instead of silently
+  // skipping inside the old section's queue.
+  @Test func indexStampedPathNotInQueue_reExpandsInsteadOfIdentitySkip() async {
+    let (selector, browser, player) = makeSelector()
+    let parentPath = "/city"
+    func stamped(_ id: String, _ index: Int) -> String {
+      BrowserPathHelper.build(parentPath: parentPath, trackId: id, index: index)
+    }
+
+    player.queueSourcePath = parentPath
+    player.tracks = [
+      Track(path: stamped("dup", 0), src: "dup"),
+      Track(path: stamped("x", 1), src: "x"),
+    ]
+    browser.expandQueueResult = (
+      tracks: [Track(path: stamped("y", 4), src: "y"), Track(path: stamped("dup", 5), src: "dup")],
+      selectedIndex: 1,
+    )
+
+    let track = Track(path: stamped("dup", 5), src: "dup")
+    let result = await selector.select(track: track, player: player)
+    guard case let .play(.setQueue(tracks, startIndex, sourcePath)) = result else {
+      Issue.record("expected .play(.setQueue), got \(result)")
+      return
+    }
+    #expect(tracks.count == 2)
+    #expect(startIndex == 1)
+    #expect(sourcePath == parentPath)
+    #expect(browser.expandedPaths == [stamped("dup", 5)])
   }
 }
 
-// MARK: - Contextual URL Expansion
+// MARK: - Contextual path Expansion
 
-@Suite("contextual URL expansion")
+@Suite("contextual path expansion")
 @MainActor
-struct ContextualUrlExpansionTests {
+struct ContextualPathExpansionTests {
   @Test func expands_returnsSetQueue() async {
     let (selector, browser, player) = makeSelector()
     let parentPath = "/library/radio"
     let trackSrc = "song.mp3"
-    let contextualUrl = BrowserPathHelper.build(parentPath: parentPath, trackId: trackSrc)
+    let contextualPath = BrowserPathHelper.build(parentPath: parentPath, trackId: trackSrc)
 
     let expandedTracks = [
       Track(id: "a", src: "first.mp3"),
@@ -187,7 +278,7 @@ struct ContextualUrlExpansionTests {
     ]
     browser.expandQueueResult = (tracks: expandedTracks, selectedIndex: 1)
 
-    let track = Track(id: "t1", url: contextualUrl, src: trackSrc)
+    let track = Track(id: "t1", path: contextualPath, src: trackSrc)
     let result = await selector.select(track: track, player: player)
     guard case let .play(intent) = result else {
       Issue.record("expected .play, got \(result)")
@@ -200,7 +291,7 @@ struct ContextualUrlExpansionTests {
     #expect(tracks.count == 3)
     #expect(startIndex == 1)
     #expect(sourcePath == parentPath)
-    #expect(browser.expandedUrls == [contextualUrl])
+    #expect(browser.expandedPaths == [contextualPath])
     #expect(browser.trackLoadEvents.count == 1)
   }
 
@@ -209,14 +300,14 @@ struct ContextualUrlExpansionTests {
     browser.trackLoadHandlerResult = true
     let parentPath = "/library/radio"
     let trackSrc = "song.mp3"
-    let contextualUrl = BrowserPathHelper.build(parentPath: parentPath, trackId: trackSrc)
+    let contextualPath = BrowserPathHelper.build(parentPath: parentPath, trackId: trackSrc)
 
     browser.expandQueueResult = (
       tracks: [Track(id: "a", src: "song.mp3")],
       selectedIndex: 0,
     )
 
-    let track = Track(id: "t1", url: contextualUrl, src: trackSrc)
+    let track = Track(id: "t1", path: contextualPath, src: trackSrc)
     let result = await selector.select(track: track, player: player)
     guard case .intercepted = result else {
       Issue.record("expected .intercepted, got \(result)")
@@ -228,11 +319,11 @@ struct ContextualUrlExpansionTests {
     let (selector, browser, player) = makeSelector()
     let parentPath = "/library/radio"
     let trackSrc = "song.mp3"
-    let contextualUrl = BrowserPathHelper.build(parentPath: parentPath, trackId: trackSrc)
+    let contextualPath = BrowserPathHelper.build(parentPath: parentPath, trackId: trackSrc)
 
     browser.expandQueueResult = nil
 
-    let track = Track(id: "t1", url: contextualUrl, src: trackSrc)
+    let track = Track(id: "t1", path: contextualPath, src: trackSrc)
     let result = await selector.select(track: track, player: player)
     guard case let .play(intent) = result else {
       Issue.record("expected .play, got \(result)")
@@ -249,11 +340,11 @@ struct ContextualUrlExpansionTests {
     let (selector, browser, player) = makeSelector()
     let parentPath = "/library/radio"
     let trackSrc = "song.mp3"
-    let contextualUrl = BrowserPathHelper.build(parentPath: parentPath, trackId: trackSrc)
+    let contextualPath = BrowserPathHelper.build(parentPath: parentPath, trackId: trackSrc)
 
     browser.expandQueueError = MockError.expansion
 
-    let track = Track(id: "t1", url: contextualUrl, src: trackSrc)
+    let track = Track(id: "t1", path: contextualPath, src: trackSrc)
     let result = await selector.select(track: track, player: player)
     guard case let .play(intent) = result else {
       Issue.record("expected .play, got \(result)")
@@ -266,3 +357,47 @@ struct ContextualUrlExpansionTests {
     #expect(loaded.src == trackSrc)
   }
 }
+
+// MARK: - Disabled Track
+
+@Suite("disabled track")
+@MainActor
+struct DisabledTrackTests {
+  @Test func disabledPlayable_returnsNone() async {
+    let (selector, browser, player) = makeSelector()
+    let track = Track(id: "t1", src: "https://example.com/a.mp3", disabled: true)
+    let result = await selector.select(track: track, player: player)
+    guard case .none = result else {
+      Issue.record("Expected .none for a disabled track, got \(result)")
+      return
+    }
+    // Refused outright: not even the JS load handler hears about it.
+    #expect(browser.trackLoadEvents.isEmpty)
+  }
+
+  @Test func disabledBrowsable_returnsNone() async {
+    // Unavailable means unavailable — a disabled browsable doesn't navigate
+    // either (the ladder grays or hides it; a delivered tap stays inert).
+    let (selector, _, player) = makeSelector()
+    let track = Track(id: "t1", path: "/gone", disabled: true)
+    let result = await selector.select(track: track, player: player)
+    guard case .none = result else {
+      Issue.record("Expected .none for a disabled browsable, got \(result)")
+      return
+    }
+  }
+
+  @Test func disabledContextual_neverExpands() async {
+    let (selector, browser, player) = makeSelector()
+    browser.expandQueueResult = (tracks: [Track(id: "a", src: "a")], selectedIndex: 0)
+    let track = Track(
+      id: "t1", path: "/home?__trackId=t1", src: "https://example.com/a.mp3", disabled: true,
+    )
+    let result = await selector.select(track: track, player: player)
+    guard case .none = result else {
+      Issue.record("Expected .none, got \(result)")
+      return
+    }
+    #expect(browser.expandedPaths.isEmpty)
+  }
+}