react-native-queue-player 1.1.2 → 2.0.0

package/nitrogen/generated/shared/c++/QueueChangeDelta.hpp

@@ -0,0 +1,113 @@
+///
+/// QueueChangeDelta.hpp
+/// This file was generated by nitrogen. DO NOT MODIFY THIS FILE.
+/// https://github.com/mrousavy/nitro
+/// Copyright © Marc Rousavy @ Margelo
+///
+
+#pragma once
+
+#if __has_include(<NitroModules/JSIConverter.hpp>)
+#include <NitroModules/JSIConverter.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+#if __has_include(<NitroModules/NitroDefines.hpp>)
+#include <NitroModules/NitroDefines.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+#if __has_include(<NitroModules/JSIHelpers.hpp>)
+#include <NitroModules/JSIHelpers.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+#if __has_include(<NitroModules/PropNameIDCache.hpp>)
+#include <NitroModules/PropNameIDCache.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+
+// Forward declaration of `TrackItem` to properly resolve imports.
+namespace margelo::nitro::queueplayer { struct TrackItem; }
+
+#include "TrackItem.hpp"
+#include <vector>
+
+namespace margelo::nitro::queueplayer {
+
+  /**
+   * A struct which can be represented as a JavaScript object (QueueChangeDelta).
+   */
+  struct QueueChangeDelta final {
+  public:
+    double revision     SWIFT_PRIVATE;
+    double length     SWIFT_PRIVATE;
+    std::vector<TrackItem> inserted     SWIFT_PRIVATE;
+    double insertedAt     SWIFT_PRIVATE;
+    std::vector<double> removed     SWIFT_PRIVATE;
+    double movedFrom     SWIFT_PRIVATE;
+    double movedTo     SWIFT_PRIVATE;
+    std::vector<double> order     SWIFT_PRIVATE;
+
+  public:
+    QueueChangeDelta() = default;
+    explicit QueueChangeDelta(double revision, double length, std::vector<TrackItem> inserted, double insertedAt, std::vector<double> removed, double movedFrom, double movedTo, std::vector<double> order): revision(revision), length(length), inserted(inserted), insertedAt(insertedAt), removed(removed), movedFrom(movedFrom), movedTo(movedTo), order(order) {}
+
+  public:
+    friend bool operator==(const QueueChangeDelta& lhs, const QueueChangeDelta& rhs) = default;
+  };
+
+} // namespace margelo::nitro::queueplayer
+
+namespace margelo::nitro {
+
+  // C++ QueueChangeDelta <> JS QueueChangeDelta (object)
+  template <>
+  struct JSIConverter<margelo::nitro::queueplayer::QueueChangeDelta> final {
+    static inline margelo::nitro::queueplayer::QueueChangeDelta fromJSI(jsi::Runtime& runtime, const jsi::Value& arg) {
+      jsi::Object obj = arg.asObject(runtime);
+      return margelo::nitro::queueplayer::QueueChangeDelta(
+        JSIConverter<double>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "revision"))),
+        JSIConverter<double>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "length"))),
+        JSIConverter<std::vector<margelo::nitro::queueplayer::TrackItem>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "inserted"))),
+        JSIConverter<double>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "insertedAt"))),
+        JSIConverter<std::vector<double>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "removed"))),
+        JSIConverter<double>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "movedFrom"))),
+        JSIConverter<double>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "movedTo"))),
+        JSIConverter<std::vector<double>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "order")))
+      );
+    }
+    static inline jsi::Value toJSI(jsi::Runtime& runtime, const margelo::nitro::queueplayer::QueueChangeDelta& arg) {
+      jsi::Object obj(runtime);
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "revision"), JSIConverter<double>::toJSI(runtime, arg.revision));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "length"), JSIConverter<double>::toJSI(runtime, arg.length));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "inserted"), JSIConverter<std::vector<margelo::nitro::queueplayer::TrackItem>>::toJSI(runtime, arg.inserted));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "insertedAt"), JSIConverter<double>::toJSI(runtime, arg.insertedAt));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "removed"), JSIConverter<std::vector<double>>::toJSI(runtime, arg.removed));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "movedFrom"), JSIConverter<double>::toJSI(runtime, arg.movedFrom));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "movedTo"), JSIConverter<double>::toJSI(runtime, arg.movedTo));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "order"), JSIConverter<std::vector<double>>::toJSI(runtime, arg.order));
+      return obj;
+    }
+    static inline bool canConvert(jsi::Runtime& runtime, const jsi::Value& value) {
+      if (!value.isObject()) {
+        return false;
+      }
+      jsi::Object obj = value.getObject(runtime);
+      if (!nitro::isPlainObject(runtime, obj)) {
+        return false;
+      }
+      if (!JSIConverter<double>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "revision")))) return false;
+      if (!JSIConverter<double>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "length")))) return false;
+      if (!JSIConverter<std::vector<margelo::nitro::queueplayer::TrackItem>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "inserted")))) return false;
+      if (!JSIConverter<double>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "insertedAt")))) return false;
+      if (!JSIConverter<std::vector<double>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "removed")))) return false;
+      if (!JSIConverter<double>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "movedFrom")))) return false;
+      if (!JSIConverter<double>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "movedTo")))) return false;
+      if (!JSIConverter<std::vector<double>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "order")))) return false;
+      return true;
+    }
+  };
+
+} // namespace margelo::nitro

