@5stones/react-native-audio-browser 0.1.0

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

@@ -0,0 +1,83 @@
+"use strict";
+
+import { RepeatMode } from '../TrackPlayer';
+/**
+ * Manages player options and configuration.
+ * Handles option updates and change detection.
+ */
+export class OptionsManager {
+  options = {
+    forwardJumpInterval: 15,
+    backwardJumpInterval: 15,
+    progressUpdateEventInterval: null,
+    repeatMode: RepeatMode.Off,
+    capabilities: {}
+  };
+
+  // Event callback
+  onOptionsChanged = () => {};
+
+  /**
+   * Updates player options with change detection.
+   * Emits onOptionsChanged event after updating.
+   *
+   * @param options Partial options to update
+   */
+  updateOptions(options) {
+    if (options.progressUpdateEventInterval !== null && options.progressUpdateEventInterval !== undefined && typeof options.progressUpdateEventInterval !== 'number') {
+      throw new Error('NullSentinal type is not valid on web.');
+    }
+
+    // Merge platform-agnostic options
+    const mergedOptions = {
+      ...this.options,
+      forwardJumpInterval: options.forwardJumpInterval ?? this.options.forwardJumpInterval,
+      backwardJumpInterval: options.backwardJumpInterval ?? this.options.backwardJumpInterval,
+      capabilities: options.capabilities ?? this.options.capabilities,
+      progressUpdateEventInterval: options.progressUpdateEventInterval === null ? null : options.progressUpdateEventInterval ?? this.options.progressUpdateEventInterval
+    };
+
+    // Store merged options
+    this.options = mergedOptions;
+
+    // Call callback with full Options type (including repeatMode)
+    const fullOptions = {
+      forwardJumpInterval: mergedOptions.forwardJumpInterval ?? 15,
+      backwardJumpInterval: mergedOptions.backwardJumpInterval ?? 15,
+      progressUpdateEventInterval: mergedOptions.progressUpdateEventInterval ?? 15,
+      capabilities: mergedOptions.capabilities ?? {},
+      repeatMode: mergedOptions.repeatMode
+    };
+    this.onOptionsChanged(fullOptions);
+  }
+
+  /**
+   * Gets current player options (excluding repeatMode).
+   */
+  getOptions() {
+    return {
+      forwardJumpInterval: this.options.forwardJumpInterval,
+      backwardJumpInterval: this.options.backwardJumpInterval,
+      progressUpdateEventInterval: this.options.progressUpdateEventInterval,
+      capabilities: this.options.capabilities
+    };
+  }
+
+  /**
+   * Gets the current repeat mode.
+   */
+  getRepeatMode() {
+    return this.options.repeatMode;
+  }
+
+  /**
+   * Sets the repeat mode.
+   * Updates internal state but does not emit events - caller should handle that.
+   *
+   * @param mode New repeat mode
+   */
+  setRepeatMode(mode) {
+    this.options.repeatMode = mode;
+  }
+}
+//# sourceMappingURL=OptionsManager.js.map

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

