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

package/android/src/test/java/com/audiobrowser/tls/CachingCertificateFetcherTest.kt

@@ -1,5 +1,7 @@
 package com.audiobrowser.tls
 
+import java.io.ByteArrayInputStream
+import java.io.InputStream
 import org.junit.Assert.assertArrayEquals
 import org.junit.Assert.assertEquals
 import org.junit.Assert.assertNull
@@ -72,4 +74,85 @@ class CachingCertificateFetcherTest {
       CachingCertificateFetcher.parseHttpResponse("garbage without a header break".toByteArray())
     )
   }
+
+  // -- response cap (the AIA URL, so the host serving it, comes from the presented cert) --
+
+  // -- URL validation (the AIA URL is attacker-supplied text from the presented cert) --
+
+  @Test
+  fun `accepts the URL form CAs actually serve`() {
+    assertTrue(CachingCertificateFetcher.isSafeUrl("http://r13.i.lencr.org/"))
+    assertTrue(CachingCertificateFetcher.isSafeUrl("http://ca.example:8080/issuer.crt?v=2"))
+  }
+
+  @Test
+  fun `rejects a URL carrying CRLF, which would inject request lines`() {
+    // java.net.URL keeps the CRLF in `file`, and the cleartext fetch writes `file` straight
+    // into "GET $path HTTP/1.0\r\n" on a raw socket.
+    assertTrue(!CachingCertificateFetcher.isSafeUrl("http://127.0.0.1:6379/\r\nSET foo bar\r\n"))
+    assertTrue(!CachingCertificateFetcher.isSafeUrl("http://ca.example/a\nX-Injected: 1"))
+  }
+
+  @Test
+  fun `rejects a URL carrying a space, which would split the request line`() {
+    assertTrue(!CachingCertificateFetcher.isSafeUrl("http://ca.example/a b"))
+  }
+
+  @Test
+  fun `reads a response that fits within the cap`() {
+    val body = ByteArray(64) { it.toByte() }
+
+    assertArrayEquals(
+      body,
+      CachingCertificateFetcher.readCapped(ByteArrayInputStream(body), limit = 128),
+    )
+  }
+
+  @Test
+  fun `returns null for a response that exceeds the cap`() {
+    val body = ByteArray(129)
+
+    assertNull(CachingCertificateFetcher.readCapped(ByteArrayInputStream(body), limit = 128))
+  }
+
+  @Test
+  fun `a stream that never ends does not read without bound`() {
+    // Endless: read() always fills the buffer and never signals EOF, the shape a slow-drip
+    // server takes — the per-read timeout never fires because every read succeeds.
+    val endless =
+      object : InputStream() {
+        override fun read() = 0
+
+        override fun read(b: ByteArray, off: Int, len: Int): Int = len
+      }
+
+    assertNull(CachingCertificateFetcher.readCapped(endless, limit = 1 shl 16))
+  }
+
+  @Test
+  fun `a slow drip is cut off by the deadline, not left to exhaust the byte cap`() {
+    // One byte per read, each one landing just inside the socket's read timeout: the byte cap
+    // alone would let this run for a million reads. The clock advances 1s per read, so the
+    // 10s budget must end it after ~10 — far short of the 1 MiB cap.
+    var reads = 0
+    val drip =
+      object : InputStream() {
+        override fun read() = 0
+
+        override fun read(b: ByteArray, off: Int, len: Int): Int {
+          reads++
+          return 1
+        }
+      }
+    var nanos = 0L
+
+    val result =
+      CachingCertificateFetcher.readCapped(drip, budgetMs = 10_000) {
+        nanos += 1_000_000_000
+        nanos
+      }
+
+    assertNull(result)
+    assertTrue("gave up after $reads reads", reads < 20)
+  }
 }

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

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

