react-native-audio-browser 0.2.0-next.54 → 0.2.0-next.55

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (271) hide show
  1. package/README.md +32 -19
  2. package/lib/commonjs/CLAUDE.md +7 -2
  3. package/lib/commonjs/features/battery.js +16 -12
  4. package/lib/commonjs/features/battery.js.map +1 -1
  5. package/lib/commonjs/features/browser-config.js +1 -1
  6. package/lib/commonjs/features/browser.js +74 -24
  7. package/lib/commonjs/features/browser.js.map +1 -1
  8. package/lib/commonjs/features/carConnection.js +3 -4
  9. package/lib/commonjs/features/carConnection.js.map +1 -1
  10. package/lib/commonjs/features/equalizer.js +9 -5
  11. package/lib/commonjs/features/equalizer.js.map +1 -1
  12. package/lib/commonjs/features/errors.js +35 -21
  13. package/lib/commonjs/features/errors.js.map +1 -1
  14. package/lib/commonjs/features/favorites.js +15 -13
  15. package/lib/commonjs/features/favorites.js.map +1 -1
  16. package/lib/commonjs/features/gate.js +12 -6
  17. package/lib/commonjs/features/gate.js.map +1 -1
  18. package/lib/commonjs/features/metadata.js +16 -14
  19. package/lib/commonjs/features/metadata.js.map +1 -1
  20. package/lib/commonjs/features/network.js +5 -1
  21. package/lib/commonjs/features/network.js.map +1 -1
  22. package/lib/commonjs/features/nowPlaying.js +28 -14
  23. package/lib/commonjs/features/nowPlaying.js.map +1 -1
  24. package/lib/commonjs/features/output.js +8 -4
  25. package/lib/commonjs/features/output.js.map +1 -1
  26. package/lib/commonjs/features/playback/controls.js +10 -5
  27. package/lib/commonjs/features/playback/controls.js.map +1 -1
  28. package/lib/commonjs/features/playback/playWhenReady.js +6 -5
  29. package/lib/commonjs/features/playback/playWhenReady.js.map +1 -1
  30. package/lib/commonjs/features/playback/playing.js +5 -3
  31. package/lib/commonjs/features/playback/playing.js.map +1 -1
  32. package/lib/commonjs/features/playback/progress.js +11 -5
  33. package/lib/commonjs/features/playback/progress.js.map +1 -1
  34. package/lib/commonjs/features/playback/state.js +3 -3
  35. package/lib/commonjs/features/playback/state.js.map +1 -1
  36. package/lib/commonjs/features/playback/trackPlaybackTime.js +6 -1
  37. package/lib/commonjs/features/playback/trackPlaybackTime.js.map +1 -1
  38. package/lib/commonjs/features/playback/volume.js +6 -5
  39. package/lib/commonjs/features/playback/volume.js.map +1 -1
  40. package/lib/commonjs/features/player/options.js +20 -10
  41. package/lib/commonjs/features/player/options.js.map +1 -1
  42. package/lib/commonjs/features/player/setup.js +34 -38
  43. package/lib/commonjs/features/player/setup.js.map +1 -1
  44. package/lib/commonjs/features/queue/activeTrack.js +0 -1
  45. package/lib/commonjs/features/queue/activeTrack.js.map +1 -1
  46. package/lib/commonjs/features/queue/queue.js +48 -20
  47. package/lib/commonjs/features/queue/queue.js.map +1 -1
  48. package/lib/commonjs/features/queue/repeatMode.js +2 -1
  49. package/lib/commonjs/features/queue/repeatMode.js.map +1 -1
  50. package/lib/commonjs/features/queue/shuffle.js +0 -1
  51. package/lib/commonjs/features/queue/shuffle.js.map +1 -1
  52. package/lib/commonjs/features/remoteControls.js +59 -35
  53. package/lib/commonjs/features/remoteControls.js.map +1 -1
  54. package/lib/commonjs/features/sleepTimer.js +15 -6
  55. package/lib/commonjs/features/sleepTimer.js.map +1 -1
  56. package/lib/commonjs/utils/LazyNativeEmitter.js +6 -9
  57. package/lib/commonjs/utils/LazyNativeEmitter.js.map +1 -1
  58. package/lib/commonjs/utils/NativeUpdatedValue.js +13 -12
  59. package/lib/commonjs/utils/NativeUpdatedValue.js.map +1 -1
  60. package/lib/commonjs/utils/getTrackIdentity.js +6 -4
  61. package/lib/commonjs/utils/getTrackIdentity.js.map +1 -1
  62. package/lib/commonjs/utils/useDebug.js +16 -3
  63. package/lib/commonjs/utils/useDebug.js.map +1 -1
  64. package/lib/commonjs/web/NativeAudioBrowser.js +2 -4
  65. package/lib/commonjs/web/NativeAudioBrowser.js.map +1 -1
  66. package/lib/commonjs/web/browser/parseSearchResponse.js +3 -4
  67. package/lib/commonjs/web/browser/parseSearchResponse.js.map +1 -1
  68. package/lib/commonjs/web/browser/sections.js +1 -1
  69. package/lib/commonjs/web/util/BrowserPathHelper.js +1 -3
  70. package/lib/commonjs/web/util/BrowserPathHelper.js.map +1 -1
  71. package/lib/module/CLAUDE.md +7 -2
  72. package/lib/module/features/battery.js +16 -12
  73. package/lib/module/features/battery.js.map +1 -1
  74. package/lib/module/features/browser-config.js +1 -1
  75. package/lib/module/features/browser.js +74 -24
  76. package/lib/module/features/browser.js.map +1 -1
  77. package/lib/module/features/carConnection.js +3 -4
  78. package/lib/module/features/carConnection.js.map +1 -1
  79. package/lib/module/features/equalizer.js +9 -5
  80. package/lib/module/features/equalizer.js.map +1 -1
  81. package/lib/module/features/errors.js +35 -21
  82. package/lib/module/features/errors.js.map +1 -1
  83. package/lib/module/features/favorites.js +15 -13
  84. package/lib/module/features/favorites.js.map +1 -1
  85. package/lib/module/features/gate.js +12 -6
  86. package/lib/module/features/gate.js.map +1 -1
  87. package/lib/module/features/metadata.js +16 -14
  88. package/lib/module/features/metadata.js.map +1 -1
  89. package/lib/module/features/network.js +5 -1
  90. package/lib/module/features/network.js.map +1 -1
  91. package/lib/module/features/nowPlaying.js +28 -14
  92. package/lib/module/features/nowPlaying.js.map +1 -1
  93. package/lib/module/features/output.js +8 -4
  94. package/lib/module/features/output.js.map +1 -1
  95. package/lib/module/features/playback/controls.js +10 -5
  96. package/lib/module/features/playback/controls.js.map +1 -1
  97. package/lib/module/features/playback/playWhenReady.js +6 -5
  98. package/lib/module/features/playback/playWhenReady.js.map +1 -1
  99. package/lib/module/features/playback/playing.js +5 -3
  100. package/lib/module/features/playback/playing.js.map +1 -1
  101. package/lib/module/features/playback/progress.js +11 -5
  102. package/lib/module/features/playback/progress.js.map +1 -1
  103. package/lib/module/features/playback/state.js +3 -3
  104. package/lib/module/features/playback/state.js.map +1 -1
  105. package/lib/module/features/playback/trackPlaybackTime.js +6 -1
  106. package/lib/module/features/playback/trackPlaybackTime.js.map +1 -1
  107. package/lib/module/features/playback/volume.js +6 -5
  108. package/lib/module/features/playback/volume.js.map +1 -1
  109. package/lib/module/features/player/options.js +20 -10
  110. package/lib/module/features/player/options.js.map +1 -1
  111. package/lib/module/features/player/setup.js +34 -38
  112. package/lib/module/features/player/setup.js.map +1 -1
  113. package/lib/module/features/queue/activeTrack.js +0 -1
  114. package/lib/module/features/queue/activeTrack.js.map +1 -1
  115. package/lib/module/features/queue/queue.js +48 -20
  116. package/lib/module/features/queue/queue.js.map +1 -1
  117. package/lib/module/features/queue/repeatMode.js +2 -1
  118. package/lib/module/features/queue/repeatMode.js.map +1 -1
  119. package/lib/module/features/queue/shuffle.js +0 -1
  120. package/lib/module/features/queue/shuffle.js.map +1 -1
  121. package/lib/module/features/remoteControls.js +59 -35
  122. package/lib/module/features/remoteControls.js.map +1 -1
  123. package/lib/module/features/sleepTimer.js +15 -6
  124. package/lib/module/features/sleepTimer.js.map +1 -1
  125. package/lib/module/utils/LazyNativeEmitter.js +6 -9
  126. package/lib/module/utils/LazyNativeEmitter.js.map +1 -1
  127. package/lib/module/utils/NativeUpdatedValue.js +13 -12
  128. package/lib/module/utils/NativeUpdatedValue.js.map +1 -1
  129. package/lib/module/utils/getTrackIdentity.js +6 -4
  130. package/lib/module/utils/getTrackIdentity.js.map +1 -1
  131. package/lib/module/utils/useDebug.js +16 -3
  132. package/lib/module/utils/useDebug.js.map +1 -1
  133. package/lib/module/web/NativeAudioBrowser.js +2 -4
  134. package/lib/module/web/NativeAudioBrowser.js.map +1 -1
  135. package/lib/module/web/browser/parseSearchResponse.js +3 -4
  136. package/lib/module/web/browser/parseSearchResponse.js.map +1 -1
  137. package/lib/module/web/browser/sections.js +1 -1
  138. package/lib/module/web/util/BrowserPathHelper.js +1 -3
  139. package/lib/module/web/util/BrowserPathHelper.js.map +1 -1
  140. package/lib/typescript/src/features/battery.d.ts +17 -12
  141. package/lib/typescript/src/features/battery.d.ts.map +1 -1
  142. package/lib/typescript/src/features/browser.d.ts +64 -24
  143. package/lib/typescript/src/features/browser.d.ts.map +1 -1
  144. package/lib/typescript/src/features/carConnection.d.ts +3 -4
  145. package/lib/typescript/src/features/carConnection.d.ts.map +1 -1
  146. package/lib/typescript/src/features/equalizer.d.ts +9 -5
  147. package/lib/typescript/src/features/equalizer.d.ts.map +1 -1
  148. package/lib/typescript/src/features/errors.d.ts +37 -22
  149. package/lib/typescript/src/features/errors.d.ts.map +1 -1
  150. package/lib/typescript/src/features/favorites.d.ts +15 -13
  151. package/lib/typescript/src/features/favorites.d.ts.map +1 -1
  152. package/lib/typescript/src/features/gate.d.ts +14 -8
  153. package/lib/typescript/src/features/gate.d.ts.map +1 -1
  154. package/lib/typescript/src/features/metadata.d.ts +37 -17
  155. package/lib/typescript/src/features/metadata.d.ts.map +1 -1
  156. package/lib/typescript/src/features/network.d.ts +5 -1
  157. package/lib/typescript/src/features/network.d.ts.map +1 -1
  158. package/lib/typescript/src/features/nowPlaying.d.ts +28 -14
  159. package/lib/typescript/src/features/nowPlaying.d.ts.map +1 -1
  160. package/lib/typescript/src/features/output.d.ts +8 -4
  161. package/lib/typescript/src/features/output.d.ts.map +1 -1
  162. package/lib/typescript/src/features/playback/controls.d.ts +10 -5
  163. package/lib/typescript/src/features/playback/controls.d.ts.map +1 -1
  164. package/lib/typescript/src/features/playback/playWhenReady.d.ts +6 -5
  165. package/lib/typescript/src/features/playback/playWhenReady.d.ts.map +1 -1
  166. package/lib/typescript/src/features/playback/playing.d.ts +16 -3
  167. package/lib/typescript/src/features/playback/playing.d.ts.map +1 -1
  168. package/lib/typescript/src/features/playback/progress.d.ts +11 -5
  169. package/lib/typescript/src/features/playback/progress.d.ts.map +1 -1
  170. package/lib/typescript/src/features/playback/state.d.ts +8 -3
  171. package/lib/typescript/src/features/playback/state.d.ts.map +1 -1
  172. package/lib/typescript/src/features/playback/trackPlaybackTime.d.ts +9 -2
  173. package/lib/typescript/src/features/playback/trackPlaybackTime.d.ts.map +1 -1
  174. package/lib/typescript/src/features/playback/volume.d.ts +6 -5
  175. package/lib/typescript/src/features/playback/volume.d.ts.map +1 -1
  176. package/lib/typescript/src/features/player/options.d.ts +52 -37
  177. package/lib/typescript/src/features/player/options.d.ts.map +1 -1
  178. package/lib/typescript/src/features/player/setup.d.ts +65 -60
  179. package/lib/typescript/src/features/player/setup.d.ts.map +1 -1
  180. package/lib/typescript/src/features/queue/activeTrack.d.ts +0 -1
  181. package/lib/typescript/src/features/queue/activeTrack.d.ts.map +1 -1
  182. package/lib/typescript/src/features/queue/queue.d.ts +48 -20
  183. package/lib/typescript/src/features/queue/queue.d.ts.map +1 -1
  184. package/lib/typescript/src/features/queue/repeatMode.d.ts +1 -1
  185. package/lib/typescript/src/features/queue/repeatMode.d.ts.map +1 -1
  186. package/lib/typescript/src/features/queue/shuffle.d.ts +0 -1
  187. package/lib/typescript/src/features/queue/shuffle.d.ts.map +1 -1
  188. package/lib/typescript/src/features/remoteControls.d.ts +58 -25
  189. package/lib/typescript/src/features/remoteControls.d.ts.map +1 -1
  190. package/lib/typescript/src/features/sleepTimer.d.ts +15 -7
  191. package/lib/typescript/src/features/sleepTimer.d.ts.map +1 -1
  192. package/lib/typescript/src/types/browser-nodes.d.ts +54 -57
  193. package/lib/typescript/src/types/browser-nodes.d.ts.map +1 -1
  194. package/lib/typescript/src/types/browser.d.ts +181 -144
  195. package/lib/typescript/src/types/browser.d.ts.map +1 -1
  196. package/lib/typescript/src/utils/LazyNativeEmitter.d.ts +6 -9
  197. package/lib/typescript/src/utils/LazyNativeEmitter.d.ts.map +1 -1
  198. package/lib/typescript/src/utils/NativeUpdatedValue.d.ts +13 -12
  199. package/lib/typescript/src/utils/NativeUpdatedValue.d.ts.map +1 -1
  200. package/lib/typescript/src/utils/getTrackIdentity.d.ts +6 -4
  201. package/lib/typescript/src/utils/getTrackIdentity.d.ts.map +1 -1
  202. package/lib/typescript/src/utils/useDebug.d.ts +16 -3
  203. package/lib/typescript/src/utils/useDebug.d.ts.map +1 -1
  204. package/package.json +1 -1
  205. package/src/CLAUDE.md +7 -2
  206. package/src/docs-floors.test.ts +71 -0
  207. package/src/features/battery.ts +17 -13
  208. package/src/features/browser-config.ts +1 -1
  209. package/src/features/browser.ts +65 -24
  210. package/src/features/carConnection.ts +3 -4
  211. package/src/features/equalizer.ts +9 -5
  212. package/src/features/errors.ts +37 -22
  213. package/src/features/favorites.ts +15 -13
  214. package/src/features/gate.ts +14 -8
  215. package/src/features/metadata.ts +37 -17
  216. package/src/features/network.ts +5 -1
  217. package/src/features/nowPlaying.ts +28 -14
  218. package/src/features/output.ts +8 -4
  219. package/src/features/playback/controls.ts +10 -5
  220. package/src/features/playback/playWhenReady.ts +6 -5
  221. package/src/features/playback/playing.ts +16 -3
  222. package/src/features/playback/progress.ts +11 -5
  223. package/src/features/playback/state.ts +8 -3
  224. package/src/features/playback/trackPlaybackTime.ts +9 -2
  225. package/src/features/playback/volume.ts +6 -5
  226. package/src/features/player/options.ts +54 -43
  227. package/src/features/player/setup.ts +67 -61
  228. package/src/features/queue/activeTrack.ts +0 -1
  229. package/src/features/queue/queue.ts +48 -20
  230. package/src/features/queue/repeatMode.ts +1 -1
  231. package/src/features/queue/shuffle.ts +0 -1
  232. package/src/features/remoteControls.ts +59 -35
  233. package/src/features/sleepTimer.ts +15 -7
  234. package/src/types/browser-nodes.ts +54 -57
  235. package/src/types/browser.ts +183 -146
  236. package/src/utils/LazyNativeEmitter.ts +6 -9
  237. package/src/utils/NativeUpdatedValue.ts +13 -12
  238. package/src/utils/getTrackIdentity.ts +6 -4
  239. package/src/utils/useDebug.ts +16 -3
  240. package/src/web/NativeAudioBrowser.ts +2 -4
  241. package/src/web/browser/parseSearchResponse.ts +3 -4
  242. package/src/web/browser/sections.ts +1 -1
  243. package/src/web/util/BrowserPathHelper.ts +1 -3
  244. package/website/guide/android-auto.md +25 -13
  245. package/website/guide/android-certificates.md +199 -120
  246. package/website/guide/artwork.md +93 -48
  247. package/website/guide/audio-output.md +86 -68
  248. package/website/guide/automotive.md +15 -10
  249. package/website/guide/basic-usage.md +5 -2
  250. package/website/guide/battery.md +50 -23
  251. package/website/guide/browser.md +155 -68
  252. package/website/guide/carplay.md +132 -49
  253. package/website/guide/configuration.md +85 -49
  254. package/website/guide/equalizer.md +36 -32
  255. package/website/guide/errors.md +106 -64
  256. package/website/guide/favorites.md +41 -31
  257. package/website/guide/gate.md +24 -10
  258. package/website/guide/getting-started.md +55 -2
  259. package/website/guide/hooks.md +53 -47
  260. package/website/guide/live-streams.md +80 -49
  261. package/website/guide/metadata.md +87 -53
  262. package/website/guide/migrating-from-track-player.md +94 -49
  263. package/website/guide/native-callback-fetch.md +46 -36
  264. package/website/guide/network.md +36 -20
  265. package/website/guide/now-playing.md +72 -44
  266. package/website/guide/playback.md +112 -35
  267. package/website/guide/queue.md +77 -43
  268. package/website/guide/remote-controls.md +87 -29
  269. package/website/guide/search.md +37 -22
  270. package/website/guide/sleep-timer.md +35 -14
  271. package/website/guide/track.md +59 -35
