react-native-audio-browser 0.1.1 → 0.2.0-next.10

package/lib/module/web/player/RemoteCommandController.js

@@ -0,0 +1,92 @@
+"use strict";
+
+import { MediaSessionManager } from './MediaSessionManager';
+
+/**
+ * The slice of the player the remote-command bridge drives. Picked straight from
+ * the spec so the contract can never drift from the real surface.
+ */
+
+/**
+ * Bridges the OS media controls (lockscreen / notification / hardware media
+ * keys, via the browser Media Session API) to the player:
+ *
+ *  - mirrors now-playing metadata, playback state and scrubber position *out*, and
+ *  - routes incoming commands *in* — preferring a consumer-provided handler,
+ *    otherwise running the default transport action, then always emitting the
+ *    observation event. This matches the native HybridAudioBrowser/AudioBrowser
+ *    contract exactly.
+ *
+ * A no-op when the Media Session API is unavailable (handled by the underlying
+ * {@link MediaSessionManager}).
+ */
+export class RemoteCommandController {
+  constructor(host) {
+    this.host = host;
+    // Handlers are read live (inside each arrow) so consumers can assign them
+    // after construction and still be honoured.
+    this.mediaSession = new MediaSessionManager({
+      play: () => this.run(host.handleRemotePlay, undefined, () => host.play(), () => host.onRemotePlay()),
+      pause: () => this.run(host.handleRemotePause, undefined, () => host.pause(), () => host.onRemotePause()),
+      stop: () => this.run(host.handleRemoteStop, undefined, () => host.stop(), () => host.onRemoteStop()),
+      next: () => this.run(host.handleRemoteNext, undefined, () => host.skipToNext(), () => host.onRemoteNext()),
+      previous: () => this.run(host.handleRemotePrevious, undefined, () => host.skipToPrevious(), () => host.onRemotePrevious()),
+      seek: position => this.run(host.handleRemoteSeek, {
+        position
+      }, () => host.seekTo(position), event => host.onRemoteSeek(event)),
+      jumpForward: interval => this.run(host.handleRemoteJumpForward, {
+        interval
+      }, () => host.seekBy(interval), event => host.onRemoteJumpForward(event)),
+      jumpBackward: interval => this.run(host.handleRemoteJumpBackward, {
+        interval
+      }, () => host.seekBy(-interval), event => host.onRemoteJumpBackward(event))
+    });
+  }
+
+  /** Publishes now-playing metadata to the OS media controls. */
+  setMetadata(metadata) {
+    this.mediaSession.setMetadata(metadata);
+  }
+
+  /** Reflects the current playing/paused/stopped state in the OS controls. */
+  syncPlaybackState() {
+    const playback = this.host.getPlayback();
+    if (playback.state === 'none') {
+      this.mediaSession.setPlaybackState('none');
+    } else if (this.host.getPlayingState().playing) {
+      this.mediaSession.setPlaybackState('playing');
+    } else {
+      this.mediaSession.setPlaybackState('paused');
+    }
+  }
+
+  /** Pushes the latest scrubber position to the OS controls. */
+  updateProgress() {
+    const {
+      duration,
+      position
+    } = this.host.getProgress();
+    // The web player has no variable-rate playback, so the rate is always 1.
+    // (Live radio has no seekable timeline anyway — the position is cleared.)
+    this.mediaSession.setPositionState({
+      duration,
+      position,
+      playbackRate: 1
+    });
+  }
+
+  /** Removes handlers and clears metadata/state. Call on teardown. */
+  dispose() {
+    this.mediaSession.dispose();
+  }
+
+  /**
+   * The remote-command contract: run the consumer handler if present, otherwise
+   * the default transport action, then always emit the observation event.
+   */
+  run(handler, event, fallback, emit) {
+    if (handler) handler(event);else fallback();
+    emit(event);
+  }
+}
+//# sourceMappingURL=RemoteCommandController.js.map

package/lib/module/web/player/RemoteCommandController.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["MediaSessionManager","RemoteCommandController","constructor","host","mediaSession","play","run","handleRemotePlay","undefined","onRemotePlay","pause","handleRemotePause","onRemotePause","stop","handleRemoteStop","onRemoteStop","next","handleRemoteNext","skipToNext","onRemoteNext","previous","handleRemotePrevious","skipToPrevious","onRemotePrevious","seek","position","handleRemoteSeek","seekTo","event","onRemoteSeek","jumpForward","interval","handleRemoteJumpForward","seekBy","onRemoteJumpForward","jumpBackward","handleRemoteJumpBackward","onRemoteJumpBackward","setMetadata","metadata","syncPlaybackState","playback","getPlayback","state","setPlaybackState","getPlayingState","playing","updateProgress","duration","getProgress","setPositionState","playbackRate","dispose","handler","fallback","emit"],"sourceRoot":"../../../../src","sources":["web/player/RemoteCommandController.ts"],"mappings":"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","ignoreList":[]}