@@ -0,0 +1 @@
+{"version":3,"names":["RepeatMode","OptionsManager","options","forwardJumpInterval","backwardJumpInterval","progressUpdateEventInterval","repeatMode","Off","capabilities","onOptionsChanged","updateOptions","undefined","Error","mergedOptions","fullOptions","getOptions","getRepeatMode","setRepeatMode","mode"],"sourceRoot":"../../../../src","sources":["web/player/OptionsManager.ts"],"mappings":";;AAMA,SAASA,UAAU,QAAQ,gBAAgB;AAM3C;AACA;AACA;AACA;AACA,OAAO,MAAMC,cAAc,CAAC;EAClBC,OAAO,GAAoB;IACjCC,mBAAmB,EAAE,EAAE;IACvBC,oBAAoB,EAAE,EAAE;IACxBC,2BAA2B,EAAE,IAAI;IACjCC,UAAU,EAAEN,UAAU,CAACO,GAAG;IAC1BC,YAAY,EAAE,CAAC;EACjB,CAAC;;EAED;EACAC,gBAAgB,GAA+BA,CAAA,KAAM,CAAC,CAAC;;EAEvD;AACF;AACA;AACA;AACA;AACA;EACEC,aAAaA,CAACR,OAA4B,EAAQ;IAChD,IACEA,OAAO,CAACG,2BAA2B,KAAK,IAAI,IAC5CH,OAAO,CAACG,2BAA2B,KAAKM,SAAS,IACjD,OAAOT,OAAO,CAACG,2BAA2B,KAAK,QAAQ,EACvD;MACA,MAAM,IAAIO,KAAK,CAAC,wCAAwC,CAAC;IAC3D;;IAEA;IACA,MAAMC,aAA8B,GAAG;MACrC,GAAG,IAAI,CAACX,OAAO;MACfC,mBAAmB,EACjBD,OAAO,CAACC,mBAAmB,IAAI,IAAI,CAACD,OAAO,CAACC,mBAAmB;MACjEC,oBAAoB,EAClBF,OAAO,CAACE,oBAAoB,IAAI,IAAI,CAACF,OAAO,CAACE,oBAAoB;MACnEI,YAAY,EAAEN,OAAO,CAACM,YAAY,IAAI,IAAI,CAACN,OAAO,CAACM,YAAY;MAC/DH,2BAA2B,EACzBH,OAAO,CAACG,2BAA2B,KAAK,IAAI,GACxC,IAAI,GACHH,OAAO,CAACG,2BAA2B,IAAI,IAAI,CAACH,OAAO,CAACG;IAC7D,CAAC;;IAED;IACA,IAAI,CAACH,OAAO,GAAGW,aAAa;;IAE5B;IACA,MAAMC,WAAoB,GAAG;MAC3BX,mBAAmB,EAAEU,aAAa,CAACV,mBAAmB,IAAI,EAAE;MAC5DC,oBAAoB,EAAES,aAAa,CAACT,oBAAoB,IAAI,EAAE;MAC9DC,2BAA2B,EACzBQ,aAAa,CAACR,2BAA2B,IAAI,EAAE;MACjDG,YAAY,EAAEK,aAAa,CAACL,YAAY,IAAI,CAAC,CAAC;MAC9CF,UAAU,EAAEO,aAAa,CAACP;IAC5B,CAAC;IACD,IAAI,CAACG,gBAAgB,CAACK,WAAW,CAAC;EACpC;;EAEA;AACF;AACA;EACEC,UAAUA,CAAA,EAAkB;IAC1B,OAAO;MACLZ,mBAAmB,EAAE,IAAI,CAACD,OAAO,CAACC,mBAAmB;MACrDC,oBAAoB,EAAE,IAAI,CAACF,OAAO,CAACE,oBAAoB;MACvDC,2BAA2B,EAAE,IAAI,CAACH,OAAO,CAACG,2BAA2B;MACrEG,YAAY,EAAE,IAAI,CAACN,OAAO,CAACM;IAC7B,CAAC;EACH;;EAEA;AACF;AACA;EACEQ,aAAaA,CAAA,EAAmB;IAC9B,OAAO,IAAI,CAACd,OAAO,CAACI,UAAU;EAChC;;EAEA;AACF;AACA;AACA;AACA;AACA;EACEW,aAAaA,CAACC,IAAoB,EAAQ;IACxC,IAAI,CAAChB,OAAO,CAACI,UAAU,GAAGY,IAAI;EAChC;AACF","ignoreList":[]}

package/lib/module/web/util/BrowserPathHelper.js