@@ -0,0 +1,162 @@
+package com.audiobrowser.util
+
+import androidx.media.utils.MediaConstants
+import com.audiobrowser.TestFixtures
+import com.audiobrowser.TestFixtures.sectionStyle
+import com.audiobrowser.TestFixtures.trackStyle
+import com.audiobrowser.browser.styleResolvedSections
+import com.margelo.nitro.audiobrowser.StyleDisplay
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Test
+import org.junit.runner.RunWith
+import org.robolectric.RobolectricTestRunner
+
+/**
+ * The extras are where a section survives the flat MediaBrowser protocol (ADR 0010): the owning
+ * section stamps the Android Auto group-title header hint and the per-item display hint. Per-item
+ * hints derive from the section resolution; a track's own `display` is positional — the page
+ * promise a browsable track emits as the parent-level hint, never its own tile shape (ADR 0011).
+ */
+@RunWith(RobolectricTestRunner::class)
+class MediaExtrasBuilderTest {
+  private val track = TestFixtures.track()
+
+  private fun sectionStyle(display: StyleDisplay?) =
+    sectionStyle(display = display, artworkRendering = null, gridWrap = null)
+
+  @Test
+  fun `owning section title stamps the group-title hint`() {
+    val section = TestFixtures.section(arrayOf(track), title = "Popular")
+    val extras = MediaExtrasBuilder.build(track, section)
+    assertEquals(
+      "Popular",
+      extras.getString(MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_GROUP_TITLE),
+    )
+  }
+
+  @Test
+  fun `an untitled section stamps no group-title hint`() {
+    val section = TestFixtures.section(arrayOf(track))
+    val extras = MediaExtrasBuilder.build(track, section)
+    assertFalse(extras.containsKey(MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_GROUP_TITLE))
+  }
+
+  @Test
+  fun `grid section display stamps the grid item hint`() {
+    val section = TestFixtures.section(arrayOf(track), style = sectionStyle(StyleDisplay.GRID))
+    val extras = MediaExtrasBuilder.build(track, section)
+    assertEquals(
+      MediaConstants.DESCRIPTION_EXTRAS_VALUE_CONTENT_STYLE_GRID_ITEM,
+      extras.getInt(MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_SINGLE_ITEM),
+    )
+  }
+
+  @Test
+  fun `list section display stamps the list item hint`() {
+    val section = TestFixtures.section(arrayOf(track), style = sectionStyle(StyleDisplay.LIST))
+    val extras = MediaExtrasBuilder.build(track, section)
+    assertEquals(
+      MediaConstants.DESCRIPTION_EXTRAS_VALUE_CONTENT_STYLE_LIST_ITEM,
+      extras.getInt(MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_SINGLE_ITEM),
+    )
+  }
+
+  @Test
+  fun `a track's own display never sets its item hint - display is positional`() {
+    val gridPromiseTrack =
+      track.copy(style = trackStyle(display = StyleDisplay.GRID, artworkRendering = null))
+    val section = TestFixtures.section(arrayOf(gridPromiseTrack), style = null)
+    val extras = MediaExtrasBuilder.build(gridPromiseTrack, section)
+    assertFalse(extras.containsKey(MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_SINGLE_ITEM))
+  }
+
+  @Test
+  fun `a browsable track's declared display emits the parent-level promise`() {
+    val handle =
+      TestFixtures.browseTrack()
+        .copy(style = trackStyle(display = StyleDisplay.GRID, artworkRendering = null))
+    val extras = MediaExtrasBuilder.build(handle)
+    val expected = MediaConstants.DESCRIPTION_EXTRAS_VALUE_CONTENT_STYLE_GRID_ITEM
+    assertEquals(
+      expected,
+      extras.getInt(MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_BROWSABLE),
+    )
+    assertEquals(
+      expected,
+      extras.getInt(MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_PLAYABLE),
+    )
+  }
+
+  @Test
+  fun `an undeclared promise emits no parent-level hint - never derived`() {
+    val handle = TestFixtures.browseTrack()
+    val extras = MediaExtrasBuilder.build(handle)
+    assertFalse(extras.containsKey(MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_BROWSABLE))
+    assertFalse(extras.containsKey(MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_PLAYABLE))
+  }
+
+  @Test
+  fun `a playable track's display is inert - playables open no page`() {
+    val playable =
+      track.copy(style = trackStyle(display = StyleDisplay.GRID, artworkRendering = null))
+    val extras = MediaExtrasBuilder.build(playable)
+    assertFalse(extras.containsKey(MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_BROWSABLE))
+    assertFalse(extras.containsKey(MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_PLAYABLE))
+  }
+
+  @Test
+  fun `no style anywhere stamps no style hint`() {
+    val extras = MediaExtrasBuilder.build(track, TestFixtures.section(arrayOf(track)))
+    assertFalse(extras.containsKey(MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_SINGLE_ITEM))
+  }
+
+  @Test
+  fun `no section (queue and now-playing surfaces) stamps neither section hint`() {
+    val extras = MediaExtrasBuilder.build(track)
+    assertFalse(extras.containsKey(MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_GROUP_TITLE))
+    assertFalse(extras.containsKey(MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_SINGLE_ITEM))
+  }
+
+  @Test
+  fun `the view-all navigation track carries the section's declared display as its promise`() {
+    // A "view all" page has no consumer-authored handle — the synthetic
+    // navigation track projects the section's declared block, the only
+    // declared promise that page can ever have.
+    val section =
+      TestFixtures.section(
+        arrayOf(track),
+        title = "Popular",
+        path = "/popular",
+        style = sectionStyle(display = StyleDisplay.GRID, artworkRendering = null, gridWrap = false),
+      )
+    val navigation = TrackFactory.navigationTrack(section, "View more")
+    assertEquals(StyleDisplay.GRID, navigation.style?.display)
+    assertEquals("View more", navigation.title)
+
+    val extras = MediaExtrasBuilder.build(navigation)
+    assertEquals(
+      MediaConstants.DESCRIPTION_EXTRAS_VALUE_CONTENT_STYLE_GRID_ITEM,
+      extras.getInt(MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_BROWSABLE),
+    )
+  }
+
+  @Test
+  fun `an unstyled section under a grid page stamps the grid hint end to end`() {
+    // The wire that makes ResolvedTrack.style real: page block ->
+    // styleResolvedSections fold -> per-item hint. Without the fold, every
+    // narrower unit test stays green while the page tier goes dark.
+    val page =
+      TestFixtures.resolvedTrack(
+        style = sectionStyle(display = StyleDisplay.GRID, artworkRendering = null, gridWrap = null),
+        sections = arrayOf(TestFixtures.section(arrayOf(track))),
+      )
+
+    val folded = page.styleResolvedSections()!!.single()
+    val extras = MediaExtrasBuilder.build(track, folded)
+    assertEquals(
+      MediaConstants.DESCRIPTION_EXTRAS_VALUE_CONTENT_STYLE_GRID_ITEM,
+      extras.getInt(MediaConstants.DESCRIPTION_EXTRAS_KEY_CONTENT_STYLE_SINGLE_ITEM),
+    )
+  }
+}

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

