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
@@ -1,15 +1,12 @@
1
1
  type Callback<T> = (arg: T) => void;
2
2
  /**
3
- * The subscription object behind the library's **discrete** events — the
4
- * remote-control exports (`onRemotePlay`, `onRemoteSeek`, …) and other
5
- * one-shot signals with no "current value" to cache. Subscribe with
6
- * {@link addListener}; the returned function unsubscribes. The emitter is
7
- * not callable itself.
3
+ * The subscription object behind the remote-control exports (`onRemotePlay`,
4
+ * `onRemoteSeek`, …) and `onGate`. Subscribe with {@link addListener}; the
5
+ * returned function unsubscribes. The emitter is not callable itself.
8
6
  *
9
- * "Lazy" is an implementation detail you may notice in timing: the native
10
- * side only starts delivering the event once the first listener is added.
11
- * State that always has a current reading uses `NativeUpdatedValue`
12
- * instead.
7
+ * Native starts delivering the event only once the first listener is added,
8
+ * and nothing is cached: there is no `lastValue`. The other `on*` exports use
9
+ * `NativeUpdatedValue`, which listens from module load.
13
10
  *
14
11
  * @example
15
12
  * ```typescript
@@ -1 +1 @@
1
- {"version":3,"file":"LazyNativeEmitter.d.ts","sourceRoot":"","sources":["../../../../src/utils/LazyNativeEmitter.ts"],"names":[],"mappings":"AAAA,KAAK,QAAQ,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,KAAK,IAAI,CAAA;AAEnC;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,iBAAiB,CAAC,CAAC;IAC9B,OAAO,CAAC,MAAM,CAAuC;IACrD,OAAO,CAAC,SAAS,CAAmC;IAOpD,OAAO,CAAC,YAAY;IAWpB;;;;;OAKG;IACH,WAAW,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI,CAI7C;CAeF"}
1
+ {"version":3,"file":"LazyNativeEmitter.d.ts","sourceRoot":"","sources":["../../../../src/utils/LazyNativeEmitter.ts"],"names":[],"mappings":"AAAA,KAAK,QAAQ,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,KAAK,IAAI,CAAA;AAEnC;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,iBAAiB,CAAC,CAAC;IAC9B,OAAO,CAAC,MAAM,CAAuC;IACrD,OAAO,CAAC,SAAS,CAAmC;IAOpD,OAAO,CAAC,YAAY;IAWpB;;;;;OAKG;IACH,WAAW,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI,CAI7C;CAeF"}
@@ -1,15 +1,17 @@
1
1
  type Callback<T> = (arg: T) => void;
2
2
  /**
3
- * The subscription object behind the library's **state** events — every
4
- * `on<Thing>Changed`-style export (`onPlaybackChanged`, `onQueueChanged`, …)
5
- * is one of these. Subscribe with {@link addListener}; the returned function
6
- * unsubscribes. The emitter is not callable itself.
3
+ * The subscription object behind most `on*` exports (`onPlaybackChanged`,
4
+ * `onQueueChanged`, `onTrackMetadata`, …). Subscribe with {@link addListener};
5
+ * the returned function unsubscribes. The emitter is not callable itself.
7
6
  *
8
- * It tracks a value that always has a *current* reading (playback state,
9
- * progress, options): {@link lastValue} caches the most recent one so hooks —
10
- * and you — can read it synchronously without a getter round-trip. Discrete
11
- * events with no current value (remote-control presses) use
12
- * `LazyNativeEmitter` instead.
7
+ * It listens to native from module load and keeps the latest payload in
8
+ * {@link lastValue}. The remote-control exports and `onGate` use
9
+ * `LazyNativeEmitter`, which listens only once a listener is added.
10
+ *
11
+ * `lastValue` is the last payload native sent, not a fresh reading: it is
12
+ * `undefined` before the first event, and for the queue and active track it
13
+ * can be stale after an in-place change (a favorite toggle). Use the getter
14
+ * (`getQueue`, `getActiveTrack`, …) when you need the current value.
13
15
  *
14
16
  * @example
15
17
  * ```typescript
@@ -25,9 +27,8 @@ type Callback<T> = (arg: T) => void;
25
27
  export declare class NativeUpdatedValue<T> {
26
28
  private listeners;
27
29
  /**
28
- * The most recent value delivered by native, or `undefined` before the
29
- * first update. Subscription starts at module load, so this is safe to
30
- * read synchronously at any time.
30
+ * The last payload native sent, or `undefined` before the first. Not a fresh
31
+ * reading: use the matching getter (`getQueue`, …) for the current value.
31
32
  */