@@ -0,0 +1,134 @@
+"use strict";
+
+/**
+ * Utility for handling browser paths and contextual URLs in the media browser system.
+ * Mirrors Android's BrowserPathHelper.kt
+ *
+ * Handles two types of special paths:
+ * 1. System paths (prefixed with `/__`): Root, recent, and search paths
+ * 2. Contextual URLs: Embed parent context in track identifiers for Media3 integration
+ *
+ * Contextual URL format: `{parentPath}?__trackId={trackSrc}`
+ * Example: "/library/radio?__trackId=song.mp3"
+ *
+ * This allows:
+ * - Media3 to reference playable-only tracks (tracks with `src` but no `url`)
+ * - Cache lookup to work consistently
+ * - Parent context to be preserved for queue restoration
+ */
+export const BrowserPathHelper = {
+  /** Search path prefix (full path is /__search?q=query) */
+  SEARCH_PATH_PREFIX: '/__search',
+  /** Query parameter name for contextual track identifiers */
+  CONTEXTUAL_TRACK_PARAM: '__trackId',
+  /**
+   * Create a search path for a given query
+   */
+  createSearchPath(query) {
+    const encodedQuery = encodeURIComponent(query);
+    return `${this.SEARCH_PATH_PREFIX}?q=${encodedQuery}`;
+  },
+  /**
+   * Checks if a path contains a contextual track identifier.
+   *
+   * @param path The URL path to check
+   * @returns true if the path contains the contextual track parameter
+   */
+  isContextual(path) {
+    return path.includes(`?${this.CONTEXTUAL_TRACK_PARAM}=`) || path.includes(`&${this.CONTEXTUAL_TRACK_PARAM}=`);
+  },
+  /**
+   * Strips the __trackId parameter from a contextual URL to get the parent path.
+   * If the URL is not contextual, returns it unchanged.
+   *
+   * @param url The URL to process
+   * @returns The URL without the __trackId parameter
+   *
+   * Example: "/library/radio?__trackId=song.mp3" → "/library/radio"
+   * Example: "/search?q=jazz&__trackId=song.mp3" → "/search?q=jazz"
+   */
+  stripTrackId(url) {
+    if (!this.isContextual(url)) {
+      return url;
+    }
+    try {
+      // Parse the URL - handle both full URLs and paths
+      const isFullUrl = url.startsWith('http://') || url.startsWith('https://');
+      const urlObj = new URL(url, isFullUrl ? undefined : 'http://placeholder');
+
+      // Remove the __trackId parameter
+      urlObj.searchParams.delete(this.CONTEXTUAL_TRACK_PARAM);
+
+      // Return the appropriate format
+      if (isFullUrl) {
+        return urlObj.toString();
+      } else {
+        const search = urlObj.searchParams.toString();
+        return search ? `${urlObj.pathname}?${search}` : urlObj.pathname;
+      }
+    } catch {
+      // Fallback: simple string manipulation
+      const paramPattern = new RegExp(`[?&]${this.CONTEXTUAL_TRACK_PARAM}=[^&]*`, 'g');
+      let result = url.replace(paramPattern, '');
+      // Clean up any trailing ? or &
+      result = result.replace(/[?&]$/, '');
+      // Fix double && or ?&
+      result = result.replace(/[?&]{2,}/g, '&').replace(/\?&/, '?');
+      return result;
+    }
+  },
+  /**
+   * Extracts the track ID from a contextual URL.
+   * Returns undefined if the URL is not contextual or doesn't contain the track ID parameter.
+   *
+   * @param path The contextual URL to parse
+   * @returns The extracted track ID, or undefined if not found
+   *
+   * Example: "/library/radio?__trackId=song.mp3" → "song.mp3"
+   */
+  extractTrackId(path) {
+    if (!this.isContextual(path)) {
+      return undefined;
+    }
+    try {
+      // Parse the URL - handle both full URLs and paths
+      const isFullUrl = path.startsWith('http://') || path.startsWith('https://');
+      const urlObj = new URL(path, isFullUrl ? undefined : 'http://placeholder');
+      return urlObj.searchParams.get(this.CONTEXTUAL_TRACK_PARAM) ?? undefined;
+    } catch {
+      // Fallback: regex extraction
+      const match = path.match(new RegExp(`[?&]${this.CONTEXTUAL_TRACK_PARAM}=([^&]*)`));
+      return match?.[1] ? decodeURIComponent(match[1]) : undefined;
+    }
+  },
+  /**
+   * Combines a base URL with a path, ensuring proper slash handling.
+   *
+   * @param baseUrl The base URL (can be undefined)
+   * @param path The path to append
+   * @returns The combined URL with proper slash handling
+   *
+   * Examples:
+   * - buildUrl("http://example.com", "api/test") → "http://example.com/api/test"
+   * - buildUrl("http://example.com/", "/api/test") → "http://example.com/api/test"
+   * - buildUrl(undefined, "/api/test") → "/api/test"
+   * - buildUrl(undefined, "http://full.url") → "http://full.url"
+   */
+  buildUrl(baseUrl, path) {
+    // If path is already a full URL, return it as-is
+    if (path.startsWith('http://') || path.startsWith('https://')) {
+      return path;
+    }
+
+    // If no baseUrl, return path as-is
+    if (!baseUrl) {
+      return path;
+    }
+
+    // Ensure baseUrl ends with / and path doesn't start with /
+    const normalizedBase = baseUrl.replace(/\/+$/, '') + '/';
+    const normalizedPath = path.replace(/^\/+/, '');
+    return `${normalizedBase}${normalizedPath}`;
+  }
+};
+//# sourceMappingURL=BrowserPathHelper.js.map