package/nitrogen/generated/shared/c++/TrackItem.hpp

@@ -49,10 +49,14 @@ namespace margelo::nitro::queueplayer {
     std::optional<double> duration     SWIFT_PRIVATE;
     std::optional<std::string> artworkUrl     SWIFT_PRIVATE;
     std::optional<std::unordered_map<std::string, std::string>> extras     SWIFT_PRIVATE;
+    std::optional<double> replayGainTrackGain     SWIFT_PRIVATE;
+    std::optional<double> replayGainTrackPeak     SWIFT_PRIVATE;
+    std::optional<double> replayGainAlbumGain     SWIFT_PRIVATE;
+    std::optional<double> replayGainAlbumPeak     SWIFT_PRIVATE;
 
   public:
     TrackItem() = default;
-    explicit TrackItem(std::optional<std::string> id, std::string url, std::optional<std::string> title, std::optional<std::string> artist, std::optional<std::string> album, std::optional<double> duration, std::optional<std::string> artworkUrl, std::optional<std::unordered_map<std::string, std::string>> extras): id(id), url(url), title(title), artist(artist), album(album), duration(duration), artworkUrl(artworkUrl), extras(extras) {}
+    explicit TrackItem(std::optional<std::string> id, std::string url, std::optional<std::string> title, std::optional<std::string> artist, std::optional<std::string> album, std::optional<double> duration, std::optional<std::string> artworkUrl, std::optional<std::unordered_map<std::string, std::string>> extras, std::optional<double> replayGainTrackGain, std::optional<double> replayGainTrackPeak, std::optional<double> replayGainAlbumGain, std::optional<double> replayGainAlbumPeak): id(id), url(url), title(title), artist(artist), album(album), duration(duration), artworkUrl(artworkUrl), extras(extras), replayGainTrackGain(replayGainTrackGain), replayGainTrackPeak(replayGainTrackPeak), replayGainAlbumGain(replayGainAlbumGain), replayGainAlbumPeak(replayGainAlbumPeak) {}
 
   public:
     friend bool operator==(const TrackItem& lhs, const TrackItem& rhs) = default;
@@ -75,7 +79,11 @@ namespace margelo::nitro {
         JSIConverter<std::optional<std::string>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "album"))),
         JSIConverter<std::optional<double>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "duration"))),
         JSIConverter<std::optional<std::string>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "artworkUrl"))),