@@ -32,10 +32,6 @@ export type ArtworkRendering = 'original' | 'stencil'
32
32
  * - `'circular'` — the standard presentation for *people* (artists, hosts,
33
33
  * DJs). Shape encodes the kind of item, so mixed grids legitimately
34
34
  * render circular artists next to rounded albums.
35
- *
36
- * Named after Apple's `imageShape` parameter (a platform passthrough), and
37
- * deliberately without a grid prefix: every tile presentation that takes a
38
- * shape reads the same property.
39
35
  */
40
36
  export type ImageShape = 'circular' | 'rounded-rectangle'
41
37
 
@@ -56,7 +52,7 @@ export type ImageShape = 'circular' | 'rounded-rectangle'
56
52
  * {@link TrackStyle.accessorySymbol}.
57
53
  *
58
54
  * Element families are mutually exclusive within a container, so this is
59
- * a container property — hence the enum, and the `grid` prefix.
55
+ * a container property.
60
56
  */
61
57
  export type GridTile = 'plain' | 'image' | 'card' | 'condensed'
62
58
 
@@ -68,9 +64,6 @@ export type GridTile = 'plain' | 'image' | 'card' | 'condensed'
68
64
  * - `'background'` — the image fills the card full-height with the labels
69
65
  * overlaid; `cardTint` fades in behind them. Selects the larger artwork