package/lib/module/web/util/BrowserPathHelper.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["BrowserPathHelper","SEARCH_PATH_PREFIX","CONTEXTUAL_TRACK_PARAM","createSearchPath","query","encodedQuery","encodeURIComponent","isContextual","path","includes","stripTrackId","url","isFullUrl","startsWith","urlObj","URL","undefined","searchParams","delete","toString","search","pathname","paramPattern","RegExp","result","replace","extractTrackId","get","match","decodeURIComponent","buildUrl","baseUrl","normalizedBase","normalizedPath"],"sourceRoot":"../../../../src","sources":["web/util/BrowserPathHelper.ts"],"mappings":";;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,MAAMA,iBAAiB,GAAG;EAC/B;EACAC,kBAAkB,EAAE,WAAW;EAE/B;EACAC,sBAAsB,EAAE,WAAW;EAEnC;AACF;AACA;EACEC,gBAAgBA,CAACC,KAAa,EAAU;IACtC,MAAMC,YAAY,GAAGC,kBAAkB,CAACF,KAAK,CAAC;IAC9C,OAAO,GAAG,IAAI,CAACH,kBAAkB,MAAMI,YAAY,EAAE;EACvD,CAAC;EAED;AACF;AACA;AACA;AACA;AACA;EACEE,YAAYA,CAACC,IAAY,EAAW;IAClC,OACEA,IAAI,CAACC,QAAQ,CAAC,IAAI,IAAI,CAACP,sBAAsB,GAAG,CAAC,IACjDM,IAAI,CAACC,QAAQ,CAAC,IAAI,IAAI,CAACP,sBAAsB,GAAG,CAAC;EAErD,CAAC;EAED;AACF;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;EACEQ,YAAYA,CAACC,GAAW,EAAU;IAChC,IAAI,CAAC,IAAI,CAACJ,YAAY,CAACI,GAAG,CAAC,EAAE;MAC3B,OAAOA,GAAG;IACZ;IAEA,IAAI;MACF;MACA,MAAMC,SAAS,GAAGD,GAAG,CAACE,UAAU,CAAC,SAAS,CAAC,IAAIF,GAAG,CAACE,UAAU,CAAC,UAAU,CAAC;MACzE,MAAMC,MAAM,GAAG,IAAIC,GAAG,CAACJ,GAAG,EAAEC,SAAS,GAAGI,SAAS,GAAG,oBAAoB,CAAC;;MAEzE;MACAF,MAAM,CAACG,YAAY,CAACC,MAAM,CAAC,IAAI,CAAChB,sBAAsB,CAAC;;MAEvD;MACA,IAAIU,SAAS,EAAE;QACb,OAAOE,MAAM,CAACK,QAAQ,CAAC,CAAC;MAC1B,CAAC,MAAM;QACL,MAAMC,MAAM,GAAGN,MAAM,CAACG,YAAY,CAACE,QAAQ,CAAC,CAAC;QAC7C,OAAOC,MAAM,GAAG,GAAGN,MAAM,CAACO,QAAQ,IAAID,MAAM,EAAE,GAAGN,MAAM,CAACO,QAAQ;MAClE;IACF,CAAC,CAAC,MAAM;MACN;MACA,MAAMC,YAAY,GAAG,IAAIC,MAAM,CAC7B,OAAO,IAAI,CAACrB,sBAAsB,QAAQ,EAC1C,GACF,CAAC;MACD,IAAIsB,MAAM,GAAGb,GAAG,CAACc,OAAO,CAACH,YAAY,EAAE,EAAE,CAAC;MAC1C;MACAE,MAAM,GAAGA,MAAM,CAACC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC;MACpC;MACAD,MAAM,GAAGA,MAAM,CAACC,OAAO,CAAC,WAAW,EAAE,GAAG,CAAC,CAACA,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC;MAC7D,OAAOD,MAAM;IACf;EACF,CAAC;EAED;AACF;AACA;AACA;AACA;AACA;AACA;AACA;AACA;EACEE,cAAcA,CAAClB,IAAY,EAAsB;IAC/C,IAAI,CAAC,IAAI,CAACD,YAAY,CAACC,IAAI,CAAC,EAAE;MAC5B,OAAOQ,SAAS;IAClB;IAEA,IAAI;MACF;MACA,MAAMJ,SAAS,GAAGJ,IAAI,CAACK,UAAU,CAAC,SAAS,CAAC,IAAIL,IAAI,CAACK,UAAU,CAAC,UAAU,CAAC;MAC3E,MAAMC,MAAM,GAAG,IAAIC,GAAG,CAACP,IAAI,EAAEI,SAAS,GAAGI,SAAS,GAAG,oBAAoB,CAAC;MAC1E,OAAOF,MAAM,CAACG,YAAY,CAACU,GAAG,CAAC,IAAI,CAACzB,sBAAsB,CAAC,IAAIc,SAAS;IAC1E,CAAC,CAAC,MAAM;MACN;MACA,MAAMY,KAAK,GAAGpB,IAAI,CAACoB,KAAK,CACtB,IAAIL,MAAM,CAAC,OAAO,IAAI,CAACrB,sBAAsB,UAAU,CACzD,CAAC;MACD,OAAO0B,KAAK,GAAG,CAAC,CAAC,GAAGC,kBAAkB,CAACD,KAAK,CAAC,CAAC,CAAC,CAAC,GAAGZ,SAAS;IAC9D;EACF,CAAC;EAED;AACF;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;EACEc,QAAQA,CAACC,OAA2B,EAAEvB,IAAY,EAAU;IAC1D;IACA,IAAIA,IAAI,CAACK,UAAU,CAAC,SAAS,CAAC,IAAIL,IAAI,CAACK,UAAU,CAAC,UAAU,CAAC,EAAE;MAC7D,OAAOL,IAAI;IACb;;IAEA;IACA,IAAI,CAACuB,OAAO,EAAE;MACZ,OAAOvB,IAAI;IACb;;IAEA;IACA,MAAMwB,cAAc,GAAGD,OAAO,CAACN,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,GAAG,GAAG;IACxD,MAAMQ,cAAc,GAAGzB,IAAI,CAACiB,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;IAC/C,OAAO,GAAGO,cAAc,GAAGC,cAAc,EAAE;EAC7C;AACF,CAAU","ignoreList":[]}

