@legendapp/spark 0.0.1-next.2 → 0.0.1-next.3

package/vendor/node_modules/@legendapp/spark-audio/src/media-session.ts

@@ -1,25 +1,58 @@
 import Native from "./NativeSparkAudio";
-import { validateSession, type MediaCommand, type MediaSession, type MediaSessionOptions } from "./media-types";
+import { onAudioEvent } from "./events";
+import { SparkError, invokeNative, parseNativeResult } from "@legendapp/spark-desktop-app/src/contracts";
+import { sessionOptions, sessionSnapshot, validMediaCommand, type MediaCommand, type MediaSession, type MediaSessionOptions } from "./media-types";
 let owner: (() => void) | undefined, sequence = 0;
-/** One explicit session owns the app's system media controls, independent of playback. */
-export async function createMediaSession(options: MediaSessionOptions, onCommand: (command: MediaCommand) => void): Promise<MediaSession> {
-  validateSession(options);
-  if (!Native) throw Object.assign(new Error("Media sessions require @legendapp/spark-audio in the native runtime"), { code: "E_UNAVAILABLE" });
+let queue: Promise<unknown> = Promise.resolve();
+function enqueue<T>(operation: () => Promise<T>): Promise<T> {
+  const result = queue.catch(() => {}).then(operation); queue = result; return result;
+}
+/** One explicit session owns system controls. New sessions replace the previous owner. */
+export async function createMediaSession(options: MediaSessionOptions): Promise<MediaSession> {
+  const state = sessionOptions(options);
+  const { onCommand, onError = console.error } = options;
+  if (!Native) throw new SparkError("E_MODULE_UNAVAILABLE", "Media sessions require @legendapp/spark-audio");
   const native = Native, id = `media-${Date.now()}-${++sequence}`;
-  let removed = false, timer: ReturnType<typeof setTimeout> | undefined;
-  const call = async <T = void>(method: string, args = {}): Promise<T> => JSON.parse(await native.call(method, JSON.stringify({ id, ...args })));
-  const stop = () => { removed = true; clearTimeout(timer); };
-  await call("sessionCreate", options); owner?.(); owner = stop;
-  async function poll() {
-    try {
-      const commands = await call<MediaCommand[]>("sessionCommands");
-      if (!removed) for (const command of commands) { try { onCommand(command); } catch (error) { console.error(error); } }
-    } catch (error) { if (!removed) { stop(); console.error(error); } }
-    finally { if (!removed) timer = setTimeout(poll, 100); }
-  }
-  void poll();
+  let stopped = false, removed = false, ready = false, removal: Promise<void> | undefined;
+  const buffered: MediaCommand[] = [];
+  const call = async <T>(method: string, args: object, validate: (value: unknown) => value is T) => parseNativeResult(await invokeNative(() => native.call(method, JSON.stringify({ id, ...args }))), validate);
+  const command = async (method: string, args = {}) => { await call(method, args, (value): value is null => value === null); };
+  const stop = () => { stopped = true; buffered.length = 0; subscription.remove(); };
+  const deliver = (value: unknown) => {
+    if (stopped) return;
+    if (!validMediaCommand(value)) { stop(); onError(new SparkError("E_INVALID_DATA", "Invalid media command")); return; }
+    if (!ready) { if (buffered.length < 128) buffered.push(value); return; }
+    if (owner !== stop) return;
+    try { onCommand(value); } catch (error) { onError(error); }
+  };
+  const subscription = onAudioEvent("sparkMediaCommand", id, deliver);
+  try { await enqueue(async () => {
+    try { await command("sessionCreate", state); }
+    catch (cause) {
+      try { await command("sessionRemove"); } catch (cleanup) { throw new SparkError("E_NATIVE", "Media creation and cleanup failed", { cause: new AggregateError([cause, cleanup]) }); }
+      throw cause;
+    }
+    owner?.(); owner = stop; ready = true;
+    for (const value of buffered.splice(0)) deliver(value);
+  }); } catch (error) { stop(); throw error; }
   return {
-    async update(patch) { if (removed) throw new Error("Media session has been removed or replaced"); validateSession(patch); await call("sessionUpdate", patch); },
-    async remove() { if (removed) return; await call("sessionRemove"); stop(); if (owner === stop) owner = undefined; },
+    async update(patch) {
+      if (stopped || owner !== stop) throw new SparkError("E_CLOSED", "Media session has been removed or replaced");
+      const snapshot = sessionSnapshot(patch);
+      await enqueue(async () => {
+        if (owner !== stop) throw new SparkError("E_CLOSED", "Media session has been replaced");
+        await command("sessionUpdate", snapshot);
+      });
+    },
+    remove() {
+      if (removed) return Promise.resolve();
+      if (removal) return removal;
+      stop();
+      removal = enqueue(async () => {
+        if (owner === stop) { await command("sessionRemove"); owner = undefined; }
+        removed = true;
+      }).finally(() => { removal = undefined; });
+      return removal;
+    },
   };
 }

package/vendor/node_modules/@legendapp/spark-audio/src/media-session.web.ts

@@ -1,18 +1,20 @@
-import { validateSession, type MediaCommand, type MediaCommandName, type MediaSession, type MediaSessionOptions } from "./media-types";
+import { SparkError } from "@legendapp/spark-desktop-app/src/contracts";
+import { sessionOptions, sessionSnapshot, type MediaCommandName, type MediaSession, type MediaSessionOptions, type MediaSessionUpdate } from "./media-types";
 let owner: object | undefined, explicit = false;
 export const hasExplicitMediaSession = () => explicit;
 export const claimPlayerMediaSession = (player: object) => { owner = player; };
 export const ownsPlayerMediaSession = (player: object) => owner === player;
 export const releasePlayerMediaSession = (player: object) => { if (owner === player) owner = undefined; };
 const actions: Record<MediaCommandName, MediaSessionAction> = { play: "play", pause: "pause", nextTrack: "nexttrack", previousTrack: "previoustrack", seekTo: "seekto" };
-export async function createMediaSession(options: MediaSessionOptions, onCommand: (command: MediaCommand) => void): Promise<MediaSession> {
-  validateSession(options);
+export async function createMediaSession(options: MediaSessionOptions): Promise<MediaSession> {
+  const initial = sessionOptions(options);
+  const { onCommand, onError = console.error } = options;
   const available = typeof navigator === "undefined" ? undefined : navigator.mediaSession;
-  if (!available) throw Object.assign(new Error("Browser media sessions are unavailable"), { code: "E_UNAVAILABLE" });
+  if (!available) throw new SparkError("E_UNSUPPORTED_PLATFORM", "Browser media sessions are unavailable");
   const media = available;
-  const id = {}; let removed = false, state: MediaSessionOptions = { commands: ["play", "pause"] };
+  const id = {}; let removed = false, state: MediaSessionUpdate = { commands: ["play", "pause"] };
   const clearActions = () => { for (const action of Object.values(actions)) { try { media.setActionHandler(action, null); } catch {} } };
-  function apply(patch: MediaSessionOptions) {
+  function apply(patch: MediaSessionUpdate) {
     state = { ...state, ...patch };
     const metadata = state.metadata ?? {};
     media.metadata = new MediaMetadata({ title: metadata.title, artist: metadata.artist, album: metadata.albumTitle, artwork: metadata.artworkUrl ? [{ src: metadata.artworkUrl }] : [] });
@@ -23,13 +25,19 @@ export async function createMediaSession(options: MediaSessionOptions, onCommand
     }
     clearActions();
     for (const command of state.commands ?? []) media.setActionHandler(actions[command], details => {
-      if (owner === id && !removed) onCommand({ command, ...(details.seekTime === undefined ? {} : { position: details.seekTime }) });
+      if (owner !== id || removed) return;
+      try {
+        if (command === "seekTo") {
+          if (typeof details.seekTime !== "number" || !Number.isFinite(details.seekTime) || details.seekTime < 0) throw new SparkError("E_INVALID_DATA", "Invalid seek command");
+          onCommand({ command, position: details.seekTime });
+        } else onCommand({ command });
+      } catch (error) { onError(error); }
     });
   }
   owner = id; explicit = true;
-  try { apply(options); } catch (error) { clearActions(); media.metadata = null; media.playbackState = "none"; owner = undefined; explicit = false; throw error; }
+  try { apply(initial); } catch (error) { clearActions(); media.metadata = null; media.playbackState = "none"; owner = undefined; explicit = false; throw error; }
   return {
-    async update(patch) { if (removed || owner !== id) throw new Error("Media session has been removed or replaced"); validateSession(patch); apply(patch); },
-    async remove() { if (removed) return; removed = true; if (owner !== id) return; clearActions(); media.metadata = null; media.playbackState = "none"; media.setPositionState?.(); owner = undefined; explicit = false; },
+    async update(patch) { if (removed || owner !== id) throw new SparkError("E_CLOSED", "Media session has been removed or replaced"); apply(sessionSnapshot(patch)); },
+    async remove() { if (owner !== id) { removed = true; return; } removed = true; clearActions(); media.metadata = null; media.playbackState = "none"; media.setPositionState?.(); owner = undefined; explicit = false; },
   };
 }

package/vendor/node_modules/@legendapp/spark-audio/src/media-types.ts

@@ -1,32 +1,59 @@
+import { SparkError } from "@legendapp/spark-desktop-app/src/contracts";
 export type AudioMetadata = { title?: string; artist?: string; albumTitle?: string; artworkUrl?: string };
 export type MediaCommandName = "play" | "pause" | "nextTrack" | "previousTrack" | "seekTo";
-export type MediaCommand = { command: MediaCommandName; position?: number };
-export type MediaSessionOptions = {
-  metadata?: AudioMetadata;
+export type MediaCommand = { command: "seekTo"; position: number } | { command: Exclude<MediaCommandName, "seekTo">; position?: never };
+export type MediaSessionUpdate = {
+  metadata?: AudioMetadata | null;
   playbackState?: "playing" | "paused" | "stopped";
   position?: number;
   duration?: number;
   playbackRate?: number;
-  commands?: MediaCommandName[];
+  commands?: readonly MediaCommandName[];
 };
+export interface MediaSessionOptions extends MediaSessionUpdate {
+  onCommand(command: MediaCommand): void;
+  onError?(error: unknown): void;
+}
 export interface MediaSession {
-  update(options: MediaSessionOptions): Promise<void>;
+  update(options: MediaSessionUpdate): Promise<void>;
   remove(): Promise<void>;
 }
 export function validateVolume(value: number) {
-  if (!Number.isFinite(value) || value < 0 || value > 1) throw new TypeError("Volume must be between 0 and 1");
+  if (!Number.isFinite(value) || value < 0 || value > 1) throw new SparkError("E_INVALID_ARGUMENT", "Volume must be between 0 and 1");
 }
 export function validateMetadata(metadata: AudioMetadata) {
+  if (!metadata || typeof metadata !== "object" || Array.isArray(metadata)) throw new SparkError("E_INVALID_ARGUMENT", "Expected audio metadata");
   for (const [key, value] of Object.entries(metadata)) {
-    if (!["title", "artist", "albumTitle", "artworkUrl"].includes(key) || typeof value !== "string") throw new TypeError("Invalid audio metadata");
+    if (!["title", "artist", "albumTitle", "artworkUrl"].includes(key) || typeof value !== "string") throw new SparkError("E_INVALID_ARGUMENT", "Invalid audio metadata");
   }
-  if (metadata.artworkUrl && !/^(https?:\/\/|file:\/\/|\/)/.test(metadata.artworkUrl)) throw new TypeError("Artwork requires an HTTP URL, file URL or absolute path");
+  if (metadata.artworkUrl && !/^(https?:\/\/|file:\/\/|\/)/.test(metadata.artworkUrl)) throw new SparkError("E_INVALID_ARGUMENT", "Artwork requires an HTTP URL, file URL or absolute path");
 }
-export function validateSession(options: MediaSessionOptions) {
-  if (options.metadata) validateMetadata(options.metadata);
+export function validateSession(options: MediaSessionUpdate) {
+  if (!options || typeof options !== "object" || Array.isArray(options)) throw new SparkError("E_INVALID_ARGUMENT", "Expected media session options");
+  for (const key of Object.keys(options)) if (!["metadata", "position", "duration", "playbackRate", "playbackState", "commands"].includes(key)) throw new SparkError("E_UNSUPPORTED_OPTION", `Unsupported media option: ${key}`);
+  if (options.metadata !== undefined && options.metadata !== null) validateMetadata(options.metadata);
   for (const key of ["position", "duration", "playbackRate"] as const) {
-    const value = options[key]; if (value !== undefined && (!Number.isFinite(value) || value < 0)) throw new TypeError(`Invalid media ${key}`);
+    const value = options[key]; if (value !== undefined && (!Number.isFinite(value) || value < 0)) throw new SparkError("E_INVALID_ARGUMENT", `Invalid media ${key}`);
   }
-  if (options.playbackState !== undefined && !["playing", "paused", "stopped"].includes(options.playbackState)) throw new TypeError("Invalid playback state");
-  if (options.commands !== undefined && (!Array.isArray(options.commands) || options.commands.some(command => !["play", "pause", "nextTrack", "previousTrack", "seekTo"].includes(command)) || new Set(options.commands).size !== options.commands.length)) throw new TypeError("Invalid media commands");
+  if (options.playbackState !== undefined && !["playing", "paused", "stopped"].includes(options.playbackState)) throw new SparkError("E_INVALID_ARGUMENT", "Invalid playback state");
+  if (options.commands !== undefined && (!Array.isArray(options.commands) || options.commands.some(command => !["play", "pause", "nextTrack", "previousTrack", "seekTo"].includes(command)) || new Set(options.commands).size !== options.commands.length)) throw new SparkError("E_INVALID_ARGUMENT", "Invalid media commands");
+}
+
+export function sessionOptions(options: MediaSessionOptions): MediaSessionUpdate {
+  if (!options || typeof options.onCommand !== "function" || (options.onError !== undefined && typeof options.onError !== "function")) throw new SparkError("E_INVALID_ARGUMENT", "Expected media session callbacks");
+  const { onCommand, onError, ...state } = options;
+  return sessionSnapshot(state);
+}
+export function sessionSnapshot(options: MediaSessionUpdate): MediaSessionUpdate {
+  validateSession(options);
+  return { ...Object.fromEntries(Object.entries(options).filter(([, value]) => value !== undefined)),
+    ...(options.metadata !== undefined ? { metadata: options.metadata === null ? {} : { ...options.metadata } } : {}),
+    ...(options.commands !== undefined ? { commands: [...options.commands] } : {}),
+  };
+}
+export function validMediaCommand(value: unknown): value is MediaCommand {
+  if (!value || typeof value !== "object") return false;
+  const command = value as MediaCommand;
+  return command.command === "seekTo" ? Number.isFinite(command.position) && command.position >= 0
+    : ["play", "pause", "nextTrack", "previousTrack"].includes(command.command) && command.position === undefined;
 }

package/vendor/node_modules/@legendapp/spark-audio/src/mobile.ts

@@ -1,38 +1,46 @@
-import { validateVolume, validateMetadata } from "./media-types";
-import { statusListeners } from "./status-listeners";
+import { SparkError, nativeError } from "@legendapp/spark-desktop-app/src/contracts";
+import { playerHandle, validatePlayerOptions, waitForAudio } from "./player";
 export type * from "./media-types";
 export { createMediaSession } from "./media-session-unavailable";
 import { createAudioPlayer as createExpoPlayer, setAudioModeAsync } from "expo-audio";
-import { validateSource, validateTime, type AudioPlayer, type AudioSource } from "./types";
-export type { AudioPlayer, AudioSource, AudioStatus } from "./types";
-export async function createAudioPlayer(source: AudioSource): Promise<AudioPlayer> {
-  validateSource(source);
+import { validateSource, type AudioPlayer, type AudioSource, type AudioPlayerOptions, type AudioStatus } from "./types";
+export type { AudioPlayer, AudioSource, AudioStatus, AudioPlayerOptions, Subscription } from "./types";
+export async function createAudioPlayer(source: AudioSource, options: AudioPlayerOptions = {}): Promise<AudioPlayer> {
+  validateSource(source); validatePlayerOptions(options);
+  options = { ...options };
+  source = { ...source };
+  const input = source;
   await setAudioModeAsync({ playsInSilentMode: true, shouldPlayInBackground: true, interruptionMode: "doNotMix" });
-  const player = createExpoPlayer(source.uri);
-  let removed = false;
-  let ended = false;
-  let failed = false;
-  const subscription = player.addListener("playbackStatusUpdate", status => { if (status.didJustFinish) ended = true; failed = status.playbackState === "error"; });
-  const alive = () => { if (removed) throw new Error("Audio player has been removed"); };
+  validatePlayerOptions(options);
+  const player = createExpoPlayer(input.uri);
+  let ended = false, failed = false, notifyReady: (() => void) | undefined;
+  const listeners = new Set<(status: AudioStatus) => void>();
+  const statusValue = (status = player.currentStatus): AudioStatus => ({ playing: status.playing, currentTime: status.currentTime, duration: status.duration, didJustFinish: ended, error: failed ? "Audio could not be decoded or loaded" : null, volume: player.volume });
+  const subscription = player.addListener("playbackStatusUpdate", status => {
+    if (status.didJustFinish) ended = true; failed = status.playbackState === "error";
+    notifyReady?.();
+    if (listeners.size) { const value = statusValue(status); for (const listener of [...listeners]) { try { listener(value); } catch (error) { console.error(error); } } }
+  });
   try {
-    if (!player.isLoaded) await new Promise<void>((resolve, reject) => {
-      const timer = setTimeout(() => { loaded.remove(); reject(new Error("Audio loading timed out")); }, 15_000);
-      const loaded = player.addListener("playbackStatusUpdate", status => {
-        if (status.isLoaded || status.playbackState === "error") { clearTimeout(timer); loaded.remove(); if (status.isLoaded) resolve(); else reject(new Error("Audio could not be loaded")); }
-      });
-    });
-    player.setActiveForLockScreen(true, { title: source.title ?? "Music" });
-  } catch (error) { subscription.remove(); player.remove(); throw error; }
-  const read = async () => { alive(); const status = player.currentStatus; return { playing: status.playing, currentTime: status.currentTime, duration: status.duration, didJustFinish: ended, error: failed ? "Audio could not be decoded or loaded" : null, volume: player.volume }; };
-  const listeners = statusListeners(read);
-  return {
-    async setVolume(volume) { alive(); validateVolume(volume); player.volume = volume; },
-    async setMetadata(metadata) { alive(); validateMetadata(metadata); player.updateLockScreenMetadata(metadata); },
-    addListener(event, listener) { if (event !== "playbackStatusUpdate") throw new TypeError("Unknown audio event"); return listeners.add(listener); },
-    async play() { alive(); ended = false; player.play(); },
-    async pause() { alive(); player.pause(); },
-    async seekTo(seconds) { alive(); validateTime(seconds); ended = false; await player.seekTo(seconds); },
-    getStatus: read,
-    async remove() { if (!removed) { removed = true; listeners.close(); subscription.remove(); player.clearLockScreenControls(); player.remove(); } },
-  };
+    await waitForAudio(async () => { if (failed || player.currentStatus.playbackState === "error") throw new SparkError("E_NATIVE", "Audio could not be loaded"); return player.isLoaded; }, options,
+      notify => { notifyReady = notify; return { remove() { notifyReady = undefined; } }; });
+    player.setActiveForLockScreen(true, { title: input.title ?? "Music" });
+  } catch (cause) {
+    subscription.remove();
+    try { player.remove(); } catch (cleanup) { throw new SparkError("E_NATIVE", "Audio loading and cleanup failed", { cause: new AggregateError([cause, cleanup]) }); }
+    throw nativeError(cause);
+  }
+  return playerHandle({
+    async setVolume(volume) { player.volume = volume; },
+    async setMetadata(metadata) { player.updateLockScreenMetadata(metadata ?? {}); },
+    async play() { ended = false; player.play(); },
+    async pause() { player.pause(); },
+    async seekTo(seconds) { ended = false; await player.seekTo(seconds); },
+    async getStatus() { return statusValue(); },
+    addStatusListener(listener) { listeners.add(listener); listener(statusValue()); return { remove() { listeners.delete(listener); } }; },
+    async remove() { listeners.clear(); subscription.remove(); player.clearLockScreenControls(); player.remove(); },
+  });
 }
+
+export { useAudioPlayer } from "./hooks";
+export type { AudioPlayerState, AudioPlayerHookOptions } from "./hooks";

package/vendor/node_modules/@legendapp/spark-audio/src/player.ts

@@ -0,0 +1,97 @@
+import { SparkError, nativeError } from "@legendapp/spark-desktop-app/src/contracts";
+import { validateMetadata, validateVolume } from "./media-types";
+import { statusListeners } from "./status-listeners";
+import { validateTime, type AudioPlayer, type AudioPlayerOptions, type AudioStatus } from "./types";
+
+export type PlayerBackend = Omit<AudioPlayer, "addListener"> & { addStatusListener(listener: (status: AudioStatus) => void): ReturnType<AudioPlayer["addListener"]> };
+export function validAudioStatus(value: unknown): value is AudioStatus {
+  if (!value || typeof value !== "object") return false;
+  const status = value as AudioStatus;
+  return typeof status.playing === "boolean" && typeof status.didJustFinish === "boolean" && (status.error === null || typeof status.error === "string") && [status.currentTime, status.duration, status.volume].every(value => typeof value === "number" && Number.isFinite(value) && value >= 0) && status.volume <= 1;
+}
+/** Command completion is ordered: AVPlayer seeks can finish after later native submissions.
+ * The queue is required for that guarantee; native status events do not enter it. */
+export function playerHandle(backend: PlayerBackend): AudioPlayer {
+  let queue: Promise<unknown> = Promise.resolve();
+  let closing = false;
+  let removed = false;
+  let removal: Promise<void> | undefined;
+  const alive = () => { if (closing) throw new SparkError("E_CLOSED", "Audio player is closing or removed"); };
+  function enqueue<T>(operation: () => Promise<T>): Promise<T> {
+    if (closing) return Promise.reject(new SparkError("E_CLOSED", "Audio player is closing or removed"));
+    const result = queue.catch(() => {}).then(operation).catch(error => { throw nativeError(error); });
+    queue = result; return result;
+  }
+  const read = () => enqueue(async () => {
+    const status = await backend.getStatus();
+    if (!validAudioStatus(status)) throw new SparkError("E_INVALID_DATA", "Invalid audio status");
+    return status;
+  });
+  const listeners = statusListeners(listener => backend.addStatusListener(status => {
+    if (!validAudioStatus(status)) { console.error(new SparkError("E_INVALID_DATA", "Invalid audio status")); return; }
+    listener(status);
+  }));
+  return {
+    async setVolume(volume) { validateVolume(volume); await enqueue(() => backend.setVolume(volume)); },
+    async setMetadata(metadata) {
+      if (metadata !== null) validateMetadata(metadata);
+      const snapshot = metadata === null ? null : { ...metadata };
+      await enqueue(() => backend.setMetadata(snapshot));
+    },
+    addListener(event, listener) {
+      alive();
+      if (event !== "playbackStatusUpdate" || typeof listener !== "function") throw new SparkError("E_INVALID_ARGUMENT", "Expected a playbackStatusUpdate listener");
+      return listeners.add(listener);
+    },
+    play: () => enqueue(() => backend.play()),
+    pause: () => enqueue(() => backend.pause()),
+    async seekTo(seconds) { validateTime(seconds); await enqueue(() => backend.seekTo(seconds)); },
+    getStatus: read,
+    remove() {
+      if (removed) return Promise.resolve();
+      if (removal) return removal;
+      closing = true; listeners.close();
+      removal = queue.catch(() => {}).then(() => backend.remove()).then(() => { removed = true; }).catch(error => { throw nativeError(error); }).finally(() => { removal = undefined; });
+      return removal;
+    },
+  };
+}
+export function validatePlayerOptions(options: AudioPlayerOptions) {
+  if (!options || typeof options !== "object" || Array.isArray(options)) throw new SparkError("E_INVALID_ARGUMENT", "Expected audio player options");
+  for (const key of Object.keys(options)) if (!["loadTimeoutMs", "signal"].includes(key)) throw new SparkError("E_UNSUPPORTED_OPTION", `Unsupported audio option: ${key}`);
+  if (options.loadTimeoutMs !== undefined && (!Number.isFinite(options.loadTimeoutMs) || options.loadTimeoutMs <= 0 || options.loadTimeoutMs > 2147483647)) throw new SparkError("E_INVALID_ARGUMENT", "loadTimeoutMs must be a positive timer duration");
+  if (options.signal !== undefined && (!options.signal || typeof options.signal.aborted !== "boolean" || typeof options.signal.addEventListener !== "function" || typeof options.signal.removeEventListener !== "function")) throw new SparkError("E_INVALID_ARGUMENT", "Expected an AbortSignal");
+  if (options.signal?.aborted) throw new SparkError("E_ABORTED", "Audio loading aborted");
+}
+/** Loading deadline begins after allocation. Wait on a native readiness promise or
+ * existing backend events; allocation itself is not timed out. */
+export async function waitForAudio(ready: () => Promise<boolean>, options: AudioPlayerOptions, subscribe?: (notify: () => void) => ReturnType<AudioPlayer["addListener"]>): Promise<void> {
+  let stopped = false;
+  let deadline: ReturnType<typeof setTimeout> | undefined;
+  let wake: (() => void) | undefined;
+  let changed = false, subscription: ReturnType<AudioPlayer["addListener"]> | undefined;
+  let abort = () => {};
+  try {
+    subscription = subscribe?.(() => { changed = true; wake?.(); });
+    await Promise.race([
+      new Promise<never>((_, reject) => {
+        abort = () => reject(new SparkError("E_ABORTED", "Audio loading aborted"));
+        options.signal?.addEventListener("abort", abort, { once: true });
+        if (options.signal?.aborted) abort();
+        deadline = setTimeout(() => reject(new SparkError("E_TIMEOUT", "Audio loading timed out")), options.loadTimeoutMs ?? 15000);
+      }),
+      (async () => {
+        while (!stopped) {
+          changed = false;
+          if (await ready()) return;
+          if (!subscribe) throw new SparkError("E_INVALID_DATA", "Native audio readiness did not acknowledge loading");
+          if (!stopped && !changed) await new Promise<void>(resolve => {
+            wake = resolve;
+          });
+        }
+      })(),
+    ]);
+  } finally {
+    stopped = true; clearTimeout(deadline); wake?.(); subscription?.remove(); options.signal?.removeEventListener("abort", abort);
+  }
+}

package/vendor/node_modules/@legendapp/spark-audio/src/status-listeners.ts

@@ -1,22 +1,28 @@
+import { SparkError } from "@legendapp/spark-desktop-app/src/contracts";
 import type { AudioStatus } from "./types";
-/** Sample status only while observed. No React state or render is involved. */
-export function statusListeners(read: () => Promise<AudioStatus>) {
+import type { Subscription } from "@legendapp/spark-desktop-app/src/contracts";
+/** Share one backend event stream without sampling reads or React state. */
+export function statusListeners(subscribe: (listener: (status: AudioStatus) => void) => Subscription) {
   const listeners = new Set<(status: AudioStatus) => void>();
-  let timer: ReturnType<typeof setTimeout> | undefined, closed = false, running = false;
-  async function tick() {
-    running = true;
-    try {
-      const status = await read();
-      if (!closed) for (const listener of [...listeners]) { try { listener(status); } catch (error) { console.error(error); } }
-    } catch (error) { if (!closed) console.error(error); }
-    finally { running = false; if (!closed && listeners.size) timer = setTimeout(tick, 250); }
-  }
+  let closed = false, starting = false;
+  let subscription: Subscription | undefined;
+  const deliver = (status: AudioStatus) => {
+    // Snapshot preserves delivery order when callbacks add/remove subscriptions.
+    if (!closed) for (const listener of [...listeners]) { try { if (!closed && listeners.has(listener)) listener(status); } catch (error) { console.error(error); } }
+  };
   return {
     add(listener: (status: AudioStatus) => void) {
-      if (closed) throw new Error("Audio player has been removed");
-      listeners.add(listener); if (!running && !timer) void tick();
-      return { remove() { listeners.delete(listener); if (!listeners.size) { clearTimeout(timer); timer = undefined; } } };
+      if (closed) throw new SparkError("E_CLOSED", "Audio player has been removed");
+      const entry = (status: AudioStatus) => listener(status);
+      listeners.add(entry);
+      if (!subscription && !starting) try {
+        starting = true;
+        const value = subscribe(deliver);
+        if (closed || !listeners.size) value.remove(); else subscription = value;
+      } catch (error) { listeners.delete(entry); throw error; }
+      finally { starting = false; }
+      return { remove() { listeners.delete(entry); if (!listeners.size) { subscription?.remove(); subscription = undefined; } } };
     },
-    close() { closed = true; clearTimeout(timer); listeners.clear(); },
+    close() { closed = true; listeners.clear(); subscription?.remove(); subscription = undefined; },
   };
 }

package/vendor/node_modules/@legendapp/spark-audio/src/types.ts

@@ -1,12 +1,15 @@
+import { SparkError, type Subscription } from "@legendapp/spark-desktop-app/src/contracts";
+export type { Subscription } from "@legendapp/spark-desktop-app/src/contracts";
 import type { AudioMetadata } from "./media-types";
 export * from "./media-types";
 /** Seconds throughout. Commands reject when the backend cannot complete them. */
 export type AudioStatus = { playing: boolean; currentTime: number; duration: number; didJustFinish: boolean; error: string | null; volume: number };
 export type AudioSource = { uri: string; title?: string };
+export interface AudioPlayerOptions { loadTimeoutMs?: number; signal?: AbortSignal }
 export interface AudioPlayer {
   setVolume(volume: number): Promise<void>;
-  setMetadata(metadata: AudioMetadata): Promise<void>;
-  addListener(event: "playbackStatusUpdate", listener: (status: AudioStatus) => void): { remove(): void };
+  setMetadata(metadata: AudioMetadata | null): Promise<void>;
+  addListener(event: "playbackStatusUpdate", listener: (status: AudioStatus) => void): Subscription;
   play(): Promise<void>;
   pause(): Promise<void>;
   seekTo(seconds: number): Promise<void>;
@@ -14,8 +17,10 @@ export interface AudioPlayer {
   remove(): Promise<void>;
 }
 export function validateSource(source: AudioSource) {
-  if (!source || typeof source.uri !== "string" || !source.uri || source.uri.includes("\0")) throw new Error("Audio requires a URI or absolute desktop file path");
+  if (!source || typeof source !== "object" || Array.isArray(source) || typeof source.uri !== "string" || !source.uri || source.uri.includes("\0")) throw new SparkError("E_INVALID_ARGUMENT", "Audio requires a URI or absolute desktop file path");
+  for (const key of Object.keys(source)) if (!["uri", "title"].includes(key)) throw new SparkError("E_UNSUPPORTED_OPTION", `Unsupported audio source option: ${key}`);
+  if (source.title !== undefined && typeof source.title !== "string") throw new SparkError("E_INVALID_ARGUMENT", "Audio title must be a string");
 }
 export function validateTime(seconds: number) {
-  if (!Number.isFinite(seconds) || seconds < 0) throw new Error("Seek position must be a finite, nonnegative number of seconds");
+  if (!Number.isFinite(seconds) || seconds < 0) throw new SparkError("E_INVALID_ARGUMENT", "Seek position must be a finite, nonnegative number of seconds");
 }