package/lib/typescript/src/AudioBrowser.d.ts

@@ -1,5 +1,4 @@
 export * from './features';
-export * from './native';
 export * from './types';
 export * from './utils/useDebug';
 //# sourceMappingURL=AudioBrowser.d.ts.map

package/lib/typescript/src/AudioBrowser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AudioBrowser.d.ts","sourceRoot":"","sources":["../../../src/AudioBrowser.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAA;AAC1B,cAAc,UAAU,CAAA;AACxB,cAAc,SAAS,CAAA;AACvB,cAAc,kBAAkB,CAAA"}
+{"version":3,"file":"AudioBrowser.d.ts","sourceRoot":"","sources":["../../../src/AudioBrowser.ts"],"names":[],"mappings":"AACA,cAAc,YAAY,CAAA;AAC1B,cAAc,SAAS,CAAA;AACvB,cAAc,kBAAkB,CAAA"}

package/lib/typescript/src/features/browser-config.d.ts

@@ -0,0 +1,12 @@
+import type { BrowserConfiguration } from '../types';
+import type { NativeBrowserConfiguration } from '../types/browser-native';
+export declare const SEARCH_ROUTE_PATH = "__search__";
+/**
+ * Dev-only sanity checks for a BrowserConfiguration. Warns (never throws) on
+ * mistakes the type system cannot catch: reserved route keys, route values
+ * that match no source shape (and would be served as garbage static content),
+ * and platform display limits. Called by configureBrowser under __DEV__.
+ */
+export declare function validateBrowserConfiguration(config: BrowserConfiguration): void;
+export declare function toNativeConfig(config: BrowserConfiguration): NativeBrowserConfiguration;
+//# sourceMappingURL=browser-config.d.ts.map

package/lib/typescript/src/features/browser-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-config.d.ts","sourceRoot":"","sources":["../../../../src/features/browser-config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,oBAAoB,EAWrB,MAAM,UAAU,CAAA;AACjB,OAAO,KAAK,EACV,0BAA0B,EAE3B,MAAM,yBAAyB,CAAA;AAwKhC,eAAO,MAAM,iBAAiB,eAAe,CAAA;AAqC7C;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAC1C,MAAM,EAAE,oBAAoB,GAC3B,IAAI,CAuCN;AAED,wBAAgB,cAAc,CAC5B,MAAM,EAAE,oBAAoB,GAC3B,0BAA0B,CAoB5B"}

package/lib/typescript/src/features/browser.d.ts

@@ -7,13 +7,30 @@ import { NativeUpdatedValue } from '../utils/NativeUpdatedValue';
  * - Android Auto / CarPlay browsing integration
  * - Playback of browsable tracks via navigate()
  *
+ * Calling this again REPLACES the entire configuration (no merging) and
+ * re-runs initial navigation — external browse UIs such as CarPlay reset to
+ * the first tab. For values that change at runtime (base URL, locale, auth
+ * token), don't reconfigure: read them inside a `request`/`browse` resolver
+ * or a `transform`, and call {@link invalidateAllContent} so every surface
+ * re-fetches in place.
+ *
  * @param configuration - Browser configuration including routes, tabs, media config, etc.
  *
  * @example
  * ```ts
  * configureBrowser({
+ *   request: { baseUrl: 'https://api.example.com' },
  *   routes: {
- *     '/albums/:id': { path: '/api/albums/:id' }
+ *     // `{id}` is a route parameter — see the `routes` docs for matching rules.
+ *     '/albums/{id}': async ({ routeParams }) => fetchAlbumPage(routeParams?.id),
+ *     // Remapping a browse path to a different API path requires a transform;
+ *     // a static `path` on a request config does NOT rewrite the path.
+ *     '/artists/{id}': {
+ *       transformSync: (request, routeParams) => ({
+ *         ...request,
+ *         path: `/api/v2/artists/${routeParams?.id}`
+ *       })
+ *     }
  *   },
  *   tabs: [
  *     { title: 'Home', url: '/' },
@@ -23,6 +40,15 @@ import { NativeUpdatedValue } from '../utils/NativeUpdatedValue';
  * ```
  */
 export declare function configureBrowser(configuration: BrowserConfiguration): void;
+/**
+ * Returns the configuration last passed to {@link configureBrowser}, in its
+ * original public shape (the native getter exposes only the lowered internal
+ * form). `undefined` until the browser is configured.
+ *
+ * Treat the returned object as read-only: it is the live reference, and
+ * mutating it does NOT reconfigure the browser — call configureBrowser again.
+ */
+export declare function getBrowserConfiguration(): BrowserConfiguration | undefined;
 export declare function navigate(pathOrTrack: string | Track): void;
 export declare function getPath(): string | undefined;
 export declare const onPathChanged: NativeUpdatedValue<string | undefined>;
