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

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/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 Cleanup function to unsubscribe
+ */
+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/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;
@@ -88,7 +143,7 @@ export declare const onFormattedNavigationError: NativeUpdatedValue<FormattedNav
  * 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/gate.d.ts

@@ -0,0 +1,77 @@
+import type { SearchParams } from '../types/browser';
+/** 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.
+ */
+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.
+ */
+export declare function setGate(resolve: GateResolver): void;
+/**
+ * Drops the gate — the real content comes back, and the current tab is kept.
+ */
+export declare function clearGate(): void;
+/**
+ * Subscribes to gate events (fired when a request is gated).
+ * @returns Cleanup function to unsubscribe.
+ */
+export declare const onGate: (callback: (arg: GateEvent) => void) => () => void;
+//# 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;AAMpD,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;;;;;;;GAOG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,IAAI,CAAA;AACjE;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,OAAO,EAAE,YAAY,GAAG,IAAI,CAAA;AAWpD;;GAEG;AACH,wBAAgB,SAAS,IAAI,IAAI,CAGhC;AAED;;;GAGG;AACH,eAAO,MAAM,MAAM,oDAElB,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.

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;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,uCAEmB,CAAA;AAEjD;;;;GAIG;AACH,eAAO,MAAM,eAAe,mCAE3B,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,eAAe,mCAE3B,CAAA"}

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

@@ -21,6 +21,33 @@ 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.

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

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

@@ -1,28 +1,38 @@
-import type { IosOutput, IosOutputType } from '../specs/audio-browser.nitro';
+import type { Output, OutputType } from '../specs/audio-browser.nitro';
 import { NativeUpdatedValue } from '../utils/NativeUpdatedValue';
-export type { IosOutput, IosOutputType };
+export type { Output, OutputType };
 /**
- * Opens the system output picker (iOS only).
- * Allows users to select output device (speaker, AirPlay, Bluetooth, etc.).
- * No-op on Android.
+ * Presents the system audio output switcher so the listener can move playback to
+ * another output. Cross-platform:
+ * - **iOS** — the system route picker (Bluetooth, AirPlay / Sonos-via-AirPlay,
+ *   speaker). Always available.
+ * - **Android** — the system Output Switcher (Bluetooth / speaker / Cast list) on
+ *   Android 11+. No-op on older Android — gate on {@link supportsOutputSwitcher}.
+ * - **Web** — no-op.
  */
-export declare function openIosOutputPicker(): void;
+export declare function openOutputPicker(): void;
 /**
- * Gets the current audio output info.
- * Always returns a value on iOS, undefined on Android.
+ * Whether {@link openOutputPicker} can present a switcher on this device — use it
+ * to decide whether to surface the output control in your UI.
+ * `true` on iOS and Android 11+ (API 30); `false` on older Android and web.
  */
-export declare function getIosOutput(): IosOutput | undefined;
+export declare function supportsOutputSwitcher(): boolean;
 /**
- * Subscribes to output state changes (iOS only).
- * Never fires on Android.
- * @param callback - Called with output info when output changes
- * @returns Cleanup function to unsubscribe
+ * The current audio output, or `undefined` when unknown. iOS reports one while a
+ * session is active; Android reports the active output route via AudioManager
+ * (the `type` is coarse — e.g. wired headphones may report as `speaker`). Guard
+ * for `undefined`.
  */
-export declare const onIosOutputChanged: NativeUpdatedValue<IosOutput>;
+export declare function getOutput(): Output | undefined;
 /**
- * Hook that returns the current audio output info.
- * Updates when the output changes (e.g., AirPods connected/disconnected).
- * Always returns a value on iOS, undefined on Android.
+ * 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.
  */
-export declare function useIosOutput(): IosOutput | undefined;
+export declare const onOutputChanged: NativeUpdatedValue<Output>;
+/**
+ * Reactive current audio output; re-renders when it changes (e.g. AirPods
+ * connect, a Bluetooth speaker is selected). `undefined` when unknown.
+ */
+export declare function useOutput(): Output | undefined;
 //# sourceMappingURL=output.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"output.d.ts","sourceRoot":"","sources":["../../../../src/features/output.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAA;AAE5E,OAAO,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAA;AAGhE,YAAY,EAAE,SAAS,EAAE,aAAa,EAAE,CAAA;AAIxC;;;;GAIG;AACH,wBAAgB,mBAAmB,IAAI,IAAI,CAE1C;AAID;;;GAGG;AACH,wBAAgB,YAAY,IAAI,SAAS,GAAG,SAAS,CAEpD;AAID;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,+BAE9B,CAAA;AAID;;;;GAIG;AACH,wBAAgB,YAAY,IAAI,SAAS,GAAG,SAAS,CAEpD"}