32
33
  lastValue: T | undefined;
33
34
  /**
@@ -1 +1 @@
1
- {"version":3,"file":"NativeUpdatedValue.d.ts","sourceRoot":"","sources":["../../../../src/utils/NativeUpdatedValue.ts"],"names":[],"mappings":"AAAA,KAAK,QAAQ,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,KAAK,IAAI,CAAA;AAEnC;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,kBAAkB,CAAC,CAAC;IAC/B,OAAO,CAAC,SAAS,CAAyB;IAE1C;;;;OAIG;IACH,SAAS,EAAE,CAAC,GAAG,SAAS,CAAY;IAapC;;;;;OAKG;IACH,WAAW,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI,CAG7C;CAcF"}
1
+ {"version":3,"file":"NativeUpdatedValue.d.ts","sourceRoot":"","sources":["../../../../src/utils/NativeUpdatedValue.ts"],"names":[],"mappings":"AAAA,KAAK,QAAQ,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,KAAK,IAAI,CAAA;AAEnC;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAAa,kBAAkB,CAAC,CAAC;IAC/B,OAAO,CAAC,SAAS,CAAyB;IAE1C;;;OAGG;IACH,SAAS,EAAE,CAAC,GAAG,SAAS,CAAY;IAapC;;;;;OAKG;IACH,WAAW,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI,CAG7C;CAcF"}
@@ -1,8 +1,10 @@
1
1
  /**
2
- * A track's identity: its opaque `id` when present (non-blank), falling back
3
- * to the playable `src`. Two tracks refer to the same item exactly when their
4
- * identities are equal. Browsable-only tracks (neither `id` nor `src`) have
5
- * no identity — they are addressed by their `path` instead.
2
+ * A track's identity: its opaque `id` when present (non-empty), falling back
3
+ * to the playable `src`. A whitespace-only `id` is the identity here and on
4
+ * iOS, but Android falls back to `src` for it, so never send one. Two tracks
5
+ * refer to the same item exactly when their identities are equal.
6
+ * Browsable-only tracks (neither `id` nor `src`) have no identity — they are
7
+ * addressed by their `path` instead.
6
8
  *
7
9
  * This is the same comparison the library uses everywhere it matches tracks:
8
10
  * favorites (`setFavorites`), the CarPlay / Android Auto "now playing" row
@@ -1 +1 @@
1
- {"version":3,"file":"getTrackIdentity.d.ts","sourceRoot":"","sources":["../../../../src/utils/getTrackIdentity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE;IACtC,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,GAAG,CAAC,EAAE,MAAM,CAAA;CACb,GAAG,MAAM,GAAG,SAAS,CAErB"}
1
+ {"version":3,"file":"getTrackIdentity.d.ts","sourceRoot":"","sources":["../../../../src/utils/getTrackIdentity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE;IACtC,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,GAAG,CAAC,EAAE,MAAM,CAAA;CACb,GAAG,MAAM,GAAG,SAAS,CAErB"}
@@ -36,10 +36,23 @@ interface DebugOptions {
36
36
  }
37
37
  declare function clearDebugLogs(): void;
38
38
  /**
39
- * Debug hook that provides state inspection and change logging.
39
+ * Debug hook that snapshots the player's state and logs each change.
40
40
  *
41
- * @param options - Configuration options
42
- * @returns Debug object with state, logs, and clear function
41
+ * Every entry is also written to the console. The log is shared by every
42
+ * mounted `useDebug`: two mounted instances each log the same change, and
43
+ * `clear` empties it for all of them. Position changes under 2 seconds are
44
+ * not logged. `enabled: false` stops only the logging; the hook still
45
+ * subscribes to the state hooks, `useProgress` among them, and re-renders on
46
+ * every change, so remove it from production code rather than disabling it.
47
+ *
48
+ * @param options - Logging options
49
+ * @param options.enabled - Log state changes. Default `__DEV__`.
50
+ * @param options.metadata - Also log `onTrackMetadata`, `onTimedMetadata` and
51
+ * `onChapterMetadata` events. Default `false`.
52
+ * @returns `state`, a summary snapshot (the queue as comma-joined `src`s, the
53
+ * content as its title, errors as their messages); `logs`, the last 100
54
+ * `{ timestamp, elapsed, type, message }` entries; and `clear`, which
55
+ * empties the log.
43
56
  *
44
57
  * @example
45
58
  * ```tsx
@@ -1 +1 @@
1
- {"version":3,"file":"useDebug.d.ts","sourceRoot":"","sources":["../../../../src/utils/useDebug.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAA;AAC9D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAA;AAChE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAA;AAC/D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,4BAA4B,CAAA;AACzD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,8BAA8B,CAAA;AAC9D,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,UAAU,CAAA;AAsBrC,UAAU,aAAa;IACrB,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,IAAI,EAAE,SAAS,GAAG,QAAQ,GAAG,UAAU,CAAA;IACvC,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,UAAU,UAAU;IAClB,WAAW,EAAE,KAAK,GAAG,SAAS,CAAA;IAC9B,KAAK,EAAE,aAAa,CAAA;IACpB,YAAY,EAAE,YAAY,CAAA;IAC1B,aAAa,EAAE,OAAO,CAAA;IACtB,QAAQ,EAAE,MAAM,CAAA;IAChB,QAAQ,EAAE,MAAM,CAAA;IAChB,KAAK,EAAE,MAAM,CAAA;IACb,UAAU,EAAE,UAAU,CAAA;IACtB,OAAO,EAAE,OAAO,CAAA;IAChB,OAAO,EAAE,OAAO,CAAA;IAChB,MAAM,EAAE,OAAO,CAAA;IACf,UAAU,EAAE,kBAAkB,GAAG,SAAS,CAAA;IAC1C,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B,eAAe,EAAE,MAAM,GAAG,IAAI,CAAA;IAC9B,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IACnB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;CACvB;AAED,UAAU,YAAY;IACpB,oDAAoD;IACpD,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAaD,iBAAS,cAAc,SAGtB;AAoDD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,QAAQ,CAAC,OAAO,GAAE,YAAiB;;;;EA8GlD"}
1
+ {"version":3,"file":"useDebug.d.ts","sourceRoot":"","sources":["../../../../src/utils/useDebug.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAA;AAC9D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAA;AAChE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAA;AAC/D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,4BAA4B,CAAA;AACzD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,8BAA8B,CAAA;AAC9D,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,UAAU,CAAA;AAsBrC,UAAU,aAAa;IACrB,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,IAAI,EAAE,SAAS,GAAG,QAAQ,GAAG,UAAU,CAAA;IACvC,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,UAAU,UAAU;IAClB,WAAW,EAAE,KAAK,GAAG,SAAS,CAAA;IAC9B,KAAK,EAAE,aAAa,CAAA;IACpB,YAAY,EAAE,YAAY,CAAA;IAC1B,aAAa,EAAE,OAAO,CAAA;IACtB,QAAQ,EAAE,MAAM,CAAA;IAChB,QAAQ,EAAE,MAAM,CAAA;IAChB,KAAK,EAAE,MAAM,CAAA;IACb,UAAU,EAAE,UAAU,CAAA;IACtB,OAAO,EAAE,OAAO,CAAA;IAChB,OAAO,EAAE,OAAO,CAAA;IAChB,MAAM,EAAE,OAAO,CAAA;IACf,UAAU,EAAE,kBAAkB,GAAG,SAAS,CAAA;IAC1C,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B,eAAe,EAAE,MAAM,GAAG,IAAI,CAAA;IAC9B,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IACnB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;CACvB;AAED,UAAU,YAAY;IACpB,oDAAoD;IACpD,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAaD,iBAAS,cAAc,SAGtB;AAoDD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,QAAQ,CAAC,OAAO,GAAE,YAAiB;;;;EA8GlD"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "react-native-audio-browser",
3
- "version": "0.2.0-next.54",
3
+ "version": "0.2.0-next.55",
4
4
  "description": "react-native-audio-browser is a react native package built with Nitro",
5
5
  "keywords": [
6
6
  "react-native",
package/src/CLAUDE.md CHANGED
@@ -1,7 +1,8 @@
1
1
  # TypeScript API
2
2
 
3
- The rules here are about the shape of the package's public surface. Both are
4
- enforced by tests, but the tests only tell you _after_ you've written it.
3
+ The rules here are about the shape of the package's public surface. The first
4
+ is enforced by `public-surface.test.ts`, which only tells you _after_ you've
5
+ written it; the second is a convention no test checks.
5
6
 
6
7
  ## Everything you export is public
7
8
 
@@ -47,6 +48,10 @@ Two emitter classes, picked by what the event _is_:
47
48
  Both are created via `emitterize(cb => (nativeBrowser.onThing = cb))` and both
48
49
  return the instance. Neither class is exported from the package.
49
50
 
51
+ No test checks this rule: `features/hook-wiring.test.ts` only records which
52
+ native slot each emitter claims, so a bare `export function onThing(cb)` would
53
+ pass the suite. Review is what catches it.
54
+
50
55
  `on*` observes; `handle*` overrides. `handleRemoteNext(cb)` is a plain setter
51
56
  that replaces the default behaviour and takes `undefined` to clear it, while
52
57
  `onRemoteNext` fires on every press regardless of who handled it.
@@ -0,0 +1,71 @@
1
+ import { readFileSync } from 'node:fs'
2
+ import { join } from 'node:path'
3
+ import { describe, expect, it } from 'vitest'
4
+
5
+ /**
6
+ * The version floors in the Getting Started guide are prose copies of the
7
+ * build files. This fails when a build file moves and the guide doesn't.
8
+ */
9
+ const ROOT = process.cwd()
10
+ const read = (path: string) => readFileSync(join(ROOT, path), 'utf8')
11
+
12
+ const pkg = JSON.parse(read('package.json')) as {
13
+ peerDependencies: Record<string, string>
14
+ }
15
+ const guide = read('website/guide/getting-started.md')
16
+
17
+ /** `>=0.76.0` → `0.76`, `^4.7.9` → `4.7.9`: the floor as the guide writes it. */
18
+ function peerFloor(name: string, parts: number): string {
19
+ const range = pkg.peerDependencies[name]
20
+ const version = range?.match(/\d+(\.\d+)*/)?.[0]
21
+ if (!version) throw new Error(`no peer range for ${name}`)
22
+ return version.split('.').slice(0, parts).join('.')
23
+ }
24
+
25
+ function stated(pattern: RegExp): string {
26
+ const match = guide.match(pattern)
27
+ if (!match?.[1])
28
+ throw new Error(`getting-started.md no longer states ${pattern}`)
29
+ return match[1]
30
+ }
31
+
32
+ describe('getting-started.md version floors', () => {
33
+ it('React Native matches the peer range', () => {
34
+ expect(stated(/React Native (\d+\.\d+) or newer/)).toBe(
35
+ peerFloor('react-native', 2)
36
+ )
37
+ })
38
+
39
+ it('React matches the peer range', () => {
40
+ expect(stated(/React (\d+\.\d+)\+/)).toBe(peerFloor('react', 2))
41
+ })
42
+
43
+ it('react-native-nitro-modules matches the peer range', () => {
44
+ expect(stated(/`react-native-nitro-modules` (\d+\.\d+) or later/)).toBe(
45
+ peerFloor('react-native-nitro-modules', 2)
46
+ )
47
+ })
48
+
49
+ it('shaka-player matches the peer range, major and floor', () => {
50
+ const range = pkg.peerDependencies['shaka-player']
51
+ expect(range?.startsWith('^')).toBe(true)
52
+ expect(stated(/shaka-player`\]\([^)]*\) (\d+) \(/)).toBe(
53
+ peerFloor('shaka-player', 1)
54
+ )
55
+ expect(
56
+ stated(/shaka-player`\]\([^)]*\) \d+ \((\d+\.\d+\.\d+) or later\)/)
57
+ ).toBe(peerFloor('shaka-player', 3))
58
+ })
59
+
60
+ it('iOS matches the podspec', () => {
61
+ const ios = read('AudioBrowser.podspec').match(/:ios => "(\d+)/)?.[1]
62
+ expect(stated(/iOS (\d+)\+/)).toBe(ios)
63
+ })
64
+
65
+ it('Android matches minSdkVersion', () => {
66
+ const sdk = read('android/gradle.properties').match(
67
+ /AudioBrowser_minSdkVersion=(\d+)/
68
+ )?.[1]
69
+ expect(stated(/Android API (\d+)\+/)).toBe(sdk)
70
+ })
71
+ })
@@ -1,11 +1,3 @@
1
- /**
2
- * Battery optimization status and warning handling for Android 12+ foreground service restrictions.
3
- *
4
- * When an external controller (Bluetooth, car head unit) tries to resume playback while the app
5
- * is killed and battery restrictions are in place, Android 12+ blocks the foreground service start.
6
- * This module exposes APIs to detect this condition and guide users to fix their settings.
7
- */
8
-
9
1
  import { nativeBrowser } from '../native'