package/lib/module/web/util/shuffle.js

@@ -0,0 +1,17 @@
+"use strict";
+
+/**
+ * Shuffles an array in place using the Fisher-Yates algorithm.
+ * https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle
+ *
+ * @param array The array to shuffle (mutated in place)
+ */
+export function fisherYatesShuffle(array) {
+  for (let i = array.length - 1; i > 0; i--) {
+    const j = Math.floor(Math.random() * (i + 1));
+    const temp = array[i];
+    array[i] = array[j];
+    array[j] = temp;
+  }
+}
+//# sourceMappingURL=shuffle.js.map

package/lib/module/web/util/shuffle.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["fisherYatesShuffle","array","i","length","j","Math","floor","random","temp"],"sourceRoot":"../../../../src","sources":["web/util/shuffle.ts"],"mappings":";;AAAA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASA,kBAAkBA,CAAIC,KAAU,EAAQ;EACtD,KAAK,IAAIC,CAAC,GAAGD,KAAK,CAACE,MAAM,GAAG,CAAC,EAAED,CAAC,GAAG,CAAC,EAAEA,CAAC,EAAE,EAAE;IACzC,MAAME,CAAC,GAAGC,IAAI,CAACC,KAAK,CAACD,IAAI,CAACE,MAAM,CAAC,CAAC,IAAIL,CAAC,GAAG,CAAC,CAAC,CAAC;IAC7C,MAAMM,IAAI,GAAGP,KAAK,CAACC,CAAC,CAAE;IACtBD,KAAK,CAACC,CAAC,CAAC,GAAGD,KAAK,CAACG,CAAC,CAAE;IACpBH,KAAK,CAACG,CAAC,CAAC,GAAGI,IAAI;EACjB;AACF","ignoreList":[]}

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

@@ -0,0 +1,5 @@
+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

@@ -0,0 +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"}

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