+{"version":3,"file":"output.d.ts","sourceRoot":"","sources":["../../../../src/features/output.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,8BAA8B,CAAA;AAEtE,OAAO,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAA;AAGhE,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,CAAA;AAIlC;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,IAAI,IAAI,CAEvC;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,IAAI,OAAO,CAEhD;AAID;;;;;GAKG;AACH,wBAAgB,SAAS,IAAI,MAAM,GAAG,SAAS,CAE9C;AAID;;;;GAIG;AACH,eAAO,MAAM,eAAe,4BAE3B,CAAA;AAID;;;GAGG;AACH,wBAAgB,SAAS,IAAI,MAAM,GAAG,SAAS,CAE9C"}

package/lib/typescript/src/features/playback/controls.d.ts

@@ -32,6 +32,11 @@ export declare function retry(): void;
  * @param position - The position to seek to in seconds.
  */
 export declare function seekTo(position: number): void;
+/**
+ * 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).
+ */
+export declare function seekToLiveEdge(): void;
 /**
  * Seeks by a relative time offset in the current track.
  * @param offset - The time offset to seek by in seconds.

package/lib/typescript/src/features/playback/controls.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"controls.d.ts","sourceRoot":"","sources":["../../../../../src/features/playback/controls.ts"],"names":[],"mappings":"AAIA;;GAEG;AACH,wBAAgB,KAAK,IAAI,IAAI,CAE5B;AAED;;GAEG;AACH,wBAAgB,IAAI,IAAI,IAAI,CAE3B;AAED;;GAEG;AACH,wBAAgB,KAAK,IAAI,IAAI,CAE5B;AAED;;GAEG;AACH,wBAAgB,cAAc,IAAI,IAAI,CAErC;AAED;;;;GAIG;AACH,wBAAgB,IAAI,IAAI,IAAI,CAE3B;AAED;;;;;GAKG;AACH,wBAAgB,KAAK,IAAI,IAAI,CAE5B;AAED;;;GAGG;AACH,wBAAgB,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAE7C;AAED;;;GAGG;AACH,wBAAgB,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAE3C"}
+{"version":3,"file":"controls.d.ts","sourceRoot":"","sources":["../../../../../src/features/playback/controls.ts"],"names":[],"mappings":"AAIA;;GAEG;AACH,wBAAgB,KAAK,IAAI,IAAI,CAE5B;AAED;;GAEG;AACH,wBAAgB,IAAI,IAAI,IAAI,CAE3B;AAED;;GAEG;AACH,wBAAgB,KAAK,IAAI,IAAI,CAE5B;AAED;;GAEG;AACH,wBAAgB,cAAc,IAAI,IAAI,CAErC;AAED;;;;GAIG;AACH,wBAAgB,IAAI,IAAI,IAAI,CAE3B;AAED;;;;;GAKG;AACH,wBAAgB,KAAK,IAAI,IAAI,CAE5B;AAED;;;GAGG;AACH,wBAAgB,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAE7C;AAED;;;GAGG;AACH,wBAAgB,cAAc,IAAI,IAAI,CAErC;AAED;;;GAGG;AACH,wBAAgB,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAE3C"}

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

@@ -3,6 +3,7 @@ export * from './state';
 export * from './playing';
 export * from './playWhenReady';
 export * from './progress';
+export * from './trackPlaybackTime';
 export * from './rate';
 export * from './volume';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/features/playback/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAA;AAC1B,cAAc,SAAS,CAAA;AACvB,cAAc,WAAW,CAAA;AACzB,cAAc,iBAAiB,CAAA;AAC/B,cAAc,YAAY,CAAA;AAC1B,cAAc,QAAQ,CAAA;AACtB,cAAc,UAAU,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/features/playback/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAA;AAC1B,cAAc,SAAS,CAAA;AACvB,cAAc,WAAW,CAAA;AACzB,cAAc,iBAAiB,CAAA;AAC/B,cAAc,YAAY,CAAA;AAC1B,cAAc,qBAAqB,CAAA;AACnC,cAAc,QAAQ,CAAA;AACtB,cAAc,UAAU,CAAA"}

package/lib/typescript/src/features/playback/progress.d.ts

@@ -44,6 +44,9 @@ export declare function useProgress(): Progress;
  *
  * Use this when you need custom polling behavior instead of event-based updates.
  *
+ * Skips updates while the app is backgrounded and refreshes once it becomes
+ * active again.
+ *
  * @param updateInterval - Update interval in milliseconds (default: 1000)
  * @returns The current playback progress
  */

package/lib/typescript/src/features/playback/progress.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"progress.d.ts","sourceRoot":"","sources":["../../../../../src/features/playback/progress.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAA;AAMnE,MAAM,WAAW,QAAQ;IACvB;;QAEI;IACJ,QAAQ,EAAE,MAAM,CAAA;IAChB;;QAEI;IACJ,QAAQ,EAAE,MAAM,CAAA;IAChB;;QAEI;IACJ,QAAQ,EAAE,MAAM,CAAA;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,4BAA6B,SAAQ,QAAQ;IAC5D,8BAA8B;IAC9B,KAAK,EAAE,MAAM,CAAA;CACd;AAID;;;;GAIG;AACH,wBAAgB,WAAW,IAAI,QAAQ,CAEtC;AAID;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,kDAG3B,CAAA;AAIH;;;;;GAKG;AACH,wBAAgB,WAAW,IAAI,QAAQ,CAEtC;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,cAAc,SAAO,GAAG,QAAQ,CA+CjE"}
+{"version":3,"file":"progress.d.ts","sourceRoot":"","sources":["../../../../../src/features/playback/progress.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAA;AAMnE,MAAM,WAAW,QAAQ;IACvB;;QAEI;IACJ,QAAQ,EAAE,MAAM,CAAA;IAChB;;QAEI;IACJ,QAAQ,EAAE,MAAM,CAAA;IAChB;;QAEI;IACJ,QAAQ,EAAE,MAAM,CAAA;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,4BAA6B,SAAQ,QAAQ;IAC5D,8BAA8B;IAC9B,KAAK,EAAE,MAAM,CAAA;CACd;AAID;;;;GAIG;AACH,wBAAgB,WAAW,IAAI,QAAQ,CAEtC;AAID;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,kDAG3B,CAAA;AAIH;;;;;GAKG;AACH,wBAAgB,WAAW,IAAI,QAAQ,CAEtC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,cAAc,SAAO,GAAG,QAAQ,CA8DjE"}