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

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

@@ -10,7 +10,8 @@ class JsonArtworkTest {
 
   @Test
   fun `decodes a single url`() {
-    val track = json.decodeFromString<JsonTrack>("""{"title":"X","artwork":"https://e.example/a.png"}""")
+    val track =
+      json.decodeFromString<JsonTrack>("""{"title":"X","artwork":"https://e.example/a.png"}""")
     assertEquals(
       Variant_String_ArtworkVariants.First("https://e.example/a.png"),
       track.toNitro().artwork,
@@ -34,7 +35,7 @@ class JsonArtworkTest {
     // so one unparseable row rejected the whole page rather than losing an image.
     val resolved =
       json.decodeFromString<JsonResolvedTrack>(
-        """{"url":"/favorites","title":"Favorites","children":[
+        """{"path":"/favorites","title":"Favorites","children":[
           {"title":"Playlist","artwork":{"light":"https://e.example/l.png","dark":"https://e.example/d.png"}}
         ]}"""
       )

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

@@ -0,0 +1,147 @@
+package com.audiobrowser.browser
+
+import com.margelo.nitro.audiobrowser.ArtworkRendering
+import com.margelo.nitro.audiobrowser.CardImage
+import com.margelo.nitro.audiobrowser.GridTile
+import com.margelo.nitro.audiobrowser.ImageShape
+import com.margelo.nitro.audiobrowser.StyleDisplay
+import kotlinx.serialization.json.Json
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertNull
+import org.junit.Test
+
+/** Style blocks on the wire, decoded tolerantly (ADR 0011). */
+class JsonStyleTest {
+  private val json = Json { ignoreUnknownKeys = true }
+
+  @Test
+  fun `decodes a block onto TrackStyle`() {
+    val track =
+      json.decodeFromString<JsonTrack>(
+        """{"title":"X","style":{"display":"grid","artworkRendering":"stencil"}}"""
+      )
+    val style = track.toNitro().style
+    assertEquals(StyleDisplay.GRID, style?.display)
+    assertEquals(ArtworkRendering.STENCIL, style?.artworkRendering)
+  }
+
+  @Test
+  fun `decodes a block onto SectionStyle`() {
+    val resolved =
+      json.decodeFromString<JsonResolvedTrack>(
+        """{"path":"/home","title":"Home","sections":[
+          {"style":{"display":"grid","gridWrap":false},"children":[{"title":"C","src":"s"}]}
+        ]}"""
+      )
+    val style = resolved.toNitro().sections?.first()?.style
+    assertEquals(StyleDisplay.GRID, style?.display)
+    assertEquals(false, style?.gridWrap)
+  }
+
+  @Test
+  fun `a stale string style decodes as no declaration - never a parse failure`() {
+    // The retired string vocabulary must never kill the page (tolerant
+    // decoding, ADR 0011).
+    val resolved =
+      json.decodeFromString<JsonResolvedTrack>(
+        """{"path":"/home","title":"Home","style":"rail","children":[
+          {"title":"C","src":"s","style":"grid"}
+        ]}"""
+      )
+    val nitro = resolved.toNitro()
+    assertNull(nitro.style)
+    assertNull(nitro.children?.first()?.style)
+  }
+
+  @Test
+  fun `unknown enum values decode as no declaration`() {
+    // All-unknown declarations collapse to "no block" — one shape for "no
+    // declaration" on every platform.
+    val track =
+      json.decodeFromString<JsonTrack>(
+        """{"title":"X","style":{"display":"carousel","artworkRendering":"embossed","gridWrap":"yes"}}"""
+      )
+    assertNull(track.toNitro().style)
+  }
+
+  @Test
+  fun `an empty block decodes as no declaration`() {
+    val track = json.decodeFromString<JsonTrack>("""{"title":"X","style":{}}""")
+    assertNull(track.toNitro().style)
+  }
+
+  @Test
+  fun `a quoted boolean gridWrap is a wrong-typed field - no declaration`() {
+    // iOS's strict-typed tolerant decode drops a quoted "false"; the lenient
+    // Kotlin mapper must not read it either, or the same payload renders a
+    // teaser shelf on one platform and a wrapping grid on the other.
+    val resolved =
+      json.decodeFromString<JsonResolvedTrack>(
+        """{"path":"/home","title":"Home","sections":[
+          {"style":{"display":"grid","gridWrap":"false"},"children":[{"title":"C","src":"s"}]}
+        ]}"""
+      )
+    val style = resolved.toNitro().sections?.first()?.style
+    assertEquals(StyleDisplay.GRID, style?.display)
+    assertNull(style?.gridWrap)
+  }
+
+  @Test
+  fun `decodes disabled`() {
+    val track = json.decodeFromString<JsonTrack>("""{"title":"X","src":"s","disabled":true}""")
+    assertEquals(true, track.toNitro().disabled)
+  }
+
+  @Test
+  fun `decodes imageShape and accessorySymbol`() {
+    val track =
+      json.decodeFromString<JsonTrack>(
+        """{"title":"X","style":{"imageShape":"circular","accessorySymbol":"lock.fill"}}"""
+      )
+    val style = track.toNitro().style
+    assertEquals(ImageShape.CIRCULAR, style?.imageShape)
+    assertEquals("lock.fill", style?.accessorySymbol)
+  }
+
+  @Test
+  fun `accessorySymbol 'none' is a value - not emptiness`() {
+    // The inheritance-escape sentinel must survive the wire — collapsing it
+    // to "no declaration" would let the section value flow back in.
+    val track =
+      json.decodeFromString<JsonTrack>("""{"title":"X","style":{"accessorySymbol":"none"}}""")
+    assertEquals("none", track.toNitro().style?.accessorySymbol)
+  }
+
+  @Test
+  fun `unknown imageShape decodes as no declaration`() {
+    val track =
+      json.decodeFromString<JsonTrack>("""{"title":"X","style":{"imageShape":"hexagonal"}}""")
+    assertNull(track.toNitro().style)
+  }
+
+  @Test
+  fun `decodes the card family`() {
+    val resolved =
+      json.decodeFromString<JsonResolvedTrack>(
+        """{"path":"/home","title":"Home","sections":[
+          {"style":{"display":"grid","gridTile":"card","cardTint":"#1e3a8a","cardImage":"background"},
+           "children":[{"title":"C","src":"s"}]}
+        ]}"""
+      )
+    val style = resolved.toNitro().sections?.first()?.style
+    assertEquals(GridTile.CARD, style?.gridTile)
+    assertEquals("#1e3a8a", style?.cardTint)
+    assertEquals(CardImage.BACKGROUND, style?.cardImage)
+  }
+
+  @Test
+  fun `unknown gridTile decodes as no declaration`() {
+    val resolved =
+      json.decodeFromString<JsonResolvedTrack>(
+        """{"path":"/home","title":"Home","sections":[
+          {"style":{"gridTile":"hexagon"},"children":[{"title":"C","src":"s"}]}
+        ]}"""
+      )
+    assertNull(resolved.toNitro().sections?.first()?.style)
+  }
+}

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

@@ -1,96 +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.sectionStyle
 import com.audiobrowser.TestFixtures.track
+import com.margelo.nitro.audiobrowser.StyleDisplay
 import org.junit.Assert.assertEquals
 import org.junit.Assert.assertNull
 import org.junit.Test
 
 class SectionScopeTest {
 
+  // 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")),
+      ),
+    )
+
   @Test
-  fun `scopes to the contiguous groupTitle run`() {
-    val children =
+  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)
+  }
+
+  @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 `flat index pins the exact copy within a section`() {
+    val playlist =
       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"),
+        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, "c") as SectionScope.Section.Run
-    assertEquals(listOf("c", "d"), 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 `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)
+  }
 
-    val first = SectionScope.section(children, "a") as SectionScope.Section.Run
-    assertEquals(listOf("a", "b"), first.tracks.map { it.src })
+  @Test
+  fun `vanished identity returns null`() {
+    assertNull(SectionScope.scoped(sections, "gone"))
   }
 
   @Test
-  fun `ungrouped items form their own run`() {
+  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 = "First"),
-        track(src = "b"),
-        track(src = "c"),
-        track(src = "d", groupTitle = "Second"),
+      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, "b") as SectionScope.Section.Run
-    assertEquals(listOf("b", "c"), 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 `identical titles in separate runs stay separate`() {
-    val children =
-      listOf(
-        track(src = "a", groupTitle = "Same"),
-        track(src = "x", groupTitle = "Other"),
-        track(src = "b", groupTitle = "Same"),
-      )
+  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 })
+  }
 
-    val section = SectionScope.section(children, "a") as SectionScope.Section.Run
-    assertEquals(listOf("a"), section.tracks.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)
   }
 
   @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"))
-
-    val section =
-      SectionScope.section(children, "s2") as SectionScope.Section.ImageRow
-    assertEquals(listOf("s1", "s2"), section.items.map { it.src })
+  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,154 @@
+package com.audiobrowser.browser
+
+import com.audiobrowser.TestFixtures.sectionStyle
+import com.audiobrowser.TestFixtures.trackStyle
+import com.margelo.nitro.audiobrowser.ArtworkRendering
+import com.margelo.nitro.audiobrowser.CardImage
+import com.margelo.nitro.audiobrowser.GridTile
+import com.margelo.nitro.audiobrowser.ImageShape
+import com.margelo.nitro.audiobrowser.StyleDisplay
+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)
+  }
+
+  @Test
+  fun `imageShape inherits and overrides per item`() {
+    // Section-wide circular (an artists shelf); one album overrides.
+    val inherited =
+      StyleResolver.trackStyle(
+        track = null,
+        section = sectionStyle(imageShape = ImageShape.CIRCULAR),
+      )
+    assertEquals(ImageShape.CIRCULAR, inherited.imageShape)
+    val overridden =
+      StyleResolver.trackStyle(
+        track = trackStyle(imageShape = ImageShape.ROUNDED_RECTANGLE),
+        section = sectionStyle(imageShape = ImageShape.CIRCULAR),
+      )
+    assertEquals(ImageShape.ROUNDED_RECTANGLE, overridden.imageShape)
+  }
+
+  @Test
+  fun `accessorySymbol inherits and 'none' resolves as a value`() {
+    val inherited =
+      StyleResolver.trackStyle(track = null, section = sectionStyle(accessorySymbol = "lock.fill"))
+    assertEquals("lock.fill", inherited.accessorySymbol)
+    // 'none' is the inheritance escape — it must survive resolution intact
+    // (the renderer, not the resolver, maps it to "no accessory").
+    val escaped =
+      StyleResolver.trackStyle(
+        track = trackStyle(accessorySymbol = "none"),
+        section = sectionStyle(accessorySymbol = "lock.fill"),
+      )
+    assertEquals("none", escaped.accessorySymbol)
+  }
+
+  @Test
+  fun `gridTile resolves by scope override`() {
+    // A page-wide card treatment; one section opts back to plain tiles.
+    val inherited =
+      StyleResolver.sectionStyle(section = null, page = sectionStyle(gridTile = GridTile.CARD))
+    assertEquals(GridTile.CARD, inherited.gridTile)
+    val overridden =
+      StyleResolver.sectionStyle(
+        section = sectionStyle(gridTile = GridTile.PLAIN),
+        page = sectionStyle(gridTile = GridTile.CARD),
+      )
+    assertEquals(GridTile.PLAIN, overridden.gridTile)
+  }
+
+  @Test
+  fun `card properties inherit and override per item`() {
+    val inherited =
+      StyleResolver.trackStyle(
+        track = null,
+        section = sectionStyle(cardTint = "#1e3a8a", cardImage = CardImage.BACKGROUND),
+      )
+    assertEquals("#1e3a8a", inherited.cardTint)
+    assertEquals(CardImage.BACKGROUND, inherited.cardImage)
+    val overridden =
+      StyleResolver.trackStyle(
+        track = trackStyle(cardImage = CardImage.NORMAL),
+        section = sectionStyle(cardTint = "#1e3a8a", cardImage = CardImage.BACKGROUND),
+      )
+    assertEquals(CardImage.NORMAL, overridden.cardImage)
+    assertEquals("#1e3a8a", overridden.cardTint)
+  }
+}

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)
+  }
+}