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

package/android/src/test/java/com/audiobrowser/browser/SectionScopeTest.kt

@@ -1,94 +1,169 @@
 package com.audiobrowser.browser
 
-import com.audiobrowser.TestFixtures.imageRowItem
+import com.audiobrowser.TestFixtures.resolvedTrack
+import com.audiobrowser.TestFixtures.section
 import com.audiobrowser.TestFixtures.track
+import com.margelo.nitro.audiobrowser.SectionStyle
+import com.margelo.nitro.audiobrowser.StyleDisplay
 import org.junit.Assert.assertEquals
 import org.junit.Assert.assertNull
 import org.junit.Test
 
 class SectionScopeTest {
 
-  @Test
-  fun `scopes to the contiguous groupTitle run`() {
-    val children =
-      listOf(
-        track(id = "a", src = "a", groupTitle = "First"),
-        track(id = "b", src = "b", groupTitle = "First"),
-        track(id = "c", src = "c", groupTitle = "Second"),
-        track(id = "d", src = "d", groupTitle = "Second"),
-        track(id = "e", src = "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 val sections =
+    listOf(
+      section(title = "First", children = arrayOf(track(src = "dup"), track(src = "x"))),
+      section(
+        title = "Second",
+        children = arrayOf(track(src = "y"), track(src = "dup"), track(src = "z")),
+      ),
+    )
 
-    val section = SectionScope.section(children, "c") as SectionScope.Section.Run
-    assertEquals(listOf("c", "d"), section.tracks.map { it.src })
+  @Test
+  fun `falls back to the first section containing the identity`() {
+    val scoped = SectionScope.scoped(sections, "dup")!!
+    assertEquals(listOf("dup", "x"), scoped.section.children.map { it.src })
+    assertNull(scoped.tappedOffset)
+  }
 
-    val first = SectionScope.section(children, "a") as SectionScope.Section.Run
-    assertEquals(listOf("a", "b"), first.tracks.map { it.src })
+  @Test
+  fun `flat index pins the tapped section`() {
+    // Flat index 3 = second section, offset 1.
+    val scoped = SectionScope.scoped(sections, "dup", tappedIndex = 3)!!
+    assertEquals(listOf("y", "dup", "z"), scoped.section.children.map { it.src })
+    assertEquals(1, scoped.tappedOffset)
   }
 
   @Test
-  fun `ungrouped items form their own run`() {
-    val children =
+  fun `flat index pins the exact copy within a section`() {
+    val playlist =
       listOf(
-        track(src = "a", groupTitle = "First"),
-        track(src = "b"),
-        track(src = "c"),
-        track(src = "d", groupTitle = "Second"),
+        section(
+          children = arrayOf(track(src = "a"), track(src = "b"), track(src = "a"), track(src = "c"))
+        )
       )
+    val scoped = SectionScope.scoped(playlist, "a", tappedIndex = 2)!!
+    assertEquals(2, scoped.tappedOffset)
+  }
 
-    val section = SectionScope.section(children, "b") as SectionScope.Section.Run
-    assertEquals(listOf("b", "c"), section.tracks.map { it.src })
+  @Test
+  fun `stale index falls back to the first identity match`() {
+    // The child at the stamped index no longer carries the tapped identity
+    // (the list shifted) — resolution ignores the index and pins nothing.
+    val scoped = SectionScope.scoped(sections, "dup", tappedIndex = 1)!!
+    assertEquals(listOf("dup", "x"), scoped.section.children.map { it.src })
+    assertNull(scoped.tappedOffset)
   }
 
   @Test
-  fun `identical titles in separate runs stay separate`() {
+  fun `out-of-range index is ignored`() {
+    val scoped = SectionScope.scoped(sections, "dup", tappedIndex = 99)!!
+    assertEquals(listOf("dup", "x"), scoped.section.children.map { it.src })
+    assertNull(scoped.tappedOffset)
+  }
+
+  @Test
+  fun `vanished identity returns null`() {
+    assertNull(SectionScope.scoped(sections, "gone"))
+  }
+
+  @Test
+  fun `locates a track by its id when it has one`() {
+    // Identity rule (ADR 0008): the id wins over the src, so a __trackId stamped
+    // from an id-bearing track must resolve — and its src must not.
     val children =
-      listOf(
-        track(src = "a", groupTitle = "Same"),
-        track(src = "x", groupTitle = "Other"),
-        track(src = "b", groupTitle = "Same"),
+      arrayOf(
+        track(id = "stable-a", src = "https://s/a.mp3"),
+        track(id = "stable-b", src = "https://s/b.mp3"),
       )
+    val scoped = SectionScope.scoped(listOf(section(children = children)), "stable-b")!!
+    assertEquals(listOf("stable-a", "stable-b"), scoped.section.children.map { it.id })
 
-    val section = SectionScope.section(children, "a") as SectionScope.Section.Run
-    assertEquals(listOf("a"), section.tracks.map { it.src })
+    // The src is shadowed by the id — it is not the track's identity.
+    assertNull(SectionScope.scoped(listOf(section(children = children)), "https://s/b.mp3"))
   }
 
+  // MARK: page shape helpers
+
   @Test
-  fun `finds the id inside an image row`() {
-    val items = arrayOf(imageRowItem("s1"), imageRowItem("s2"))
-    val row = track(title = "Most Played", src = null, imageRow = items)
-    val children = listOf(row, track(src = "a"))
+  fun `children sugar normalizes to one untitled section`() {
+    val page = resolvedTrack(children = arrayOf(track(src = "a"), track(src = "b")))
+    val sections = page.normalizedSections!!
+    assertEquals(1, sections.size)
+    assertNull(sections[0].title)
+    assertEquals(listOf("a", "b"), sections[0].children.map { it.src })
+  }
+
+  @Test
+  fun `sections win over children`() {
+    val page =
+      resolvedTrack(
+        sections = arrayOf(section(title = "S", children = arrayOf(track(src = "a")))),
+        children = arrayOf(track(src = "zzz")),
+      )
+    val sections = page.normalizedSections!!
+    assertEquals(1, sections.size)
+    assertEquals("S", sections[0].title)
+  }
 
-    val section = SectionScope.section(children, "s2") as SectionScope.Section.ImageRow
-    assertEquals(listOf("s1", "s2"), section.items.map { it.src })
+  @Test
+  fun `flattened children concatenate in section order`() {
+    val page =
+      resolvedTrack(
+        sections =
+          arrayOf(
+            section(title = "A", children = arrayOf(track(src = "a1"), track(src = "a2"))),
+            section(children = arrayOf(track(src = "b1"))),
+          )
+      )
+    assertEquals(listOf("a1", "a2", "b1"), page.flattenedChildren!!.map { it.src })
   }
 
   @Test
-  fun `unknown id returns null`() {
-    assertNull(SectionScope.section(listOf(track(src = "a")), "zz"))
+  fun `childless page has no sections`() {
+    assertNull(resolvedTrack().normalizedSections)
   }
 
-  // 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.
+  // --- styleResolvedSections: the page->section fold (ADR 0011) ---
+
   @Test
-  fun `image row wins over a flat-list duplicate`() {
-    val row = track(title = "Row", src = null, imageRow = arrayOf(imageRowItem("dup")))
-    val children = listOf(row, track(src = "dup"), track(src = "b"))
+  fun `an unstyled section reaches the surface with the page's block folded in`() {
+    // The end-to-end wire for ResolvedTrack.style: without this fold, the
+    // page tier is a dead field — every existing unit test would stay green
+    // while a whole tier of ADR 0011 went dark in production.
+    val page =
+      resolvedTrack(
+        style =
+          SectionStyle(display = StyleDisplay.GRID, artworkRendering = null, gridWrap = false),
+        sections = arrayOf(section(children = arrayOf(track(src = "a")))),
+      )
 
-    val section = SectionScope.section(children, "dup") as SectionScope.Section.ImageRow
-    assertEquals(listOf("dup"), section.items.map { it.src })
+    val folded = page.styleResolvedSections()!!.single()
+    assertEquals(StyleDisplay.GRID, folded.style?.display)
+    assertEquals(false, folded.style?.gridWrap)
+    // The extras leg of this wire — folded section → per-item grid hint — is
+    // asserted in MediaExtrasBuilderTest (it needs Robolectric for Bundle).
   }
 
   @Test
-  fun `duplicate src across runs resolves to the earlier run`() {
-    val children =
-      listOf(
-        track(src = "dup", groupTitle = "First"),
-        track(src = "x", groupTitle = "Second"),
-        track(src = "dup", groupTitle = "Second"),
+  fun `a section's own block overrides the page's in the fold`() {
+    val page =
+      resolvedTrack(
+        style = SectionStyle(display = StyleDisplay.GRID, artworkRendering = null, gridWrap = null),
+        sections =
+          arrayOf(
+            section(
+              style =
+                SectionStyle(display = StyleDisplay.LIST, artworkRendering = null, gridWrap = null),
+              children = arrayOf(track(src = "a")),
+            )
+          ),
       )
 
-    val section = SectionScope.section(children, "dup") as SectionScope.Section.Run
-    assertEquals(listOf("dup"), section.tracks.map { it.src })
+    assertEquals(StyleDisplay.LIST, page.styleResolvedSections()!!.single().style?.display)
   }
 }

package/android/src/test/java/com/audiobrowser/browser/StyleResolverTest.kt

@@ -0,0 +1,87 @@
+package com.audiobrowser.browser
+
+import com.margelo.nitro.audiobrowser.ArtworkRendering
+import com.margelo.nitro.audiobrowser.SectionStyle
+import com.margelo.nitro.audiobrowser.StyleDisplay
+import com.margelo.nitro.audiobrowser.TrackStyle
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertNull
+import org.junit.Test
+
+/**
+ * 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.
+ */
+class StyleResolverTest {
+
+  @Test
+  fun `section overrides the page per property`() {
+    val resolved =
+      StyleResolver.sectionStyle(
+        section =
+          SectionStyle(display = StyleDisplay.LIST, artworkRendering = null, gridWrap = null),
+        page =
+          SectionStyle(
+            display = StyleDisplay.GRID,
+            artworkRendering = ArtworkRendering.STENCIL,
+            gridWrap = false,
+          ),
+      )
+    // Declared on the section: wins. Undeclared: the page's scope-wide value.
+    assertEquals(StyleDisplay.LIST, resolved.display)
+    assertEquals(ArtworkRendering.STENCIL, resolved.artworkRendering)
+    assertEquals(false, resolved.gridWrap)
+  }
+
+  @Test
+  fun `a styleless section takes the page block`() {
+    val resolved =
+      StyleResolver.sectionStyle(
+        section = null,
+        page = SectionStyle(display = StyleDisplay.GRID, artworkRendering = null, gridWrap = true),
+      )
+    assertEquals(StyleDisplay.GRID, resolved.display)
+    assertEquals(true, resolved.gridWrap)
+  }
+
+  @Test
+  fun `track overrides the section per property`() {
+    val resolved =
+      StyleResolver.trackStyle(
+        track = TrackStyle(display = null, artworkRendering = ArtworkRendering.ORIGINAL),
+        section =
+          SectionStyle(
+            display = StyleDisplay.GRID,
+            artworkRendering = ArtworkRendering.STENCIL,
+            gridWrap = null,
+          ),
+      )
+    assertEquals(ArtworkRendering.ORIGINAL, resolved.artworkRendering)
+  }
+
+  @Test
+  fun `a styleless track inherits the section value`() {
+    val resolved =
+      StyleResolver.trackStyle(
+        track = null,
+        section =
+          SectionStyle(display = null, artworkRendering = ArtworkRendering.STENCIL, gridWrap = null),
+      )
+    assertEquals(ArtworkRendering.STENCIL, resolved.artworkRendering)
+  }
+
+  @Test
+  fun `display never inherits onto an item`() {
+    // 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.
+    val resolved =
+      StyleResolver.trackStyle(
+        track = TrackStyle(display = StyleDisplay.GRID, artworkRendering = null),
+        section =
+          SectionStyle(display = StyleDisplay.GRID, artworkRendering = null, gridWrap = null),
+      )
+    assertNull(resolved.display)
+  }
+}

package/android/src/test/java/com/audiobrowser/extension/TappedTrackTest.kt

@@ -0,0 +1,43 @@
+package com.audiobrowser.extension
+
+import com.audiobrowser.TestFixtures.track
+import com.audiobrowser.util.BrowserPathHelper
+import org.junit.Assert.assertEquals
+import org.junit.Test
+import org.junit.runner.RunWith
+import org.robolectric.RobolectricTestRunner
+
+/**
+ * The skip-in-place queue match (ADR 0009): exact contextual-path equality pins the tapped copy;
+ * the identity match remains for index-less paths; an index-stamped path with no exact match
+ * misses, so the caller re-expands. Robolectric for `android.net.Uri` (contextual-path parsing).
+ */
+@RunWith(RobolectricTestRunner::class)
+class TappedTrackTest {
+
+  private fun stamped(id: String, index: Int) = BrowserPathHelper.build("/page", id, index)
+
+  private val queue =
+    arrayOf(
+      track(src = "a").copy(path = stamped("a", 0)),
+      track(src = "b").copy(path = stamped("b", 1)),
+      track(src = "a").copy(path = stamped("a", 2)),
+    )
+
+  @Test
+  fun `exact path match pins the tapped copy of a duplicate identity`() {
+    assertEquals(2, queue.indexOfTappedTrack(stamped("a", 2), "a"))
+  }
+
+  @Test
+  fun `index-less path falls back to the identity match`() {
+    assertEquals(0, queue.indexOfTappedTrack(BrowserPathHelper.build("/page", "a"), "a"))
+  }
+
+  @Test
+  fun `index-stamped path with no exact match misses instead of identity-skipping`() {
+    // A tap in another section whose identity also sits in this queue: the
+    // caller must re-expand (re-scoping to the tapped section), not skip.
+    assertEquals(-1, queue.indexOfTappedTrack(stamped("a", 7), "a"))
+  }
+}

package/android/src/test/java/com/audiobrowser/extension/TrackIdentityTest.kt

@@ -0,0 +1,41 @@
+package com.audiobrowser.extension
+
+import com.audiobrowser.TestFixtures.track
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertNull
+import org.junit.Test
+
+/**
+ * THE identity rule (ADR 0008): a track's identity is its `id` when non-blank, else its `src`.
+ * Everything that compares tracks — favorites, section scoping, skip-in-place, `__trackId` — goes
+ * through this extension.
+ */
+class TrackIdentityTest {
+
+  @Test
+  fun `id wins over src`() {
+    assertEquals("stable-id", track(id = "stable-id", src = "https://s/a.mp3").identity)
+  }
+
+  @Test
+  fun `blank id falls back to src`() {
+    assertEquals("https://s/a.mp3", track(id = "", src = "https://s/a.mp3").identity)
+    assertEquals("https://s/a.mp3", track(id = "  ", src = "https://s/a.mp3").identity)
+  }
+
+  @Test
+  fun `missing id falls back to src`() {
+    assertEquals("https://s/a.mp3", track(id = null, src = "https://s/a.mp3").identity)
+  }
+
+  @Test
+  fun `id alone is an identity`() {
+    assertEquals("stable-id", track(id = "stable-id", src = null).identity)
+  }
+
+  @Test
+  fun `neither id nor src means no identity`() {
+    assertNull(track(id = null, src = null).identity)
+    assertNull(track(id = "", src = null).identity)
+  }
+}

package/android/src/test/java/com/audiobrowser/player/CapabilityControlsTest.kt

@@ -3,7 +3,6 @@ package com.audiobrowser.player
 import com.margelo.nitro.audiobrowser.PlayerCapabilities
 import com.margelo.nitro.audiobrowser.RemoteButton
 import com.margelo.nitro.audiobrowser.RemoteButtonLayout
-import com.margelo.nitro.audiobrowser.Variant_Boolean_FavoriteConfig
 import org.junit.Assert.assertEquals
 import org.junit.Assert.assertFalse
 import org.junit.Assert.assertTrue
@@ -36,7 +35,7 @@ class CapabilityControlsTest {
       skipToPrevious = skipToPrevious,
       jumpForward = jumpForward,
       jumpBackward = jumpBackward,
-      favorite = favorite?.let { Variant_Boolean_FavoriteConfig.First(it) },
+      favorite = favorite,
       shuffleMode = null,
       repeatMode = null,
       playbackRate = null,

package/android/src/test/java/com/audiobrowser/player/NowPlayingUpdaterTest.kt

@@ -377,7 +377,7 @@ class NowPlayingUpdaterTest {
   }
 
   @Test
-  fun `artwork re-resolves for a new track id and skips without an id`() = runTest {
+  fun `artwork re-resolves for a new track identity including id-less tracks`() = runTest {
     val surface =
       FakeSurface().apply {
         currentTrack = track("A", id = "a")
@@ -393,10 +393,31 @@ class NowPlayingUpdaterTest {
     runCurrent()
     assertEquals(2, surface.artworkResolveCount)
 
+    // The config runs for id-less tracks too — no blanket skip.
     surface.currentTrack = track("C", id = null, src = "https://s/c.mp3")
     updater.render()
     runCurrent()
-    assertEquals(2, surface.artworkResolveCount) // no id → no resolve
+    assertEquals(3, surface.artworkResolveCount)
+    assertEquals(0 to "https://img/a.png", surface.artworkStamps.last())
+  }
+
+  @Test
+  fun `artwork for an id-less track resolves once keyed on src identity`() = runTest {
+    val surface =
+      FakeSurface().apply {
+        currentTrack = track("C", id = null, src = "https://s/c.mp3")
+        hasNowPlayingArtworkConfig = true
+        artworkResult = "https://img/c.png"
+      }
+    val updater = NowPlayingUpdater(surface, backgroundScope)
+
+    updater.render()
+    runCurrent()
+    updater.updateNowPlaying(update(title = "Song")) // re-render, same track
+    runCurrent()
+
+    assertEquals(1, surface.artworkResolveCount)
+    assertEquals(listOf(0 to "https://img/c.png"), surface.artworkStamps)
   }
 
   @Test
@@ -439,4 +460,23 @@ class NowPlayingUpdaterTest {
 
     assertTrue(surface.artworkStamps.isEmpty())
   }
+
+  @Test
+  fun `a stale artwork result for an id-less track is not stamped after a track change`() =
+    runTest {
+      val surface =
+        FakeSurface().apply {
+          currentTrack = track("A", id = null, src = "https://s/a.mp3")
+          hasNowPlayingArtworkConfig = true
+          artworkResult = "https://img/a.png"
+        }
+      val updater = NowPlayingUpdater(surface, backgroundScope)
+
+      updater.render() // schedules the artwork resolve
+      // Skip to another id-less track before it lands: identity (src) keying must catch it.
+      surface.currentTrack = track("B", id = null, src = "https://s/b.mp3")
+      runCurrent()
+
+      assertTrue(surface.artworkStamps.isEmpty())
+    }
 }

package/android/src/test/java/com/audiobrowser/player/PlaybackStateStoreTrackJsonTest.kt

@@ -0,0 +1,55 @@
+package com.audiobrowser.player
+
+import com.audiobrowser.TestFixtures
+import com.margelo.nitro.audiobrowser.ArtworkRendering
+import com.margelo.nitro.audiobrowser.StyleDisplay
+import com.margelo.nitro.audiobrowser.TrackStyle
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertNull
+import org.junit.Test
+import org.junit.runner.RunWith
+import org.robolectric.RobolectricTestRunner
+
+/**
+ * The bespoke org.json persistence of the resumption track. ADR 0011: the style block and
+ * `disabled` survive process death (a restored queue keeps its visible fidelity), and a snapshot
+ * written before the block model — `style` as an enum-name string — restores without a declaration
+ * rather than failing.
+ */
+@RunWith(RobolectricTestRunner::class)
+class PlaybackStateStoreTrackJsonTest {
+
+  @Test
+  fun `style and disabled survive the round-trip`() {
+    val track =
+      TestFixtures.track(title = "Night Mix", src = "https://s/a.mp3", disabled = true)
+        .copy(
+          style =
+            TrackStyle(display = StyleDisplay.GRID, artworkRendering = ArtworkRendering.STENCIL)
+        )
+
+    val restored = PlaybackStateStore.trackFromJson(PlaybackStateStore.trackToJson(track))
+
+    assertEquals(StyleDisplay.GRID, restored?.style?.display)
+    assertEquals(ArtworkRendering.STENCIL, restored?.style?.artworkRendering)
+    assertEquals(true, restored?.disabled)
+  }
+
+  @Test
+  fun `a track without style round-trips without one`() {
+    val track = TestFixtures.track(title = "Plain", src = "https://s/a.mp3")
+
+    val restored = PlaybackStateStore.trackFromJson(PlaybackStateStore.trackToJson(track))
+
+    assertNull(restored?.style)
+    assertNull(restored?.disabled)
+  }
+
+  @Test
+  fun `a pre-block snapshot with a string style restores without a declaration`() {
+    val restored = PlaybackStateStore.trackFromJson("""{"title":"X","src":"s","style":"LIST"}""")
+
+    assertEquals("X", restored?.title)
+    assertNull(restored?.style)
+  }
+}

package/android/src/test/java/com/audiobrowser/util/BrowserPathHelperTest.kt

@@ -1,28 +1,53 @@
 package com.audiobrowser.util
 
-import org.junit.Assert.assertFalse
-import org.junit.Assert.assertTrue
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertNull
 import org.junit.Test
+import org.junit.runner.RunWith
+import org.robolectric.RobolectricTestRunner
 
+@RunWith(RobolectricTestRunner::class)
 class BrowserPathHelperTest {
 
   @Test
-  fun `containsSegment matches a uid as a full path segment`() {
-    val path = "/listen/amsterdam-funk-channel/Gw0LGB8j"
-    assertTrue(BrowserPathHelper.containsSegment(path, "Gw0LGB8j"))
-    assertTrue(BrowserPathHelper.containsSegment(path, "amsterdam-funk-channel"))
-    assertTrue(BrowserPathHelper.containsSegment(path, "listen"))
-    assertTrue(BrowserPathHelper.containsSegment("/listen/x/Gw0LGB8j?hl=en", "Gw0LGB8j"))
-    assertTrue(BrowserPathHelper.containsSegment("/listen/x/Gw0LGB8j#frag", "Gw0LGB8j"))
+  fun `build round-trips a src carrying its own query params`() {
+    // A src carrying its own query string (signed CDN URL) must survive the
+    // build → extract/strip round-trip: an unescaped `&` would split the src
+    // into stray query params, truncating the trackId and polluting the
+    // parent path.
+    val src = "https://cdn.example.com/stream.mp3?token=abc&exp=1699999999"
+    val url = BrowserPathHelper.build("/library", src)
+    assertEquals(src, BrowserPathHelper.extractTrackId(url))
+    assertEquals("/library", BrowserPathHelper.stripTrackId(url))
   }
 
   @Test
-  fun `containsSegment rejects partial-segment and missing matches`() {
-    val path = "/listen/amsterdam-funk-channel/Gw0LGB8j"
-    assertFalse(BrowserPathHelper.containsSegment(path, "Gw0LGB8"))
-    assertFalse(BrowserPathHelper.containsSegment(path, "funk"))
-    assertFalse(BrowserPathHelper.containsSegment(path, "msterdam-funk-channe"))
-    assertFalse(BrowserPathHelper.containsSegment(path, "NopeNope"))
-    assertFalse(BrowserPathHelper.containsSegment(path, ""))
+  fun `build round-trips a src with equals and plus`() {
+    val src = "https://cdn.example.com/a+b.mp3?sig=x=y"
+    val url = BrowserPathHelper.build("/library", src)
+    assertEquals(src, BrowserPathHelper.extractTrackId(url))
+    assertEquals("/library", BrowserPathHelper.stripTrackId(url))
+  }
+
+  @Test
+  fun `build stamps the index and round-trips it`() {
+    val src = "https://cdn.example.com/stream.mp3?token=abc&exp=1"
+    val url = BrowserPathHelper.build("/library", src, 3)
+    assertEquals(src, BrowserPathHelper.extractTrackId(url))
+    assertEquals(3, BrowserPathHelper.extractIndex(url))
+    assertEquals("/library", BrowserPathHelper.stripTrackId(url))
+  }
+
+  @Test
+  fun `extractIndex returns null without a stamped index`() {
+    val url = BrowserPathHelper.build("/library", "song.mp3")
+    assertNull(BrowserPathHelper.extractIndex(url))
+  }
+
+  @Test
+  fun `extractIndex returns null for non-contextual or malformed-index URLs`() {
+    assertNull(BrowserPathHelper.extractIndex("/library"))
+    assertNull(BrowserPathHelper.extractIndex("/library?__trackId=song.mp3&__index=x"))
+    assertNull(BrowserPathHelper.extractIndex("/library?__trackId=song.mp3&__index=-1"))
   }
 }