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

package/lib/module/features/carConnection.js

@@ -21,7 +21,7 @@ export function isCarConnected() {
  * Subscribes to car connection changes (CarPlay on iOS, Android Auto /
  * Android Automotive on Android). Never fires on web.
  * @param callback - Called with the new connection state
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onCarConnectedChanged = NativeUpdatedValue.emitterize(cb => nativeBrowser.onCarConnectedChanged = cb);
 

package/lib/module/features/equalizer.js

@@ -44,7 +44,7 @@ export function setEqualizerLevels(levels) {
 /**
  * Subscribes to equalizer settings changes (Android only).
  * @param callback - Called when equalizer settings change
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onEqualizerChanged = NativeUpdatedValue.emitterize(cb => nativeBrowser.onEqualizerChanged = cb);
 

package/lib/module/features/errors.js

@@ -74,7 +74,7 @@ export function getPlaybackError() {
 /**
  * Subscribes to playback error events.
  * @param callback - Called when a playback error occurs
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onPlaybackError = NativeUpdatedValue.emitterize(cb => nativeBrowser.onPlaybackError = cb);
 
@@ -102,7 +102,7 @@ export function getNavigationError() {
 /**
  * Subscribes to navigation error events.
  * @param callback - Called when a navigation error occurs
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onNavigationError = NativeUpdatedValue.emitterize(cb => nativeBrowser.onNavigationError = cb);
 
@@ -130,7 +130,7 @@ export function getFormattedNavigationError() {
 /**
  * Subscribes to formatted navigation error changes.
  * @param callback - Called when the formatted navigation error changes
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onFormattedNavigationError = NativeUpdatedValue.emitterize(cb => nativeBrowser.onFormattedNavigationError = cb);
 

package/lib/module/features/favorites.js

@@ -38,26 +38,29 @@ export function toggleActiveTrackFavorited() {
 }
 
 /**
- * Sets the list of favorited track source identifiers.
+ * Sets the list of favorited track identifiers.
  *
  * This syncs your app's favorites with the native favorites cache, enabling
  * the heart button in media controllers (notification, Android Auto, CarPlay)
  * to show the correct state.
  *
- * Note: This is only needed if the tracks provided to AudioBrowser do not
- * include the `favorited` field. If your API already includes favorite state in
- * track responses, the native favorites cache is populated automatically during browsing.
+ * Each identifier is matched **exactly** against a track's *identity* — its
+ * `id` when set, falling back to `src`. Store favorites as the same stable
+ * identifier you put in `Track.id` (or as the full `src` for id-less tracks).
  *
- * When the heart button is tapped in media controllers or when you call
- * `setActiveTrackFavorited()`, the native favorites cache is automatically
- * updated. You only need to call this on app launch to hydrate the cache.
+ * A track whose response already carries `favorited` keeps that value on
+ * display surfaces — a caller-set flag wins over cache hydration. The cache
+ * itself is written only by this call and by heart toggles
+ * (`setActiveTrackFavorited()` / media-controller taps), so you only need to
+ * call this on app launch — and again whenever the collection changes outside
+ * the player (a sync from another device, say).
  *
- * @param favorites - Array of favorited track `src` values
+ * @param favorites - Array of favorited track identities (`id`, or `src` for id-less tracks)
  *
  * @example
  * ```ts
- * const favoriteSrcs = await loadFavoritesFromStorage()
- * setFavorites(favoriteSrcs)
+ * const favoriteIds = await loadFavoritesFromStorage()
+ * setFavorites(favoriteIds)
  * ```
  */
 export function setFavorites(favorites) {
@@ -77,7 +80,7 @@ export function setFavorites(favorites) {
  * The native side has already updated the track's favorite state and UI.
  *
  * @param callback - Called with the track and its new favorite state
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  *
  * @example
  * ```ts

package/lib/module/features/favorites.js.map

@@ -1 +1 @@
-{"version":3,"names":["nativeBrowser","NativeUpdatedValue","setActiveTrackFavorited","favorited","toggleActiveTrackFavorited","setFavorites","favorites","onFavoriteChanged","emitterize","cb"],"sourceRoot":"../../../src","sources":["features/favorites.ts"],"mappings":";;AACA,SAASA,aAAa,QAAQ,WAAW;AACzC,SAASC,kBAAkB,QAAQ,6BAA6B;;AAEhE;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,uBAAuBA,CAACC,SAAkB,EAAQ;EAChEH,aAAa,CAACE,uBAAuB,CAACC,SAAS,CAAC;AAClD;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,0BAA0BA,CAAA,EAAS;EACjDJ,aAAa,CAACI,0BAA0B,CAAC,CAAC;AAC5C;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,YAAYA,CAACC,SAAmB,EAAQ;EACtDN,aAAa,CAACK,YAAY,CAACC,SAAS,CAAC;AACvC;;AAEA;;AAEA;AACA;AACA;AACA;;AAQA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,MAAMC,iBAAiB,GAC5BN,kBAAkB,CAACO,UAAU,CAC1BC,EAAE,IAAMT,aAAa,CAACO,iBAAiB,GAAGE,EAC7C,CAAC","ignoreList":[]}
+{"version":3,"names":["nativeBrowser","NativeUpdatedValue","setActiveTrackFavorited","favorited","toggleActiveTrackFavorited","setFavorites","favorites","onFavoriteChanged","emitterize","cb"],"sourceRoot":"../../../src","sources":["features/favorites.ts"],"mappings":";;AACA,SAASA,aAAa,QAAQ,WAAW;AACzC,SAASC,kBAAkB,QAAQ,6BAA6B;;AAEhE;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,uBAAuBA,CAACC,SAAkB,EAAQ;EAChEH,aAAa,CAACE,uBAAuB,CAACC,SAAS,CAAC;AAClD;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,0BAA0BA,CAAA,EAAS;EACjDJ,aAAa,CAACI,0BAA0B,CAAC,CAAC;AAC5C;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,YAAYA,CAACC,SAAmB,EAAQ;EACtDN,aAAa,CAACK,YAAY,CAACC,SAAS,CAAC;AACvC;;AAEA;;AAEA;AACA;AACA;AACA;;AAQA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,MAAMC,iBAAiB,GAC5BN,kBAAkB,CAACO,UAAU,CAC1BC,EAAE,IAAMT,aAAa,CAACO,iBAAiB,GAAGE,EAC7C,CAAC","ignoreList":[]}

package/lib/module/features/gate.js

@@ -110,12 +110,20 @@ nativeBrowser.resolveGate = async req => {
  * some surfaces (CarPlay) any gate change pops pushed navigation back to root,
  * so a page the user had drilled into is reset to the tab root. Set the gate
  * before the car connects and it'll be there the moment it does.
+ *
+ * @platform ios android
+ * A no-op on web, which has no CarPlay or Android Auto surfaces for the gate to
+ * cover. Nothing is lost: the gate never covered in-app browse UI on any
+ * platform — that stays yours to gate.
  */
 
 /**
  * Raises the gate with a resolver only (no default chrome).
  * The resolver must return a {@link Gate} or `true` for gated requests;
  * native uses the built-in fallback chrome when `true` and no default is set.
+ *
+ * @platform ios android
+ * A no-op on web — the resolver is never consulted there.
  */
 
 export function setGate(a, b) {
@@ -130,6 +138,9 @@ export function setGate(a, b) {
 
 /**
  * Drops the gate — the real content comes back, and the current tab is kept.
+ *
+ * @platform ios android
+ * A no-op on web, where no gate was ever raised.
  */
 export function clearGate() {
   resolver = undefined;
@@ -138,7 +149,11 @@ export function clearGate() {
 
 /**
  * Subscribes to gate events (fired when a request is gated).
- * @returns Cleanup function to unsubscribe.
+ *
+ * @platform ios android
+ * Never fires on web — there are no gated serves to report.
+ *
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onGate = LazyNativeEmitter.emitterize(cb => nativeBrowser.onGate = cb);
 //# sourceMappingURL=gate.js.map

package/lib/module/features/gate.js.map

@@ -1 +1 @@
-{"version":3,"names":["nativeBrowser","LazyNativeEmitter","resolver","toPublicRequest","req","reason","kind","path","params","search","_exhaustive","Error","String","resolveGate","result","gated","gate","setGate","a","b","undefined","clearGate","onGate","emitterize","cb"],"sourceRoot":"../../../src","sources":["features/gate.ts"],"mappings":";;AACA,SAASA,aAAa,QAAQ,WAAW;AACzC,SAASC,iBAAiB,QAAQ,4BAA4B;;AAE9D;;AAEA;;AAGA;AACA;AACA;AACA;AACA;;AAOA;AACA;AACA;AACA;;AAGA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAGA;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAWA;AACA;AACA;AACA;;AAGA;AACA;AACA;AACA;AACA;;AAKA;AACA;AACA;AACA;AACA;AACA;;AAGA;;AAEA,IAAIC,QAAkC;AAEtC,SAASC,eAAeA,CAACC,GAAsB,EAAe;EAC5D,QAAQA,GAAG,CAACC,MAAM;IAChB,KAAK,QAAQ;MACX,OAAO;QAAEC,IAAI,EAAE,QAAQ;QAAEC,IAAI,EAAEH,GAAG,CAACG,IAAI,IAAI;MAAG,CAAC;IACjD,KAAK,QAAQ;MACX;MACA;MACA;MACA;MACA,OAAO;QAAED,IAAI,EAAE,QAAQ;QAAEE,MAAM,EAAEJ,GAAG,CAACK;MAAQ,CAAC;IAChD;MAAS;QACP,MAAMC,WAAkB,GAAGN,GAAG,CAACC,MAAM;QACrC,MAAM,IAAIM,KAAK,CAAC,yBAAyBC,MAAM,CAACF,WAAW,CAAC,EAAE,CAAC;MACjE;EACF;AACF;;AAEA;AACA;AACAV,aAAa,CAACa,WAAW,GAAG,MAC1BT,GAAsB,IACI;EAC1B,MAAMU,MAAM,GAAGZ,QAAQ,GAAGA,QAAQ,CAACC,eAAe,CAACC,GAAG,CAAC,CAAC,GAAG,IAAI;EAC/D,IAAIU,MAAM,KAAK,KAAK,EAAE,OAAO;IAAEC,KAAK,EAAE;EAAM,CAAC;EAC7C,IAAID,MAAM,KAAK,IAAI,EAAE,OAAO;IAAEC,KAAK,EAAE;EAAK,CAAC;EAC3C,OAAO;IAAEA,KAAK,EAAE,IAAI;IAAEC,IAAI,EAAEF;EAAO,CAAC;AACtC,CAAC;;AAED;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAEA;AACA;AACA;AACA;AACA;;AAEA,OAAO,SAASG,OAAOA,CAACC,CAAsB,EAAEC,CAAgB,EAAQ;EACtE,IAAI,OAAOD,CAAC,KAAK,UAAU,EAAE;IAC3BhB,QAAQ,GAAGgB,CAAC;IACZlB,aAAa,CAACiB,OAAO,CAACG,SAAS,EAAE,IAAI,CAAC;EACxC,CAAC,MAAM;IACLlB,QAAQ,GAAGiB,CAAC;IACZnB,aAAa,CAACiB,OAAO,CAACC,CAAC,EAAEC,CAAC,IAAI,IAAI,CAAC;EACrC;AACF;;AAEA;AACA;AACA;AACA,OAAO,SAASE,SAASA,CAAA,EAAS;EAChCnB,QAAQ,GAAGkB,SAAS;EACpBpB,aAAa,CAACqB,SAAS,CAAC,CAAC;AAC3B;;AAEA;AACA;AACA;AACA;AACA,OAAO,MAAMC,MAAM,GAAGrB,iBAAiB,CAACsB,UAAU,CAC/CC,EAAE,IAAMxB,aAAa,CAACsB,MAAM,GAAGE,EAClC,CAAC","ignoreList":[]}
+{"version":3,"names":["nativeBrowser","LazyNativeEmitter","resolver","toPublicRequest","req","reason","kind","path","params","search","_exhaustive","Error","String","resolveGate","result","gated","gate","setGate","a","b","undefined","clearGate","onGate","emitterize","cb"],"sourceRoot":"../../../src","sources":["features/gate.ts"],"mappings":";;AACA,SAASA,aAAa,QAAQ,WAAW;AACzC,SAASC,iBAAiB,QAAQ,4BAA4B;;AAE9D;;AAEA;;AAGA;AACA;AACA;AACA;AACA;;AAOA;AACA;AACA;AACA;;AAGA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAGA;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAWA;AACA;AACA;AACA;;AAGA;AACA;AACA;AACA;AACA;;AAKA;AACA;AACA;AACA;AACA;AACA;;AAGA;;AAEA,IAAIC,QAAkC;AAEtC,SAASC,eAAeA,CAACC,GAAsB,EAAe;EAC5D,QAAQA,GAAG,CAACC,MAAM;IAChB,KAAK,QAAQ;MACX,OAAO;QAAEC,IAAI,EAAE,QAAQ;QAAEC,IAAI,EAAEH,GAAG,CAACG,IAAI,IAAI;MAAG,CAAC;IACjD,KAAK,QAAQ;MACX;MACA;MACA;MACA;MACA,OAAO;QAAED,IAAI,EAAE,QAAQ;QAAEE,MAAM,EAAEJ,GAAG,CAACK;MAAQ,CAAC;IAChD;MAAS;QACP,MAAMC,WAAkB,GAAGN,GAAG,CAACC,MAAM;QACrC,MAAM,IAAIM,KAAK,CAAC,yBAAyBC,MAAM,CAACF,WAAW,CAAC,EAAE,CAAC;MACjE;EACF;AACF;;AAEA;AACA;AACAV,aAAa,CAACa,WAAW,GAAG,MAC1BT,GAAsB,IACI;EAC1B,MAAMU,MAAM,GAAGZ,QAAQ,GAAGA,QAAQ,CAACC,eAAe,CAACC,GAAG,CAAC,CAAC,GAAG,IAAI;EAC/D,IAAIU,MAAM,KAAK,KAAK,EAAE,OAAO;IAAEC,KAAK,EAAE;EAAM,CAAC;EAC7C,IAAID,MAAM,KAAK,IAAI,EAAE,OAAO;IAAEC,KAAK,EAAE;EAAK,CAAC;EAC3C,OAAO;IAAEA,KAAK,EAAE,IAAI;IAAEC,IAAI,EAAEF;EAAO,CAAC;AACtC,CAAC;;AAED;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAEA,OAAO,SAASG,OAAOA,CAACC,CAAsB,EAAEC,CAAgB,EAAQ;EACtE,IAAI,OAAOD,CAAC,KAAK,UAAU,EAAE;IAC3BhB,QAAQ,GAAGgB,CAAC;IACZlB,aAAa,CAACiB,OAAO,CAACG,SAAS,EAAE,IAAI,CAAC;EACxC,CAAC,MAAM;IACLlB,QAAQ,GAAGiB,CAAC;IACZnB,aAAa,CAACiB,OAAO,CAACC,CAAC,EAAEC,CAAC,IAAI,IAAI,CAAC;EACrC;AACF;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASE,SAASA,CAAA,EAAS;EAChCnB,QAAQ,GAAGkB,SAAS;EACpBpB,aAAa,CAACqB,SAAS,CAAC,CAAC;AAC3B;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,MAAMC,MAAM,GAAGrB,iBAAiB,CAACsB,UAAU,CAC/CC,EAAE,IAAMxB,aAAa,CAACsB,MAAM,GAAGE,EAClC,CAAC","ignoreList":[]}

package/lib/module/features/metadata.js

@@ -30,22 +30,39 @@ import { NativeUpdatedValue } from '../utils/NativeUpdatedValue';
 
 /**
  * Subscribes to chapter metadata events.
+ *
+ * @platform ios android
+ * Never fires on web — the web player does not read chapter markers. See
+ * {@link https://github.com/radio-garden/react-native-audio-browser/issues/118 | #118}.
+ *
  * @param callback - Called when chapter metadata is received
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onChapterMetadata = NativeUpdatedValue.emitterize(cb => nativeBrowser.onChapterMetadata = cb);
 
 /**
  * Subscribes to track metadata events.
+ *
+ * @platform ios android
+ * Never fires on web — the web player does not read embedded file tags. See
+ * {@link https://github.com/radio-garden/react-native-audio-browser/issues/118 | #118}.
+ *
  * @param callback - Called when static track metadata is received
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onTrackMetadata = NativeUpdatedValue.emitterize(cb => nativeBrowser.onTrackMetadata = cb);
 
 /**
  * Subscribes to timed metadata events (ICY/ID3 from live streams).
+ *
+ * @platform ios android
+ * Never fires on web. ICY metadata is stripped by the browser before the player
+ * can see it, and no browser API exposes it; in-band ID3 from HLS is reachable
+ * but not yet wired. See
+ * {@link https://github.com/radio-garden/react-native-audio-browser/issues/118 | #118}.
+ *
  * @param callback - Called when stream metadata is received (title, artist from ICY/ID3 tags)
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onTimedMetadata = NativeUpdatedValue.emitterize(cb => nativeBrowser.onTimedMetadata = cb);
 //# sourceMappingURL=metadata.js.map

package/lib/module/features/metadata.js.map

@@ -1 +1 @@
-{"version":3,"names":["nativeBrowser","NativeUpdatedValue","onChapterMetadata","emitterize","cb","onTrackMetadata","onTimedMetadata"],"sourceRoot":"../../../src","sources":["features/metadata.ts"],"mappings":";;AAAA,SAASA,aAAa,QAAQ,WAAW;AACzC,SAASC,kBAAkB,QAAQ,6BAA6B;;AAEhE;;AAyBA;AACA;AACA;AACA;AACA;;AAcA;AACA;AACA;AACA;;AASA;AACA;AACA;AACA;;AAoBA;AACA;AACA;AACA;;AAYA;;AAEA;AACA;AACA;AACA;AACA;AACA,OAAO,MAAMC,iBAAiB,GAAGD,kBAAkB,CAACE,UAAU,CAE3DC,EAAE,IAAMJ,aAAa,CAACE,iBAAiB,GAAGE,EAAG,CAAC;;AAEjD;AACA;AACA;AACA;AACA;AACA,OAAO,MAAMC,eAAe,GAAGJ,kBAAkB,CAACE,UAAU,CACzDC,EAAE,IAAMJ,aAAa,CAACK,eAAe,GAAGD,EAC3C,CAAC;;AAED;AACA;AACA;AACA;AACA;AACA,OAAO,MAAME,eAAe,GAAGL,kBAAkB,CAACE,UAAU,CACzDC,EAAE,IAAMJ,aAAa,CAACM,eAAe,GAAGF,EAC3C,CAAC","ignoreList":[]}
+{"version":3,"names":["nativeBrowser","NativeUpdatedValue","onChapterMetadata","emitterize","cb","onTrackMetadata","onTimedMetadata"],"sourceRoot":"../../../src","sources":["features/metadata.ts"],"mappings":";;AAAA,SAASA,aAAa,QAAQ,WAAW;AACzC,SAASC,kBAAkB,QAAQ,6BAA6B;;AAEhE;;AAyBA;AACA;AACA;AACA;AACA;;AAcA;AACA;AACA;AACA;;AASA;AACA;AACA;AACA;;AAoBA;AACA;AACA;AACA;;AAYA;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,MAAMC,iBAAiB,GAAGD,kBAAkB,CAACE,UAAU,CAE3DC,EAAE,IAAMJ,aAAa,CAACE,iBAAiB,GAAGE,EAAG,CAAC;;AAEjD;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,MAAMC,eAAe,GAAGJ,kBAAkB,CAACE,UAAU,CACzDC,EAAE,IAAMJ,aAAa,CAACK,eAAe,GAAGD,EAC3C,CAAC;;AAED;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,MAAME,eAAe,GAAGL,kBAAkB,CAACE,UAAU,CACzDC,EAAE,IAAMJ,aAAa,CAACM,eAAe,GAAGF,EAC3C,CAAC","ignoreList":[]}

package/lib/module/features/network.js

@@ -19,7 +19,7 @@ export function getOnline() {
 /**
  * Subscribes to network connectivity changes.
  * @param callback - Called when network state changes
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onOnlineChanged = NativeUpdatedValue.emitterize(cb => nativeBrowser.onOnlineChanged = cb);
 

package/lib/module/features/nowPlaying.js

@@ -72,7 +72,7 @@ export function clearNowPlayingFlash() {
  * Subscribes to now playing metadata change events.
  * Fires when updateNowPlaying is called or when the track changes.
  * @param callback - Called when now playing metadata changes
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onNowPlayingChanged = NativeUpdatedValue.emitterize(cb => nativeBrowser.onNowPlayingChanged = cb);
 

package/lib/module/features/output.js

@@ -44,7 +44,7 @@ export function getOutput() {
 /**
  * Subscribes to current-output changes (headphones unplugged, Bluetooth speaker
  * connected, AirPlay/route selected). Fires on iOS and Android 11+; never below.
- * @returns Cleanup function to unsubscribe.
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onOutputChanged = NativeUpdatedValue.emitterize(cb => nativeBrowser.onOutputChanged = cb);
 

package/lib/module/features/playback/controls.js

@@ -60,8 +60,10 @@ export function seekTo(position) {
 }
 
 /**
- * Jump to the live edge of the current track. No-op for non-live tracks; for
- * live, seeks to the window end (HLS) or reconnects (non-seekable streams).
+ * Jump to the live edge of the current track; no-op unless the track
+ * declares `live: true`. A stream with a seekable live window (HLS) seeks
+ * to the window's edge; a non-seekable stream (e.g. ICY radio) reconnects
+ * to rejoin live — an expired URL re-resolves through `media.resolve`.
  */
 export function seekToLiveEdge() {
   nativeBrowser.seekToLiveEdge();

package/lib/module/features/playback/controls.js.map

@@ -1 +1 @@
-{"version":3,"names":["nativeBrowser","reset","play","pause","togglePlayback","stop","retry","seekTo","position","seekToLiveEdge","seekBy","offset"],"sourceRoot":"../../../../src","sources":["features/playback/controls.ts"],"mappings":";;AAAA;;AAEA,SAASA,aAAa,QAAQ,cAAc;;AAE5C;AACA;AACA;AACA,OAAO,SAASC,KAAKA,CAAA,EAAS;EAC5BD,aAAa,CAACC,KAAK,CAAC,CAAC;AACvB;;AAEA;AACA;AACA;AACA,OAAO,SAASC,IAAIA,CAAA,EAAS;EAC3BF,aAAa,CAACE,IAAI,CAAC,CAAC;AACtB;;AAEA;AACA;AACA;AACA,OAAO,SAASC,KAAKA,CAAA,EAAS;EAC5BH,aAAa,CAACG,KAAK,CAAC,CAAC;AACvB;;AAEA;AACA;AACA;AACA,OAAO,SAASC,cAAcA,CAAA,EAAS;EACrCJ,aAAa,CAACI,cAAc,CAAC,CAAC;AAChC;;AAEA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,IAAIA,CAAA,EAAS;EAC3BL,aAAa,CAACK,IAAI,CAAC,CAAC;AACtB;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,KAAKA,CAAA,EAAS;EAC5BN,aAAa,CAACM,KAAK,CAAC,CAAC;AACvB;;AAEA;AACA;AACA;AACA;AACA,OAAO,SAASC,MAAMA,CAACC,QAAgB,EAAQ;EAC7CR,aAAa,CAACO,MAAM,CAACC,QAAQ,CAAC;AAChC;;AAEA;AACA;AACA;AACA;AACA,OAAO,SAASC,cAAcA,CAAA,EAAS;EACrCT,aAAa,CAACS,cAAc,CAAC,CAAC;AAChC;;AAEA;AACA;AACA;AACA;AACA,OAAO,SAASC,MAAMA,CAACC,MAAc,EAAQ;EAC3CX,aAAa,CAACU,MAAM,CAACC,MAAM,CAAC;AAC9B","ignoreList":[]}
+{"version":3,"names":["nativeBrowser","reset","play","pause","togglePlayback","stop","retry","seekTo","position","seekToLiveEdge","seekBy","offset"],"sourceRoot":"../../../../src","sources":["features/playback/controls.ts"],"mappings":";;AAAA;;AAEA,SAASA,aAAa,QAAQ,cAAc;;AAE5C;AACA;AACA;AACA,OAAO,SAASC,KAAKA,CAAA,EAAS;EAC5BD,aAAa,CAACC,KAAK,CAAC,CAAC;AACvB;;AAEA;AACA;AACA;AACA,OAAO,SAASC,IAAIA,CAAA,EAAS;EAC3BF,aAAa,CAACE,IAAI,CAAC,CAAC;AACtB;;AAEA;AACA;AACA;AACA,OAAO,SAASC,KAAKA,CAAA,EAAS;EAC5BH,aAAa,CAACG,KAAK,CAAC,CAAC;AACvB;;AAEA;AACA;AACA;AACA,OAAO,SAASC,cAAcA,CAAA,EAAS;EACrCJ,aAAa,CAACI,cAAc,CAAC,CAAC;AAChC;;AAEA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,IAAIA,CAAA,EAAS;EAC3BL,aAAa,CAACK,IAAI,CAAC,CAAC;AACtB;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,KAAKA,CAAA,EAAS;EAC5BN,aAAa,CAACM,KAAK,CAAC,CAAC;AACvB;;AAEA;AACA;AACA;AACA;AACA,OAAO,SAASC,MAAMA,CAACC,QAAgB,EAAQ;EAC7CR,aAAa,CAACO,MAAM,CAACC,QAAQ,CAAC;AAChC;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,cAAcA,CAAA,EAAS;EACrCT,aAAa,CAACS,cAAc,CAAC,CAAC;AAChC;;AAEA;AACA;AACA;AACA;AACA,OAAO,SAASC,MAAMA,CAACC,MAAc,EAAQ;EAC3CX,aAAa,CAACU,MAAM,CAACC,MAAM,CAAC;AAC9B","ignoreList":[]}

package/lib/module/features/playback/playWhenReady.js

@@ -33,7 +33,7 @@ export function setPlayWhenReady(playWhenReady) {
 /**
  * Subscribes to play when ready changes.
  * @param callback - Called when playWhenReady changes
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onPlayWhenReadyChanged = NativeUpdatedValue.emitterize(cb => nativeBrowser.onPlaybackPlayWhenReadyChanged = cb);
 

package/lib/module/features/playback/playing.js

@@ -20,7 +20,7 @@ export function getPlayingState() {
 /**
  * Subscribes to playing state changes.
  * @param callback - Called when playing or buffering state changes
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onPlayingState = NativeUpdatedValue.emitterize(cb => nativeBrowser.onPlaybackPlayingState = cb);
 

package/lib/module/features/playback/progress.js

@@ -29,7 +29,7 @@ export function getProgress() {
 /**
  * Subscribes to playback progress updates.
  * @param callback - Called periodically with playback progress updates
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onProgressUpdated = NativeUpdatedValue.emitterize(cb => nativeBrowser.onPlaybackProgressUpdated = cb);
 
@@ -95,7 +95,8 @@ export function usePolledProgress(updateInterval = 1000) {
       poll();
     };
     const stop = () => {
-      clearTimeout(timer);
+      // Guarded: React Native types clearTimeout(handle: number) — no undefined.
+      if (timer !== undefined) clearTimeout(timer);
       timer = undefined;
       unsubscribeState?.();
       unsubscribeState = undefined;

package/lib/module/features/playback/progress.js.map

@@ -1 +1 @@
-{"version":3,"names":["useEffect","useState","AppState","nativeBrowser","NativeUpdatedValue","useNativeUpdatedValue","onPlaybackChanged","getProgress","onProgressUpdated","emitterize","cb","onPlaybackProgressUpdated","useProgress","usePolledProgress","updateInterval","state","setState","position","duration","buffered","timer","unsubscribeState","update","currentState","poll","setTimeout","start","undefined","addListener","stop","clearTimeout","appStateSub","addEventListener","next","remove"],"sourceRoot":"../../../../src","sources":["features/playback/progress.ts"],"mappings":";;AAAA,SAASA,SAAS,EAAEC,QAAQ,QAAQ,OAAO;AAC3C,SAASC,QAAQ,QAAQ,cAAc;AACvC,SAASC,aAAa,QAAQ,cAAc;AAC5C,SAASC,kBAAkB,QAAQ,gCAAgC;AACnE,SAASC,qBAAqB,QAAQ,mCAAmC;AACzE,SAASC,iBAAiB,QAAQ,SAAS;;AAE3C;;AAiBA;AACA;AACA;;AAMA;;AAEA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,WAAWA,CAAA,EAAa;EACtC,OAAOJ,aAAa,CAACI,WAAW,CAAC,CAAC;AACpC;;AAEA;;AAEA;AACA;AACA;AACA;AACA;AACA,OAAO,MAAMC,iBAAiB,GAC5BJ,kBAAkB,CAACK,UAAU,CAC1BC,EAAE,IAAMP,aAAa,CAACQ,yBAAyB,GAAGD,EACrD,CAAC;;AAEH;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASE,WAAWA,CAAA,EAAa;EACtC,OAAOP,qBAAqB,CAACE,WAAW,EAAEC,iBAAiB,CAAC;AAC9D;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASK,iBAAiBA,CAACC,cAAc,GAAG,IAAI,EAAY;EACjE,MAAM,CAACC,KAAK,EAAEC,QAAQ,CAAC,GAAGf,QAAQ,CAAW;IAC3CgB,QAAQ,EAAE,CAAC;IACXC,QAAQ,EAAE,CAAC;IACXC,QAAQ,EAAE;EACZ,CAAC,CAAC;EAEFnB,SAAS,CAAC,MAAM;IACd,IAAIoB,KAAgD;IACpD,IAAIC,gBAA0C;IAE9C,MAAMC,MAAM,GAAGA,CAAA,KAAM;MACnB,IAAI;QACF,MAAM;UAAEL,QAAQ;UAAEC,QAAQ;UAAEC;QAAS,CAAC,GAAGZ,WAAW,CAAC,CAAC;QAEtDS,QAAQ,CAAEO,YAAY,IACpBN,QAAQ,KAAKM,YAAY,CAACN,QAAQ,IAClCC,QAAQ,KAAKK,YAAY,CAACL,QAAQ,IAClCC,QAAQ,KAAKI,YAAY,CAACJ,QAAQ,GAC9BI,YAAY,GACZ;UAAEN,QAAQ;UAAEC,QAAQ;UAAEC;QAAS,CACrC,CAAC;MACH,CAAC,CAAC,MAAM;QACN;MAAA;IAEJ,CAAC;IAED,MAAMK,IAAI,GAAGA,CAAA,KAAM;MACjBF,MAAM,CAAC,CAAC;MACRF,KAAK,GAAGK,UAAU,CAACD,IAAI,EAAEV,cAAc,CAAC;IAC1C,CAAC;;IAED;IACA;IACA;IACA,MAAMY,KAAK,GAAGA,CAAA,KAAM;MAClB,IAAIN,KAAK,KAAKO,SAAS,EAAE;MACzBN,gBAAgB,GAAGf,iBAAiB,CAACsB,WAAW,CAACN,MAAM,CAAC;MACxDE,IAAI,CAAC,CAAC;IACR,CAAC;IAED,MAAMK,IAAI,GAAGA,CAAA,KAAM;MACjBC,YAAY,CAACV,KAAK,CAAC;MACnBA,KAAK,GAAGO,SAAS;MACjBN,gBAAgB,GAAG,CAAC;MACpBA,gBAAgB,GAAGM,SAAS;IAC9B,CAAC;IAED,MAAMI,WAAW,GAAG7B,QAAQ,CAAC8B,gBAAgB,CAAC,QAAQ,EAAGC,IAAI,IAAK;MAChE,IAAIA,IAAI,KAAK,QAAQ,EAAEP,KAAK,CAAC,CAAC,MACzBG,IAAI,CAAC,CAAC;IACb,CAAC,CAAC;IAEF,IAAI3B,QAAQ,CAACqB,YAAY,KAAK,QAAQ,EAAEG,KAAK,CAAC,CAAC;IAE/C,OAAO,MAAM;MACXG,IAAI,CAAC,CAAC;MACNE,WAAW,CAACG,MAAM,CAAC,CAAC;IACtB,CAAC;EACH,CAAC,EAAE,CAACpB,cAAc,CAAC,CAAC;EAEpB,OAAOC,KAAK;AACd","ignoreList":[]}
+{"version":3,"names":["useEffect","useState","AppState","nativeBrowser","NativeUpdatedValue","useNativeUpdatedValue","onPlaybackChanged","getProgress","onProgressUpdated","emitterize","cb","onPlaybackProgressUpdated","useProgress","usePolledProgress","updateInterval","state","setState","position","duration","buffered","timer","unsubscribeState","update","currentState","poll","setTimeout","start","undefined","addListener","stop","clearTimeout","appStateSub","addEventListener","next","remove"],"sourceRoot":"../../../../src","sources":["features/playback/progress.ts"],"mappings":"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","ignoreList":[]}

package/lib/module/features/playback/rate.js

@@ -16,8 +16,15 @@ export function getRate() {
 
 /**
  * Sets the playback rate.
+ *
+ * The rate is a speed multiplier, not a transport control — it is independent
+ * of play/pause, and setting it while paused never starts playback. Use
+ * {@link play} / {@link pause} for that.
+ *
  * @param rate - The playback rate to change to, where 0.5 would be half speed,
- * 1 would be regular speed, 2 would be double speed etc.
+ * 1 would be regular speed, 2 would be double speed etc. Must be greater than
+ * zero; platforms disagree on what a non-positive rate does (iOS ignores it,
+ * Android throws, web stalls the element), so treat it as unsupported.
  */
 export function setRate(rate) {
   nativeBrowser.setRate(rate);

package/lib/module/features/playback/rate.js.map

@@ -1 +1 @@
-{"version":3,"names":["nativeBrowser","getRate","setRate","rate"],"sourceRoot":"../../../../src","sources":["features/playback/rate.ts"],"mappings":";;AAAA;;AAEA,SAASA,aAAa,QAAQ,cAAc;;AAE5C;AACA;AACA;AACA;AACA,OAAO,SAASC,OAAOA,CAAA,EAAW;EAChC,OAAOD,aAAa,CAACC,OAAO,CAAC,CAAC;AAChC;;AAEA;;AAEA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,OAAOA,CAACC,IAAY,EAAQ;EAC1CH,aAAa,CAACE,OAAO,CAACC,IAAI,CAAC;AAC7B","ignoreList":[]}
+{"version":3,"names":["nativeBrowser","getRate","setRate","rate"],"sourceRoot":"../../../../src","sources":["features/playback/rate.ts"],"mappings":";;AAAA;;AAEA,SAASA,aAAa,QAAQ,cAAc;;AAE5C;AACA;AACA;AACA;AACA,OAAO,SAASC,OAAOA,CAAA,EAAW;EAChC,OAAOD,aAAa,CAACC,OAAO,CAAC,CAAC;AAChC;;AAEA;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,OAAOA,CAACC,IAAY,EAAQ;EAC1CH,aAAa,CAACE,OAAO,CAACC,IAAI,CAAC;AAC7B","ignoreList":[]}

package/lib/module/features/playback/state.js

@@ -19,9 +19,8 @@ import { useNativeUpdatedValue } from '../../utils/useNativeUpdatedValue';
  * - `'buffering'`: Indicates that the player is currently loading more data
  *   before it can continue playing or is ready to start playing.
  * - `'error'`: Indicates that playback of the current item failed. Call
- *   `AudioBrowser.getError()` to get more information on the type of error that
- *   occurred. Call `AudioBrowser.retry()` or `AudioBrowser.play()` to try to play
- *   the item again.
+ *   `getPlaybackError()` (or subscribe via `usePlaybackError()`) for the
+ *   error details. Call `retry()` or `play()` to try to play the item again.
  * - `'ended'`: Indicates that playback stopped due to the end of the queue
  *   being reached.
  */
@@ -41,7 +40,7 @@ export function getPlayback() {
 /**
  * Subscribes to playback state changes.
  * @param callback - Called when the playback state changes
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onPlaybackChanged = NativeUpdatedValue.emitterize(cb => nativeBrowser.onPlaybackChanged = cb);
 

package/lib/module/features/playback/state.js.map

@@ -1 +1 @@
-{"version":3,"names":["nativeBrowser","NativeUpdatedValue","useNativeUpdatedValue","getPlayback","onPlaybackChanged","emitterize","cb","usePlayback"],"sourceRoot":"../../../../src","sources":["features/playback/state.ts"],"mappings":";;AACA,SAASA,aAAa,QAAQ,cAAc;AAC5C,SAASC,kBAAkB,QAAQ,gCAAgC;AACnE,SAASC,qBAAqB,QAAQ,mCAAmC;;AAEzE;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAiBA;;AAEA;AACA;AACA;AACA;AACA,OAAO,SAASC,WAAWA,CAAA,EAAa;EACtC,OAAOH,aAAa,CAACG,WAAW,CAAC,CAAC;AACpC;;AAEA;;AAEA;AACA;AACA;AACA;AACA;AACA,OAAO,MAAMC,iBAAiB,GAAGH,kBAAkB,CAACI,UAAU,CAC3DC,EAAE,IAAMN,aAAa,CAACI,iBAAiB,GAAGE,EAC7C,CAAC;;AAED;;AAEA;AACA;AACA;AACA;AACA,OAAO,SAASC,WAAWA,CAAA,EAAa;EACtC,OAAOL,qBAAqB,CAACC,WAAW,EAAEC,iBAAiB,CAAC;AAC9D","ignoreList":[]}
+{"version":3,"names":["nativeBrowser","NativeUpdatedValue","useNativeUpdatedValue","getPlayback","onPlaybackChanged","emitterize","cb","usePlayback"],"sourceRoot":"../../../../src","sources":["features/playback/state.ts"],"mappings":";;AACA,SAASA,aAAa,QAAQ,cAAc;AAC5C,SAASC,kBAAkB,QAAQ,gCAAgC;AACnE,SAASC,qBAAqB,QAAQ,mCAAmC;;AAEzE;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAiBA;;AAEA;AACA;AACA;AACA;AACA,OAAO,SAASC,WAAWA,CAAA,EAAa;EACtC,OAAOH,aAAa,CAACG,WAAW,CAAC,CAAC;AACpC;;AAEA;;AAEA;AACA;AACA;AACA;AACA;AACA,OAAO,MAAMC,iBAAiB,GAAGH,kBAAkB,CAACI,UAAU,CAC3DC,EAAE,IAAMN,aAAa,CAACI,iBAAiB,GAAGE,EAC7C,CAAC;;AAED;;AAEA;AACA;AACA;AACA;AACA,OAAO,SAASC,WAAWA,CAAA,EAAa;EACtC,OAAOL,qBAAqB,CAACC,WAAW,EAAEC,iBAAiB,CAAC;AAC9D","ignoreList":[]}

package/lib/module/features/playback/trackPlaybackTime.js

@@ -80,9 +80,4 @@ export function trackPlaybackTime(callback, period) {
     if (handles.size === 0) nativeBrowser.setPlaybackIntervalEnabled(false);
   };
 }
-
-/** @internal test hook — drives the fan-out without a native tick. */
-export function __emitTickForTests(ticks = 1) {
-  for (let i = 0; i < ticks; i++) onTick();
-}
 //# sourceMappingURL=trackPlaybackTime.js.map

package/lib/module/features/playback/trackPlaybackTime.js.map

@@ -1 +1 @@
-{"version":3,"names":["nativeBrowser","onActiveTrackChanged","handles","Set","installed","currentTrack","onTick","handle","totalSeconds","sinceLast","lastFireSeconds","period","callback","total","track","install","onPlaybackInterval","addListener","event","trackPlaybackTime","Error","add","size","setPlaybackIntervalEnabled","delete","__emitTickForTests","ticks","i"],"sourceRoot":"../../../../src","sources":["features/playback/trackPlaybackTime.ts"],"mappings":";;AACA,SAASA,aAAa,QAAQ,cAAc;AAC5C,SAASC,oBAAoB,QAAQ,sBAAsB;;AAE3D;;AAkBA;;AAEA,MAAMC,OAAO,GAAG,IAAIC,GAAG,CAAS,CAAC;AACjC,IAAIC,SAAS,GAAG,KAAK;AACrB,IAAIC,YAA+B;;AAEnC;AACA;AACA;AACA,SAASC,MAAMA,CAAA,EAAG;EAChB,KAAK,MAAMC,MAAM,IAAIL,OAAO,EAAE;IAC5BK,MAAM,CAACC,YAAY,IAAI,CAAC;IACxB,MAAMC,SAAS,GAAGF,MAAM,CAACC,YAAY,GAAGD,MAAM,CAACG,eAAe;IAC9D,IAAID,SAAS,IAAIF,MAAM,CAACI,MAAM,EAAE;MAC9BJ,MAAM,CAACG,eAAe,GAAGH,MAAM,CAACC,YAAY;MAC5CD,MAAM,CAACK,QAAQ,CAAC;QACdC,KAAK,EAAEN,MAAM,CAACC,YAAY;QAC1BC,SAAS;QACTK,KAAK,EAAET;MACT,CAAC,CAAC;IACJ;EACF;AACF;AAEA,SAASU,OAAOA,CAAA,EAAG;EACjB,IAAIX,SAAS,EAAE;EACfA,SAAS,GAAG,IAAI;EAChBJ,aAAa,CAACgB,kBAAkB,GAAGV,MAAM;EACzCL,oBAAoB,CAACgB,WAAW,CAAEC,KAAK,IAAK;IAC1Cb,YAAY,GAAGa,KAAK,CAACJ,KAAK;EAC5B,CAAC,CAAC;AACJ;;AAEA;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASK,iBAAiBA,CAC/BP,QAA4C,EAC5CD,MAAc,EACF;EACZ,IAAI,EAAEA,MAAM,IAAI,CAAC,CAAC,EAAE;IAClB,MAAM,IAAIS,KAAK,CAAC,wCAAwC,CAAC;EAC3D;EACAL,OAAO,CAAC,CAAC;EACT,MAAMR,MAAc,GAAG;IACrBI,MAAM;IACNH,YAAY,EAAE,CAAC;IACfE,eAAe,EAAE,CAAC;IAClBE;EACF,CAAC;EACDV,OAAO,CAACmB,GAAG,CAACd,MAAM,CAAC;EACnB,IAAIL,OAAO,CAACoB,IAAI,KAAK,CAAC,EAAEtB,aAAa,CAACuB,0BAA0B,CAAC,IAAI,CAAC;EACtE,OAAO,MAAM;IACX,IAAI,CAACrB,OAAO,CAACsB,MAAM,CAACjB,MAAM,CAAC,EAAE;IAC7B,IAAIL,OAAO,CAACoB,IAAI,KAAK,CAAC,EAAEtB,aAAa,CAACuB,0BAA0B,CAAC,KAAK,CAAC;EACzE,CAAC;AACH;;AAEA;AACA,OAAO,SAASE,kBAAkBA,CAACC,KAAK,GAAG,CAAC,EAAE;EAC5C,KAAK,IAAIC,CAAC,GAAG,CAAC,EAAEA,CAAC,GAAGD,KAAK,EAAEC,CAAC,EAAE,EAAErB,MAAM,CAAC,CAAC;AAC1C","ignoreList":[]}
+{"version":3,"names":["nativeBrowser","onActiveTrackChanged","handles","Set","installed","currentTrack","onTick","handle","totalSeconds","sinceLast","lastFireSeconds","period","callback","total","track","install","onPlaybackInterval","addListener","event","trackPlaybackTime","Error","add","size","setPlaybackIntervalEnabled","delete"],"sourceRoot":"../../../../src","sources":["features/playback/trackPlaybackTime.ts"],"mappings":";;AACA,SAASA,aAAa,QAAQ,cAAc;AAC5C,SAASC,oBAAoB,QAAQ,sBAAsB;;AAE3D;;AAkBA;;AAEA,MAAMC,OAAO,GAAG,IAAIC,GAAG,CAAS,CAAC;AACjC,IAAIC,SAAS,GAAG,KAAK;AACrB,IAAIC,YAA+B;;AAEnC;AACA;AACA;AACA,SAASC,MAAMA,CAAA,EAAG;EAChB,KAAK,MAAMC,MAAM,IAAIL,OAAO,EAAE;IAC5BK,MAAM,CAACC,YAAY,IAAI,CAAC;IACxB,MAAMC,SAAS,GAAGF,MAAM,CAACC,YAAY,GAAGD,MAAM,CAACG,eAAe;IAC9D,IAAID,SAAS,IAAIF,MAAM,CAACI,MAAM,EAAE;MAC9BJ,MAAM,CAACG,eAAe,GAAGH,MAAM,CAACC,YAAY;MAC5CD,MAAM,CAACK,QAAQ,CAAC;QACdC,KAAK,EAAEN,MAAM,CAACC,YAAY;QAC1BC,SAAS;QACTK,KAAK,EAAET;MACT,CAAC,CAAC;IACJ;EACF;AACF;AAEA,SAASU,OAAOA,CAAA,EAAG;EACjB,IAAIX,SAAS,EAAE;EACfA,SAAS,GAAG,IAAI;EAChBJ,aAAa,CAACgB,kBAAkB,GAAGV,MAAM;EACzCL,oBAAoB,CAACgB,WAAW,CAAEC,KAAK,IAAK;IAC1Cb,YAAY,GAAGa,KAAK,CAACJ,KAAK;EAC5B,CAAC,CAAC;AACJ;;AAEA;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASK,iBAAiBA,CAC/BP,QAA4C,EAC5CD,MAAc,EACF;EACZ,IAAI,EAAEA,MAAM,IAAI,CAAC,CAAC,EAAE;IAClB,MAAM,IAAIS,KAAK,CAAC,wCAAwC,CAAC;EAC3D;EACAL,OAAO,CAAC,CAAC;EACT,MAAMR,MAAc,GAAG;IACrBI,MAAM;IACNH,YAAY,EAAE,CAAC;IACfE,eAAe,EAAE,CAAC;IAClBE;EACF,CAAC;EACDV,OAAO,CAACmB,GAAG,CAACd,MAAM,CAAC;EACnB,IAAIL,OAAO,CAACoB,IAAI,KAAK,CAAC,EAAEtB,aAAa,CAACuB,0BAA0B,CAAC,IAAI,CAAC;EACtE,OAAO,MAAM;IACX,IAAI,CAACrB,OAAO,CAACsB,MAAM,CAACjB,MAAM,CAAC,EAAE;IAC7B,IAAIL,OAAO,CAACoB,IAAI,KAAK,CAAC,EAAEtB,aAAa,CAACuB,0BAA0B,CAAC,KAAK,CAAC;EACzE,CAAC;AACH","ignoreList":[]}

package/lib/module/features/playback/volume.js

@@ -44,7 +44,7 @@ export function setSystemVolume(level) {
 /**
  * Subscribes to system volume changes.
  * @param callback - Called when the system volume changes
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onSystemVolumeChanged = NativeUpdatedValue.emitterize(cb => nativeBrowser.onSystemVolumeChanged = cb);
 

package/lib/module/features/player/options.js

@@ -3,6 +3,7 @@
 import { nativeBrowser } from '../../native';
 import { NativeUpdatedValue } from '../../utils/NativeUpdatedValue';
 import { useNativeUpdatedValue } from '../../utils/useNativeUpdatedValue';
+import { validateIOSUpdateOptions } from './validateOptions';
 
 // MARK: - Types
 
@@ -24,34 +25,64 @@ import { useNativeUpdatedValue } from '../../utils/useNativeUpdatedValue';
  */
 
 /**
- * Buttons that can be assigned to Android notification button slots.
- * These represent the interactive buttons users can tap in the notification.
+ * Buttons that can be placed in the Android button layout — the interactive
+ * controls a listener taps in the notification, on the Android Auto Now Playing
+ * screen, and in the Android 13+ system media controls.
  */
 
 /**
- * Configuration for notification button layout on Android.
- * Allows explicit control over which buttons appear in which slots.
+ * Where each button sits on Android.
  *
- * Slot behavior:
- * - **Omit a slot**: Derive from capabilities (smart default)
- * - **Set to null**: Explicitly empty slot
- * - **Set to button**: Show that button in that slot
+ * Android offers exactly three positions, and play/pause always occupies the
+ * centre — you cannot move it, and you cannot put two buttons on the same side
+ * of it:
+ *
+ * ```
+ *   back  │  ▶ play/pause  │  forward        overflow ⋯
+ * ```
+ *
+ * - **`back`** — the single position left of play/pause
+ * - **`forward`** — the single position right of play/pause
+ * - **`overflow`** — everything else, in priority order
+ *
+ * **A layout describes the whole arrangement.** All three fields are required —
+ * there is no per-field merge with the capability defaults, so what you write is
+ * exactly what renders. Use `undefined` for an empty position and `[]` for no
+ * overflow. To go back to the derived defaults, omit `remoteButtonLayout`
+ * entirely (or set it to `null`); that is the only switch.
+ *
+ * **Overflow order is priority, not coordinates.** Each surface renders as many
+ * buttons as it has room for, taking them from the front — a phone
+ * notification, the Android 13+ system media controls, and a car head unit all
+ * have different budgets. A head unit with a spare slot may promote the first
+ * overflow entry onto the main row, and a long list gets truncated by whichever
+ * surface is showing it. Put what matters most first.
+ *
+ * Placement never changes what a control *can* do: a button left out entirely
+ * still responds to a Bluetooth remote or headset, as long as its
+ * {@link PlayerCapabilities} entry is enabled.
  *
  * @example
  * ```typescript
- * // Podcast-style: jump buttons as primary
- * notificationButtons: {
+ * // Podcast-style: jump either side of play/pause
+ * remoteButtonLayout: {
  *   back: 'jump-backward',
  *   forward: 'jump-forward',
- *   overflow: ['favorite']
+ *   overflow: ['skip-to-previous', 'skip-to-next', 'favorite']
  * }
  *
- * // Music-style: skip as primary, jump as secondary
- * notificationButtons: {
+ * // Music-style: skip either side of play/pause
+ * remoteButtonLayout: {
  *   back: 'skip-to-previous',
  *   forward: 'skip-to-next',
- *   backSecondary: 'jump-backward',
- *   forwardSecondary: 'jump-forward'
+ *   overflow: ['favorite']
+ * }
+ *
+ * // Live radio: forward only, nothing to the left
+ * remoteButtonLayout: {
+ *   back: undefined,
+ *   forward: 'skip-to-next',
+ *   overflow: []
  * }
  * ```
  */
@@ -135,22 +166,6 @@ import { useNativeUpdatedValue } from '../../utils/useNativeUpdatedValue';
 
 // MARK: - Functions
 
-const MAX_CARPLAY_NOW_PLAYING_BUTTONS = 5;
-
-/**
- * Warns when more CarPlay now-playing buttons are configured than CarPlay renders.
- * Shared by {@link updateOptions} and `setupPlayer` (both can carry `ios` options).
- *
- * @internal Validation helper, not public API — `stripInternal` removes it from
- * the published types and typedoc hides it from the docs.
- */
-export function validateIOSUpdateOptions(ios) {
-  const buttons = ios?.carPlayNowPlayingButtons;
-  if (buttons && buttons.length > MAX_CARPLAY_NOW_PLAYING_BUTTONS) {
-    console.warn(`[react-native-audio-browser] ${buttons.length} CarPlay now-playing ` + `buttons configured; CarPlay shows at most ${MAX_CARPLAY_NOW_PLAYING_BUTTONS}.`);
-  }
-}
-
 /**
  * Updates the configuration for the components.
  * Pass only the properties you want to change - all properties are optional.
@@ -195,7 +210,7 @@ export function getOptions() {
 /**
  * Subscribes to player options changes.
  * @param callback - Called when the player options change
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onOptionsChanged = NativeUpdatedValue.emitterize(cb => nativeBrowser.onOptionsChanged = cb);
 

package/lib/module/features/player/options.js.map

@@ -1 +1 @@
-{"version":3,"names":["nativeBrowser","NativeUpdatedValue","useNativeUpdatedValue","MAX_CARPLAY_NOW_PLAYING_BUTTONS","validateIOSUpdateOptions","ios","buttons","carPlayNowPlayingButtons","length","console","warn","updateOptions","options","getOptions","onOptionsChanged","emitterize","cb","useOptions"],"sourceRoot":"../../../../src","sources":["features/player/options.ts"],"mappings":";;AAEA,SAASA,aAAa,QAAQ,cAAc;AAC5C,SAASC,kBAAkB,QAAQ,gCAAgC;AACnE,SAASC,qBAAqB,QAAQ,mCAAmC;;AAEzE;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AA+FA;AACA;AACA;AACA;;AAQA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAcA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAMA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAkCA;AACA;AACA;AACA;;AA4EA;AACA;AACA;AACA;;AAOA;AACA;AACA;AACA;;AA6BA;AACA;AACA;AACA;;AAOA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AA6CA;AACA;AACA;AACA;;AA8BA;;AAEA,MAAMC,+BAA+B,GAAG,CAAC;;AAEzC;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,wBAAwBA,CAACC,GAAsB,EAAQ;EACrE,MAAMC,OAAO,GAAGD,GAAG,EAAEE,wBAAwB;EAC7C,IAAID,OAAO,IAAIA,OAAO,CAACE,MAAM,GAAGL,+BAA+B,EAAE;IAC/DM,OAAO,CAACC,IAAI,CACV,gCAAgCJ,OAAO,CAACE,MAAM,uBAAuB,GACnE,6CAA6CL,+BAA+B,GAChF,CAAC;EACH;AACF;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASQ,aAAaA,CAACC,OAAsB,EAAQ;EAC1DR,wBAAwB,CAACQ,OAAO,CAACP,GAAG,CAAC;EACrCL,aAAa,CAACW,aAAa,CAACC,OAAO,CAAC;AACtC;;AAEA;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,UAAUA,CAAA,EAAY;EACpC,OAAOb,aAAa,CAACa,UAAU,CAAC,CAAC;AACnC;;AAEA;;AAEA;AACA;AACA;AACA;AACA;AACA,OAAO,MAAMC,gBAAgB,GAAGb,kBAAkB,CAACc,UAAU,CAC1DC,EAAE,IAAMhB,aAAa,CAACc,gBAAgB,GAAGE,EAC5C,CAAC;;AAED;;AAEA;AACA;AACA;AACA;AACA,OAAO,SAASC,UAAUA,CAAA,EAAY;EACpC,OAAOf,qBAAqB,CAACW,UAAU,EAAEC,gBAAgB,CAAC;AAC5D","ignoreList":[]}
+{"version":3,"names":["nativeBrowser","NativeUpdatedValue","useNativeUpdatedValue","validateIOSUpdateOptions","updateOptions","options","ios","getOptions","onOptionsChanged","emitterize","cb","useOptions"],"sourceRoot":"../../../../src","sources":["features/player/options.ts"],"mappings":";;AAIA,SAASA,aAAa,QAAQ,cAAc;AAC5C,SAASC,kBAAkB,QAAQ,gCAAgC;AACnE,SAASC,qBAAqB,QAAQ,mCAAmC;AACzE,SAASC,wBAAwB,QAAQ,mBAAmB;;AAE5D;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAuFA;AACA;AACA;AACA;AACA;;AAQA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAaA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAMA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AA4CA;AACA;AACA;AACA;;AAmFA;AACA;AACA;AACA;;AAOA;AACA;AACA;AACA;;AAoCA;AACA;AACA;AACA;;AAQA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAuDA;AACA;AACA;AACA;;AAwCA;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,aAAaA,CAACC,OAAsB,EAAQ;EAC1DF,wBAAwB,CAACE,OAAO,CAACC,GAAG,CAAC;EACrCN,aAAa,CAACI,aAAa,CAACC,OAAO,CAAC;AACtC;;AAEA;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASE,UAAUA,CAAA,EAAY;EACpC,OAAOP,aAAa,CAACO,UAAU,CAAC,CAAC;AACnC;;AAEA;;AAEA;AACA;AACA;AACA;AACA;AACA,OAAO,MAAMC,gBAAgB,GAAGP,kBAAkB,CAACQ,UAAU,CAC1DC,EAAE,IAAMV,aAAa,CAACQ,gBAAgB,GAAGE,EAC5C,CAAC;;AAED;;AAEA;AACA;AACA;AACA;AACA,OAAO,SAASC,UAAUA,CAAA,EAAY;EACpC,OAAOT,qBAAqB,CAACK,UAAU,EAAEC,gBAAgB,CAAC;AAC5D","ignoreList":[]}