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

package/lib/commonjs/features/browser.js

@@ -4,10 +4,12 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.configureBrowser = configureBrowser;
+exports.getBrowserConfiguration = getBrowserConfiguration;
 exports.getContent = getContent;
 exports.getPath = getPath;
 exports.getTabs = getTabs;
 exports.hasSearch = hasSearch;
+exports.invalidateAllContent = void 0;
 exports.navigate = navigate;
 exports.onTabsChanged = exports.onPathChanged = exports.onContentChanged = exports.notifyContentChanged = void 0;
 exports.search = search;
@@ -17,160 +19,8 @@ exports.useTabs = useTabs;
 var _native = require("../native");
 var _NativeUpdatedValue = require("../utils/NativeUpdatedValue");
 var _useNativeUpdatedValue = require("../utils/useNativeUpdatedValue");
-// ─────────────────────────────────────────────────────────────────────────────
-// Configuration Transformation
-// ─────────────────────────────────────────────────────────────────────────────
-
-function isCallback(source) {
-  return typeof source === 'function';
-}
-function isTransformableRequestConfig(source) {
-  if (typeof source !== 'object' || source === null) return false;
-  const obj = source;
-  // Has request config properties (not a ResolvedTrack which has 'title')
-  return 'baseUrl' in obj || 'path' in obj || 'headers' in obj || 'query' in obj || 'transform' in obj;
-}
-function isRouteConfig(source) {
-  if (typeof source !== 'object' || source === null) return false;
-  const obj = source;
-  // RouteConfig has browse/media/artwork properties at the top level
-  return 'browse' in obj || 'media' in obj && !('baseUrl' in obj);
-}
-function flattenBrowseSource(source) {
-  if (!source) return {};
-  if (isCallback(source)) return {
-    browseCallback: source
-  };
-  if (isTransformableRequestConfig(source)) return {
-    browseConfig: source
-  };
-  return {
-    browseStatic: source
-  };
-}
-
-/**
- * Converts a SearchSource to a NativeRouteEntry for the __search__ path.
- */
-function searchSourceToRouteEntry(source) {
-  if (isCallback(source)) {
-    return {
-      path: SEARCH_ROUTE_PATH,
-      searchCallback: source
-    };
-  }
-  return {
-    path: SEARCH_ROUTE_PATH,
-    searchConfig: source
-  };
-}
-
-/**
- * Wraps a Track[] into a ResolvedTrack for tabs.
- * Tabs are represented as a special route that returns children.
- */
-function wrapTracksAsResolvedTrack(tracks) {
-  return {
-    url: TABS_ROUTE_PATH,
-    title: 'Tabs',
-    children: tracks
-  };
-}
-
-/**
- * Converts a TabsSource to a NativeRouteEntry for the __tabs__ path.
- * Track[] is wrapped in ResolvedTrack, callbacks are wrapped to return ResolvedTrack.
- */
-function tabsSourceToRouteEntry(source) {
-  if (Array.isArray(source)) {
-    // Static Track[] - wrap as ResolvedTrack
-    return {
-      path: TABS_ROUTE_PATH,
-      browseStatic: wrapTracksAsResolvedTrack(source)
-    };
-  }
-  if (isCallback(source)) {
-    // Callback returning Track[] - wrap to return ResolvedTrack
-    const wrappedCallback = async () => {
-      const tracks = await source();
-      return wrapTracksAsResolvedTrack(tracks);
-    };
-    return {
-      path: TABS_ROUTE_PATH,
-      browseCallback: wrappedCallback
-    };
-  }
-
-  // TransformableRequestConfig - native will handle wrapping the response
-  return {
-    path: TABS_ROUTE_PATH,
-    browseConfig: source
-  };
-}
-function flattenRouteEntry(path, source) {
-  if (isRouteConfig(source)) {
-    return {
-      path,
-      ...flattenBrowseSource(source.browse),
-      media: source.media,
-      artwork: source.artwork
-    };
-  }
-  return {
-    path,
-    ...flattenBrowseSource(source)
-  };
-}
-
-/** Internal path used for the default/root browse source */
-const DEFAULT_ROUTE_PATH = '__default__';
-
-/** Internal path used for navigation tabs */
-const TABS_ROUTE_PATH = '__tabs__';
-
-/** Internal path used for search */
-const SEARCH_ROUTE_PATH = '__search__';
-function flattenRoutes(routes, rootBrowse, tabs, search) {
-  const entries = [];
-
-  // Add explicit routes
-  if (routes) {
-    for (const [path, source] of Object.entries(routes)) {
-      entries.push(flattenRouteEntry(path, source));
-    }
-  }
-
-  // Add root browse as default fallback
-  if (rootBrowse) {
-    entries.push(flattenRouteEntry(DEFAULT_ROUTE_PATH, rootBrowse));
-  }
-
-  // Add tabs as special route
-  if (tabs) {
-    entries.push(tabsSourceToRouteEntry(tabs));
-  }
-
-  // Add search as special route
-  if (search) {
-    entries.push(searchSourceToRouteEntry(search));
-  }
-  return entries.length > 0 ? entries : undefined;
-}
-function toNativeConfig(config) {
-  return {
-    path: config.path,
-    request: config.request,
-    media: config.media,
-    artwork: config.artwork,
-    routes: flattenRoutes(config.routes, config.browse, config.tabs, config.search),
-    singleTrack: config.singleTrack,
-    handleTrackLoad: config.handleTrackLoad,
-    androidControllerOfflineError: config.androidControllerOfflineError,
-    carPlayUpNextButton: config.carPlayUpNextButton,
-    carPlayNowPlayingButtons: config.carPlayNowPlayingButtons,
-    formatNavigationError: config.formatNavigationError
-  };
-}
+var _browserConfig = require("./browser-config");
+let currentConfiguration;
 
 /**
  * Configures the browser with routes, tabs, and other settings.
@@ -179,13 +29,30 @@ function toNativeConfig(config) {
  * - 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: '/' },
@@ -195,7 +62,24 @@ function toNativeConfig(config) {
  * ```
  */
 function configureBrowser(configuration) {
-  _native.nativeBrowser.configuration = toNativeConfig(configuration);
+  // __DEV__ is a React Native global; absent under plain node (vitest).
+  if (typeof __DEV__ !== 'undefined' && __DEV__) {
+    (0, _browserConfig.validateBrowserConfiguration)(configuration);
+  }
+  currentConfiguration = configuration;
+  _native.nativeBrowser.configuration = (0, _browserConfig.toNativeConfig)(configuration);
+}
+
+/**
+ * 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.
+ */
+function getBrowserConfiguration() {
+  return currentConfiguration;
 }
 function navigate(pathOrTrack) {
   if (typeof pathOrTrack === 'string') {
@@ -243,12 +127,29 @@ const notifyContentChanged = path => {
 };
 
 /**
- * Returns whether search functionality is configured via `configureBrowser({ search: ... })`.
+ * 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()
+ * ```
  */
 exports.notifyContentChanged = notifyContentChanged;
+const invalidateAllContent = () => {
+  _native.nativeBrowser.invalidateAllContent();
+};
+
+/**
+ * Returns whether search functionality is configured via `configureBrowser({ search: ... })`.
+ */
+exports.invalidateAllContent = invalidateAllContent;
 function hasSearch() {
   const config = _native.nativeBrowser.configuration;
-  const searchRoute = config.routes?.find(r => r.path === SEARCH_ROUTE_PATH);
+  const searchRoute = config.routes?.find(r => r.path === _browserConfig.SEARCH_ROUTE_PATH);
   return !!(searchRoute?.searchCallback || searchRoute?.searchConfig);
 }
 
@@ -267,6 +168,6 @@ function hasSearch() {
  * ```
  */
 async function search(query) {
-  return _native.nativeBrowser.onSearch(query);
+  return _native.nativeBrowser.search(query);
 }
 //# sourceMappingURL=browser.js.map

package/lib/commonjs/features/browser.js.map

@@ -1 +1 @@
-{"version":3,"names":["_native","require","_NativeUpdatedValue","_useNativeUpdatedValue","isCallback","source","isTransformableRequestConfig","obj","isRouteConfig","flattenBrowseSource","browseCallback","browseConfig","browseStatic","searchSourceToRouteEntry","path","SEARCH_ROUTE_PATH","searchCallback","searchConfig","wrapTracksAsResolvedTrack","tracks","url","TABS_ROUTE_PATH","title","children","tabsSourceToRouteEntry","Array","isArray","wrappedCallback","flattenRouteEntry","browse","media","artwork","DEFAULT_ROUTE_PATH","flattenRoutes","routes","rootBrowse","tabs","search","entries","Object","push","length","undefined","toNativeConfig","config","request","singleTrack","handleTrackLoad","androidControllerOfflineError","carPlayUpNextButton","carPlayNowPlayingButtons","formatNavigationError","configureBrowser","configuration","nativeBrowser","navigate","pathOrTrack","navigatePath","navigateTrack","getPath","onPathChanged","exports","NativeUpdatedValue","emitterize","cb","usePath","useNativeUpdatedValue","getContent","onContentChanged","useContent","getTabs","onTabsChanged","useTabs","notifyContentChanged","hasSearch","searchRoute","find","r","query","onSearch"],"sourceRoot":"../../../src","sources":["features/browser.ts"],"mappings":"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","ignoreList":[]}
+{"version":3,"names":["_native","require","_NativeUpdatedValue","_useNativeUpdatedValue","_browserConfig","currentConfiguration","configureBrowser","configuration","__DEV__","validateBrowserConfiguration","nativeBrowser","toNativeConfig","getBrowserConfiguration","navigate","pathOrTrack","navigatePath","navigateTrack","getPath","path","onPathChanged","exports","NativeUpdatedValue","emitterize","cb","usePath","useNativeUpdatedValue","getContent","onContentChanged","useContent","getTabs","tabs","onTabsChanged","useTabs","notifyContentChanged","invalidateAllContent","hasSearch","config","searchRoute","routes","find","r","SEARCH_ROUTE_PATH","searchCallback","searchConfig","search","query"],"sourceRoot":"../../../src","sources":["features/browser.ts"],"mappings":"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","ignoreList":[]}

package/lib/commonjs/features/carConnection.js

@@ -0,0 +1,42 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.isCarConnected = isCarConnected;
+exports.onCarConnectedChanged = void 0;
+exports.useCarConnected = useCarConnected;
+var _native = require("../native");
+var _NativeUpdatedValue = require("../utils/NativeUpdatedValue");
+var _useNativeUpdatedValue = require("../utils/useNativeUpdatedValue");
+// MARK: - Getters
+
+/**
+ * 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.
+ */
+function isCarConnected() {
+  return _native.nativeBrowser.isCarConnected();
+}
+
+// MARK: - Event Callbacks
+
+/**
+ * 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
+ */
+const onCarConnectedChanged = exports.onCarConnectedChanged = _NativeUpdatedValue.NativeUpdatedValue.emitterize(cb => _native.nativeBrowser.onCarConnectedChanged = cb);
+
+// MARK: - Hooks
+
+/**
+ * Hook that returns whether a car is connected and updates on changes
+ * (always false on web).
+ */
+function useCarConnected() {
+  return (0, _useNativeUpdatedValue.useNativeUpdatedValue)(isCarConnected, onCarConnectedChanged);
+}
+//# sourceMappingURL=carConnection.js.map

package/lib/commonjs/features/carConnection.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["_native","require","_NativeUpdatedValue","_useNativeUpdatedValue","isCarConnected","nativeBrowser","onCarConnectedChanged","exports","NativeUpdatedValue","emitterize","cb","useCarConnected","useNativeUpdatedValue"],"sourceRoot":"../../../src","sources":["features/carConnection.ts"],"mappings":";;;;;;;;AAAA,IAAAA,OAAA,GAAAC,OAAA;AACA,IAAAC,mBAAA,GAAAD,OAAA;AACA,IAAAE,sBAAA,GAAAF,OAAA;AAEA;;AAEA;AACA;AACA;AACA;AACA;AACO,SAASG,cAAcA,CAAA,EAAY;EACxC,OAAOC,qBAAa,CAACD,cAAc,CAAC,CAAC;AACvC;;AAEA;;AAEA;AACA;AACA;AACA;AACA;AACA;AACO,MAAME,qBAAqB,GAAAC,OAAA,CAAAD,qBAAA,GAAGE,sCAAkB,CAACC,UAAU,CAC/DC,EAAE,IAAML,qBAAa,CAACC,qBAAqB,GAAGI,EACjD,CAAC;;AAED;;AAEA;AACA;AACA;AACA;AACO,SAASC,eAAeA,CAAA,EAAY;EACzC,OAAO,IAAAC,4CAAqB,EAACR,cAAc,EAAEE,qBAAqB,CAAC;AACrE","ignoreList":[]}

package/lib/commonjs/features/equalizer.js

@@ -53,7 +53,7 @@ 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
  */
 const onEqualizerChanged = exports.onEqualizerChanged = _NativeUpdatedValue.NativeUpdatedValue.emitterize(cb => _native.nativeBrowser.onEqualizerChanged = cb);
 

package/lib/commonjs/features/errors.js

@@ -15,8 +15,36 @@ var _NativeUpdatedValue = require("../utils/NativeUpdatedValue");
 var _useNativeUpdatedValue = require("../utils/useNativeUpdatedValue");
 // Re-export for Nitro spec
 
+/**
+ * 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`.
+ */
+
 /**
  * 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.
  */
 
 /**
@@ -30,6 +58,10 @@ var _useNativeUpdatedValue = require("../utils/useNativeUpdatedValue");
  * - `'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.
  */
 
 /**
@@ -51,7 +83,7 @@ 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
  */
 const onPlaybackError = exports.onPlaybackError = _NativeUpdatedValue.NativeUpdatedValue.emitterize(cb => _native.nativeBrowser.onPlaybackError = cb);
 
@@ -79,7 +111,7 @@ 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
  */
 const onNavigationError = exports.onNavigationError = _NativeUpdatedValue.NativeUpdatedValue.emitterize(cb => _native.nativeBrowser.onNavigationError = cb);
 
@@ -107,7 +139,7 @@ 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
  */
 const onFormattedNavigationError = exports.onFormattedNavigationError = _NativeUpdatedValue.NativeUpdatedValue.emitterize(cb => _native.nativeBrowser.onFormattedNavigationError = cb);
 
@@ -115,7 +147,7 @@ const onFormattedNavigationError = exports.onFormattedNavigationError = _NativeU
  * 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.
@@ -156,7 +188,7 @@ const onFormattedNavigationError = exports.onFormattedNavigationError = _NativeU
  * })
  * ```
  *
- * @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
  */
 function useFormattedNavigationError() {

package/lib/commonjs/features/errors.js.map

@@ -1 +1 @@
-{"version":3,"names":["_native","require","_NativeUpdatedValue","_useNativeUpdatedValue","getPlaybackError","nativeBrowser","onPlaybackError","exports","NativeUpdatedValue","emitterize","cb","usePlaybackError","useNativeUpdatedValue","getNavigationError","error","undefined","onNavigationError","useNavigationError","getFormattedNavigationError","onFormattedNavigationError","useFormattedNavigationError"],"sourceRoot":"../../../src","sources":["features/errors.ts"],"mappings":";;;;;;;;;;;;AACA,IAAAA,OAAA,GAAAC,OAAA;AACA,IAAAC,mBAAA,GAAAD,OAAA;AACA,IAAAE,sBAAA,GAAAF,OAAA;AAEA;;AAQA;AACA;AACA;;AAKA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAiBA;AACA;AACA;;AAKA;;AAEA;AACA;AACA;AACA;AACO,SAASG,gBAAgBA,CAAA,EAA8B;EAC5D,OAAOC,qBAAa,CAACD,gBAAgB,CAAC,CAAC;AACzC;;AAEA;;AAEA;AACA;AACA;AACA;AACA;AACO,MAAME,eAAe,GAAAC,OAAA,CAAAD,eAAA,GAC1BE,sCAAkB,CAACC,UAAU,CAC1BC,EAAE,IAAML,qBAAa,CAACC,eAAe,GAAGI,EAC3C,CAAC;;AAEH;;AAEA;AACA;AACA;AACA;AACO,SAASC,gBAAgBA,CAAA,EAA8B;EAC5D,OAAO,IAAAC,4CAAqB,EAACR,gBAAgB,EAAEE,eAAe,EAAE,OAAO,CAAC;AAC1E;;AAEA;;AAEA;AACA;AACA;AACA;AACO,SAASO,kBAAkBA,CAAA,EAAgC;EAChE,MAAMC,KAAK,GAAGT,qBAAa,CAACQ,kBAAkB,CAAC,CAAC;EAChD,OAAOC,KAAK,IAAIC,SAAS;AAC3B;;AAEA;AACA;AACA;AACA;AACA;AACO,MAAMC,iBAAiB,GAAAT,OAAA,CAAAS,iBAAA,GAC5BR,sCAAkB,CAACC,UAAU,CAC1BC,EAAE,IAAML,qBAAa,CAACW,iBAAiB,GAAGN,EAC7C,CAAC;;AAEH;AACA;AACA;AACA;AACO,SAASO,kBAAkBA,CAAA,EAAgC;EAChE,OAAO,IAAAL,4CAAqB,EAACC,kBAAkB,EAAEG,iBAAiB,EAAE,OAAO,CAAC;AAC9E;;AAEA;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAASE,2BAA2BA,CAAA,EAE7B;EACZ,OAAOb,qBAAa,CAACa,2BAA2B,CAAC,CAAC,IAAIH,SAAS;AACjE;;AAEA;AACA;AACA;AACA;AACA;AACO,MAAMI,0BAA0B,GAAAZ,OAAA,CAAAY,0BAAA,GAAGX,sCAAkB,CAACC,UAAU,CAEpEC,EAAE,IAAML,qBAAa,CAACc,0BAA0B,GAAGT,EAAG,CAAC;;AAE1D;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;AACO,SAASU,2BAA2BA,CAAA,EAE7B;EACZ,OAAO,IAAAR,4CAAqB,EAC1BM,2BAA2B,EAC3BC,0BACF,CAAC;AACH","ignoreList":[]}
+{"version":3,"names":["_native","require","_NativeUpdatedValue","_useNativeUpdatedValue","getPlaybackError","nativeBrowser","onPlaybackError","exports","NativeUpdatedValue","emitterize","cb","usePlaybackError","useNativeUpdatedValue","getNavigationError","error","undefined","onNavigationError","useNavigationError","getFormattedNavigationError","onFormattedNavigationError","useFormattedNavigationError"],"sourceRoot":"../../../src","sources":["features/errors.ts"],"mappings":";;;;;;;;;;;;AACA,IAAAA,OAAA,GAAAC,OAAA;AACA,IAAAC,mBAAA,GAAAD,OAAA;AACA,IAAAE,sBAAA,GAAAF,OAAA;AAEA;;AAGA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAuCA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAKA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAmBA;AACA;AACA;;AAKA;;AAEA;AACA;AACA;AACA;AACO,SAASG,gBAAgBA,CAAA,EAA8B;EAC5D,OAAOC,qBAAa,CAACD,gBAAgB,CAAC,CAAC;AACzC;;AAEA;;AAEA;AACA;AACA;AACA;AACA;AACO,MAAME,eAAe,GAAAC,OAAA,CAAAD,eAAA,GAC1BE,sCAAkB,CAACC,UAAU,CAC1BC,EAAE,IAAML,qBAAa,CAACC,eAAe,GAAGI,EAC3C,CAAC;;AAEH;;AAEA;AACA;AACA;AACA;AACO,SAASC,gBAAgBA,CAAA,EAA8B;EAC5D,OAAO,IAAAC,4CAAqB,EAACR,gBAAgB,EAAEE,eAAe,EAAE,OAAO,CAAC;AAC1E;;AAEA;;AAEA;AACA;AACA;AACA;AACO,SAASO,kBAAkBA,CAAA,EAAgC;EAChE,MAAMC,KAAK,GAAGT,qBAAa,CAACQ,kBAAkB,CAAC,CAAC;EAChD,OAAOC,KAAK,IAAIC,SAAS;AAC3B;;AAEA;AACA;AACA;AACA;AACA;AACO,MAAMC,iBAAiB,GAAAT,OAAA,CAAAS,iBAAA,GAC5BR,sCAAkB,CAACC,UAAU,CAC1BC,EAAE,IAAML,qBAAa,CAACW,iBAAiB,GAAGN,EAC7C,CAAC;;AAEH;AACA;AACA;AACA;AACO,SAASO,kBAAkBA,CAAA,EAAgC;EAChE,OAAO,IAAAL,4CAAqB,EAACC,kBAAkB,EAAEG,iBAAiB,EAAE,OAAO,CAAC;AAC9E;;AAEA;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAASE,2BAA2BA,CAAA,EAE7B;EACZ,OAAOb,qBAAa,CAACa,2BAA2B,CAAC,CAAC,IAAIH,SAAS;AACjE;;AAEA;AACA;AACA;AACA;AACA;AACO,MAAMI,0BAA0B,GAAAZ,OAAA,CAAAY,0BAAA,GAAGX,sCAAkB,CAACC,UAAU,CAEpEC,EAAE,IAAML,qBAAa,CAACc,0BAA0B,GAAGT,EAAG,CAAC;;AAE1D;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;AACO,SAASU,2BAA2BA,CAAA,EAE7B;EACZ,OAAO,IAAAR,4CAAqB,EAC1BM,2BAA2B,EAC3BC,0BACF,CAAC;AACH","ignoreList":[]}

package/lib/commonjs/features/favorites.js

@@ -83,7 +83,7 @@ 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/commonjs/features/gate.js

@@ -0,0 +1,164 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.clearGate = clearGate;
+exports.onGate = void 0;
+exports.setGate = setGate;
+var _native = require("../native");
+var _LazyNativeEmitter = require("../utils/LazyNativeEmitter");
+// MARK: - Wire types (cross the Nitro bridge; native↔JS)
+
+/** Discriminant for gate requests and events. */
+
+/**
+ * Flat wire struct for a gate request (crosses the Nitro bridge).
+ * Use {@link GateRequest} in consumer-facing code; `gate.ts` converts between them.
+ * @internal
+ */
+
+/**
+ * Wire form of a resolver result (native awaits this from JS).
+ * @internal
+ */
+
+/**
+ * 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).
+ */
+
+// MARK: - Public types (consumer-facing)
+
+/**
+ * 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).
+ */
+
+/**
+ * The gate chrome crosses the bridge as-is; this alias marks the wire side.
+ * @internal
+ */
+
+/**
+ * Describes the request being decided by a {@link GateResolver}.
+ * Discriminated by `kind`: `'browse'` for content navigation, `'search'` for
+ * voice/manual search queries.
+ */
+
+/**
+ * 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.
+ */
+
+// MARK: - Internal state
+
+let resolver;
+function toPublicRequest(req) {
+  switch (req.reason) {
+    case 'browse':
+      return {
+        kind: 'browse',
+        path: req.path ?? ''
+      };
+    case 'search':
+      // req.search is always present on a well-formed search request — the
+      // native wire contract guarantees it for reason:'search'. Assert the
+      // native contract with `!` so we never hand consumer code a SearchParams
+      // with its required `query` field missing.
+      return {
+        kind: 'search',
+        params: req.search
+      };
+    default:
+      {
+        const _exhaustive = req.reason;
+        throw new Error(`Unhandled GateReason: ${String(_exhaustive)}`);
+      }
+  }
+}
+
+// Native awaits this per request at a serve site.
+// No resolver → static gate → every request is gated (native applies stored default / built-in).
+_native.nativeBrowser.resolveGate = async req => {
+  const result = resolver ? resolver(toPublicRequest(req)) : true;
+  if (result === false) return {
+    gated: false
+  };
+  if (result === true) return {
+    gated: true
+  };
+  return {
+    gated: true,
+    gate: result
+  };
+};
+
+// MARK: - Public API
+
+/**
+ * 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.
+ */
+
+/**
+ * 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.
+ */
+
+function setGate(a, b) {
+  if (typeof a === 'function') {
+    resolver = a;
+    _native.nativeBrowser.setGate(undefined, true);
+  } else {
+    resolver = b;
+    _native.nativeBrowser.setGate(a, b != null);
+  }
+}
+
+/**
+ * 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.
+ */
+function clearGate() {
+  resolver = undefined;
+  _native.nativeBrowser.clearGate();
+}
+
+/**
+ * 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
+ */
+const onGate = exports.onGate = _LazyNativeEmitter.LazyNativeEmitter.emitterize(cb => _native.nativeBrowser.onGate = cb);
+//# sourceMappingURL=gate.js.map

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

@@ -0,0 +1 @@
+{"version":3,"names":["_native","require","_LazyNativeEmitter","resolver","toPublicRequest","req","reason","kind","path","params","search","_exhaustive","Error","String","nativeBrowser","resolveGate","result","gated","gate","setGate","a","b","undefined","clearGate","onGate","exports","LazyNativeEmitter","emitterize","cb"],"sourceRoot":"../../../src","sources":["features/gate.ts"],"mappings":";;;;;;;;AACA,IAAAA,OAAA,GAAAC,OAAA;AACA,IAAAC,kBAAA,GAAAD,OAAA;AAEA;;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,IAAIE,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;AACAG,qBAAa,CAACC,WAAW,GAAG,MAC1BV,GAAsB,IACI;EAC1B,MAAMW,MAAM,GAAGb,QAAQ,GAAGA,QAAQ,CAACC,eAAe,CAACC,GAAG,CAAC,CAAC,GAAG,IAAI;EAC/D,IAAIW,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;;AAEO,SAASG,OAAOA,CAACC,CAAsB,EAAEC,CAAgB,EAAQ;EACtE,IAAI,OAAOD,CAAC,KAAK,UAAU,EAAE;IAC3BjB,QAAQ,GAAGiB,CAAC;IACZN,qBAAa,CAACK,OAAO,CAACG,SAAS,EAAE,IAAI,CAAC;EACxC,CAAC,MAAM;IACLnB,QAAQ,GAAGkB,CAAC;IACZP,qBAAa,CAACK,OAAO,CAACC,CAAC,EAAEC,CAAC,IAAI,IAAI,CAAC;EACrC;AACF;;AAEA;AACA;AACA;AACA;AACA;AACA;AACO,SAASE,SAASA,CAAA,EAAS;EAChCpB,QAAQ,GAAGmB,SAAS;EACpBR,qBAAa,CAACS,SAAS,CAAC,CAAC;AAC3B;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,MAAMC,MAAM,GAAAC,OAAA,CAAAD,MAAA,GAAGE,oCAAiB,CAACC,UAAU,CAC/CC,EAAE,IAAMd,qBAAa,CAACU,MAAM,GAAGI,EAClC,CAAC","ignoreList":[]}