@@ -46,6 +72,19 @@ export declare function useTabs(): Track[] | undefined;
  * ```
  */
 export declare const notifyContentChanged: (path: string) => void;
+/**
+ * Invalidates all cached browse content and refreshes every currently-displayed
+ * browse surface. Use when something app-wide changed (locale switch, sign-out,
+ * etc.) and every browse path should re-fetch from its route handler — unlike
+ * {@link notifyContentChanged}, which targets a single path.
+ *
+ * @example
+ * ```ts
+ * // After the user changes the app language
+ * invalidateAllContent()
+ * ```
+ */
+export declare const invalidateAllContent: () => void;
 /**
  * Returns whether search functionality is configured via `configureBrowser({ search: ... })`.
  */

package/lib/typescript/src/features/browser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../../../../src/features/browser.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,oBAAoB,EAGpB,aAAa,EAKb,KAAK,EAEN,MAAM,UAAU,CAAA;AAMjB,OAAO,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAA;AA4LhE;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,gBAAgB,CAAC,aAAa,EAAE,oBAAoB,GAAG,IAAI,CAE1E;AAED,wBAAgB,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,KAAK,QAMnD;AAED,wBAAgB,OAAO,uBAEtB;AAED,eAAO,MAAM,aAAa,wCAEzB,CAAA;AAED,wBAAgB,OAAO,IAAI,MAAM,GAAG,SAAS,CAE5C;AAED,wBAAgB,UAAU,IAAI,aAAa,GAAG,SAAS,CAEtD;AAED,eAAO,MAAM,gBAAgB,+CAEmB,CAAA;AAEhD,wBAAgB,UAAU,IAAI,aAAa,GAAG,SAAS,CAEtD;AACD,wBAAgB,OAAO,IAAI,KAAK,EAAE,GAAG,SAAS,CAE7C;AAED,eAAO,MAAM,aAAa,yCAEzB,CAAA;AAED,wBAAgB,OAAO,IAAI,KAAK,EAAE,GAAG,SAAS,CAE7C;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,oBAAoB,GAAI,MAAM,MAAM,KAAG,IAEnD,CAAA;AAED;;GAEG;AACH,wBAAgB,SAAS,IAAI,OAAO,CAInC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,EAAE,CAAC,CAE5D"}
+{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../../../../src/features/browser.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,UAAU,CAAA;AAE1E,OAAO,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAA;AAUhE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,wBAAgB,gBAAgB,CAAC,aAAa,EAAE,oBAAoB,GAAG,IAAI,CAO1E;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,IAAI,oBAAoB,GAAG,SAAS,CAE1E;AAED,wBAAgB,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,KAAK,QAMnD;AAED,wBAAgB,OAAO,uBAEtB;AAED,eAAO,MAAM,aAAa,wCAEzB,CAAA;AAED,wBAAgB,OAAO,IAAI,MAAM,GAAG,SAAS,CAE5C;AAED,wBAAgB,UAAU,IAAI,aAAa,GAAG,SAAS,CAEtD;AAED,eAAO,MAAM,gBAAgB,+CAEmB,CAAA;AAEhD,wBAAgB,UAAU,IAAI,aAAa,GAAG,SAAS,CAEtD;AACD,wBAAgB,OAAO,IAAI,KAAK,EAAE,GAAG,SAAS,CAE7C;AAED,eAAO,MAAM,aAAa,yCAEzB,CAAA;AAED,wBAAgB,OAAO,IAAI,KAAK,EAAE,GAAG,SAAS,CAE7C;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,oBAAoB,SAAU,MAAM,KAAG,IAEnD,CAAA;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,oBAAoB,QAAO,IAEvC,CAAA;AAED;;GAEG;AACH,wBAAgB,SAAS,IAAI,OAAO,CAInC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,EAAE,CAAC,CAE5D"}

package/lib/typescript/src/features/carConnection.d.ts

@@ -0,0 +1,20 @@
+import { NativeUpdatedValue } from '../utils/NativeUpdatedValue';
+/**
+ * Whether a car is currently connected: a CarPlay scene on iOS, an
+ * Android Auto / Android Automotive connection on Android (via the
+ * androidx.car.app CarConnection provider). Always false on web.
+ */
+export declare function isCarConnected(): boolean;
+/**
+ * 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 An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
+ */
+export declare const onCarConnectedChanged: NativeUpdatedValue<boolean>;
+/**
+ * Hook that returns whether a car is connected and updates on changes
+ * (always false on web).
+ */
+export declare function useCarConnected(): boolean;
+//# sourceMappingURL=carConnection.d.ts.map

package/lib/typescript/src/features/carConnection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"carConnection.d.ts","sourceRoot":"","sources":["../../../../src/features/carConnection.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAA;AAKhE;;;;GAIG;AACH,wBAAgB,cAAc,IAAI,OAAO,CAExC;AAID;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,6BAEjC,CAAA;AAID;;;GAGG;AACH,wBAAgB,eAAe,IAAI,OAAO,CAEzC"}

package/lib/typescript/src/features/equalizer.d.ts

@@ -24,7 +24,7 @@ export declare function setEqualizerLevels(levels: number[]): void;
 /**
  * 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 declare const onEqualizerChanged: NativeUpdatedValue<EqualizerSettings>;
 /**

package/lib/typescript/src/features/errors.d.ts

@@ -1,12 +1,63 @@
 import type { FormattedNavigationError } from '../types/browser';
 import { NativeUpdatedValue } from '../utils/NativeUpdatedValue';
 export type { FormattedNavigationError } from '../types/browser';
+/**
+ * Normalized, cross-platform classification of a playback failure.
+ *
+ * Both platforms map their native failure onto this set, so consumers can
+ * branch on it without knowing whether the error came from AVFoundation or
+ * ExoPlayer. Use this — not `code` — for anything user-visible.
+ *
+ * - `'offline'` - The device had no network connection at the moment of
+ *   failure. The stream itself may be fine.
+ * - `'unreachable'` - The stream host could not be reached: DNS failure,
+ *   connection refused, timed out, or the connection dropped while loading.
+ * - `'not-found'` - The server said this stream is gone (HTTP 404 / 410).
+ *   Retrying will not help; the station is dead.
+ * - `'rejected'` - The server refused the request (HTTP 401 / 403), e.g.
+ *   geo-blocking or an expired token.
+ * - `'server-error'` - The server responded with 5xx. Usually transient.
+ * - `'unplayable'` - The stream was fetched but cannot be played: unknown
+ *   container, unsupported codec, or a decoder failure.
+ * - `'stalled'` - Playback had started and then stopped, and the player
+ *   exhausted its recovery budget without recovering.
+ * - `'unknown'` - The failure could not be classified. Inspect `code`.
+ */
+export type PlaybackErrorKind = 'offline' | 'unreachable' | 'not-found' | 'rejected' | 'server-error' | 'unplayable' | 'stalled' | 'unknown';
 export type PlaybackError = {
+    /** Normalized classification. Branch on this, not on `code`. */
+    kind: PlaybackErrorKind;
+    /**
+     * The raw native failure identifier, for diagnostics and telemetry only.
+     * Platform-specific and unstable: loader cases on iOS
+     * (`failed-to-load`, `playback-failed`, …), lower-cased ExoPlayer error
+     * names on Android (`io-bad-http-status`, `parsing-container-malformed`, …).
+     */
     code: string;
     message: string;
+    /** HTTP status code, when the failure came from an HTTP response. */
+    statusCode?: number;
+    /**
+     * True while the player is still retrying this failure in the background.
+     *
+     * A retrying error arrives via `onPlaybackChanged` with the playback state
+     * still `loading`/`buffering` (or `paused`) — show it as advisory ("Stream
+     * unreachable" over a spinner), because playback may yet recover. It clears
+     * (the next `Playback` carries no error) once data flows again, and hardens
+     * into a terminal error (state `error`, `retrying` absent) when the retry
+     * budget runs out. Absent when retry is disabled: every error is then
+     * terminal. Native platforms only — the web implementation has no automatic
+     * retry, so its errors are always terminal.
+     */
+    retrying?: boolean;
 };
 /**
  * Emitted when a playback error occurs.
+ *
+ * Terminal errors only: this fires on both edges of the `error` state —
+ * entering it (with the error) and leaving it (with `error` undefined).
+ * Errors the player is still retrying (`retrying: true`) are surfaced through
+ * `onPlaybackChanged` instead, attached to the `loading`/`buffering` state.
  */
 export interface PlaybackErrorEvent {
     error?: PlaybackError;
@@ -22,8 +73,12 @@ export interface PlaybackErrorEvent {
  * - `'callback-error'` - The browse callback returned an error (e.g., `{ error: 'message' }`).
  *   Use this for business logic errors like authentication failures or subscription requirements.
  * - `'unknown-error'` - An unexpected error occurred (e.g., invalid configuration).
+ * - `'empty-content'` - The path resolved successfully but the container has no children (e.g. an
+ *   empty Favorites tab, a search with no results).
+ * - `'timeout'` - The resolve did not complete within the allotted time (a stalled request or
+ *   unresponsive bridge). Surfaced on External surfaces that render their own browse list.
  */
-export type NavigationErrorType = 'content-not-found' | 'network-error' | 'http-error' | 'callback-error' | 'unknown-error';
+export type NavigationErrorType = 'content-not-found' | 'network-error' | 'http-error' | 'callback-error' | 'unknown-error' | 'empty-content' | 'timeout';
 export type NavigationError = {
     code: NavigationErrorType;
     message: string;
@@ -46,7 +101,7 @@ export declare function getPlaybackError(): PlaybackError | undefined;
 /**
  * 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 declare const onPlaybackError: NativeUpdatedValue<PlaybackErrorEvent>;
 /**
@@ -62,7 +117,7 @@ export declare function getNavigationError(): NavigationError | undefined;
 /**
  * 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 declare const onNavigationError: NativeUpdatedValue<NavigationErrorEvent>;
 /**
@@ -81,14 +136,14 @@ export declare function getFormattedNavigationError(): FormattedNavigationError
 /**
  * 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 declare const onFormattedNavigationError: NativeUpdatedValue<FormattedNavigationError | undefined>;
 /**
  * Hook that returns the current navigation error formatted for display.
  *
  * Native formats the error using the `formatNavigationError` callback configured
- * in {@link BrowserConfiguration}, or falls back to default English messages.
+ * in `BrowserConfiguration`, or falls back to default English messages.
  *
  * The same formatted error is used by CarPlay and Android Auto error dialogs,
  * ensuring consistent error presentation across your app and external controllers.
@@ -129,7 +184,7 @@ export declare const onFormattedNavigationError: NativeUpdatedValue<FormattedNav
  * })
  * ```
  *