@@ -22,27 +22,27 @@ class TrackFactoryMediaIdTest {
   }
 
   @Test
-  fun `stable id wins over the contextual url for playable tracks`() {
+  fun `stable id wins over the contextual path for playable tracks`() {
     val track =
       TestFixtures.track(id = "abc123", src = "/listen/abc123/channel.mp3")
-        .copy(url = "/home?__trackId=%2Flisten%2Fabc123%2Fchannel.mp3")
+        .copy(path = "/home?__trackId=%2Flisten%2Fabc123%2Fchannel.mp3")
     assertEquals("abc123", TrackFactory.toMedia3(track).mediaId)
   }
 
   @Test
-  fun `playable track without id falls back to url then src`() {
-    val withUrl = TestFixtures.track(src = "/a.mp3").copy(url = "/home?__trackId=%2Fa.mp3")
-    assertEquals("/home?__trackId=%2Fa.mp3", TrackFactory.toMedia3(withUrl).mediaId)
+  fun `playable track without id falls back to path then src`() {
+    val withPath = TestFixtures.track(src = "/a.mp3").copy(path = "/home?__trackId=%2Fa.mp3")
+    assertEquals("/home?__trackId=%2Fa.mp3", TrackFactory.toMedia3(withPath).mediaId)
 
     val srcOnly = TestFixtures.track(src = "/a.mp3")
     assertEquals("/a.mp3", TrackFactory.toMedia3(srcOnly).mediaId)
   }
 
   @Test
-  fun `browsable-only track keeps url as mediaId even with an id`() {
+  fun `browsable-only track keeps path as mediaId even with an id`() {
     // Navigation parentIds must stay resolvable paths, so a container's id is
     // never its mediaId.
-    val track = TestFixtures.browseTrack(url = "/stations").copy(id = "abc123")
+    val track = TestFixtures.browseTrack(path = "/stations").copy(id = "abc123")
     assertEquals("/stations", TrackFactory.toMedia3(track).mediaId)
   }
 

package/ios/Browser/BrowserConfig.swift

@@ -48,9 +48,9 @@ struct BrowserConfig {
   let carPlayLoadingTitle: String?
 
   /// Resolves a browse path for the CarPlay Now Playing album line when the
-  /// active track has no albumUrl. Invoked on track changes (not at tap) so
+  /// active track has no albumPath. Invoked on track changes (not at tap) so
   /// the album line only becomes tappable when a destination exists.
-  let resolveAlbumUrl: ((_ track: Track) -> Promise<String?>)?
+  let resolveAlbumPath: ((_ track: Track) -> Promise<String?>)?
 
   /// Custom handler for track load events (overrides default load behavior)
   let handleTrackLoad: ((_ event: TrackLoadEvent) -> Promise<Promise<Void>>)?
@@ -72,7 +72,7 @@ struct BrowserConfig {
     handleTrackLoad: ((_ event: TrackLoadEvent) -> Promise<Promise<Void>>)? = nil,
     androidControllerOfflineError: Bool = true,
     carPlayLoadingTitle: String? = nil,
-    resolveAlbumUrl: ((_ track: Track) -> Promise<String?>)? = nil,
+    resolveAlbumPath: ((_ track: Track) -> Promise<String?>)? = nil,
     formatNavigationError: ((_ params: FormatNavigationErrorParams) -> Promise<FormattedNavigationError?>)? = nil,
   ) {
     self.request = request
@@ -87,7 +87,7 @@ struct BrowserConfig {
     self.handleTrackLoad = handleTrackLoad
     self.androidControllerOfflineError = androidControllerOfflineError
     self.carPlayLoadingTitle = carPlayLoadingTitle
-    self.resolveAlbumUrl = resolveAlbumUrl
+    self.resolveAlbumPath = resolveAlbumPath
     self.formatNavigationError = formatNavigationError
   }
 
@@ -105,10 +105,31 @@ struct BrowserConfig {
     handleTrackLoad = config.handleTrackLoad
     androidControllerOfflineError = config.androidControllerOfflineError ?? true
     carPlayLoadingTitle = config.carPlayLoadingTitle
-    resolveAlbumUrl = config.resolveAlbumUrl
+    resolveAlbumPath = config.resolveAlbumPath
     formatNavigationError = config.formatNavigationError
   }
 
+  /// A copy of this config with every JS-provided function dropped — at every
+  /// level, not just the top; each nested type's strip below nils its own —
+  /// keeping the static fields (URLs, headers, routes' shape). Makes the config
+  /// safe to hold after its JS runtime is gone: callers take their
+  /// static/built-in fallback paths (a callback-only route degrades to its
+  /// no-content path). See `HybridAudioBrowser.dropStaleJSCallbacks` for why
+  /// invoking a stale callback is fatal.
+  func strippingJSCallbacks() -> BrowserConfig {
+    BrowserConfig(
+      request: request?.strippingJSCallbacks(),
+      browse: browse?.strippingJSCallbacks(),
+      media: media?.strippingJSCallbacks(),
+      artwork: artwork?.strippingJSCallbacks(),
+      nowPlayingArtwork: nowPlayingArtwork?.strippingJSCallbacks(),
+      routes: routes?.map { $0.strippingJSCallbacks() },
+      singleTrack: singleTrack,
+      androidControllerOfflineError: androidControllerOfflineError,
+      carPlayLoadingTitle: carPlayLoadingTitle,
+    )
+  }
+
   // MARK: - Track Load Handler
 
   private static let logger = Logger(subsystem: "com.audiobrowser", category: "BrowserConfig")
@@ -139,3 +160,79 @@ struct BrowserConfig {
 // MARK: - NativeRouteEntry + RouteEntry conformance
 
 extension NativeRouteEntry: RouteEntry {}
+
+// MARK: - Deep JS-callback stripping
+
+// The generated structs are get-only from Swift, so each strip rebuilds the
+// value through the memberwise initializer with the function fields nil'd.
+
+private extension TransformableRequestConfig {
+  func strippingJSCallbacks() -> TransformableRequestConfig {
+    TransformableRequestConfig(
+      transform: nil,
+      transformSync: nil,
+      method: method,
+      path: path,
+      baseUrl: baseUrl,
+      headers: headers,
+      query: query,
+      body: body,
+      contentType: contentType,
+      userAgent: userAgent,
+    )
+  }
+}
+
+private extension MediaRequestConfig {
+  func strippingJSCallbacks() -> MediaRequestConfig {
+    MediaRequestConfig(
+      resolve: nil,
+      resolveSync: nil,
+      transform: nil,
+      transformSync: nil,
+      method: method,
+      path: path,
+      baseUrl: baseUrl,
+      headers: headers,
+      query: query,
+      body: body,
+      contentType: contentType,
+      userAgent: userAgent,
+    )
+  }
+}
+
+private extension ArtworkRequestConfig {
+  func strippingJSCallbacks() -> ArtworkRequestConfig {
+    ArtworkRequestConfig(
+      resolve: nil,
+      resolveSync: nil,
+      transform: nil,
+      transformSync: nil,
+      imageQueryParams: imageQueryParams,
+      method: method,
+      path: path,
+      baseUrl: baseUrl,
+      headers: headers,
+      query: query,
+      body: body,
+      contentType: contentType,
+      userAgent: userAgent,
+    )
+  }
+}
+
+private extension NativeRouteEntry {
+  func strippingJSCallbacks() -> NativeRouteEntry {
+    NativeRouteEntry(
+      path: path,
+      browseCallback: nil,
+      browseConfig: browseConfig?.strippingJSCallbacks(),
+      browseStatic: browseStatic,
+      searchCallback: nil,
+      searchConfig: searchConfig?.strippingJSCallbacks(),
+      media: media?.strippingJSCallbacks(),
+      artwork: artwork?.strippingJSCallbacks(),
+    )
+  }
+}

package/ios/Browser/BrowserManager+URLResolution.swift

@@ -262,10 +262,14 @@ extension BrowserManager {
       }
 
       // Substitute the `{id}` template token with the track's id across path/query/header values.
-      // (Configs without the token are unaffected — e.g. browse artwork.) Only when the track has an id.
-      if let id = track.id, !id.isEmpty {
-        mergedConfig = substituteTrackId(in: mergedConfig, id: id)
-      }
+      // (Configs without the token are unaffected — e.g. browse artwork.) A track without a
+      // non-blank id leaves the token LITERALLY in place — the request then visibly 404s, which
+      // is intended (self-describing error trail) — with a single warning logged below once the
+      // URL is built.
+      mergedConfig = substituteTrackId(in: mergedConfig, id: track.id)
+      let hasUnfilledIdToken = TrackIdTemplate.containsToken(mergedConfig.path)
+        || TrackIdTemplate.containsToken(mergedConfig.query)
+        || TrackIdTemplate.containsToken(mergedConfig.headers)
 
       // Build final URL - if no path after merging, no artwork to transform
       guard mergedConfig.path != nil else {
@@ -280,6 +284,10 @@ extension BrowserManager {
         headers["User-Agent"] = userAgent
       }
 
+      if hasUnfilledIdToken {
+        logger.warning("nowPlayingArtwork: track has no id — '{id}' left unfilled in \(uri)")
+      }
+
       logger.debug("Artwork URL transformed: \(track.artwork?.url ?? "nil") -> \(uri)")
 
       return ImageSource(
@@ -315,18 +323,14 @@ extension BrowserManager {
 
   /// Replaces the `{id}` token with the track id in a request config's path, query values, and
   /// header values. Used so a `nowPlayingArtwork` like `{ path: "/artwork/{id}" }` resolves.
-  private func substituteTrackId(in config: RequestConfig, id: String) -> RequestConfig {
-    func sub(_ s: String?) -> String? { s?.replacingOccurrences(of: "{id}", with: id) }
-    func subDict(_ d: [String: String]?) -> [String: String]? {
-      guard let d else { return nil }
-      return d.mapValues { $0.replacingOccurrences(of: "{id}", with: id) }
-    }
-    return RequestConfig(
+  /// A nil/blank id leaves the values unchanged (token left literal — see TrackIdTemplate).
+  private func substituteTrackId(in config: RequestConfig, id: String?) -> RequestConfig {
+    RequestConfig(
       method: config.method,
-      path: sub(config.path),
+      path: TrackIdTemplate.substitute(config.path, id: id),
       baseUrl: config.baseUrl,
-      headers: subDict(config.headers),
-      query: subDict(config.query),
+      headers: TrackIdTemplate.substitute(config.headers, id: id),
+      query: TrackIdTemplate.substitute(config.query, id: id),
       body: config.body,
       contentType: config.contentType,
       userAgent: config.userAgent,