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

package/lib/module/web/http/followMediaRedirect.js

@@ -0,0 +1,215 @@
+"use strict";
+
+/**
+ * Resolves a media URL that is authenticated by a header.
+ *
+ * Shaka only routes manifest requests through its networking engine, where a
+ * request filter can attach headers. A progressive file is played by assigning
+ * `mediaElement.src`, and a media element cannot send custom headers — so such
+ * a URL is unplayable that way. Following the redirect here yields the signed,
+ * public URL these endpoints hand back, which needs no auth of its own.
+ *
+ * Best effort and bounded: anything that fails — including taking too long, see
+ * {@link PROBE_TIMEOUT_MS} — falls back to the original URL, so the load fails
+ * or succeeds on its own terms rather than ours. It must never be the reason a
+ * load hangs: `load()` awaits this before Shaka sees the URL at all.
+ *
+ * Gated, because the probe is not free: a HEAD at a third-party stream host
+ * costs a CORS preflight, and most will refuse it, so an app that never
+ * authenticates its media would pay a round trip on every play for a result it
+ * always discards. It runs only for headers that look like media credentials
+ * ({@link isMediaAuth}), on media a media element actually has to play
+ * ({@link isManifestUrl}), and never on a URL the browser resolves locally.
+ */
+
+/** URLs the browser resolves locally; there is no redirect to follow. */
+const isLocalUrl = url => /^(file|blob|data|mediasource):/i.test(url);
+
+/**
+ * Extensions Shaka types as a manifest, from its own `EXTENSIONS_TO_MIME_TYPES_`
+ * map: HLS, DASH and Smooth Streaming.
+ */
+const MANIFEST_EXTENSIONS = new Set(['m3u8', 'mpd', 'ism']);
+
+/**
+ * Whether Shaka will parse this as a manifest rather than hand it to the media
+ * element — in which case the probe has nothing to offer and something to cost.
+ *
+ * A manifest goes through Shaka's networking engine, where the request filter
+ * attaches the headers to the manifest, its segments and any key requests. The
+ * probe cannot improve on that, and it actively breaks it: on a cross-origin
+ * redirect the probe clears the headers, so the segments that Android still
+ * authenticates would go out bare and 401. So this is a correctness fix as much
+ * as it is one fewer round trip.
+ *
+ * Extension-based, and therefore partial — Shaka guesses the same way
+ * (`NetworkingUtils.getExtension`), but plenty of HLS endpoints have no
+ * extension at all. Those still get probed, which is the status quo rather than
+ * a regression. Nothing on `Track` carries a MIME type to do better with.
+ */
+const isManifestUrl = url => {
+  const path = url.split(/[?#]/)[0] ?? '';
+  const filename = path.slice(path.lastIndexOf('/') + 1);
+  const pieces = filename.split('.');
+  return pieces.length > 1 && MANIFEST_EXTENSIONS.has(pieces[pieces.length - 1].toLowerCase());
+};
+/**
+ * How long the probe may take before the original URL is played instead.
+ *
+ * The same 8s the Android media client allows a connect or a read
+ * (`MediaFactory.mediaHttpClient`), which is generous for a HEAD but errs the
+ * safe way: a slow-but-working auth endpoint should not be abandoned, since
+ * giving up means playing a URL that will 401.
+ */
+const PROBE_TIMEOUT_MS = 8_000;
+
+/**
+ * `AbortSignal.timeout` where it exists (Safari 16+, Chrome 103+, Node 17.3+),
+ * else a hand-rolled equivalent, else nothing — an environment with neither
+ * still gets the deadline below, just without cancelling the request.
+ */
+const timeoutSignal = ms => {
+  if (typeof AbortSignal === 'undefined') return undefined;
+  if (typeof AbortSignal.timeout === 'function') return AbortSignal.timeout(ms);
+  if (typeof AbortController === 'undefined') return undefined;
+  const controller = new AbortController();
+  setTimeout(() => controller.abort(), ms);
+  return controller.signal;
+};
+
+/**
+ * The probe, with a deadline. `load()` awaits this before Shaka is asked to
+ * play anything, so an unreachable host would otherwise stall the load
+ * indefinitely — no audio, and no error to show for it.
+ *
+ * Two mechanisms, each with its own job: the signal cancels the request, so a
+ * dead host does not hold a connection open behind us, and the race bounds *us*
+ * even where the fetch implementation ignores the signal. Whichever fires, the
+ * caller treats it as any other probe failure and plays the original URL.
+ */
+const fetchWithDeadline = async (doFetch, url, headers, timeoutMs) => {
+  let timer;
+  try {
+    return await Promise.race([doFetch(url, {
+      method: 'HEAD',
+      headers,
+      redirect: 'follow',
+      signal: timeoutSignal(timeoutMs)
+    }), new Promise((_resolve, reject) => {
+      timer = setTimeout(() => reject(new Error(`Media redirect probe timed out (${timeoutMs}ms)`)), timeoutMs);
+    })]);
+  } finally {
+    if (timer !== undefined) clearTimeout(timer);
+  }
+};
+
+/**
+ * Whether these headers look like a media credential — the only thing the
+ * probe can fix, and the only thing worth a preflight.
+ *
+ * A header the `media` layer set is media-specific by construction. Otherwise
+ * only `Authorization` counts: an app authenticating one API for browse and
+ * media alike puts it on the shared `request` layer, and that is the common
+ * shape. Shared plumbing that also rides browse requests — an `X-Client-Version`
+ * — is not a credential and must not trigger the probe.
+ *
+ * The residual case is a shared layer carrying a custom auth header, say
+ * `X-Api-Key`, for media that needs it: move it to the `media` layer and the
+ * probe runs.
+ */
+const isMediaAuth = (headers, mediaLayerHeaders) => mediaLayerHeaders || Object.keys(headers).some(key => key.toLowerCase() === 'authorization');
+/**
+ * Origin of an http(s) URL, or undefined when it cannot be determined.
+ *
+ * Relative URLs are resolved against the document, because that is what the
+ * probe's own `fetch` does — a `src` of `/api/authed/7` is a request to the
+ * page's origin, so the credential went there. Without this a relative `src`
+ * has no origin, never matches the absolute URL the response reports, and the
+ * headers are dropped from every load that uses one.
+ *
+ * Parsed rather than pattern-matched so the comparison normalizes the way
+ * Android's `CrossOriginHeaderStripper.sameOrigin` does: `URL.host` omits a
+ * default port, so `https://a.com` and `https://a.com:443` are one origin, and
+ * it excludes userinfo, so `https://user@a.com` is not a third.
+ */
+const originOf = url => {
+  try {
+    const base = typeof location === 'undefined' ? undefined : location.href;
+    const {
+      protocol,
+      host
+    } = new URL(url, base);
+    if (protocol !== 'http:' && protocol !== 'https:') return undefined;
+    return `${protocol}//${host}`;
+  } catch {
+    return undefined;
+  }
+};
+
+/**
+ * Whether the redirect left the origin the credential was addressed to.
+ *
+ * Only when both origins are known and differ. An origin we could not work out
+ * — a relative URL with no document base, outside a browser — is not evidence
+ * of a hop, and treating it as one is how the headers went missing before.
+ */
+const leftTheOrigin = (from, to) => {
+  const origin = originOf(from);
+  return origin !== undefined && originOf(to) !== origin;
+};
+export async function followMediaRedirect(url, headers, {
+  fetchImpl,
+  mediaLayerHeaders = false,
+  timeoutMs = PROBE_TIMEOUT_MS
+} = {}) {
+  if (!headers || Object.keys(headers).length === 0) return {
+    src: url,
+    headers
+  };
+  if (!isMediaAuth(headers, mediaLayerHeaders)) return {
+    src: url,
+    headers
+  };
+  if (isManifestUrl(url)) return {
+    src: url,
+    headers
+  };
+  if (isLocalUrl(url)) return {
+    src: url,
+    headers
+  };
+  const doFetch = fetchImpl ?? globalThis.fetch;
+  if (typeof doFetch !== 'function') return {
+    src: url,
+    headers
+  };
+  try {
+    // HEAD walks the chain without tripping download counting, which keys off
+    // ranged GETs. Deadlined, because the load waits on it.
+    const response = await fetchWithDeadline(doFetch, url, headers, timeoutMs);
+    const src = response.url || url;
+
+    // The status belongs to the *last* hop, so it only speaks for the
+    // authenticating endpoint when there was no redirect. Once one has
+    // happened, hop one authenticated and handed us its target, and a refusal
+    // past that is routinely about the method rather than the credential:
+    // presigned S3 and GCS URLs sign it — SigV4's canonical request opens with
+    // HTTPMethod, GCS V4's with HTTP_VERB — so a URL signed for GET answers a
+    // HEAD with 403. Keep the signed URL, which is the whole point of the walk,
+    // and let a real error surface through the player.
+    if (!response.ok && src === url) return {
+      src: url,
+      headers
+    };
+    return {
+      src,
+      headers: leftTheOrigin(url, src) ? undefined : headers
+    };
+  } catch {
+    return {
+      src: url,
+      headers
+    };
+  }
+}
+//# sourceMappingURL=followMediaRedirect.js.map

package/lib/module/web/http/followMediaRedirect.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["isLocalUrl","url","test","MANIFEST_EXTENSIONS","Set","isManifestUrl","path","split","filename","slice","lastIndexOf","pieces","length","has","toLowerCase","PROBE_TIMEOUT_MS","timeoutSignal","ms","AbortSignal","undefined","timeout","AbortController","controller","setTimeout","abort","signal","fetchWithDeadline","doFetch","headers","timeoutMs","timer","Promise","race","method","redirect","_resolve","reject","Error","clearTimeout","isMediaAuth","mediaLayerHeaders","Object","keys","some","key","originOf","base","location","href","protocol","host","URL","leftTheOrigin","from","to","origin","followMediaRedirect","fetchImpl","src","globalThis","fetch","response","ok"],"sourceRoot":"../../../../src","sources":["web/http/followMediaRedirect.ts"],"mappings":"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","ignoreList":[]}

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

@@ -1,6 +1,7 @@
 "use strict";
 
 import { artworkUrl } from '../../utils/artwork';
+import { getTrackIdentity } from '../../utils/getTrackIdentity';
 
 /**
  * Manages now playing metadata overrides.
@@ -28,7 +29,7 @@ export class NowPlayingManager {
       album: update.album ?? currentTrack.album,
       artwork: artworkUrl(currentTrack.artwork),
       description: currentTrack.description,
-      mediaId: currentTrack.src ?? currentTrack.url,
+      mediaId: getTrackIdentity(currentTrack) ?? currentTrack.path,
       genre: currentTrack.genre,
       duration
     } : {
@@ -37,7 +38,7 @@ export class NowPlayingManager {
       album: currentTrack.album,
       artwork: artworkUrl(currentTrack.artwork),
       description: currentTrack.description,
-      mediaId: currentTrack.src ?? currentTrack.url,
+      mediaId: getTrackIdentity(currentTrack) ?? currentTrack.path,
       genre: currentTrack.genre,
       duration
     };
@@ -59,7 +60,7 @@ export class NowPlayingManager {
       album: this.override?.album ?? currentTrack.album,
       artwork: artworkUrl(currentTrack.artwork),
       description: currentTrack.description,
-      mediaId: currentTrack.src ?? currentTrack.url,
+      mediaId: getTrackIdentity(currentTrack) ?? currentTrack.path,
       genre: currentTrack.genre,
       duration
     };

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

@@ -1 +1 @@
-{"version":3,"names":["artworkUrl","NowPlayingManager","onNowPlayingChanged","updateNowPlaying","update","currentTrack","duration","override","metadata","title","artist","album","artwork","description","mediaId","src","url","genre","getNowPlaying","undefined","clearNowPlayingOverride"],"sourceRoot":"../../../../src","sources":["web/player/NowPlayingManager.ts"],"mappings":";;AAEA,SAASA,UAAU,QAAQ,qBAAqB;;AAEhD;AACA;AACA;AACA;AACA;AACA,OAAO,MAAMC,iBAAiB,CAAC;EAG7B;EACAC,mBAAmB,GAA2CA,CAAA,KAAM,CAAC,CAAC;;EAEtE;AACF;AACA;AACA;AACA;AACA;AACA;AACA;EACEC,gBAAgBA,CACdC,MAAoC,EACpCC,YAA+B,EAC/BC,QAAgB,EACV;IACN,IAAI,CAACC,QAAQ,GAAGH,MAAM;IAEtB,IAAI,CAACC,YAAY,EAAE;IAEnB,MAAMG,QAA4B,GAAGJ,MAAM,GACvC;MACEK,KAAK,EAAEL,MAAM,CAACK,KAAK,IAAIJ,YAAY,CAACI,KAAK;MACzCC,MAAM,EAAEN,MAAM,CAACM,MAAM,IAAIL,YAAY,CAACK,MAAM;MAC5CC,KAAK,EAAEP,MAAM,CAACO,KAAK,IAAIN,YAAY,CAACM,KAAK;MACzCC,OAAO,EAAEZ,UAAU,CAACK,YAAY,CAACO,OAAO,CAAC;MACzCC,WAAW,EAAER,YAAY,CAACQ,WAAW;MACrCC,OAAO,EAAET,YAAY,CAACU,GAAG,IAAIV,YAAY,CAACW,GAAG;MAC7CC,KAAK,EAAEZ,YAAY,CAACY,KAAK;MACzBX;IACF,CAAC,GACD;MACEG,KAAK,EAAEJ,YAAY,CAACI,KAAK;MACzBC,MAAM,EAAEL,YAAY,CAACK,MAAM;MAC3BC,KAAK,EAAEN,YAAY,CAACM,KAAK;MACzBC,OAAO,EAAEZ,UAAU,CAACK,YAAY,CAACO,OAAO,CAAC;MACzCC,WAAW,EAAER,YAAY,CAACQ,WAAW;MACrCC,OAAO,EAAET,YAAY,CAACU,GAAG,IAAIV,YAAY,CAACW,GAAG;MAC7CC,KAAK,EAAEZ,YAAY,CAACY,KAAK;MACzBX;IACF,CAAC;IAEL,IAAI,CAACJ,mBAAmB,CAACM,QAAQ,CAAC;EACpC;;EAEA;AACF;AACA;AACA;AACA;AACA;AACA;EACEU,aAAaA,CACXb,YAA+B,EAC/BC,QAAgB,EACgB;IAChC,IAAI,CAACD,YAAY,EAAE,OAAOc,SAAS;IAEnC,OAAO;MACLV,KAAK,EAAE,IAAI,CAACF,QAAQ,EAAEE,KAAK,IAAIJ,YAAY,CAACI,KAAK;MACjDC,MAAM,EAAE,IAAI,CAACH,QAAQ,EAAEG,MAAM,IAAIL,YAAY,CAACK,MAAM;MACpDC,KAAK,EAAE,IAAI,CAACJ,QAAQ,EAAEI,KAAK,IAAIN,YAAY,CAACM,KAAK;MACjDC,OAAO,EAAEZ,UAAU,CAACK,YAAY,CAACO,OAAO,CAAC;MACzCC,WAAW,EAAER,YAAY,CAACQ,WAAW;MACrCC,OAAO,EAAET,YAAY,CAACU,GAAG,IAAIV,YAAY,CAACW,GAAG;MAC7CC,KAAK,EAAEZ,YAAY,CAACY,KAAK;MACzBX;IACF,CAAC;EACH;;EAEA;AACF;AACA;AACA;EACEc,uBAAuBA,CAAA,EAAS;IAC9B,IAAI,CAACb,QAAQ,GAAGY,SAAS;EAC3B;AACF","ignoreList":[]}
+{"version":3,"names":["artworkUrl","getTrackIdentity","NowPlayingManager","onNowPlayingChanged","updateNowPlaying","update","currentTrack","duration","override","metadata","title","artist","album","artwork","description","mediaId","path","genre","getNowPlaying","undefined","clearNowPlayingOverride"],"sourceRoot":"../../../../src","sources":["web/player/NowPlayingManager.ts"],"mappings":";;AAEA,SAASA,UAAU,QAAQ,qBAAqB;AAChD,SAASC,gBAAgB,QAAQ,8BAA8B;;AAE/D;AACA;AACA;AACA;AACA;AACA,OAAO,MAAMC,iBAAiB,CAAC;EAG7B;EACAC,mBAAmB,GAA2CA,CAAA,KAAM,CAAC,CAAC;;EAEtE;AACF;AACA;AACA;AACA;AACA;AACA;AACA;EACEC,gBAAgBA,CACdC,MAAoC,EACpCC,YAA+B,EAC/BC,QAAgB,EACV;IACN,IAAI,CAACC,QAAQ,GAAGH,MAAM;IAEtB,IAAI,CAACC,YAAY,EAAE;IAEnB,MAAMG,QAA4B,GAAGJ,MAAM,GACvC;MACEK,KAAK,EAAEL,MAAM,CAACK,KAAK,IAAIJ,YAAY,CAACI,KAAK;MACzCC,MAAM,EAAEN,MAAM,CAACM,MAAM,IAAIL,YAAY,CAACK,MAAM;MAC5CC,KAAK,EAAEP,MAAM,CAACO,KAAK,IAAIN,YAAY,CAACM,KAAK;MACzCC,OAAO,EAAEb,UAAU,CAACM,YAAY,CAACO,OAAO,CAAC;MACzCC,WAAW,EAAER,YAAY,CAACQ,WAAW;MACrCC,OAAO,EAAEd,gBAAgB,CAACK,YAAY,CAAC,IAAIA,YAAY,CAACU,IAAI;MAC5DC,KAAK,EAAEX,YAAY,CAACW,KAAK;MACzBV;IACF,CAAC,GACD;MACEG,KAAK,EAAEJ,YAAY,CAACI,KAAK;MACzBC,MAAM,EAAEL,YAAY,CAACK,MAAM;MAC3BC,KAAK,EAAEN,YAAY,CAACM,KAAK;MACzBC,OAAO,EAAEb,UAAU,CAACM,YAAY,CAACO,OAAO,CAAC;MACzCC,WAAW,EAAER,YAAY,CAACQ,WAAW;MACrCC,OAAO,EAAEd,gBAAgB,CAACK,YAAY,CAAC,IAAIA,YAAY,CAACU,IAAI;MAC5DC,KAAK,EAAEX,YAAY,CAACW,KAAK;MACzBV;IACF,CAAC;IAEL,IAAI,CAACJ,mBAAmB,CAACM,QAAQ,CAAC;EACpC;;EAEA;AACF;AACA;AACA;AACA;AACA;AACA;EACES,aAAaA,CACXZ,YAA+B,EAC/BC,QAAgB,EACgB;IAChC,IAAI,CAACD,YAAY,EAAE,OAAOa,SAAS;IAEnC,OAAO;MACLT,KAAK,EAAE,IAAI,CAACF,QAAQ,EAAEE,KAAK,IAAIJ,YAAY,CAACI,KAAK;MACjDC,MAAM,EAAE,IAAI,CAACH,QAAQ,EAAEG,MAAM,IAAIL,YAAY,CAACK,MAAM;MACpDC,KAAK,EAAE,IAAI,CAACJ,QAAQ,EAAEI,KAAK,IAAIN,YAAY,CAACM,KAAK;MACjDC,OAAO,EAAEb,UAAU,CAACM,YAAY,CAACO,OAAO,CAAC;MACzCC,WAAW,EAAER,YAAY,CAACQ,WAAW;MACrCC,OAAO,EAAEd,gBAAgB,CAACK,YAAY,CAAC,IAAIA,YAAY,CAACU,IAAI;MAC5DC,KAAK,EAAEX,YAAY,CAACW,KAAK;MACzBV;IACF,CAAC;EACH;;EAEA;AACF;AACA;AACA;EACEa,uBAAuBA,CAAA,EAAS;IAC9B,IAAI,CAACZ,QAAQ,GAAGW,SAAS;EAC3B;AACF","ignoreList":[]}

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

@@ -8,8 +8,12 @@
  * 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"
+ * Contextual URL format: `{parentPath}?__trackId={trackIdentity}&__index={childIndex}`
+ * Example: "/library/radio?__trackId=song.mp3&__index=2"
+ *
+ * `__trackId` is the identity check; `__index` (the child's position on the
+ * page at stamp time) is only a tie-breaker between surfaces that carry the
+ * same identity — a stale index never selects a different track.
  *
  * This allows:
  * - Media3 to reference playable-only tracks (tracks with `src` but no `url`)
@@ -21,6 +25,8 @@ export const BrowserPathHelper = {
   SEARCH_PATH_PREFIX: '/__search',
   /** Query parameter name for contextual track identifiers */
   CONTEXTUAL_TRACK_PARAM: '__trackId',
+  /** Query parameter name for the tapped child's page position (tie-breaker) */
+  CONTEXTUAL_INDEX_PARAM: '__index',
   /**
    * Create a search path for a given query
    */
@@ -38,13 +44,13 @@ export const BrowserPathHelper = {
     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.
+   * Strips the contextual parameters (__trackId and __index) 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
+   * @returns The URL without the contextual parameters
    *
-   * Example: "/library/radio?__trackId=song.mp3" → "/library/radio"
+   * Example: "/library/radio?__trackId=song.mp3&__index=2" → "/library/radio"
    * Example: "/search?q=jazz&__trackId=song.mp3" → "/search?q=jazz"
    */
   stripTrackId(url) {
@@ -56,8 +62,9 @@ export const BrowserPathHelper = {
       const isFullUrl = url.startsWith('http://') || url.startsWith('https://');
       const urlObj = new URL(url, isFullUrl ? undefined : 'http://placeholder');
 
-      // Remove the __trackId parameter
+      // Remove the contextual parameters
       urlObj.searchParams.delete(this.CONTEXTUAL_TRACK_PARAM);
+      urlObj.searchParams.delete(this.CONTEXTUAL_INDEX_PARAM);
 
       // Return the appropriate format
       if (isFullUrl) {
@@ -68,7 +75,7 @@ export const BrowserPathHelper = {
       }
     } catch {
       // Fallback: simple string manipulation
-      const paramPattern = new RegExp(`[?&]${this.CONTEXTUAL_TRACK_PARAM}=[^&]*`, 'g');
+      const paramPattern = new RegExp(`[?&](?:${this.CONTEXTUAL_TRACK_PARAM}|${this.CONTEXTUAL_INDEX_PARAM})=[^&]*`, 'g');
       let result = url.replace(paramPattern, '');
       // Clean up any trailing ? or &
       result = result.replace(/[?&]$/, '');
@@ -77,6 +84,22 @@ export const BrowserPathHelper = {
       return result;
     }
   },
+  /**
+   * Builds a contextual URL by appending a track identifier — and optionally
+   * the tapped child's page position — to a parent path.
+   *
+   * @param parentPath The parent container path
+   * @param trackId The track identity (`id` when non-blank, else `src`)
+   * @param index The child's position on the page at stamp time (tie-breaker)
+   * @returns A contextual URL combining parent path, track ID, and index
+   *
+   * Example: build("/library", "song.mp3", 2) → "/library?__trackId=song.mp3&__index=2"
+   */
+  build(parentPath, trackId, index) {
+    const separator = parentPath.includes('?') ? '&' : '?';
+    const indexParam = index === undefined ? '' : `&${this.CONTEXTUAL_INDEX_PARAM}=${index}`;
+    return `${parentPath}${separator}${this.CONTEXTUAL_TRACK_PARAM}=${encodeURIComponent(trackId)}${indexParam}`;
+  },
   /**
    * Extracts the track ID from a contextual URL.
    * Returns undefined if the URL is not contextual or doesn't contain the track ID parameter.
@@ -90,14 +113,36 @@ export const BrowserPathHelper = {
     if (!this.isContextual(path)) {
       return undefined;
     }
+    return this.extractParam(path, this.CONTEXTUAL_TRACK_PARAM);
+  },
+  /**
+   * Extracts the stamped page index from a contextual URL, or undefined when
+   * the URL is not contextual or carries no (valid, non-negative) index.
+   *
+   * Example: "/library/radio?__trackId=song.mp3&__index=2" → 2
+   */
+  extractIndex(path) {
+    if (!this.isContextual(path)) {
+      return undefined;
+    }
+    const raw = this.extractParam(path, this.CONTEXTUAL_INDEX_PARAM);
+    if (raw === undefined || !/^\d+$/.test(raw)) {
+      return undefined;
+    }
+    return Number.parseInt(raw, 10);
+  },
+  /**
+   * Extracts a single query parameter, handling both full URLs and paths,
+   * with a regex fallback for input the URL parser rejects.
+   */
+  extractParam(path, param) {
     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;
+      return urlObj.searchParams.get(param) ?? undefined;
     } catch {
       // Fallback: regex extraction
-      const match = path.match(new RegExp(`[?&]${this.CONTEXTUAL_TRACK_PARAM}=([^&]*)`));
+      const match = path.match(new RegExp(`[?&]${param}=([^&]*)`));
       return match?.[1] ? decodeURIComponent(match[1]) : undefined;
     }
   },

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

@@ -1 +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":"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","ignoreList":[]}
+{"version":3,"names":["BrowserPathHelper","SEARCH_PATH_PREFIX","CONTEXTUAL_TRACK_PARAM","CONTEXTUAL_INDEX_PARAM","createSearchPath","query","encodedQuery","encodeURIComponent","isContextual","path","includes","stripTrackId","url","isFullUrl","startsWith","urlObj","URL","undefined","searchParams","delete","toString","search","pathname","paramPattern","RegExp","result","replace","build","parentPath","trackId","index","separator","indexParam","extractTrackId","extractParam","extractIndex","raw","test","Number","parseInt","param","get","match","decodeURIComponent","buildUrl","baseUrl","normalizedBase","normalizedPath"],"sourceRoot":"../../../../src","sources":["web/util/BrowserPathHelper.ts"],"mappings":"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","ignoreList":[]}

package/lib/typescript/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

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

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

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

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

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

@@ -1 +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"}
+{"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;AA2KhC,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,CAqB5B"}

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

@@ -33,8 +33,8 @@ import { NativeUpdatedValue } from '../utils/NativeUpdatedValue';
  *     }
  *   },
  *   tabs: [
- *     { title: 'Home', url: '/' },
- *     { title: 'Search', url: '/search' }
+ *     { title: 'Home', path: '/' },
+ *     { title: 'Search', path: '/search' }
  *   ]
  * })
  * ```
@@ -92,8 +92,16 @@ export declare function hasSearch(): boolean;
 /**
  * Searches for tracks using the configured search source.
  *
+ * Resolves `[]` only when the source found nothing; a failed search rejects,
+ * so a caller can tell "no results" from "the request failed". The rejection's
+ * message describes the failure — native platforms reject with the underlying
+ * throwable and JS sees only its message. On web the `Error` also carries a
+ * `code`, the {@link NavigationErrorType} the browse path reports as a
+ * {@link NavigationError} (`'http-error'`, `'network-error'`).
+ *
  * @param query - The search query string
  * @returns Promise resolving to an array of matching tracks
+ * @throws When the search source or its request fails
  *
  * @see {@link configureBrowser}
  *

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,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"}
+{"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;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,EAAE,CAAC,CAE5D"}

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

@@ -9,7 +9,7 @@ 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
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export declare const onCarConnectedChanged: NativeUpdatedValue<boolean>;
 /**

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

@@ -24,7 +24,7 @@ export declare function setEqualizerLevels(levels: number[]): void;
 /**
  * Subscribes to equalizer settings changes (Android only).
  * @param callback - Called when equalizer settings change
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export declare const onEqualizerChanged: NativeUpdatedValue<EqualizerSettings>;
 /**

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

@@ -101,7 +101,7 @@ export declare function getPlaybackError(): PlaybackError | undefined;
 /**
  * Subscribes to playback error events.
  * @param callback - Called when a playback error occurs
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export declare const onPlaybackError: NativeUpdatedValue<PlaybackErrorEvent>;
 /**
@@ -117,7 +117,7 @@ export declare function getNavigationError(): NavigationError | undefined;
 /**
  * Subscribes to navigation error events.
  * @param callback - Called when a navigation error occurs
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export declare const onNavigationError: NativeUpdatedValue<NavigationErrorEvent>;
 /**
@@ -136,7 +136,7 @@ export declare function getFormattedNavigationError(): FormattedNavigationError
 /**
  * Subscribes to formatted navigation error changes.
  * @param callback - Called when the formatted navigation error changes
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export declare const onFormattedNavigationError: NativeUpdatedValue<FormattedNavigationError | undefined>;
 /**

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

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

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

@@ -1 +1 @@
-{"version":3,"file":"favorites.d.ts","sourceRoot":"","sources":["../../../../src/features/favorites.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,UAAU,CAAA;AAErC,OAAO,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAA;AAIhE;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,OAAO,GAAG,IAAI,CAEhE;AAED;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,IAAI,IAAI,CAEjD;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,IAAI,CAEtD;AAID;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC,8CAA8C;IAC9C,KAAK,EAAE,KAAK,CAAA;IACZ,8BAA8B;IAC9B,SAAS,EAAE,OAAO,CAAA;CACnB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,iBAAiB,0CAG3B,CAAA"}
+{"version":3,"file":"favorites.d.ts","sourceRoot":"","sources":["../../../../src/features/favorites.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,UAAU,CAAA;AAErC,OAAO,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAA;AAIhE;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,OAAO,GAAG,IAAI,CAEhE;AAED;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,IAAI,IAAI,CAEjD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,IAAI,CAEtD;AAID;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC,8CAA8C;IAC9C,KAAK,EAAE,KAAK,CAAA;IACZ,8BAA8B;IAC9B,SAAS,EAAE,OAAO,CAAA;CACnB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,iBAAiB,0CAG3B,CAAA"}

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

@@ -1,4 +1,5 @@
 import type { SearchParams } from '../types/browser';
+import { LazyNativeEmitter } from '../utils/LazyNativeEmitter';
 /** Discriminant for gate requests and events. */
 export type GateReason = 'browse' | 'search';
 /**
@@ -57,21 +58,36 @@ export type GateResolver = (request: GateRequest) => Gate | boolean;
  * some surfaces (CarPlay) any gate change pops pushed navigation back to root,
  * so a page the user had drilled into is reset to the tab root. Set the gate
  * before the car connects and it'll be there the moment it does.
+ *
+ * @platform ios android
+ * A no-op on web, which has no CarPlay or Android Auto surfaces for the gate to
+ * cover. Nothing is lost: the gate never covered in-app browse UI on any
+ * platform — that stays yours to gate.
  */
 export declare function setGate(gate: Gate, resolve?: GateResolver): void;
 /**
  * Raises the gate with a resolver only (no default chrome).
  * The resolver must return a {@link Gate} or `true` for gated requests;
  * native uses the built-in fallback chrome when `true` and no default is set.
+ *
+ * @platform ios android
+ * A no-op on web — the resolver is never consulted there.
  */
 export declare function setGate(resolve: GateResolver): void;
 /**
  * Drops the gate — the real content comes back, and the current tab is kept.
+ *
+ * @platform ios android
+ * A no-op on web, where no gate was ever raised.
  */
 export declare function clearGate(): void;
 /**
  * Subscribes to gate events (fired when a request is gated).
- * @returns Cleanup function to unsubscribe.
+ *
+ * @platform ios android
+ * Never fires on web — there are no gated serves to report.
+ *
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
-export declare const onGate: (callback: (arg: GateEvent) => void) => () => void;
+export declare const onGate: LazyNativeEmitter<GateEvent>;
 //# sourceMappingURL=gate.d.ts.map

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

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