- * @see {@link BrowserConfiguration.formatNavigationError} - Configure custom error formatting
+ * @see `BrowserConfiguration.formatNavigationError` - Configure custom error formatting
  * @see {@link useNavigationError} - Access the raw error with code and status details
  */
 export declare function useFormattedNavigationError(): FormattedNavigationError | undefined;

package/lib/typescript/src/features/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../../src/features/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,kBAAkB,CAAA;AAEhE,OAAO,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAA;AAIhE,YAAY,EAAE,wBAAwB,EAAE,MAAM,kBAAkB,CAAA;AAEhE,MAAM,MAAM,aAAa,GAAG;IAC1B,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;CAChB,CAAA;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,KAAK,CAAC,EAAE,aAAa,CAAA;CACtB;AAED;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,mBAAmB,GAC3B,mBAAmB,GACnB,eAAe,GACf,YAAY,GACZ,gBAAgB,GAChB,eAAe,CAAA;AAEnB,MAAM,MAAM,eAAe,GAAG;IAC5B,IAAI,EAAE,mBAAmB,CAAA;IACzB,OAAO,EAAE,MAAM,CAAA;IACf,iDAAiD;IACjD,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,+FAA+F;IAC/F,iBAAiB,CAAC,EAAE,OAAO,CAAA;CAC5B,CAAA;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,KAAK,CAAC,EAAE,eAAe,CAAA;CACxB;AAID;;;GAGG;AACH,wBAAgB,gBAAgB,IAAI,aAAa,GAAG,SAAS,CAE5D;AAID;;;;GAIG;AACH,eAAO,MAAM,eAAe,wCAGzB,CAAA;AAIH;;;GAGG;AACH,wBAAgB,gBAAgB,IAAI,aAAa,GAAG,SAAS,CAE5D;AAID;;;GAGG;AACH,wBAAgB,kBAAkB,IAAI,eAAe,GAAG,SAAS,CAGhE;AAED;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,0CAG3B,CAAA;AAEH;;;GAGG;AACH,wBAAgB,kBAAkB,IAAI,eAAe,GAAG,SAAS,CAEhE;AAID;;;;;;GAMG;AACH,wBAAgB,2BAA2B,IACvC,wBAAwB,GACxB,SAAS,CAEZ;AAED;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,0DAEmB,CAAA;AAE1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,wBAAgB,2BAA2B,IACvC,wBAAwB,GACxB,SAAS,CAKZ"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../../src/features/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,kBAAkB,CAAA;AAEhE,OAAO,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAA;AAIhE,YAAY,EAAE,wBAAwB,EAAE,MAAM,kBAAkB,CAAA;AAEhE;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,MAAM,iBAAiB,GACzB,SAAS,GACT,aAAa,GACb,WAAW,GACX,UAAU,GACV,cAAc,GACd,YAAY,GACZ,SAAS,GACT,SAAS,CAAA;AAEb,MAAM,MAAM,aAAa,GAAG;IAC1B,gEAAgE;IAChE,IAAI,EAAE,iBAAiB,CAAA;IACvB;;;;;OAKG;IACH,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;IACf,qEAAqE;IACrE,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB,CAAA;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,kBAAkB;IACjC,KAAK,CAAC,EAAE,aAAa,CAAA;CACtB;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,mBAAmB,GAC3B,mBAAmB,GACnB,eAAe,GACf,YAAY,GACZ,gBAAgB,GAChB,eAAe,GACf,eAAe,GACf,SAAS,CAAA;AAEb,MAAM,MAAM,eAAe,GAAG;IAC5B,IAAI,EAAE,mBAAmB,CAAA;IACzB,OAAO,EAAE,MAAM,CAAA;IACf,iDAAiD;IACjD,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,+FAA+F;IAC/F,iBAAiB,CAAC,EAAE,OAAO,CAAA;CAC5B,CAAA;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,KAAK,CAAC,EAAE,eAAe,CAAA;CACxB;AAID;;;GAGG;AACH,wBAAgB,gBAAgB,IAAI,aAAa,GAAG,SAAS,CAE5D;AAID;;;;GAIG;AACH,eAAO,MAAM,eAAe,wCAGzB,CAAA;AAIH;;;GAGG;AACH,wBAAgB,gBAAgB,IAAI,aAAa,GAAG,SAAS,CAE5D;AAID;;;GAGG;AACH,wBAAgB,kBAAkB,IAAI,eAAe,GAAG,SAAS,CAGhE;AAED;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,0CAG3B,CAAA;AAEH;;;GAGG;AACH,wBAAgB,kBAAkB,IAAI,eAAe,GAAG,SAAS,CAEhE;AAID;;;;;;GAMG;AACH,wBAAgB,2BAA2B,IACvC,wBAAwB,GACxB,SAAS,CAEZ;AAED;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,0DAEmB,CAAA;AAE1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,wBAAgB,2BAA2B,IACvC,wBAAwB,GACxB,SAAS,CAKZ"}