@@ -0,0 +1,112 @@
+/**
+ * Battery optimization status and warning handling for Android 12+ foreground service restrictions.
+ *
+ * When an external controller (Bluetooth, car head unit) tries to resume playback while the app
+ * is killed and battery restrictions are in place, Android 12+ blocks the foreground service start.
+ * This module exposes APIs to detect this condition and guide users to fix their settings.
+ */
+import { NativeUpdatedValue } from '../utils/NativeUpdatedValue';
+/**
+ * Battery optimization status.
+ *
+ * - `unrestricted`: App can run freely in background. User explicitly allowed it.
+ * - `optimized`: System may limit background work (Doze, App Standby). Default state.
+ * - `restricted`: User or system severely limited background. Services blocked.
+ */
+export type BatteryOptimizationStatus = 'unrestricted' | 'optimized' | 'restricted';
+/**
+ * Event fired when battery warning pending state changes.
+ */
+export type BatteryWarningPendingChangedEvent = {
+    pending: boolean;
+};
+/**
+ * Event fired when battery optimization status changes.
+ */
+export type BatteryOptimizationStatusChangedEvent = {
+    status: BatteryOptimizationStatus;
+};
+/**
+ * Check if a battery warning is pending (Android only).
+ * Returns true if a foreground service start was blocked and the user hasn't dismissed
+ * the warning or fixed their battery settings.
+ * Auto-clears when battery status becomes unrestricted.
+ * @returns true if warning is pending, always false on iOS
+ */
+export declare function getBatteryWarningPending(): boolean;
+/**
+ * Get the current battery optimization status (Android only).
+ * Also fires onBatteryOptimizationStatusChanged if status changed since last call.
+ * @returns Current status, always 'unrestricted' on iOS
+ */
+export declare function getBatteryOptimizationStatus(): BatteryOptimizationStatus;
+/**
+ * Dismiss the battery warning without fixing settings (Android only).
+ * Call this when the user chooses to ignore the warning.
+ * No-op on iOS.
+ */
+export declare function dismissBatteryWarning(): void;
+/**
+ * Open the system battery settings for this app (Android only).
+ * No-op on iOS.
+ */
+export declare function openBatterySettings(): void;
+/**
+ * Subscribes to battery warning pending state changes (Android only).
+ * Fires when: failure occurs (true), dismissBatteryWarning() called (false),
+ * or status becomes unrestricted (false).
+ * Never fires on iOS.
+ */
+export declare const onBatteryWarningPendingChanged: NativeUpdatedValue<BatteryWarningPendingChangedEvent>;
+/**
+ * Subscribes to battery optimization status changes (Android only).
+ * Fires when user returns from settings with a different status.
+ * Never fires on iOS.
+ */
+export declare const onBatteryOptimizationStatusChanged: NativeUpdatedValue<BatteryOptimizationStatusChangedEvent>;
+/**
+ * Hook that returns whether a battery warning is pending and updates when it changes (Android only).
+ * @returns true if warning is pending, always false on iOS
+ */
+export declare function useBatteryWarningPending(): boolean;
+/**
+ * Hook that returns the current battery optimization status and updates when it changes (Android only).
+ * @returns Current status, always 'unrestricted' on iOS
+ */
+export declare function useBatteryOptimizationStatus(): BatteryOptimizationStatus;
+/**
+ * Return type for useBatteryWarning hook.
+ */
+export interface BatteryWarning {
+    /** Whether a battery warning is pending */
+    pending: boolean;
+    /** Current battery optimization status */
+    status: BatteryOptimizationStatus;
+    /** Dismiss the warning without changing settings */
+    dismiss: () => void;
+    /** Open system battery settings for this app */
+    openSettings: () => void;
+}
+/**
+ * Meta hook that bundles all battery warning state and actions (Android only).
+ * Use this for a complete battery warning UI implementation.
+ *
+ * @example
+ * ```tsx
+ * function BatteryWarningBanner() {
+ *   const { pending, status, dismiss, openSettings } = useBatteryWarning()
+ *
+ *   if (!pending) return null
+ *
+ *   return (
+ *     <View>
+ *       <Text>Battery status: {status}</Text>
+ *       <Button onPress={openSettings} title="Fix" />
+ *       <Button onPress={dismiss} title="Dismiss" />
+ *     </View>
+ *   )
+ * }
+ * ```
+ */
+export declare function useBatteryWarning(): BatteryWarning;
+//# sourceMappingURL=battery.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"battery.d.ts","sourceRoot":"","sources":["../../../../src/features/battery.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAA;AAKhE;;;;;;GAMG;AACH,MAAM,MAAM,yBAAyB,GACjC,cAAc,GACd,WAAW,GACX,YAAY,CAAA;AAEhB;;GAEG;AACH,MAAM,MAAM,iCAAiC,GAAG;IAC9C,OAAO,EAAE,OAAO,CAAA;CACjB,CAAA;AAED;;GAEG;AACH,MAAM,MAAM,qCAAqC,GAAG;IAClD,MAAM,EAAE,yBAAyB,CAAA;CAClC,CAAA;AAID;;;;;;GAMG;AACH,wBAAgB,wBAAwB,IAAI,OAAO,CAElD;AAED;;;;GAIG;AACH,wBAAgB,4BAA4B,IAAI,yBAAyB,CAExE;AAID;;;;GAIG;AACH,wBAAgB,qBAAqB,IAAI,IAAI,CAE5C;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,IAAI,IAAI,CAE1C;AAID;;;;;GAKG;AACH,eAAO,MAAM,8BAA8B,uDAGxC,CAAA;AAEH;;;;GAIG;AACH,eAAO,MAAM,kCAAkC,2DAG5C,CAAA;AAIH;;;GAGG;AACH,wBAAgB,wBAAwB,IAAI,OAAO,CAMlD;AAED;;;GAGG;AACH,wBAAgB,4BAA4B,IAAI,yBAAyB,CAMxE;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,2CAA2C;IAC3C,OAAO,EAAE,OAAO,CAAA;IAChB,0CAA0C;IAC1C,MAAM,EAAE,yBAAyB,CAAA;IACjC,oDAAoD;IACpD,OAAO,EAAE,MAAM,IAAI,CAAA;IACnB,gDAAgD;IAChD,YAAY,EAAE,MAAM,IAAI,CAAA;CACzB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,iBAAiB,IAAI,cAAc,CAUlD"}

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