70
66
  * target size.
71
- *
72
- * An enum rather than a boolean: it names the card's image mode and
73
- * leaves room for future modes.
74
67
  */
75
68
  export type CardImage = 'normal' | 'background'
76
69
 
@@ -155,9 +148,7 @@ export interface TrackStyle {
155
148
  * surface); plain and card tiles have no slot for one. A resolved
156
149
  * symbol replaces the derived accessory (the disclosure chevron a
157
150
  * browsable row gets); `'none'` clears an inherited value, restoring
158
- * the derived behavior — inheritance has no other escape, and no SF
159
- * Symbol is named `none`, so the sentinel is collision-free. Inert off
160
- * CarPlay.
151
+ * the derived accessory. Inert off CarPlay.
161
152
  *
162
153
  * @platform carplay
163
154
  */
@@ -254,12 +245,12 @@ export interface ImageSource {
254
245
  }
255
246
 
256
247
  /**
257
- * Per-track override applied as the most-specific layer of THIS track's media
258
- * request (after the shared `request` and `media` layers). Deliberately narrow:
259
- * a track may customize HOW its request is made (identity, auth, signed-URL
260
- * params), not WHERE it goes — `baseUrl`/`path`/`method`/`body` are intentionally
261
- * absent so a (often server-sourced) track can't repoint its own host or verb.
262
- * Carried verbatim on the Track and round-tripped like any other field.
248
+ * Per-track request fields, carried verbatim on the Track and round-tripped like
249
+ * any other field. Not applied: no platform merges them into the track's
250
+ * media request, so they set no header, user agent or query. For per-track
251
+ * headers or query, return them from `media.resolve` / `resolveSync(track)`.
252
+ * `baseUrl`/`path`/`method`/`body` are absent so a (often server-sourced)
253
+ * track can't repoint its own host or verb.
263
254
  */