10
2
  import { NativeUpdatedValue } from '../utils/NativeUpdatedValue'
11
3
  import { useNativeUpdatedValue } from '../utils/useNativeUpdatedValue'
@@ -42,7 +34,10 @@ export type BatteryOptimizationStatusChangedEvent = {
42
34
 
43
35
  /**
44
36
  * Check if a battery warning is pending (Android only).
45
- * Returns true if a foreground service start was blocked and the user hasn't dismissed
37
+ * On Android 12+, when a Bluetooth or car controller resumes playback while the
38
+ * app is killed and battery restrictions apply, the system blocks the foreground
39
+ * service start.
40
+ * Returns true if such a start was blocked and the user hasn't dismissed
46
41
  * the warning or fixed their battery settings.
47
42
  * Auto-clears when battery status becomes unrestricted.
48
43
  * @returns true if warning is pending, always false on iOS
@@ -53,7 +48,6 @@ export function getBatteryWarningPending(): boolean {
53
48
 
54
49
  /**
55
50
  * Get the current battery optimization status (Android only).
56
- * Also fires onBatteryOptimizationStatusChanged if status changed since last call.
57
51
  * @returns Current status, always 'unrestricted' on iOS
58
52
  */
59
53
  export function getBatteryOptimizationStatus(): BatteryOptimizationStatus {
@@ -72,7 +66,12 @@ export function dismissBatteryWarning(): void {
72
66
  }
73
67
 
74
68
  /**
75
- * Open the system battery settings for this app (Android only).
69
+ * Prompt the user to lift this app's battery restriction (Android only).
70
+ * With status `'optimized'` it starts the system's one-tap "ignore battery
71
+ * optimizations" dialog. Android shows that dialog only if the app's manifest
72
+ * declares `android.permission.REQUEST_IGNORE_BATTERY_OPTIMIZATIONS`, which the
73
+ * library does not declare; without it nothing appears. With any other status it
74
+ * opens the app's App info page.
76
75
  * No-op on iOS.
77
76
  */
78
77
  export function openBatterySettings(): void {
@@ -94,7 +93,8 @@ export const onBatteryWarningPendingChanged =
94
93
 
95
94
  /**
96
95
  * Subscribes to battery optimization status changes (Android only).
97
- * Fires when user returns from settings with a different status.
96
+ * Fires when the app comes to the foreground with a different status from the
97
+ * one it had at the previous foreground, typically on return from settings.
98
98
  * Never fires on iOS.
99
99
  */
100
100
  export const onBatteryOptimizationStatusChanged =
@@ -138,7 +138,7 @@ export interface BatteryWarning {
138
138
  status: BatteryOptimizationStatus
139
139
  /** Dismiss the warning without changing settings */
140
140
  dismiss: () => void
141
- /** Open system battery settings for this app */
141
+ /** Prompt the user to lift the restriction; see {@link openBatterySettings} */
142
142
  openSettings: () => void
143
143
  }
144
144
 
@@ -146,6 +146,10 @@ export interface BatteryWarning {
146
146
  * Meta hook that bundles all battery warning state and actions (Android only).
147
147
  * Use this for a complete battery warning UI implementation.
148
148
  *
149
+ * On Android 12+, when a Bluetooth or car controller resumes playback while the
150
+ * app is killed and battery restrictions apply, the system blocks the foreground
151
+ * service start. See the [Battery guide](https://audiobrowser.dev/guide/battery).
152
+ *
149
153
  * @example
150
154
  * ```tsx
151
155
  * function BatteryWarningBanner() {
@@ -219,7 +219,7 @@ function flattenRoutes(
219
219
  return entries.length > 0 ? entries : undefined
220
220
  }
221
221
 
222
- /** Android Auto / CarPlay display at most this many tabs. */
222
+ /** Android Auto displays at most this many tabs; CarPlay reads CPTabBarTemplate.maximumTabCount. */
223
223
  const MAX_TABS = 4
224
224
 
225
225
  /**
@@ -15,24 +15,25 @@ let currentConfiguration: BrowserConfiguration | undefined
15
15
  * Also registers the browser with the player to enable:
16
16
  * - Media URL transformation for authenticated playback
17
17
  * - Android Auto / CarPlay browsing integration
18
- * - Playback of browsable tracks via navigate()
18
+ * - Playing a Playable track selected with navigate()
19
19
  *
20
20
  * Calling this again REPLACES the entire configuration (no merging) and
21
- * re-runs initial navigation — external browse UIs such as CarPlay reset to
22
- * the first tab. For values that change at runtime (base URL, locale, auth
23
- * token), don't reconfigure: read them inside a `request`/`browse` resolver
24
- * or a `transform`, and call {@link invalidateAllContent} so every surface
25
- * re-fetches in place.
26
- *
27
- * @param configuration - Browser configuration including routes, tabs, media config, etc.
21
+ * re-runs initial navigation: the in-app browser returns to `path` or the
22
+ * first tab (on web, the first tab only when `tabs` is an array; otherwise
23
+ * '/'). CarPlay and Android Auto keep their place. For values that change at
24
+ * runtime (base URL, locale, auth token), don't reconfigure: read them
25
+ * inside a `request`/`browse` resolver or a `transform`, and call
26
+ * {@link invalidateAllContent} so every surface re-fetches in place.
28
27
  *
29
28
  * @example
30
29
  * ```ts
31
30
  * configureBrowser({
32
31
  * request: { baseUrl: 'https://api.example.com' },
33
32
  * routes: {
34
- * // `{id}` is a route parameter — see the `routes` docs for matching rules.
35
- * '/albums/{id}': async ({ routeParams }) => fetchAlbumPage(routeParams?.id),
33
+ * // `{id}` is a route parameter — see the `routes` docs for matching
34
+ * // rules.
35
+ * '/albums/{id}': async ({ routeParams }) =>
36
+ * fetchAlbumPage(routeParams?.id),
36
37
  * // Remapping a browse path to a different API path requires a transform;
37
38
  * // a static `path` on a request config does NOT rewrite the path.
38
39
  * '/artists/{id}': {
@@ -70,6 +71,15 @@ export function getBrowserConfiguration(): BrowserConfiguration | undefined {
70
71
  return currentConfiguration
71
72
  }
72
73
 
74
+ /**
75
+ * Opens a Path in the in-app browser, or selects a Track.
76
+ *
77
+ * A string opens that Path; {@link getPath} and {@link getContent} and their
78
+ * events update. A Track is a selection: a Playable track plays, by default
79
+ * with its page as the queue (see `singleTrack` and `handleTrackLoad` on
80
+ * {@link BrowserConfiguration}); a Browsable track opens its path; a disabled
81
+ * track is ignored.
82
+ */
73
83
  export function navigate(pathOrTrack: string | Track) {
74
84
  if (typeof pathOrTrack === 'string') {
75
85
  return nativeBrowser.navigatePath(pathOrTrack)
@@ -78,46 +88,67 @@ export function navigate(pathOrTrack: string | Track) {
78
88
  }
79
89
  }
80
90
 
91
+ /**
92
+ * The Path the in-app browser shows. Before the first navigation it is '/' on
93
+ * iOS and Android and `undefined` on web.
94
+ */
81
95
  export function getPath() {
82
96
  return nativeBrowser.path
83
97
  }
84
98
 
99
+ /** Emits the new Path when the in-app browser navigates. */
85
100
  export const onPathChanged = NativeUpdatedValue.emitterize<string | undefined>(
86
101
  (cb) => (nativeBrowser.onPathChanged = cb)
87
102
  )
88
103
 
104
+ /** Hook that returns {@link getPath} and updates on {@link onPathChanged}. */
89
105
  export function usePath(): string | undefined {
90
106
  return useNativeUpdatedValue(getPath, onPathChanged)
91
107
  }
92
108
 
109
+ /**
110
+ * The resolved page the in-app browser shows; `undefined` until the first
111
+ * navigation resolves.
112
+ */
93
113
  export function getContent(): ResolvedTrack | undefined {
94
114
  return nativeBrowser.getContent()
95
115
  }
96
116
 
117
+ /** Emits the new page when the in-app browser's content changes. */
97
118
  export const onContentChanged = NativeUpdatedValue.emitterize<
98
119
  ResolvedTrack | undefined
99
120
  >((cb) => (nativeBrowser.onContentChanged = cb))
100
121
 
122
+ /**
123
+ * Hook that returns {@link getContent} and updates on {@link onContentChanged}.
124
+ */
101
125
  export function useContent(): ResolvedTrack | undefined {
102
126
  return useNativeUpdatedValue(getContent, onContentChanged)
103
127
  }
128
+
129
+ /**
130
+ * The configured tabs, resolved; `undefined` until {@link configureBrowser}
131
+ * has run and the tabs have resolved.
132
+ */
104
133
  export function getTabs(): Track[] | undefined {
105
134
  return nativeBrowser.tabs
106
135
  }
107
136
 
137
+ /** Emits the new tabs when they resolve or change. */
108
138
  export const onTabsChanged = NativeUpdatedValue.emitterize<Track[] | undefined>(
109
139
  (cb) => (nativeBrowser.onTabsChanged = cb)
110
140
  )
111
141
 
142
+ /** Hook that returns {@link getTabs} and updates on {@link onTabsChanged}. */
112
143
  export function useTabs(): Track[] | undefined {
113
144
  return useNativeUpdatedValue(getTabs, onTabsChanged)
114
145
  }
115
146
 
116
147
  /**
117
- * Notifies external media controllers (Android Auto, CarPlay) that content
118
- * at the specified path has changed and should be refreshed.
119
- *
120
- * @param path - The path where content has changed (e.g., '/favorites')
148
+ * Re-fetches the content at `path` on every surface showing it (the in-app
149
+ * browser, Android Auto, CarPlay); other paths stay as they are. On iOS and
150
+ * Android it also drops the path's cached page. Pass a container path such as
151
+ * '/favorites', not a track's Contextual Path, which iOS and Android reject.
121
152
  *
122
153
  * @example
123
154
  * ```ts
@@ -146,7 +177,8 @@ export const invalidateAllContent = (): void => {
146
177
  }
147
178
 
148
179
  /**
149
- * Returns whether search functionality is configured via `configureBrowser({ search: ... })`.
180
+ * Returns whether search functionality is configured via
181
+ * `configureBrowser({ search: ... })`.
150
182
  */
151
183
  export function hasSearch(): boolean {
152
184
  const config = nativeBrowser.configuration
@@ -157,16 +189,25 @@ export function hasSearch(): boolean {
157
189
  /**
158
190
  * Searches for tracks using the configured search source.
159
191
  *
160
- * Resolves `[]` only when the source found nothing; a failed search rejects,
161
- * so a caller can tell "no results" from "the request failed". The rejection's
162
- * message describes the failure — native platforms reject with the underlying
163
- * throwable and JS sees only its message. On web the `Error` also carries a
164
- * `code`, the {@link NavigationErrorType} the browse path reports as a
165
- * {@link NavigationError} (`'http-error'`, `'network-error'`).
192
+ * When a search source is configured, resolves `[]` only when it found
193
+ * nothing; a failed search rejects, so a caller can tell "no results" from
194
+ * "the request failed". Exception: on Android an HTTP search source
195
+ * (`TransformableRequestConfig`) resolves `[]` on any failure (non-2xx,
196
+ * network or decode error); a callback source still rejects there. With no
197
+ * search source configured, Android and web resolve `[]` and iOS rejects;
198
+ * call {@link hasSearch} first.
199
+ *
200
+ * The rejection's message describes the failure; on native platforms JS sees
201
+ * only that message. On web, a failed search request's `Error` also carries a
202
+ * `code`, the
203
+ * {@link features/errors!NavigationErrorType | NavigationErrorType} the
204
+ * browse path reports as a
205
+ * {@link features/errors!NavigationError | NavigationError}
206
+ * (`'http-error'`, `'network-error'`); a search callback's rejection passes
207
+ * through unchanged.
166
208
  *
167
- * @param query - The search query string
168
- * @returns Promise resolving to an array of matching tracks
169
- * @throws When the search source or its request fails
209
+ * @throws When the search source or its request fails, or on iOS when no
210
+ * search source is configured
170
211
  *
171
212
  * @see {@link configureBrowser}
172
213
  *
@@ -16,10 +16,9 @@ export function isCarConnected(): boolean {
16
16
  // MARK: - Event Callbacks
17
17
 
18
18
  /**
19
- * Subscribes to car connection changes (CarPlay on iOS, Android Auto /
20
- * Android Automotive on Android). Never fires on web.
21
- * @param callback - Called with the new connection state
22
- * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
19
+ * Emits when a car connects or disconnects (CarPlay on iOS, Android Auto /
20
+ * Android Automotive on Android), with the new state. Subscribe with
21
+ * `addListener`, which returns the unsubscribe function. Never emits on web.
23
22
  */
24
23
  export const onCarConnectedChanged = NativeUpdatedValue.emitterize<boolean>(
25
24
  (cb) => (nativeBrowser.onCarConnectedChanged = cb)
@@ -9,7 +9,8 @@ export type { EqualizerSettings }
9
9
 
10
10
  /**
11
11
  * Gets the current equalizer settings (Android only).
12
- * @returns Equalizer settings, or undefined if not available
12
+ * @returns Equalizer settings; undefined on iOS and web, and on Android before
13
+ * `setupPlayer` and until the player's audio session arrives
13
14
  */
14
15
  export function getEqualizerSettings(): EqualizerSettings | undefined {
15
16
  return nativeBrowser.getEqualizerSettings()
@@ -27,7 +28,8 @@ export function setEqualizerEnabled(enabled: boolean): void {
27
28
 
28
29
  /**
29
30
  * Sets the equalizer to a preset (Android only).
30
- * @param preset - The name of the preset to apply
31
+ * @param preset - A name from `settings.presets`; matched case-insensitively,
32
+ * an unknown name is ignored
31
33
  */
32
34
  export function setEqualizerPreset(preset: string): void {
33
35
  nativeBrowser.setEqualizerPreset(preset)
@@ -35,7 +37,9 @@ export function setEqualizerPreset(preset: string): void {
35
37
 
36
38
  /**
37
39
  * Sets custom equalizer band levels (Android only).
38
- * @param levels - Array of level values for each band (in millibels)
40
+ * @param levels - One level per band, in millibels, within
41
+ * `lowerBandLevelLimit`…`upperBandLevelLimit`. The length must equal
42
+ * `bandCount`, or the call is ignored
39
43
  */
40
44
  export function setEqualizerLevels(levels: number[]): void {
41
45
  nativeBrowser.setEqualizerLevels(levels)
@@ -45,7 +49,6 @@ export function setEqualizerLevels(levels: number[]): void {
45
49
 
46
50
  /**
47
51
  * Subscribes to equalizer settings changes (Android only).
48
- * @param callback - Called when equalizer settings change
49
52
  * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
50
53
  */
51
54
  export const onEqualizerChanged =
@@ -57,7 +60,8 @@ export const onEqualizerChanged =
57
60
 
58
61
  /**
59
62
  * Hook that returns the current equalizer settings and updates when they change (Android only).
60
- * @returns Current equalizer settings, or undefined if not available
63
+ * @returns Current equalizer settings; undefined on iOS and web, and on
64
+ * Android before `setupPlayer` and until the player's audio session arrives
61
65
  */
62
66
  export function useEqualizerSettings(): EqualizerSettings | undefined {
63
67
  return useNativeUpdatedValue(getEqualizerSettings, onEqualizerChanged)