package/lib/typescript/src/features/favorites.d.ts

@@ -66,7 +66,7 @@ export interface FavoriteChangedEvent {
  * 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/typescript/src/features/gate.d.ts

@@ -0,0 +1,93 @@
+import type { SearchParams } from '../types/browser';
+import { LazyNativeEmitter } from '../utils/LazyNativeEmitter';
+/** Discriminant for gate requests and events. */
+export type GateReason = 'browse' | 'search';
+/**
+ * Fired once per gated serve (each time the gate chrome is rendered for a
+ * request). This is **not** once per user action: on car surfaces a single
+ * action can serve the gate for several requests at once — e.g. building the
+ * tab bar resolves and serves each gated tab, firing one event per gated tab.
+ * There is no library-side dedup; debounce on the consumer side (e.g. record a
+ * gate-hit at most once per session).
+ */
+export type GateEvent = {
+    reason: GateReason;
+};
+/**
+ * A gate's chrome (title and optional message).
+ *
+ * While the gate is active, every browse or search request on car surfaces
+ * (CarPlay, Android Auto) shows this page instead of the real content.
+ * Playback, the queue, and now-playing are unaffected.
+ *
+ * - **CarPlay**: plain centered message page.
+ * - **Android Auto**: one non-playable list tile (message not shown).
+ */
+export type Gate = {
+    /** Headline shown on the gate page. */
+    title: string;
+    /**
+     * The explanatory copy under the title. On CarPlay this is the centered
+     * message body; newlines become spaces. Android Auto does not display it.
+     */
+    message?: string;
+};
+/**
+ * Describes the request being decided by a {@link GateResolver}.
+ * Discriminated by `kind`: `'browse'` for content navigation, `'search'` for
+ * voice/manual search queries.
+ */
+export type GateRequest = {
+    kind: 'browse';
+    path: string;
+} | {
+    kind: 'search';
+    params: SearchParams;
+};
+/**
+ * Decides per request whether to gate.
+ * - Return a {@link Gate} to gate with specific chrome for this request.
+ * - Return `true` to gate using the default chrome (or the built-in fallback).
+ * - Return `false` to allow the request through.
+ */
+export type GateResolver = (request: GateRequest) => Gate | boolean;
+/**
+ * Raises the gate with default chrome, optionally with a per-request resolver.
+ * Calling it again while a gate is already up updates the chrome in place,
+ * keeping the current tab. Note this is **not** fully navigation-preserving: on
+ * 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.
+ */
+export declare function setGate(gate: Gate, resolve?: GateResolver): void;
+/**
+ * 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 declare function setGate(resolve: GateResolver): void;
+/**
+ * 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 declare function clearGate(): void;
+/**
+ * Subscribes to gate events (fired when a request is gated).
+ *
+ * @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 declare const onGate: LazyNativeEmitter<GateEvent>;
+//# sourceMappingURL=gate.d.ts.map

package/lib/typescript/src/features/gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gate.d.ts","sourceRoot":"","sources":["../../../../src/features/gate.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AAEpD,OAAO,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAA;AAI9D,iDAAiD;AACjD,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,QAAQ,CAAA;AAmB5C;;;;;;;GAOG;AACH,MAAM,MAAM,SAAS,GAAG;IAAE,MAAM,EAAE,UAAU,CAAA;CAAE,CAAA;AAI9C;;;;;;;;;GASG;AACH,MAAM,MAAM,IAAI,GAAG;IACjB,uCAAuC;IACvC,KAAK,EAAE,MAAM,CAAA;IACb;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB,CAAA;AAQD;;;;GAIG;AACH,MAAM,MAAM,WAAW,GACnB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAChC;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,YAAY,CAAA;CAAE,CAAA;AAE5C;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,EAAE,WAAW,KAAK,IAAI,GAAG,OAAO,CAAA;AAoCnE;;;;;;;;;;;;GAYG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,IAAI,CAAA;AACjE;;;;;;;GAOG;AACH,wBAAgB,OAAO,CAAC,OAAO,EAAE,YAAY,GAAG,IAAI,CAAA;AAWpD;;;;;GAKG;AACH,wBAAgB,SAAS,IAAI,IAAI,CAGhC;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,MAAM,8BAElB,CAAA"}

package/lib/typescript/src/features/index.d.ts

@@ -11,7 +11,9 @@ export * from './playback';
 export * from './player';
 export * from './queue';
 export * from './battery';
+export * from './gate';
 export * from './browser';
+export * from './carConnection';
 export * from './equalizer';
 export * from './errors';
 export * from './favorites';

package/lib/typescript/src/features/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/features/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,cAAc,UAAU,CAAA;AACxB,cAAc,YAAY,CAAA;AAC1B,cAAc,UAAU,CAAA;AACxB,cAAc,SAAS,CAAA;AACvB,cAAc,WAAW,CAAA;AACzB,cAAc,WAAW,CAAA;AACzB,cAAc,aAAa,CAAA;AAC3B,cAAc,UAAU,CAAA;AACxB,cAAc,aAAa,CAAA;AAC3B,cAAc,YAAY,CAAA;AAC1B,cAAc,WAAW,CAAA;AACzB,cAAc,cAAc,CAAA;AAC5B,cAAc,kBAAkB,CAAA;AAChC,cAAc,cAAc,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/features/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,cAAc,UAAU,CAAA;AACxB,cAAc,YAAY,CAAA;AAC1B,cAAc,UAAU,CAAA;AACxB,cAAc,SAAS,CAAA;AACvB,cAAc,WAAW,CAAA;AACzB,cAAc,QAAQ,CAAA;AACtB,cAAc,WAAW,CAAA;AACzB,cAAc,iBAAiB,CAAA;AAC/B,cAAc,aAAa,CAAA;AAC3B,cAAc,UAAU,CAAA;AACxB,cAAc,aAAa,CAAA;AAC3B,cAAc,YAAY,CAAA;AAC1B,cAAc,WAAW,CAAA;AACzB,cAAc,cAAc,CAAA;AAC5B,cAAc,kBAAkB,CAAA;AAChC,cAAc,cAAc,CAAA"}

package/lib/typescript/src/features/metadata.d.ts

@@ -1,6 +1,4 @@
-import type { Rating } from './rating';
 import { NativeUpdatedValue } from '../utils/NativeUpdatedValue';
-export type RatingType = 'heart' | 'thumbs-up-down' | 'three-stars' | 'four-stars' | 'five-stars' | 'percentage' | 'none';
 export interface TrackMetadataBase {
     /** The track title */
     title?: string;
@@ -18,8 +16,6 @@ export interface TrackMetadataBase {
     mediaId?: string;
     /** The track genre */
     genre?: string;
-    /** The track rating */
-    rating?: Rating;
 }
 export interface NowPlayingMetadata extends TrackMetadataBase {
     elapsedTime?: number;
@@ -34,6 +30,12 @@ export type NowPlayingUpdate = {
     title?: string;
     /** Artist shown in notification */
     artist?: string;
+    /**
+     * Album line, on surfaces that render one (CarPlay's third line, some
+     * Bluetooth head units). Never shown on the iOS lock screen or the Android
+     * notification.
+     */
+    album?: string;
 };
 /**
  * Timed metadata received during playback.
@@ -84,20 +86,37 @@ export interface ChapterMetadata {
 }
 /**
  * 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 declare const onChapterMetadata: NativeUpdatedValue<ChapterMetadata[]>;
 /**
  * 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 declare const onTrackMetadata: NativeUpdatedValue<TrackMetadata>;
 /**
  * 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 declare const onTimedMetadata: NativeUpdatedValue<TimedMetadata>;
 //# sourceMappingURL=metadata.d.ts.map

package/lib/typescript/src/features/metadata.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"metadata.d.ts","sourceRoot":"","sources":["../../../../src/features/metadata.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAA;AAEtC,OAAO,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAA;AAIhE,MAAM,MAAM,UAAU,GAClB,OAAO,GACP,gBAAgB,GAChB,aAAa,GACb,YAAY,GACZ,YAAY,GACZ,YAAY,GACZ,MAAM,CAAA;AAEV,MAAM,WAAW,iBAAiB;IAChC,sBAAsB;IACtB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,sBAAsB;IACtB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,uBAAuB;IACvB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,oCAAoC;IACpC,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,wBAAwB;IACxB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,wBAAwB;IACxB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,oBAAoB;IACpB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,sBAAsB;IACtB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,uBAAuB;IACvB,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,WAAW,kBAAmB,SAAQ,iBAAiB;IAC3D,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,kCAAkC;IAClC,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,mCAAmC;IACnC,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB,CAAA;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,GAAG,CAAC,EAAE,MAAM,CAAA;CACb;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,oCAAoC;IACpC,SAAS,EAAE,MAAM,CAAA;IACjB,kCAAkC;IAClC,OAAO,EAAE,MAAM,CAAA;IACf,oBAAoB;IACpB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,sCAAsC;IACtC,GAAG,CAAC,EAAE,MAAM,CAAA;CACb;AAID;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,uCAEmB,CAAA;AAEjD;;;;GAIG;AACH,eAAO,MAAM,eAAe,mCAE3B,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,eAAe,mCAE3B,CAAA"}
+{"version":3,"file":"metadata.d.ts","sourceRoot":"","sources":["../../../../src/features/metadata.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAA;AAIhE,MAAM,WAAW,iBAAiB;IAChC,sBAAsB;IACtB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,sBAAsB;IACtB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,uBAAuB;IACvB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,oCAAoC;IACpC,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,wBAAwB;IACxB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,wBAAwB;IACxB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,oBAAoB;IACpB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,sBAAsB;IACtB,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,kBAAmB,SAAQ,iBAAiB;IAC3D,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,kCAAkC;IAClC,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,mCAAmC;IACnC,MAAM,CAAC,EAAE,MAAM,CAAA;IACf;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;CACf,CAAA;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,GAAG,CAAC,EAAE,MAAM,CAAA;CACb;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,oCAAoC;IACpC,SAAS,EAAE,MAAM,CAAA;IACjB,kCAAkC;IAClC,OAAO,EAAE,MAAM,CAAA;IACf,oBAAoB;IACpB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,sCAAsC;IACtC,GAAG,CAAC,EAAE,MAAM,CAAA;CACb;AAID;;;;;;;;;GASG;AACH,eAAO,MAAM,iBAAiB,uCAEmB,CAAA;AAEjD;;;;;;;;;GASG;AACH,eAAO,MAAM,eAAe,mCAE3B,CAAA;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,eAAe,mCAE3B,CAAA"}

package/lib/typescript/src/features/network.d.ts

@@ -7,7 +7,7 @@ export declare function getOnline(): boolean;
 /**
  * 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 declare const onOnlineChanged: NativeUpdatedValue<boolean>;
 /**

package/lib/typescript/src/features/nowPlaying.d.ts

@@ -21,11 +21,38 @@ export declare function updateNowPlaying(update: NowPlayingUpdate | null): void;
  * Gets the current now playing metadata (override if set, else track metadata).
  */
 export declare function getNowPlaying(): NowPlayingMetadata | undefined;
+/**
+ * Temporarily replaces now-playing fields for `durationMs`, then reverts to
+ * the live metadata. The flash outranks the now-playing formatter and the
+ * `updateNowPlaying` override while active (live metadata can't stomp it),
+ * and the revert runs on a native timer — JS timers pause in a backgrounded
+ * host (the lock screen case) — so it fires reliably. A track change clears
+ * the flash early; repeated calls restart the window.
+ *
+ * The feedback channel for refused remote commands: external surfaces have
+ * no toast primitive, so a transient metadata swap is the only way to talk
+ * to the user there.
+ *
+ * @example
+ * ```ts
+ * // A radio product with an hourly skip allowance:
+ * handleRemoteNext(() => {
+ *   if (skipsRemaining() > 0) skipToNext()
+ *   else flashNowPlaying({ artist: 'Skip limit reached' }, 3000)
+ * })
+ * ```
+ */
+export declare function flashNowPlaying(update: NowPlayingUpdate, durationMs: number): void;
+/**
+ * Clears an active flash immediately, reverting to the live metadata.
+ * No-op when no flash is active.
+ */
+export declare function clearNowPlayingFlash(): void;
 /**
  * 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 declare const onNowPlayingChanged: NativeUpdatedValue<NowPlayingMetadata>;
 /**

package/lib/typescript/src/features/nowPlaying.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"nowPlaying.d.ts","sourceRoot":"","sources":["../../../../src/features/nowPlaying.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAEtE,OAAO,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAA;AAKhE;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,gBAAgB,GAAG,IAAI,GAAG,IAAI,CAEtE;AAED;;GAEG;AACH,wBAAgB,aAAa,IAAI,kBAAkB,GAAG,SAAS,CAE9D;AAID;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,wCAG7B,CAAA;AAIH;;;GAGG;AACH,wBAAgB,aAAa,IAAI,kBAAkB,GAAG,SAAS,CAE9D"}
+{"version":3,"file":"nowPlaying.d.ts","sourceRoot":"","sources":["../../../../src/features/nowPlaying.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAEtE,OAAO,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAA;AAKhE;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,gBAAgB,GAAG,IAAI,GAAG,IAAI,CAEtE;AAED;;GAEG;AACH,wBAAgB,aAAa,IAAI,kBAAkB,GAAG,SAAS,CAE9D;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,gBAAgB,EACxB,UAAU,EAAE,MAAM,GACjB,IAAI,CAEN;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,IAAI,IAAI,CAE3C;AAID;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,wCAG7B,CAAA;AAIH;;;GAGG;AACH,wBAAgB,aAAa,IAAI,kBAAkB,GAAG,SAAS,CAE9D"}