@@ -0,0 +1,68 @@
+import type { BrowserConfiguration, ResolvedTrack, Track } from '../types';
+import { NativeUpdatedValue } from '../utils/NativeUpdatedValue';
+/**
+ * Configures the browser with routes, tabs, and other settings.
+ * Also registers the browser with the player to enable:
+ * - Media URL transformation for authenticated playback
+ * - Android Auto / CarPlay browsing integration
+ * - Playback of browsable tracks via navigate()
+ *
+ * @param configuration - Browser configuration including routes, tabs, media config, etc.
+ *
+ * @example
+ * ```ts
+ * configureBrowser({
+ *   routes: {
+ *     '/albums/:id': { path: '/api/albums/:id' }
+ *   },
+ *   tabs: [
+ *     { title: 'Home', url: '/' },
+ *     { title: 'Search', url: '/search' }
+ *   ]
+ * })
+ * ```
+ */
+export declare function configureBrowser(configuration: BrowserConfiguration): void;
+export declare function navigate(pathOrTrack: string | Track): void;
+export declare function getPath(): string | undefined;
+export declare const onPathChanged: NativeUpdatedValue<string | undefined>;
+export declare function usePath(): string | undefined;
+export declare function getContent(): ResolvedTrack | undefined;
+export declare const onContentChanged: NativeUpdatedValue<ResolvedTrack | undefined>;
+export declare function useContent(): ResolvedTrack | undefined;
+export declare function getTabs(): Track[] | undefined;
+export declare const onTabsChanged: NativeUpdatedValue<Track[] | undefined>;
+export declare function useTabs(): Track[] | undefined;
+/**
+ * Notifies external media controllers (Android Auto, CarPlay) that content
+ * at the specified path has changed and should be refreshed.
+ *
+ * @param path - The path where content has changed (e.g., '/favorites')
+ *
+ * @example
+ * ```ts
+ * // After adding a track to favorites
+ * notifyContentChanged('/favorites')
+ * ```
+ */
+export declare const notifyContentChanged: (path: string) => void;
+/**
+ * Returns whether search functionality is configured via `configureBrowser({ search: ... })`.
+ */
+export declare function hasSearch(): boolean;
+/**
+ * Searches for tracks using the configured search source.
+ *
+ * @param query - The search query string
+ * @returns Promise resolving to an array of matching tracks
+ *
+ * @see {@link configureBrowser}
+ *
+ * @example
+ * ```ts
+ * const results = await search('jazz')
+ * console.log(`Found ${results.length} tracks`)
+ * ```
+ */
+export declare function search(query: string): Promise<Track[]>;
+//# sourceMappingURL=browser.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../../../../src/features/browser.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,oBAAoB,EAGpB,aAAa,EAKb,KAAK,EAEN,MAAM,UAAU,CAAA;AAKjB,OAAO,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAA;AA2LhE;;;;;;;;;;;;;;;;;;;;;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"}

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

@@ -0,0 +1,35 @@
+import type { EqualizerSettings } from '../specs/audio-browser.nitro';
+import { NativeUpdatedValue } from '../utils/NativeUpdatedValue';
+export type { EqualizerSettings };
+/**
+ * Gets the current equalizer settings (Android only).
+ * @returns Equalizer settings, or undefined if not available
+ */
+export declare function getEqualizerSettings(): EqualizerSettings | undefined;
+/**
+ * Enables or disables the equalizer (Android only).
+ * @param enabled - Whether to enable the equalizer
+ */
+export declare function setEqualizerEnabled(enabled: boolean): void;
+/**
+ * Sets the equalizer to a preset (Android only).
+ * @param preset - The name of the preset to apply
+ */
+export declare function setEqualizerPreset(preset: string): void;
+/**
+ * Sets custom equalizer band levels (Android only).
+ * @param levels - Array of level values for each band (in millibels)
+ */
+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
+ */
+export declare const onEqualizerChanged: NativeUpdatedValue<EqualizerSettings>;
+/**
+ * Hook that returns the current equalizer settings and updates when they change (Android only).
+ * @returns Current equalizer settings, or undefined if not available
+ */
+export declare function useEqualizerSettings(): EqualizerSettings | undefined;
+//# sourceMappingURL=equalizer.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"equalizer.d.ts","sourceRoot":"","sources":["../../../../src/features/equalizer.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAA;AACrE,OAAO,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAA;AAGhE,YAAY,EAAE,iBAAiB,EAAE,CAAA;AAIjC;;;GAGG;AACH,wBAAgB,oBAAoB,IAAI,iBAAiB,GAAG,SAAS,CAEpE;AAID;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAE1D;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAEvD;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,IAAI,CAEzD;AAID;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,uCAG5B,CAAA;AAIH;;;GAGG;AACH,wBAAgB,oBAAoB,IAAI,iBAAiB,GAAG,SAAS,CAEpE"}

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

