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

package/lib/commonjs/utils/NativeUpdatedValue.js

@@ -5,29 +5,39 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.NativeUpdatedValue = void 0;
 /**
- * Bridges native value changes to JavaScript, storing the latest value for immediate access.
+ * The subscription object behind the library's **state** events — every
+ * `on<Thing>Changed`-style export (`onPlaybackChanged`, `onQueueChanged`, …)
+ * is one of these. Subscribe with {@link addListener}; the returned function
+ * unsubscribes. The emitter is not callable itself.
  *
- * Subscribes to native changes immediately at module load to ensure no updates are missed.
- * The `lastValue` property caches the most recent value, allowing hooks to read the current
- * state synchronously without calling a separate getter function.
- *
- * Use this for state-based values that have a "current value" (playback state, options, progress).
- * For discrete events without a current value (remote controls), use LazyNativeEmitter instead.
+ * It tracks a value that always has a *current* reading (playback state,
+ * progress, options): {@link lastValue} caches the most recent one so hooks —
+ * and you — can read it synchronously without a getter round-trip. Discrete
+ * events with no current value (remote-control presses) use
+ * `LazyNativeEmitter` instead.
  *
  * @example
  * ```typescript
- * export const onPlaybackChanged = NativeUpdatedValue.emitterize<Playback>(
- *   (cb) => (nativeBrowser.onPlaybackChanged = cb)
- * )
+ * import { onPlaybackChanged } from 'react-native-audio-browser'
  *
- * export function usePlayback(): Playback {
- *   return useUpdatedNativeValue(getPlayback, onPlaybackChanged)
- * }
+ * const unsubscribe = onPlaybackChanged.addListener((p) => {
+ *   console.log(p.state)
+ * })
+ * // later:
+ * unsubscribe()
  * ```
  */
 class NativeUpdatedValue {
   listeners = new Set();
+
+  /**
+   * The most recent value delivered by native, or `undefined` before the
+   * first update. Subscription starts at module load, so this is safe to
+   * read synchronously at any time.
+   */
   lastValue = undefined;
+
+  /** @internal */
   constructor(setter) {
     // Install native callback immediately at module load
     setter(data => {
@@ -37,6 +47,13 @@ class NativeUpdatedValue {
       }
     });
   }
+
+  /**
+   * Subscribes to value changes.
+   *
+   * @param callback - Invoked with each new value
+   * @returns A function that removes the listener
+   */
   addListener(callback) {
     this.listeners.add(callback);
     return () => this.listeners.delete(callback);
@@ -47,6 +64,7 @@ class NativeUpdatedValue {
    *
    * @param setter - Function that sets the native callback property
    * @returns The subscription instance with lastValue and addListener
+   * @internal
    */
   static emitterize(setter) {
     return new NativeUpdatedValue(setter);

package/lib/commonjs/utils/NativeUpdatedValue.js.map

@@ -1 +1 @@
-{"version":3,"names":["NativeUpdatedValue","listeners","Set","lastValue","undefined","constructor","setter","data","listener","addListener","callback","add","delete","emitterize","exports"],"sourceRoot":"../../../src","sources":["utils/NativeUpdatedValue.ts"],"mappings":";;;;;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,MAAMA,kBAAkB,CAAI;EACzBC,SAAS,GAAG,IAAIC,GAAG,CAAc,CAAC;EAC1CC,SAAS,GAAkBC,SAAS;EAEpCC,WAAWA,CAACC,MAA6C,EAAE;IACzD;IACAA,MAAM,CAAEC,IAAO,IAAK;MAClB,IAAI,CAACJ,SAAS,GAAGI,IAAI;MACrB,KAAK,MAAMC,QAAQ,IAAI,IAAI,CAACP,SAAS,EAAE;QACrCO,QAAQ,CAACD,IAAI,CAAC;MAChB;IACF,CAAC,CAAC;EACJ;EAEAE,WAAWA,CAACC,QAAqB,EAAc;IAC7C,IAAI,CAACT,SAAS,CAACU,GAAG,CAACD,QAAQ,CAAC;IAC5B,OAAO,MAAM,IAAI,CAACT,SAAS,CAACW,MAAM,CAACF,QAAQ,CAAC;EAC9C;;EAEA;AACF;AACA;AACA;AACA;AACA;EACE,OAAOG,UAAUA,CACfP,MAA6C,EACtB;IACvB,OAAO,IAAIN,kBAAkB,CAACM,MAAM,CAAC;EACvC;AACF;AAACQ,OAAA,CAAAd,kBAAA,GAAAA,kBAAA","ignoreList":[]}
+{"version":3,"names":["NativeUpdatedValue","listeners","Set","lastValue","undefined","constructor","setter","data","listener","addListener","callback","add","delete","emitterize","exports"],"sourceRoot":"../../../src","sources":["utils/NativeUpdatedValue.ts"],"mappings":";;;;;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,MAAMA,kBAAkB,CAAI;EACzBC,SAAS,GAAG,IAAIC,GAAG,CAAc,CAAC;;EAE1C;AACF;AACA;AACA;AACA;EACEC,SAAS,GAAkBC,SAAS;;EAEpC;EACAC,WAAWA,CAACC,MAA6C,EAAE;IACzD;IACAA,MAAM,CAAEC,IAAO,IAAK;MAClB,IAAI,CAACJ,SAAS,GAAGI,IAAI;MACrB,KAAK,MAAMC,QAAQ,IAAI,IAAI,CAACP,SAAS,EAAE;QACrCO,QAAQ,CAACD,IAAI,CAAC;MAChB;IACF,CAAC,CAAC;EACJ;;EAEA;AACF;AACA;AACA;AACA;AACA;EACEE,WAAWA,CAACC,QAAqB,EAAc;IAC7C,IAAI,CAACT,SAAS,CAACU,GAAG,CAACD,QAAQ,CAAC;IAC5B,OAAO,MAAM,IAAI,CAACT,SAAS,CAACW,MAAM,CAACF,QAAQ,CAAC;EAC9C;;EAEA;AACF;AACA;AACA;AACA;AACA;AACA;EACE,OAAOG,UAAUA,CACfP,MAA6C,EACtB;IACvB,OAAO,IAAIN,kBAAkB,CAACM,MAAM,CAAC;EACvC;AACF;AAACQ,OAAA,CAAAd,kBAAA,GAAAA,kBAAA","ignoreList":[]}

package/lib/commonjs/utils/getTrackIdentity.js

@@ -0,0 +1,24 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.getTrackIdentity = getTrackIdentity;
+/**
+ * A track's identity: its opaque `id` when present (non-blank), falling back
+ * to the playable `src`. Two tracks refer to the same item exactly when their
+ * identities are equal. Browsable-only tracks (neither `id` nor `src`) have
+ * no identity — they are addressed by their `path` instead.
+ *
+ * This is the same comparison the library uses everywhere it matches tracks:
+ * favorites (`setFavorites`), the CarPlay / Android Auto "now playing" row
+ * indicator, and queue expansion and in-place skipping when a track is
+ * selected from browse content. Use it for your own bookkeeping — keying a
+ * favorites collection, deduplicating history — so your comparisons agree
+ * with the library's.
+ */
+// Decision record: ADR 0008 (docs/adr/).
+function getTrackIdentity(track) {
+  return track.id?.length ? track.id : track.src;
+}
+//# sourceMappingURL=getTrackIdentity.js.map

package/lib/commonjs/utils/getTrackIdentity.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["getTrackIdentity","track","id","length","src"],"sourceRoot":"../../../src","sources":["utils/getTrackIdentity.ts"],"mappings":";;;;;;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAASA,gBAAgBA,CAACC,KAGhC,EAAsB;EACrB,OAAOA,KAAK,CAACC,EAAE,EAAEC,MAAM,GAAGF,KAAK,CAACC,EAAE,GAAGD,KAAK,CAACG,GAAG;AAChD","ignoreList":[]}

package/lib/commonjs/utils/useNativeValueRefreshedBy.js

@@ -0,0 +1,33 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.useNativeValueRefreshedBy = useNativeValueRefreshedBy;
+var _react = require("react");
+/**
+ * Hook for a native-fetched value that must stay fresh across SEVERAL event
+ * sources — e.g. the active track, which changes on a queue transition
+ * (`onActiveTrackChanged`) but is also mutated in place by a favorite toggle
+ * (`onFavoriteChanged`).
+ *
+ * Unlike {@link useNativeUpdatedValue}, this never reads a cached event
+ * payload: every trigger re-reads `getter()`, and the mount effect re-reads
+ * once after the subscriptions attach (so an event firing between render and
+ * effect cannot be missed). The getters are cheap synchronous Nitro calls.
+ *
+ * @param getter - Synchronous native getter for the current value
+ * @param emitters - Event sources that invalidate the value (a stable,
+ *   module-level array — identity changes resubscribe)
+ */
+function useNativeValueRefreshedBy(getter, emitters) {
+  const [value, setValue] = (0, _react.useState)(getter);
+  (0, _react.useEffect)(() => {
+    setValue(getter());
+    const cleanups = emitters.map(emitter => emitter.addListener(() => setValue(getter())));
+    return () => cleanups.forEach(cleanup => cleanup());
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [getter, ...emitters]);
+  return value;
+}
+//# sourceMappingURL=useNativeValueRefreshedBy.js.map

package/lib/commonjs/utils/useNativeValueRefreshedBy.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["_react","require","useNativeValueRefreshedBy","getter","emitters","value","setValue","useState","useEffect","cleanups","map","emitter","addListener","forEach","cleanup"],"sourceRoot":"../../../src","sources":["utils/useNativeValueRefreshedBy.ts"],"mappings":";;;;;;AAAA,IAAAA,MAAA,GAAAC,OAAA;AAMA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAASC,yBAAyBA,CACvCC,MAAe,EACfC,QAAiC,EAC9B;EACH,MAAM,CAACC,KAAK,EAAEC,QAAQ,CAAC,GAAG,IAAAC,eAAQ,EAACJ,MAAM,CAAC;EAE1C,IAAAK,gBAAS,EAAC,MAAM;IACdF,QAAQ,CAACH,MAAM,CAAC,CAAC,CAAC;IAClB,MAAMM,QAAQ,GAAGL,QAAQ,CAACM,GAAG,CAAEC,OAAO,IACpCA,OAAO,CAACC,WAAW,CAAC,MAAMN,QAAQ,CAACH,MAAM,CAAC,CAAC,CAAC,CAC9C,CAAC;IACD,OAAO,MAAMM,QAAQ,CAACI,OAAO,CAAEC,OAAO,IAAKA,OAAO,CAAC,CAAC,CAAC;IACrD;EACF,CAAC,EAAE,CAACX,MAAM,EAAE,GAAGC,QAAQ,CAAC,CAAC;EAEzB,OAAOC,KAAK;AACd","ignoreList":[]}

package/lib/commonjs/web/NativeAudioBrowser.js

@@ -4,11 +4,13 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.NativeAudioBrowser = void 0;
+var _getTrackIdentity = require("../utils/getTrackIdentity");
 var _BrowserManager = require("./browser/BrowserManager");
 var _classifyTrackNavigation = require("./browser/classifyTrackNavigation");
 var _FavoriteManager = require("./browser/FavoriteManager");
 var _NavigationErrorManager = require("./browser/NavigationErrorManager");
 var _SearchManager = require("./browser/SearchManager");
+var _followMediaRedirect = require("./http/followMediaRedirect");
 var _HttpClient = require("./http/HttpClient");
 var _RequestConfigBuilder = require("./http/RequestConfigBuilder");
 var _NowPlayingManager = require("./player/NowPlayingManager");
@@ -17,6 +19,7 @@ var _RemoteCommandController = require("./player/RemoteCommandController");
 var _TrackPlayer = require("./TrackPlayer");
 var _PlaybackTimer = require("./TrackPlayer/PlaybackTimer");
 var _PlayingStateFactory = require("./TrackPlayer/PlayingStateFactory");
+var _BrowserPathHelper = require("./util/BrowserPathHelper");
 /**
  * Web implementation of AudioBrowser (unified browser + player)
  */
@@ -42,7 +45,6 @@ class NativeAudioBrowser extends _TrackPlayer.QueuePlayer {
   // Managers
 
   // Player state
-  currentLoadId = 0;
   progressTimer = new _PlaybackTimer.PlaybackTimer();
   intervalTimer = new _PlaybackTimer.PlaybackTimer();
   _online = typeof navigator !== 'undefined' ? navigator.onLine : true;
@@ -209,6 +211,13 @@ class NativeAudioBrowser extends _TrackPlayer.QueuePlayer {
       this.onPlaybackError({
         error: newState.error
       });
+    } else if (oldState.state === 'error') {
+      // Leaving the error state clears it, as it does natively. The getter
+      // already reads undefined — consumers subscribe to the event, so without
+      // this a stale error outlives the next successful load.
+      this.onPlaybackError({
+        error: undefined
+      });
     }
   }
   /**
@@ -296,16 +305,27 @@ class NativeAudioBrowser extends _TrackPlayer.QueuePlayer {
    * Attempts to skip to a track already in the current queue.
    * Used as an optimization to avoid re-expanding the queue.
    *
-   * @param trackId The track's src identifier
+   * @param track The tapped track (its contextual path pins the exact copy)
+   * @param trackId The track's identity (id, falling back to src)
    * @param parentPath The parent path to check against queueSourcePath
    * @returns true if successfully skipped to existing track, false otherwise
    */
-  async trySkipToExistingQueueTrack(trackId, parentPath) {
+  async trySkipToExistingQueueTrack(track, trackId, parentPath) {
     if (parentPath !== this.browserManager.queueSourcePath) {
       return false;
     }
+
+    // Exact-surface match first: a contextual path carries the tapped page
+    // position (__index), so path equality pins the exact copy when the page
+    // holds the same identity more than once. The identity match remains for
+    // index-less paths (e.g. pre-stamp persisted state); an index-stamped path
+    // with no exact match falls through to expansion, which re-scopes the
+    // queue to the tapped section.
     const queue = this.getQueue();
-    const index = queue.findIndex(t => t.src === trackId);
+    let index = queue.findIndex(t => t.path != null && t.path === track.path);
+    if (index < 0 && track.path != null && _BrowserPathHelper.BrowserPathHelper.extractIndex(track.path) === undefined) {
+      index = queue.findIndex(t => (0, _getTrackIdentity.getTrackIdentity)(t) === trackId);
+    }
     if (index < 0) {
       return false;
     }
@@ -344,11 +364,15 @@ class NativeAudioBrowser extends _TrackPlayer.QueuePlayer {
    */
   async navigateTrackAsync(track) {
     try {
+      // A disabled track is unavailable — it never plays, whichever surface
+      // or stale resume path delivered the selection (Track.disabled; mirrors
+      // iOS TrackSelector.select and Android navigateTrack).
+      if (track.disabled === true) return;
       const nav = (0, _classifyTrackNavigation.classifyTrackNavigation)(track);
       switch (nav.kind) {
         case 'contextual':
           // Optimization: skip to the track if it's already in the queue.
-          if (nav.trackId && (await this.trySkipToExistingQueueTrack(nav.trackId, nav.parentPath))) {
+          if (nav.trackId && (await this.trySkipToExistingQueueTrack(track, nav.trackId, nav.parentPath))) {
             return;
           }
           // Otherwise expand the queue from the contextual URL, falling back to
@@ -365,7 +389,7 @@ class NativeAudioBrowser extends _TrackPlayer.QueuePlayer {
           await this.playSingleTrack(track);
           return;
         case 'invalid':
-          throw new Error("Track must have either 'url' or 'src' property");
+          throw new Error("Track must have either 'path' or 'src' property");
       }
     } catch (error) {
       const message = error instanceof Error ? error.message : 'Unknown error';
@@ -380,7 +404,7 @@ class NativeAudioBrowser extends _TrackPlayer.QueuePlayer {
       this.play();
     });
   }
-  async onSearch(query) {
+  async search(query) {
     // Wrap query string in SearchParams (matches Android's search(query: String) overload)
     return this.searchManager.search({
       query,
@@ -438,68 +462,101 @@ class NativeAudioBrowser extends _TrackPlayer.QueuePlayer {
    * Supports the transform callback for URL manipulation.
    * Mirrors Android's MediaFactory.getMediaRequestConfig behavior.
    */
-  async resolveMediaUrl(src) {
+  async resolveMediaRequest(src, track) {
+    // The *resolved* request layer, not `configuration.request`: a
+    // resolver-only config would otherwise reach media with no baseUrl and no
+    // headers. Browse, search and browse artwork all read it this way too.
+    //
+    // Caught, because unlike those three this one cannot fail the load: a
+    // resolver hiccup — a token refresh timing out — would otherwise take down
+    // a track whose `src` is already absolute and public and needed no layer at
+    // all. Native degrades the same way, `getMediaRequestConfig` returning null
+    // and the original URL playing on.
+    let request;
+    try {
+      request = await this.browserManager.resolvedRequestConfig();
+    } catch (e) {
+      console.error('Failed to resolve the request layer for media', e);
+    }
     const {
-      request,
       media
     } = this.browserManager.configuration;
-    return _RequestConfigBuilder.RequestConfigBuilder.resolveMediaUrl(src, request, media);
+    return _RequestConfigBuilder.RequestConfigBuilder.resolveMediaRequest(src, request, media, track);
   }
 
   /**
-   * Reload from the queue's own entry, whose `src` is still unresolved —
-   * `current` holds the resolved track, and re-feeding it into `load()` would
-   * re-resolve the resolved URL (double-applying a `transform`) and replace
-   * the queue entry with it.
+   * The queue's own entry, so the queue stays the source of truth for what is
+   * playing. `current` preserves the track as queued — the resolved URL is
+   * passed to `load()` separately — so either is safe to re-feed.
    */
-  reloadCurrent() {
+  trackToReload() {
     const index = this.queue.currentIndex;
-    const sourceTrack = index !== undefined ? this.queue.getTrack(index) : undefined;
-    if (sourceTrack) {
-      this.load(sourceTrack);
-    } else {
-      super.reloadCurrent();
-    }
+    const queued = index !== undefined ? this.queue.getTrack(index) : undefined;
+    // The queue entry wins, so it stays the source of truth for what is
+    // playing; `current` is the fallback for a player loaded without one.
+    return queued ?? super.trackToReload();
   }
-  load(track, callback) {
-    const element = this.requireElement();
-
-    // Clear now playing override when track changes (matches Android's PlayerListener.onMediaItemTransition)
-    this.nowPlayingManager.clearNowPlayingOverride();
 
-    // Match Android: load() modifies the queue.
-    // If queue is empty, add the track. If queue has items, replace at currentIndex.
+  /**
+   * Makes `track` the queue's current entry, emitting the change.
+   *
+   * Matches Android, where `load()` modifies the queue: an empty queue takes
+   * the track as its only entry, a populated one has its current entry
+   * replaced.
+   */
+  syncQueueTo(track) {
     if (this.queue.length === 0) {
       this.queue.setTracks([track]);
       this.queue.currentIndex = 0;
       this.emitQueueChanged();
-    } else if (this.queue.currentIndex !== undefined && this.queue.getTrack(this.queue.currentIndex) !== track) {
+      return;
+    }
+    if (this.queue.currentIndex !== undefined && this.queue.getTrack(this.queue.currentIndex) !== track) {
       this.queue.replaceTrack(this.queue.currentIndex, track);
       this.emitQueueChanged();
     }
+  }
+
+  /**
+   * Everything native does in its media-item transition, all of it before any
+   * network work: announce the new track, publish its now-playing metadata,
+   * cut the outgoing one, and report `loading`.
+   *
+   * Android's `onMediaItemTransition` fires at `prepare()` and does exactly
+   * this, with its LOADING following from `onEvents`; resolution happens later
+   * still, inside `TransformingDataSource.open()`. Doing it here rather than
+   * after the URL resolves is what gives the resolution window a state, and
+   * keeps `activeTrack` ahead of `loading` — the order a consumer that reads
+   * `getActiveTrack()` on the loading edge depends on.
+   */
+  transitionTo(track) {
+    const element = this.requireElement();
     const lastTrack = this.current;
     const lastPosition = element.currentTime;
     const lastIndex = this.queue.lastIndex;
     const currentIndex = this.queue.currentIndex;
 
-    // Set loading flag early so seekTo() calls during async URL resolution
-    // are captured as pending seeks rather than silently dropped
-    this._loadInProgress = true;
-    this._pendingSeek = undefined;
+    // A re-prepare of the item already current is not a transition, and must
+    // not be announced as one: ExoPlayer's `prepare()` does not re-fire
+    // `onMediaItemTransition` for an unchanged media item, so a consumer that
+    // resets on a track change would have its UI wiped by every retry. The
+    // `lastTrack === track` payload was the tell.
+    const isTransition = this.current !== track;
 
-    // Resolve the media URL before loading (async but we don't await)
-    const loadId = ++this.currentLoadId;
-    const doLoad = async () => {
-      const resolvedTrack = track.src ? {
-        ...track,
-        src: await this.resolveMediaUrl(track.src)
-      } : track;
-
-      // A newer load() was called while resolving — discard this stale result
-      if (loadId !== this.currentLoadId) {
-        return;
-      }
-      super.load(resolvedTrack, loadedTrack => {
+    // `current` first, so `getActiveTrack()` already reads the new track inside
+    // a handler and so `getNowPlaying()` publishes the new track's metadata. It
+    // also stops `getActiveTrackIndex()` — which moved with the queue already,
+    // synchronously — from disagreeing with it for the length of the
+    // resolution.
+    this.current = track;
+
+    // Separately guarded: a throwing consumer handler must not skip the
+    // publish, and neither may fail the load.
+    if (isTransition) {
+      // As Android's onMediaItemTransition does: a new item is a clean slate,
+      // a retry of the same one keeps what the consumer set.
+      this.nowPlayingManager.clearNowPlayingOverride();
+      try {
         this.onPlaybackActiveTrackChanged({
           lastTrack,
           lastPosition,
@@ -507,24 +564,101 @@ class NativeAudioBrowser extends _TrackPlayer.QueuePlayer {
           index: currentIndex,
           track
         });
-
-        // Update now playing metadata
+      } catch (error) {
+        console.error('Failed to announce the active track change:', error);
+      }
+      try {
+        // Once, here: duration reaches the media session through
+        // `updateProgress()` on each tick, so only metadata needs publishing.
+        // Android publishes from the same transition handler that announces.
         const nowPlaying = this.getNowPlaying();
         if (nowPlaying) {
           this.publishNowPlaying(nowPlaying);
         }
+      } catch (error) {
+        console.error('Failed to publish now-playing metadata:', error);
+      }
+    }
+
+    // Stop the outgoing track now rather than when Shaka eventually gets a URL.
+    // Announcing the new track while the old one is still audible is worse than
+    // the silence, and native has no such window — prepare() cuts the old item
+    // at the moment it announces. This adds no teardown: `player.load()`
+    // already unloads first (shaka player.js:1757-1762). It only moves when.
+    // Verified in a real browser to emit no `pause`, so no state comes of it.
+    this.requirePlayer().unload().catch(error => console.error('Failed to unload the previous track:', error));
+
+    // Loading covers the resolution too. Shaka dispatches its own `loading`
+    // once `player.load()` is called — after resolution — and the state setter
+    // drops that as a no-op. The `buffering` that follows is Shaka's to report.
+    this.dispatch({
+      type: 'trackLoading'
+    });
+  }
+  load(track, callback) {
+    // Before the queue is touched, so a load before `setupPlayer()` throws
+    // rather than half-applying.
+    this.requireElement();
+    this.syncQueueTo(track);
+
+    // Begun here, at the call, so a newer load supersedes this one immediately
+    // rather than once its own URL has resolved. Both continuations below carry
+    // it, as does `super.load()`.
+    const attempt = this.beginLoadAttempt();
+    // Read now: `reloadCurrent` holds the flag only for this synchronous call,
+    // and `super.load()` runs after the URL has resolved.
+    const reprepare = this._repreparing;
 
+    // Loading ends being stopped. `dispatch()` drops every event while
+    // `_isStopped`, to keep Shaka's teardown noise off the stopped state, so
+    // the `trackLoading` in `transitionTo` would be swallowed on the stop → play
+    // path and the resolution window would report nothing. `super.load()` clears
+    // this too, but only after the URL resolves.
+    this._isStopped = false;
+
+    // Set loading flag early so seekTo() calls during async URL resolution
+    // are captured as pending seeks rather than silently dropped
+    this._loadInProgress = true;
+    this._pendingSeek = undefined;
+    this.transitionTo(track);
+
+    // Resolve the media URL before loading (async but we don't await)
+    const doLoad = async () => {
+      const resolvedRequest = track.src ? await this.resolveMediaRequest(track.src, track) : undefined;
+      // Web-only, and forced: a progressive file plays via `mediaElement.src`,
+      // which cannot carry headers. Native sends them with the media request
+      // and follows the redirect inline, so it needs none of this.
+      const resolvedMedia = resolvedRequest ? await (0, _followMediaRedirect.followMediaRedirect)(resolvedRequest.path ?? track.src, resolvedRequest.headers, {
+        mediaLayerHeaders: resolvedRequest.mediaLayerHeaders
+      }) : undefined;
+
+      // Something took over while the URL was resolving — discard this result
+      if (!attempt.isCurrent) return;
+      super.load(track, loadedTrack => {
         // Call the provided callback if any
         if (callback) {
           callback(loadedTrack);
         }
+      }, {
+        headers: resolvedMedia?.headers,
+        src: resolvedMedia?.src,
+        attempt,
+        reprepare
       });
     };
 
     // Execute async load without blocking, with error handling
     doLoad().catch(error => {
-      // Only the active load may surface a resolution failure.
-      if (loadId !== this.currentLoadId) return;
+      // A backstop with no reachable trigger today, kept because an unhandled
+      // rejection would be worse than a dead branch. Every await inside
+      // `doLoad` catches internally; `shaka.Player.load` is `async`, so it
+      // rejects rather than throwing and its rejection is handled against the
+      // attempt inside `Player.load`; and `this.player` is only ever assigned,
+      // so `requirePlayer()` cannot start succeeding and then fail mid-load.
+      //
+      // No attempt check either, for the same reason it would be dead: nothing
+      // awaits between the guard above and `super.load()`, so the attempt
+      // cannot have changed. Add an await there and this needs the check back.
       this._loadInProgress = false;
       this._pendingSeek = undefined;
       console.error('Error loading track:', error);
@@ -687,10 +821,8 @@ class NativeAudioBrowser extends _TrackPlayer.QueuePlayer {
     this.clearSleepTimerIfFading();
   }
   stop() {
-    // Invalidate any in-flight load: its post-await continuation would call
-    // super.load(), whose first line re-arms the player (_isStopped = false)
-    // and revives the state out of Stopped.
-    this.currentLoadId++;
+    // `Player.stop()` cancels the load attempt, so an in-flight load's
+    // continuation cannot re-arm the player and revive it out of Stopped.
     super.stop();
     this.clearSleepTimerIfFading();
   }
@@ -716,11 +848,13 @@ class NativeAudioBrowser extends _TrackPlayer.QueuePlayer {
       this.sleepTimer.clear();
       this.pause();
       this.onSleepTimerChanged(null);
-      return;
+      // Nothing is loading, so the caller must still report the end — the
+      // element has stopped and its own `pause` is swallowed as end-of-track.
+      return false;
     }
 
     // Otherwise proceed with normal track end behavior
-    super.onTrackEnded();
+    return super.onTrackEnded();
   }
 
   // MARK: Queue management
@@ -762,13 +896,13 @@ class NativeAudioBrowser extends _TrackPlayer.QueuePlayer {
   setActiveTrackFavorited(favorited) {
     const track = this.getActiveTrack();
     const index = this.getActiveTrackIndex();
-    if (!track || !track.src || index === undefined) return;
+    if (!track || (0, _getTrackIdentity.getTrackIdentity)(track) === undefined || index === undefined) return;
 
-    // Update favorites set via manager
+    // Update favorites set via manager (keyed by track identity)
     if (favorited) {
-      this.favoriteManager.addFavorite(track.src);
+      this.favoriteManager.addFavorite(track);
     } else {
-      this.favoriteManager.removeFavorite(track.src);
+      this.favoriteManager.removeFavorite(track);
     }
 
     // Create updated track with new favorited state
@@ -780,28 +914,19 @@ class NativeAudioBrowser extends _TrackPlayer.QueuePlayer {
     // Replace the track in the queue
     this.queue.replaceTrack(index, updatedTrack);
 
-    // Emit favorite changed event
+    // Emit favorite changed only. A favorite toggle is an in-place mutation of
+    // the active track, not a transition — onPlaybackActiveTrackChanged and
+    // onPlaybackQueueChanged stay transition-only, and the useActiveTrack /
+    // useQueue hooks subscribe to onFavoriteChanged themselves.
     this.onFavoriteChanged({
       track: updatedTrack,
       favorited
     });
-
-    // Emit active track changed so useActiveTrack() hook updates
-    this.onPlaybackActiveTrackChanged({
-      lastIndex: index,
-      lastTrack: track,
-      lastPosition: this.element?.currentTime ?? 0,
-      index,
-      track: updatedTrack
-    });
-
-    // Emit queue changed so useQueue() hook updates
-    this.emitQueueChanged();
   }
   toggleActiveTrackFavorited() {
     const track = this.getActiveTrack();
-    if (!track || !track.src) return;
-    const isFavorited = this.favoriteManager.isFavorited(track.src);
+    if (!track || (0, _getTrackIdentity.getTrackIdentity)(track) === undefined) return;
+    const isFavorited = this.favoriteManager.isFavorited(track);
     this.setActiveTrackFavorited(!isFavorited);
   }