264
255
  export interface TrackRequest {
265
256
  userAgent?: string
@@ -271,15 +262,16 @@ export interface TrackRequest {
271
262
  * Artwork URLs for a track that ships a different image per appearance.
272
263
  *
273
264
  * Both are required: a pair with one side missing has no sensible fallback at
274
- * render time, and making that unrepresentable is the reason this is a pair
275
- * rather than two optional fields.
265
+ * render time.
276
266
  *
277
- * Android Auto is dark-only and takes `dark`.
267
+ * The pair adapts to appearance only on CarPlay browse rows and tabs. Every
268
+ * other surface takes `dark` whatever the appearance: now-playing and the lock
269
+ * screen on every platform, Android Auto, and {@link Track.artworkSource}.
278
270
  */
279
271
  export interface ArtworkVariants {
280
- /** Shown in light mode. */
272
+ /** Shown on CarPlay in light mode. */
281
273
  light: string
282
- /** Shown in dark mode, and on Android Auto. */
274
+ /** Shown on CarPlay in dark mode, and on every other surface. */
283
275
  dark: string
284
276
  }
285
277
 
@@ -302,10 +294,8 @@ export interface Section {
302
294
  title?: string
303
295
  /**
304
296
  * Presentation, separated from content. Each surface renders the
305
- * declared layout's nearest supported form; on CarPlay
306
- * a wrapping grid requires iOS 26+ and renders a list before that,
307
- * since CarPlay's only earlier tile container truncates at a width the
308
- * system doesn't report. Use the artwork `resolve` hook to supply
297
+ * declared layout's nearest supported form (CarPlay's grid limits:
298
+ * {@link StyleDisplay}). Use the artwork `resolve` hook to supply
309
299
  * fallback art for tile layouts.
310
300
  */
311
301
  style?: SectionStyle
@@ -314,7 +304,7 @@ export interface Section {
314
304
  * fuller page this section is a teaser for. Absent = a self-contained
315
305
  * section: the header is a plain label, not a link.
316
306
  *
317
- * The surface picks the form (ADR 0010), and each carries the copy
307
+ * The surface picks the form, and each carries the copy
318
308
  * itself — a `path` never adds words to the section:
319
309
  *
320
310
  * - **CarPlay** — a tile section's row draws a disclosure chevron and
@@ -323,7 +313,7 @@ export interface Section {
323
313
  * spend an item from the template's cap.
324
314
  * - **Android Auto** — no header is tappable at any display, so the
325
315
  * section gets an appended browsable row, titled by the global
326
- * `viewMoreTitle` browser option ("View more" by default).
316
+ * `viewMoreTitle` browser option.
327
317
  */
328
318
  path?: string
329
319
  /** The section's tracks. */
@@ -343,8 +333,9 @@ export interface Track {
343
333
  /**
344
334
  * Opaque, stable identifier for this track.
345
335
  *
346
- * A track's **identity** is `id` when set (non-blank), falling back to
347
- * `src`. That single rule drives every comparison the library makes:
336
+ * A track's **identity** is `id` when set (non-empty), falling back to
337
+ * `src`; Android also treats a whitespace-only `id` as unset, so never
338
+ * send one. That single rule drives every comparison the library makes:
348
339
  * favorites matching (`setFavorites`), the CarPlay / Android Auto
349
340
  * "now playing" row indicator, section scoping and skip-in-place, and the
350
341
  * contextual queue re-expansion. Two tracks refer to the same item iff
@@ -405,8 +396,9 @@ export interface Track {
405
396
  * with the `sf:` prefix and optional color params:
406
397
  * `sf:heart.fill?bg=#FF0090&fg=#fff`. `bg` sets the background color
407
398
  * (transparent if omitted), `fg` sets the symbol color (black if omitted).
408
- * On CarPlay, SF Symbols without explicit colors automatically adapt to
409
- * light/dark mode.
399
+ * CarPlay rows key off `fg` instead: without it, the symbol is drawn black
400
+ * or white to match light/dark mode over a grey tile, and `bg` is ignored;
401
+ * with it, an omitted `bg` is a grey tile. CarPlay tabs ignore both.
410
402
  */
411
403
  artwork?: TrackArtwork
412
404
 
@@ -421,12 +413,13 @@ export interface Track {
421
413
  *
422
414
  * @example
423
415
  * ```tsx
424
- * <Image source={audioBrowser.activeTrack?.artworkSource} />
416
+ * const track = useActiveTrack()
417
+ * <Image source={track?.artworkSource} />
425
418
  * ```
426
419
  */
427
420
  readonly artworkSource?: ImageSource
428
421
 
429
- /** Per-track media-request override; merged last (request → media → track.request). */
422
+ /** Per-track request fields, round-tripped verbatim; see {@link TrackRequest} for whether they reach the media request. */
430
423
  request?: TrackRequest
431
424
 
432
425
  // type?: TrackType
@@ -505,26 +498,27 @@ export interface Track {
505
498
  style?: TrackStyle
506
499
 
507
500
  /**
508
- * Unavailable — a content-state fact beside `favorited` and `live`,
509
- * with full behavioral weight (content facts may carry behavior; style
510
- * never does): a disabled track never plays — tap refused, queue
511
- * expansion excludes it, voice search won't match it.
501
+ * Marks the track unavailable: the library never plays it — taps and
502
+ * voice selection are refused, queue expansion and resume exclude it. A
503
+ * queue you pass to `setQueue` is not filtered, and your own UI must
504
+ * honor the flag itself.
512
505
  *
513
- * Rendering ladder, never a trap: **grayed + inert** where the surface
514
- * can draw it (CarPlay) → **hidden** where it can't (Android Auto) —
515
- * never a normal-looking dead control. Hiding is behavior-safe because
516
- * the track is inert everywhere regardless; the cost is losing the
517
- * "Available at 9 PM" tease on surfaces that hide, so put the reason
518
- * in the title for the ones that gray. Applied at page (re-)serve,
519
- * like style.
506
+ * Drawn **grayed + inert** where the surface can (CarPlay list rows and
507
+ * iOS 26+ tiles), **hidden** where it can't (CarPlay tile rows before
508
+ * iOS 26, CarPlay tabs, Android Auto). Surfaces that hide lose any
509
+ * "Available at 9 PM" tease, so put the reason in the title for the ones
510
+ * that gray. Applied when the page is (re-)served, like style.
520
511
  *
521
512
  * @default false
522
513
  */
523
514
  disabled?: boolean
524
515
 
525
516
  /**
526
- * Whether this track is favorited. When the `favorite` capability is enabled,
527
- * displays a filled/empty heart icon in media controllers (notification, Android Auto).
517
+ * Whether this track is favorited. It fills or empties the heart on
518
+ * CarPlay now-playing when `ios.carPlayNowPlayingButtons` includes
519
+ * `'favorite'`. When the `favorite` capability is enabled, it does the
520
+ * same on Android in the notification, Android Auto, the system media
521
+ * controls and playable browse rows. iOS Control Center shows no heart.
528
522
  */
529
523
  favorited?: boolean
530
524
 
@@ -541,14 +535,17 @@ export interface Track {
541
535
  * track declared live — without the declaration it is a no-op.
542
536
  * - **Persistence** (iOS): no position is stored, so a cold-start resume
543
537
  * rejoins the current broadcast instead of seeking a stale timestamp.
544
- * - **Now-playing** (iOS): the live indicator and live-style
545
- * (non-scrubbing) progress UI.
546
- *
547
- * The iOS-heavy list is deliberate, not a gap: on Android, ExoPlayer's
548
- * own classification already covers these — a dropped live connection
549
- * surfaces as a load error (never end-of-stream), and persistence keys
550
- * off its detected liveness — so the declaration's only Android reader
551
- * is the `seekToLiveEdge()` gate. Android Auto has no live badge.
538
+ * - **Now-playing** (iOS and Android): non-scrubbing controls; on iOS
539
+ * also the live indicator. On Android the seek command is removed from
540
+ * media controllers, so the notification and Android Auto draw no
541
+ * scrubber.
542
+ * - **Casting** (Android): a cast receiver loads the item as a live
543
+ * stream, at the live edge.
544
+ *
545
+ * On Android, ExoPlayer's own liveness detection covers end of stream
546
+ * and persistence: a dropped live connection surfaces as a load error
547
+ * (never end-of-stream), and persistence keys off the detected liveness.
548
+ * Android Auto has no live badge.
552
549
  *
553
550
  * Omitting it never breaks playback — it silently breaks these judgment
554
551
  * calls. Declare it on every live track.
@@ -599,8 +596,8 @@ export interface ResolvedTrack extends Track {
599
596
  * block widens to {@link SectionStyle}: the declaration for the whole
600
597
  * page. Item properties set here are inherited by every item on the
601
598
  * page unless a section or track declares its own; the container
602
- * property (`gridWrap`) and the positional `display` are the page-wide
603
- * values a section overrides for its own children.
599
+ * properties (`gridWrap`, `gridTile`) and the positional `display` are
600
+ * the page-wide values a section overrides for its own children.
604
601
  */
605
602
  style?: SectionStyle
606
603