@@ -0,0 +1,136 @@
+import type { FormattedNavigationError } from '../types/browser';
+import { NativeUpdatedValue } from '../utils/NativeUpdatedValue';
+export type { FormattedNavigationError } from '../types/browser';
+export type PlaybackError = {
+    code: string;
+    message: string;
+};
+/**
+ * Emitted when a playback error occurs.
+ */
+export interface PlaybackErrorEvent {
+    error?: PlaybackError;
+}
+/**
+ * Type of navigation error that occurred.
+ *
+ * - `'content-not-found'` - No route configured for the requested path, or route resolution
+ *   returned no content. This is a configuration issue, not an HTTP 404 from the server.
+ * - `'network-error'` - Network request failed (connection error, timeout, no internet).
+ * - `'http-error'` - Server returned a non-2xx HTTP status code, or returned 2xx but response
+ *   parsing failed. Check `statusCode` and `statusCodeSuccess` for details.
+ * - `'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).
+ */
+export type NavigationErrorType = 'content-not-found' | 'network-error' | 'http-error' | 'callback-error' | 'unknown-error';
+export type NavigationError = {
+    code: NavigationErrorType;
+    message: string;
+    /** HTTP status code when code is 'http-error' */
+    statusCode?: number;
+    /** True if HTTP status code was 2xx (success), useful when error is due to response parsing */
+    statusCodeSuccess?: boolean;
+};
+/**
+ * Emitted when a navigation error occurs.
+ */
+export interface NavigationErrorEvent {
+    error?: NavigationError;
+}
+/**
+ * Gets the current playback error, if any.
+ * @returns The current error or undefined if there is no error
+ */
+export declare function getPlaybackError(): PlaybackError | undefined;
+/**
+ * Subscribes to playback error events.
+ * @param callback - Called when a playback error occurs
+ * @returns Cleanup function to unsubscribe
+ */
+export declare const onPlaybackError: NativeUpdatedValue<PlaybackErrorEvent>;
+/**
+ * Hook that returns the current playback error and updates when it changes.
+ * @returns The current playback error or undefined
+ */
+export declare function usePlaybackError(): PlaybackError | undefined;
+/**
+ * Gets the current navigation error, if any.
+ * @returns The current navigation error or undefined if there is no error
+ */
+export declare function getNavigationError(): NavigationError | undefined;
+/**
+ * Subscribes to navigation error events.
+ * @param callback - Called when a navigation error occurs
+ * @returns Cleanup function to unsubscribe
+ */
+export declare const onNavigationError: NativeUpdatedValue<NavigationErrorEvent>;
+/**
+ * Hook that returns the current navigation error and updates when it changes.
+ * @returns The current navigation error or undefined
+ */
+export declare function useNavigationError(): NavigationError | undefined;
+/**
+ * Gets the current navigation error formatted for display.
+ * Native formats the error using the configured `formatNavigationError` callback,
+ * or falls back to default formatting.
+ *
+ * @returns Formatted error with title and message, or undefined if no error
+ */
+export declare function getFormattedNavigationError(): FormattedNavigationError | undefined;
+/**
+ * Subscribes to formatted navigation error changes.
+ * @param callback - Called when the formatted navigation error changes
+ * @returns Cleanup function to unsubscribe
+ */
+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.
+ *
+ * The same formatted error is used by CarPlay and Android Auto error dialogs,
+ * ensuring consistent error presentation across your app and external controllers.
+ *
+ * @returns Formatted error with title and message, or undefined if no error
+ *
+ * @example
+ * ```tsx
+ * // Basic usage
+ * const error = useFormattedNavigationError()
+ *
+ * if (error) {
+ *   return <ErrorView title={error.title} message={error.message} />
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Configure custom formatting - override only specific errors or routes
+ * configureBrowser({
+ *   formatNavigationError: ({ error, defaultFormatted, path }) => {
+ *     // Custom message for specific routes
+ *     if (error.code === 'network-error' && path.startsWith('/json-api')) {
+ *       return {
+ *         title: 'API Server Not Running',
+ *         message: 'Start the API server first'
+ *       }
+ *     }
+ *     if (error.code === 'http-error') {
+ *       return {
+ *         title: t('error.serverError'),
+ *         message: t('error.httpMessage', { status: error.statusCode })
+ *       }
+ *     }
+ *     // Use default for other error types
+ *     return defaultFormatted
+ *   }
+ * })
+ * ```
+ *
+ * @see {@link BrowserConfiguration.formatNavigationError} - Configure custom error formatting
+ * @see {@link useNavigationError} - Access the raw error with code and status details
+ */
+export declare function useFormattedNavigationError(): FormattedNavigationError | undefined;
+//# sourceMappingURL=errors.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../../src/features/errors.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,kBAAkB,CAAA;AAChE,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"}