-        JSIConverter<std::optional<std::unordered_map<std::string, std::string>>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "extras")))
+        JSIConverter<std::optional<std::unordered_map<std::string, std::string>>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "extras"))),
+        JSIConverter<std::optional<double>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "replayGainTrackGain"))),
+        JSIConverter<std::optional<double>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "replayGainTrackPeak"))),
+        JSIConverter<std::optional<double>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "replayGainAlbumGain"))),
+        JSIConverter<std::optional<double>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "replayGainAlbumPeak")))
       );
     }
     static inline jsi::Value toJSI(jsi::Runtime& runtime, const margelo::nitro::queueplayer::TrackItem& arg) {
@@ -88,6 +96,10 @@ namespace margelo::nitro {
       obj.setProperty(runtime, PropNameIDCache::get(runtime, "duration"), JSIConverter<std::optional<double>>::toJSI(runtime, arg.duration));
       obj.setProperty(runtime, PropNameIDCache::get(runtime, "artworkUrl"), JSIConverter<std::optional<std::string>>::toJSI(runtime, arg.artworkUrl));
       obj.setProperty(runtime, PropNameIDCache::get(runtime, "extras"), JSIConverter<std::optional<std::unordered_map<std::string, std::string>>>::toJSI(runtime, arg.extras));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "replayGainTrackGain"), JSIConverter<std::optional<double>>::toJSI(runtime, arg.replayGainTrackGain));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "replayGainTrackPeak"), JSIConverter<std::optional<double>>::toJSI(runtime, arg.replayGainTrackPeak));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "replayGainAlbumGain"), JSIConverter<std::optional<double>>::toJSI(runtime, arg.replayGainAlbumGain));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "replayGainAlbumPeak"), JSIConverter<std::optional<double>>::toJSI(runtime, arg.replayGainAlbumPeak));
       return obj;
     }
     static inline bool canConvert(jsi::Runtime& runtime, const jsi::Value& value) {
@@ -106,6 +118,10 @@ namespace margelo::nitro {
       if (!JSIConverter<std::optional<double>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "duration")))) return false;
       if (!JSIConverter<std::optional<std::string>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "artworkUrl")))) return false;
       if (!JSIConverter<std::optional<std::unordered_map<std::string, std::string>>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "extras")))) return false;
+      if (!JSIConverter<std::optional<double>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "replayGainTrackGain")))) return false;
+      if (!JSIConverter<std::optional<double>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "replayGainTrackPeak")))) return false;
+      if (!JSIConverter<std::optional<double>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "replayGainAlbumGain")))) return false;
+      if (!JSIConverter<std::optional<double>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "replayGainAlbumPeak")))) return false;
       return true;
     }
   };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "react-native-queue-player",
-  "version": "1.1.2",
-  "description": "Nitro Modules audio playback library for React Native — gapless, EQ, crossfade, automotive, voice, casting",
+  "version": "2.0.0",
+  "description": "Nitro Modules audio playback library for React Native \u2014 gapless, EQ, crossfade, automotive, voice, casting",
   "main": "./lib/module/index.js",
   "types": "./lib/typescript/index.d.ts",
   "exports": {
@@ -83,17 +83,17 @@
   "devDependencies": {
     "@expo/config-plugins": "^54.0.0",
     "@jest/globals": "^29.7.0",
-    "@react-native/babel-preset": "0.85.3",
-    "@react-native/jest-preset": "0.85.3",
+    "@react-native/babel-preset": "0.86.3",
+    "@react-native/jest-preset": "0.86.3",
     "@types/react": "^19.2.0",
     "@types/react-test-renderer": "19.1.0",
     "del-cli": "^7.0.0",
     "jest": "^29.7.0",
-    "nitrogen": "^0.36.1",
+    "nitrogen": "^0.37.1",
     "react": "19.2.3",
-    "react-native": "0.85.3",
+    "react-native": "0.86.3",
     "react-native-builder-bob": "^0.41.0",
-    "react-native-nitro-modules": "^0.36.1",
+    "react-native-nitro-modules": "^0.37.1",
     "react-test-renderer": "19.2.3",
     "turbo": "^2.8.21",
     "typescript": "^6.0.2"
@@ -102,7 +102,7 @@
     "@expo/config-plugins": ">=10.0.0",
     "react": "*",
     "react-native": "*",
-    "react-native-nitro-modules": "^0.36.1"
+    "react-native-nitro-modules": "^0.37.1"
   },
   "peerDependenciesMeta": {
     "@expo/config-plugins": {

package/src/TrackPlayer.nitro.ts

@@ -10,6 +10,7 @@ import type {
   StateChangeReason,
   TrackChangeReason,
   QueueChangeReason,
+  QueueChangeDelta,
   TrackSource,
   PlaybackError,
   PlayerProgress,
@@ -111,17 +112,18 @@ export interface TrackPlayer
    */
   moveInQueue(fromIndex: number, toIndex: number): Promise<void>;
   /**
-   * Returns the current queue snapshot.
+   * Resolves with the current queue snapshot.
    *
-   * Cross-platform note: on Android the read crosses thread boundaries
-   * (`@Volatile tracks` field, no main-hop) — calling `getQueue()` and
-   * `getCurrentTrackIndex()` back-to-back can observe a one-tick skew
-   * during a concurrent queue mutation (e.g. mid-`setQueue`). For UI
-   * code that needs the pair to be consistent, prefer the
-   * `useActiveTrack` hook which subscribes to `onTrackChange` and
-   * receives both atomically.
+   * Each platform reads the queue on the thread that owns it (the player's
+   * serial queue on iOS, main on Android), so the array is internally
+   * consistent. The pair `getQueue()` + `getCurrentTrackIndex()` is still
+   * **not** atomic — awaiting the first leaves a gap in which a mutation can
+   * land, so the index can name a position in a queue you no longer hold. For
+   * UI that needs the pair consistent, subscribe: `onTrackChange` delivers
+   * `(track, index)` together, and `onQueueChange` delivers the delta and the
+   * post-mutation index together under the same mutation.
    */
-  getQueue(): TrackItem[];
+  getQueue(): Promise<TrackItem[]>;
   clearQueue(): Promise<void>;
 
   // Transport
@@ -129,12 +131,12 @@ export interface TrackPlayer
   pause(): Promise<void>;
   stop(): Promise<void>;
   /**
-   * Manually re-attempt the current track after its automatic retries were
-   * exhausted (the track is in the error state). Rebuilds the failed item and
-   * resumes from where it stopped, then plays. Use for a "tap to retry" button:
-   * e.g. the user left WiFi coverage so the auto-retries failed, then came back
-   * in range and taps retry. A no-op when there is no current track or the
-   * current track is not in the error state.
+   * Re-attempt the current track, from any state. Rebuilds the item, resumes
+   * from where it stopped, then plays, and restores the track's automatic
+   * retry budget. Use for a "tap to retry" button: e.g. the user left WiFi
+   * coverage so the auto-retries failed, then came back in range and taps
+   * retry. While casting, forwards a play to the receiver instead. A no-op
+   * only when there is no current track.
    */
   retry(): Promise<void>;
   /** position in seconds from the start of the current track */
@@ -381,10 +383,12 @@ export interface TrackPlayer
    * e.g. inserting a "play next" item or removing an upcoming track — so
    * a reactive queue UI stays in sync.
    *
-   * The `(queue, currentIndex)` pair is delivered **atomically**: it is
-   * the post-mutation snapshot captured on the native side under the same
-   * mutation, so it never exhibits the one-tick skew of reading
-   * `getQueue()` + `getCurrentTrackIndex()` back-to-back. `currentIndex`
+   * The `(delta, currentIndex)` pair is delivered **atomically**: both are
+   * captured on the native side under the same mutation, so they never exhibit
+   * the skew of awaiting `getQueue()` and then reading
+   * `getCurrentTrackIndex()`. The delta describes the change rather than
+   * carrying the whole queue, so a reorder costs two numbers instead of one
+   * `TrackItem` per entry — see `QueueChangeDelta`. `currentIndex`
    * is `-1` when the queue is empty; note it can shift without the active
    * track changing (e.g. an insert before the current item), which is the
    * case `onTrackChange` does not cover.
@@ -393,14 +397,14 @@ export interface TrackPlayer
    * `addToQueue`, out-of-range `removeFromQueue`, `moveInQueue` with
    * `from === to`) does not fire, and neither do current-index-only
    * changes from auto-advance / skip (those are `onTrackChange`). Does not
-   * auto-fire on subscribe; seed initial state from `getQueue()` (the
-   * `useQueue()` hook does this). For a mutation that also changes the
+   * auto-fire on subscribe; seed initial state from `getQueue()` once, then
+   * apply each delta (the `useQueue()` hook does this). For a mutation that also changes the
    * active track (`set-queue` / `clear` / `shuffle`) this fires first,
    * then `onTrackChange` follows.
    */
   onQueueChange(
     callback: (
-      queue: TrackItem[],
+      delta: QueueChangeDelta,
       currentIndex: number,
       reason: QueueChangeReason
     ) => void
@@ -452,10 +456,8 @@ export interface TrackPlayer
    * call `getCanSkipNext` / `getCanSkipPrevious` first).
    *
    * Wrapped in a `SkipCapability` struct (rather than two boolean
-   * callback args) so future capability flags can be added without
-   * a breaking API change. Also works around a Nitrogen 0.35.4
-   * codegen bug for `(bool, bool) → void` callback signatures
-   * specifically.
+   * callback args) so further capability flags can be added without
+   * a breaking API change.
    */
   onSkipCapabilityChange(
     callback: (capability: SkipCapability) => void
@@ -562,6 +564,16 @@ export interface TrackPlayer
    * library refresh — not every launch — and the lib dispatches the
    * actual write to a background queue per Apple's guidance.
    *
+   * **Inert unless `PlayerConfig.voiceVocabularyDonationEnabled` was `true` at
+   * the first `configure()`,** and enabling that requires the
+   * `com.apple.developer.siri` entitlement — Xcode's Siri capability — not
+   * just `NSSiriUsageDescription` in Info.plist. `INVocabulary` checks for the
+   * entitlement at runtime and raises an Objective-C exception without it,
+   * which cannot be caught from Swift and terminates the app. iOS gives a
+   * process no way to read its own entitlements, so the opt-in is the
+   * library's only signal that this is safe to call: leave it `false` unless
+   * the Siri capability is on the target.
+   *
    * **Android**: no-op. Google Assistant has no in-app vocabulary
    * donation API.
    */
@@ -641,6 +653,15 @@ export interface TrackPlayer
    * immediate Android eviction must `await player.destroy()` then
    * `await player.configure({ ... })` to force a rebuild.
    *
+   * **Cross-platform note on `allowsCellularAccess`**: live on both,
+   * but enforced at different points. iOS sets it on each prefetch
+   * request and the OS refuses the request; a download already on
+   * the wire finishes under the value it started with. Android has
+   * no per-request equivalent, so prefetch stops being scheduled
+   * while the default network is cellular, which also cancels the
+   * download in flight — its partial data stays cached and resumes
+   * later. Neither platform gates playback on it.
+   *
    * **Cross-platform note on enable transition**: flipping `enabled`
    * from `false` → `true` follows the same Android limitation —
    * a fresh SimpleCache is only constructed during `configureInternal`,
@@ -650,7 +671,7 @@ export interface TrackPlayer
    * immediate.
    */
   setLookaheadCache(config: LookaheadCacheConfig): Promise<void>;
-  getLookaheadCacheStatus(): CacheStatus;
+  getLookaheadCacheStatus(): Promise<CacheStatus>;
   /**
    * Wipe every cached entry + cancel any in-flight prefetch. Does
    * NOT auto-restart the prefetcher — `clear` means "wipe and stop".
@@ -659,6 +680,11 @@ export interface TrackPlayer
    * prefetch window.
    */
   clearLookaheadCache(): Promise<void>;
+  /**
+   * Fires once on subscribe with the current status, then after every
+   * `setLookaheadCache()`, prefetch completion and `clearLookaheadCache()`.
+   * An eviction shows in the next snapshot those produce.
+   */
   onCacheStatusChange(callback: (status: CacheStatus) => void): () => void;
 
   /**

package/src/hooks/useActiveTrack.ts

@@ -19,36 +19,43 @@ const INITIAL: ActiveTrackSnapshot = {
 /**
  * Subscribes to native `onTrackChange` updates.
  *
- * The first-render seed reads `getQueue()` and `getCurrentTrackIndex()`
- * separately — the pair is not atomic against a concurrent queue
- * mutation on either platform, so the seed can briefly observe the
- * new list with the old index (or vice versa). Self-healing: the
- * next `onTrackChange` event delivers a consistent
- * `(track, index, reason)` triple. Consumers needing an atomic
- * snapshot should wait for the first listener fire.
+ * Renders empty for the first frame, then fills in: the seed reads
+ * `getQueue()`, which resolves asynchronously, and pairs it with a separately
+ * read index — so it can briefly observe a new list against an old index. Any
+ * `onTrackChange` that arrives first wins and the seed is dropped, since the
+ * event delivers a consistent `(track, index, reason)` triple.
  */
 export function useActiveTrack(): ActiveTrackSnapshot {
-  const [snapshot, setSnapshot] = useState<ActiveTrackSnapshot>(() => {
-    try {
-      const player = getTrackPlayer();
-      const queue = player.getQueue();
-      const index = player.getCurrentTrackIndex();
-      return {
-        track: index >= 0 && index < queue.length ? queue[index] : undefined,
-        index,
-        reason: 'queue-replaced',
-      };
-    } catch {
-      return INITIAL;
-    }
-  });
+  const [snapshot, setSnapshot] = useState<ActiveTrackSnapshot>(INITIAL);
 
   useEffect(() => {
     const player = getTrackPlayer();
+    let seeded = false;
+    // A seed still in flight when this effect is cleaned up (a StrictMode
+    // remount, an unmount) must not land on a later mount's state.
+    let disposed = false;
+    void (async () => {
+      try {
+        const queue = await player.getQueue();
+        const index = player.getCurrentTrackIndex();
+        if (disposed || seeded) return;
+        setSnapshot({
+          track: index >= 0 && index < queue.length ? queue[index] : undefined,
+          index,
+          reason: 'queue-replaced',
+        });
+      } catch {
+        // Player not configured yet; the first event seeds instead.
+      }
+    })();
     const dispose = player.onTrackChange((track, index, reason) => {
+      seeded = true;
       setSnapshot({ track, index, reason });
     });
-    return dispose;
+    return () => {
+      disposed = true;
+      dispose();
+    };
   }, []);
 
   return snapshot;

package/src/hooks/useCast.ts

@@ -6,6 +6,7 @@ import {
   addRouteListener,
   addSessionDiedListener,
   getCurrentRoute,
+  getLocalNetworkPermissionState,
   getReceivers,
   getSupportedProtocols,
   isCastAvailable,
@@ -34,7 +35,12 @@ export interface CastSnapshot {
    * clear by re-reading state after surfacing a banner.
    */
   lastSessionDied: CastSessionDiedEvent | null;
-  /** iOS Local Network permission state; `'granted'` on Android. */
+  /**
+   * Local Network permission state. Seeded from
+   * `getLocalNetworkPermissionState()` on mount and updated by every
+   * `onLocalNetworkPermissionChange` delivery; `'granted'` on Android below
+   * target SDK 37, which never emits a change.
+   */
   permission: CastLocalNetworkPermission;
 }
 
@@ -69,7 +75,7 @@ export function useCast(): CastSnapshot {
         route: getCurrentRoute(),
         isDiscovering: isDiscovering(),
         lastSessionDied: null,
-        permission: 'undetermined',
+        permission: getLocalNetworkPermissionState(),
       };
     } catch {
       return INITIAL;
@@ -79,32 +85,25 @@ export function useCast(): CastSnapshot {
   useEffect(() => {
     if (!isCastAvailable()) return;
 
-    // Each `addXxxListener` synchronously replays the current value on
-    // subscribe. The initial `useState` initializer already captured
-    // every initial value; skipping the first replay per stream avoids
-    // five back-to-back `setSnapshot` calls on mount.
-    let firstRoute = true;
-    let firstReceivers = true;
-    let firstDiscovery = true;
-    let firstPermission = true;
-
+    // Each `addXxxListener` replays the current value synchronously on
+    // subscribe, and every delivery is applied: a replay that equals the
+    // `useState` seed costs one batched render, while a replay that differs
+    // is a change that landed between the render and this effect — dropping
+    // it would leave the snapshot on the stale seed (on Android the
+    // permission replay is the only delivery there ever is).
     const routeSub = addRouteListener((route) => {
-      if (firstRoute) { firstRoute = false; return; }
       setSnapshot((prev) => ({ ...prev, route }));
     });
     const receiversSub = addReceiversListener((receivers) => {
-      if (firstReceivers) { firstReceivers = false; return; }
       setSnapshot((prev) => ({ ...prev, receivers }));
     });
     const discoverySub = addDiscoveryStateListener((state) => {
-      if (firstDiscovery) { firstDiscovery = false; return; }
       setSnapshot((prev) => ({ ...prev, isDiscovering: state.isDiscovering }));
     });
     const deathSub = addSessionDiedListener((event) =>
       setSnapshot((prev) => ({ ...prev, lastSessionDied: event }))
     );
     const permissionSub = addLocalNetworkPermissionListener((event) => {
-      if (firstPermission) { firstPermission = false; return; }
       setSnapshot((prev) => ({ ...prev, permission: event.state }));
     });
 

package/src/hooks/useEqualizer.ts

@@ -16,7 +16,8 @@ export interface UseEqualizerResult {
 }
 
 /**
- * Subscribes to Equalizer band-change events and exposes imperative setters.
+ * Subscribes to Equalizer band-change and enabled-change events and
+ * exposes imperative setters.
  * Initial state is pulled synchronously on mount so consumers don't flash
  * empty bands.
  */
@@ -45,21 +46,28 @@ export function useEqualizer(): UseEqualizerResult {
 
   useEffect(() => {
     const eq = getEqualizer();
-    const dispose = eq.onBandChange((updated) => {
+    const disposeBands = eq.onBandChange((updated) => {
       setBands(updated);
     });
-    return dispose;
+    const disposeEnabled = eq.onEnabledChange((next) => {
+      setEnabledState(next);
+    });
+    return () => {
+      disposeBands();
+      disposeEnabled();
+    };
   }, []);
 
   const setEnabled = useCallback(async (next: boolean) => {
     const eq = getEqualizer();
     await eq.setEnabled(next);
-    // Read back rather than echoing the requested value: the native
-    // side may reject (or coerce) the change in a future build, and
-    // mirroring its actual state keeps JS aligned without a separate
-    // `onEnabledChange` event. Fall back to the requested value when
-    // the read-back throws (today's behaviour against the
-    // unimplemented native — matches the seed's try/catch on init).
+    // `isEnabled()` is the authority on what the native side committed,
+    // so read it back rather than echoing the request. `onEnabledChange`
+    // has already delivered the same value — both platforms emit it
+    // synchronously inside `setEnabled`'s promise body — which makes this
+    // a redundant write on the happy path and the only correction if a
+    // future native build stops emitting. Fall back to the requested
+    // value when the read-back throws, matching the seed's try/catch.
     try {
       setEnabledState(eq.isEnabled());
     } catch {
@@ -79,9 +87,8 @@ export function useEqualizer(): UseEqualizerResult {
     await getEqualizer().applyPreset(name);
   }, []);
 
-  // TODO: wire onPresetsChange when added to Equalizer.nitro.ts —
-  // until then, save/delete refresh the local presets list with a
-  // manual sync re-fetch.
+  // The spec carries no presets-changed event, so save and delete
+  // re-read `getPresets()` themselves to refresh the local list.
   const saveCustomPreset = useCallback(async (name: string) => {
     await getEqualizer().saveCustomPreset(name);
     setPresets(getEqualizer().getPresets());

package/src/hooks/useLookaheadCache.ts

@@ -26,13 +26,9 @@ const INITIAL: CacheStatus = {
  * and drop the lookahead count).
  */
 export function useLookaheadCache(): UseLookaheadCacheResult {
-  const [status, setStatus] = useState<CacheStatus>(() => {
-    try {
-      return getTrackPlayer().getLookaheadCacheStatus();
-    } catch {
-      return INITIAL;
-    }
-  });
+  // Seeded by the listener's own first fire, which delivers current status on
+  // registration — no getter call, so this survives the getter being async.
+  const [status, setStatus] = useState<CacheStatus>(INITIAL);
 
   useEffect(() => {
     const player = getTrackPlayer();