@wwdrew/expo-spotify-sdk 0.8.0 → 1.0.0

package/build/hooks/index.js

@@ -0,0 +1,326 @@
+import { useSyncExternalStore } from "react";
+import { AppRemote } from "../app-remote";
+import { Auth } from "../auth";
+import { Player } from "../player";
+import { User } from "../user";
+// ---------------------------------------------------------------------------
+// Connection-state store
+//
+// A module-level singleton that caches the latest ConnectionState, exposes a
+// subscribe function for useSyncExternalStore, and stays in sync via the
+// native onConnectionStateChange event. Initialised lazily on first use.
+// ---------------------------------------------------------------------------
+let _connectionState = "disconnected";
+const _connectionListeners = new Set();
+let _connectionStoreInitialised = false;
+function initConnectionStore() {
+    if (_connectionStoreInitialised)
+        return;
+    _connectionStoreInitialised = true;
+    // Seed with the current native state so the first snapshot is accurate.
+    AppRemote.getConnectionState().then((state) => {
+        if (state !== _connectionState) {
+            _connectionState = state;
+            _connectionListeners.forEach((l) => l());
+        }
+    });
+    AppRemote.addListener("connectionStateChange", ({ state }) => {
+        _connectionState = state;
+        _connectionListeners.forEach((l) => l());
+    });
+}
+function subscribeConnectionState(listener) {
+    initConnectionStore();
+    _connectionListeners.add(listener);
+    return () => _connectionListeners.delete(listener);
+}
+function getConnectionSnapshot() {
+    return _connectionState;
+}
+// ---------------------------------------------------------------------------
+// Session store
+// ---------------------------------------------------------------------------
+let _session = null;
+const _sessionListeners = new Set();
+let _sessionStoreInitialised = false;
+function initSessionStore() {
+    if (_sessionStoreInitialised)
+        return;
+    _sessionStoreInitialised = true;
+    Auth.addListener("sessionChange", (event) => {
+        if (event.type === "didInitiate" || event.type === "didRenew") {
+            _session = event.session;
+        }
+        else {
+            _session = null;
+        }
+        _sessionListeners.forEach((l) => l());
+    });
+}
+function subscribeSession(listener) {
+    initSessionStore();
+    _sessionListeners.add(listener);
+    return () => _sessionListeners.delete(listener);
+}
+function getSessionSnapshot() {
+    return _session;
+}
+// ---------------------------------------------------------------------------
+// Player-state store
+//
+// Seeded from the first playerStateChange event after subscription. The
+// native side automatically starts streaming player state updates once the
+// App Remote connection is established.
+// ---------------------------------------------------------------------------
+let _playerState = null;
+const _playerListeners = new Set();
+let _playerStoreInitialised = false;
+function normalizePlayerState(nextState, previousState) {
+    const nextName = nextState.track.name?.trim() ?? "";
+    const previousName = previousState?.track.name?.trim() ?? "";
+    const sameTrack = previousState != null && previousState.track.uri === nextState.track.uri;
+    // App Remote can occasionally emit a transient blank title between valid
+    // snapshots for the same URI; keep the last non-empty title to avoid UI
+    // flicker/regression in hooks consumers.
+    if (sameTrack && nextName.length === 0 && previousName.length > 0) {
+        return {
+            ...nextState,
+            track: {
+                ...nextState.track,
+                name: previousState.track.name,
+            },
+        };
+    }
+    return nextState;
+}
+function notifyPlayerListeners() {
+    _playerListeners.forEach((l) => l());
+}
+async function hydratePlayerState() {
+    try {
+        const state = await Player.getPlayerState();
+        _playerState = normalizePlayerState(state, _playerState);
+        notifyPlayerListeners();
+    }
+    catch {
+        // Ignore one-shot hydration failures (e.g., connection races). Event stream
+        // updates still populate this store once available.
+    }
+}
+function initPlayerStore() {
+    if (_playerStoreInitialised)
+        return;
+    _playerStoreInitialised = true;
+    // Hydrate immediately if the module is already connected before any consumer
+    // subscribes to player events.
+    AppRemote.getConnectionState().then((state) => {
+        if (state === "connected") {
+            void hydratePlayerState();
+        }
+    });
+    // Refresh the one-shot snapshot whenever App Remote reconnects, and clear on
+    // disconnect so stale "now playing" data is not retained.
+    AppRemote.addListener("connectionStateChange", ({ state }) => {
+        if (state === "connected") {
+            void hydratePlayerState();
+            return;
+        }
+        if (_playerState !== null) {
+            _playerState = null;
+            notifyPlayerListeners();
+        }
+    });
+    Player.addListener("playerStateChange", (state) => {
+        _playerState = normalizePlayerState(state, _playerState);
+        notifyPlayerListeners();
+    });
+}
+function subscribePlayerState(listener) {
+    initPlayerStore();
+    _playerListeners.add(listener);
+    return () => _playerListeners.delete(listener);
+}
+function getPlayerSnapshot() {
+    return _playerState;
+}
+// ---------------------------------------------------------------------------
+// Capabilities store
+// ---------------------------------------------------------------------------
+let _capabilities = null;
+const _capabilitiesListeners = new Set();
+let _capabilitiesStoreInitialised = false;
+function initCapabilitiesStore() {
+    if (_capabilitiesStoreInitialised)
+        return;
+    _capabilitiesStoreInitialised = true;
+    User.getCapabilities()
+        .then((capabilities) => {
+        _capabilities = capabilities;
+        _capabilitiesListeners.forEach((l) => l());
+    })
+        .catch(() => {
+        // Swallow initial read failures (e.g., not connected yet). The event
+        // stream will hydrate this later.
+    });
+    User.addListener("capabilitiesChange", (capabilities) => {
+        _capabilities = capabilities;
+        _capabilitiesListeners.forEach((l) => l());
+    });
+}
+function subscribeCapabilities(listener) {
+    initCapabilitiesStore();
+    _capabilitiesListeners.add(listener);
+    return () => _capabilitiesListeners.delete(listener);
+}
+function getCapabilitiesSnapshot() {
+    return _capabilities;
+}
+const _libraryStores = new Map();
+function getOrCreateLibraryStore(uri) {
+    const key = String(uri);
+    let store = _libraryStores.get(key);
+    if (!store) {
+        store = { state: null, listeners: new Set(), initialised: false };
+        _libraryStores.set(key, store);
+    }
+    return store;
+}
+function initLibraryStore(uri) {
+    const store = getOrCreateLibraryStore(uri);
+    if (store.initialised)
+        return;
+    store.initialised = true;
+    User.getLibraryState(uri)
+        .then((state) => {
+        store.state = state;
+        store.listeners.forEach((l) => l());
+    })
+        .catch(() => {
+        // Not connected / unavailable yet; listener updates can still arrive later.
+    });
+    User.addLibraryStateListener(uri, (state) => {
+        const next = getOrCreateLibraryStore(uri);
+        next.state = state;
+        next.listeners.forEach((l) => l());
+    });
+}
+function subscribeLibraryState(uri, listener) {
+    const key = String(uri);
+    initLibraryStore(uri);
+    const store = getOrCreateLibraryStore(uri);
+    store.listeners.add(listener);
+    return () => {
+        const current = _libraryStores.get(key);
+        if (!current)
+            return;
+        current.listeners.delete(listener);
+    };
+}
+function getLibrarySnapshot(uri) {
+    return _libraryStores.get(String(uri))?.state ?? null;
+}
+// ---------------------------------------------------------------------------
+// Public hooks
+// ---------------------------------------------------------------------------
+/**
+ * Returns the current Spotify OAuth session, or `null` when not authenticated.
+ * Updates automatically whenever `Auth.authenticate()` or `Auth.refresh()`
+ * resolves, and on session failure.
+ *
+ * Built on `useSyncExternalStore` for tearing-free React rendering.
+ */
+export function useSession() {
+    return useSyncExternalStore(subscribeSession, getSessionSnapshot, getSessionSnapshot);
+}
+/**
+ * Returns the current App Remote {@link ConnectionState}
+ * (`"disconnected"` | `"connecting"` | `"connected"`). Updates automatically
+ * on every state transition driven by `AppRemote.connect()` and `disconnect()`.
+ *
+ * Built on `useSyncExternalStore` for tearing-free React rendering.
+ *
+ * @example
+ * ```tsx
+ * function ConnectionBanner() {
+ *   const state = useConnectionState();
+ *   return <Text>{state === "connected" ? "Connected" : "Disconnected"}</Text>;
+ * }
+ * ```
+ */
+export function useConnectionState() {
+    return useSyncExternalStore(subscribeConnectionState, getConnectionSnapshot, getConnectionSnapshot);
+}
+/**
+ * Returns the latest {@link PlayerState} from the Spotify app, or `null`
+ * before the first update arrives (i.e., before `AppRemote.connect()` resolves
+ * and the native subscription emits its first event).
+ *
+ * Updates on every state change reported by the Spotify app (track change,
+ * pause/resume, seek, shuffle/repeat toggle, etc.).
+ *
+ * Built on `useSyncExternalStore` for tearing-free React rendering.
+ *
+ * @example
+ * ```tsx
+ * function NowPlaying() {
+ *   const state = usePlayerState();
+ *   if (!state) return <Text>Not playing</Text>;
+ *   return <Text>{state.track.name} — {state.isPaused ? "Paused" : "Playing"}</Text>;
+ * }
+ * ```
+ */
+export function usePlayerState() {
+    return useSyncExternalStore(subscribePlayerState, getPlayerSnapshot, getPlayerSnapshot);
+}
+/**
+ * Returns the currently playing {@link Track}, or `null` when nothing is
+ * playing or before the first state update arrives.
+ *
+ * Derived from `usePlayerState`.
+ */
+export function useCurrentTrack() {
+    return usePlayerState()?.track ?? null;
+}
+/**
+ * Returns `true` when the Spotify player is actively playing (not paused),
+ * and `false` otherwise (including before the first state update arrives).
+ *
+ * Derived from `usePlayerState`.
+ */
+export function useIsPlaying() {
+    const state = usePlayerState();
+    return state !== null && !state.isPaused;
+}
+/**
+ * Returns the current playback position in milliseconds. Returns `0` before
+ * the first state update arrives.
+ *
+ * **Note:** This value updates whenever the native side emits a player state
+ * change (track transitions, pause/resume, seek, etc.) — not on a fixed timer.
+ * For a progress bar that ticks smoothly, combine this with a local `Date.now`
+ * offset and `requestAnimationFrame`.
+ *
+ * Derived from `usePlayerState`.
+ */
+export function usePlaybackPosition() {
+    return usePlayerState()?.playbackPosition ?? 0;
+}
+/**
+ * Returns the latest Spotify user capabilities, or `null` before the first
+ * snapshot arrives.
+ *
+ * Derived from `User.getCapabilities()` + `User.addListener("capabilitiesChange")`.
+ */
+export function useCapabilities() {
+    return useSyncExternalStore(subscribeCapabilities, getCapabilitiesSnapshot, getCapabilitiesSnapshot);
+}
+/**
+ * Returns the library state for a specific URI, or `null` before the first
+ * snapshot arrives.
+ *
+ * Derived from `User.getLibraryState(uri)` + `User.addLibraryStateListener(uri, ...)`.
+ */
+export function useLibraryState(uri) {
+    return useSyncExternalStore((listener) => subscribeLibraryState(uri, listener), () => getLibrarySnapshot(uri), () => getLibrarySnapshot(uri));
+}
+//# sourceMappingURL=index.js.map

package/build/hooks/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/hooks/index.ts"],"names":[],"mappings":"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","sourcesContent":["import { useSyncExternalStore } from \"react\";\n\nimport { AppRemote, ConnectionState } from \"../app-remote\";\nimport { Auth, SpotifySession } from \"../auth\";\nimport { Player, PlayerState, Track } from \"../player\";\nimport { Capabilities, LibraryState, User } from \"../user\";\nimport type { SpotifyURI as SpotifyURIType } from \"../uri\";\n\n// ---------------------------------------------------------------------------\n// Shared utilities\n// ---------------------------------------------------------------------------\n\ntype Listener = () => void;\n\n// ---------------------------------------------------------------------------\n// Connection-state store\n//\n// A module-level singleton that caches the latest ConnectionState, exposes a\n// subscribe function for useSyncExternalStore, and stays in sync via the\n// native onConnectionStateChange event. Initialised lazily on first use.\n// ---------------------------------------------------------------------------\n\nlet _connectionState: ConnectionState = \"disconnected\";\nconst _connectionListeners = new Set<Listener>();\nlet _connectionStoreInitialised = false;\n\nfunction initConnectionStore() {\n  if (_connectionStoreInitialised) return;\n  _connectionStoreInitialised = true;\n\n  // Seed with the current native state so the first snapshot is accurate.\n  AppRemote.getConnectionState().then((state) => {\n    if (state !== _connectionState) {\n      _connectionState = state;\n      _connectionListeners.forEach((l) => l());\n    }\n  });\n\n  AppRemote.addListener(\"connectionStateChange\", ({ state }) => {\n    _connectionState = state;\n    _connectionListeners.forEach((l) => l());\n  });\n}\n\nfunction subscribeConnectionState(listener: Listener): () => void {\n  initConnectionStore();\n  _connectionListeners.add(listener);\n  return () => _connectionListeners.delete(listener);\n}\n\nfunction getConnectionSnapshot(): ConnectionState {\n  return _connectionState;\n}\n\n// ---------------------------------------------------------------------------\n// Session store\n// ---------------------------------------------------------------------------\n\nlet _session: SpotifySession | null = null;\nconst _sessionListeners = new Set<Listener>();\nlet _sessionStoreInitialised = false;\n\nfunction initSessionStore() {\n  if (_sessionStoreInitialised) return;\n  _sessionStoreInitialised = true;\n\n  Auth.addListener(\"sessionChange\", (event) => {\n    if (event.type === \"didInitiate\" || event.type === \"didRenew\") {\n      _session = event.session;\n    } else {\n      _session = null;\n    }\n    _sessionListeners.forEach((l) => l());\n  });\n}\n\nfunction subscribeSession(listener: Listener): () => void {\n  initSessionStore();\n  _sessionListeners.add(listener);\n  return () => _sessionListeners.delete(listener);\n}\n\nfunction getSessionSnapshot(): SpotifySession | null {\n  return _session;\n}\n\n// ---------------------------------------------------------------------------\n// Player-state store\n//\n// Seeded from the first playerStateChange event after subscription. The\n// native side automatically starts streaming player state updates once the\n// App Remote connection is established.\n// ---------------------------------------------------------------------------\n\nlet _playerState: PlayerState | null = null;\nconst _playerListeners = new Set<Listener>();\nlet _playerStoreInitialised = false;\n\nfunction normalizePlayerState(\n  nextState: PlayerState,\n  previousState: PlayerState | null,\n): PlayerState {\n  const nextName = nextState.track.name?.trim() ?? \"\";\n  const previousName = previousState?.track.name?.trim() ?? \"\";\n  const sameTrack =\n    previousState != null && previousState.track.uri === nextState.track.uri;\n\n  // App Remote can occasionally emit a transient blank title between valid\n  // snapshots for the same URI; keep the last non-empty title to avoid UI\n  // flicker/regression in hooks consumers.\n  if (sameTrack && nextName.length === 0 && previousName.length > 0) {\n    return {\n      ...nextState,\n      track: {\n        ...nextState.track,\n        name: previousState.track.name,\n      },\n    };\n  }\n\n  return nextState;\n}\n\nfunction notifyPlayerListeners() {\n  _playerListeners.forEach((l) => l());\n}\n\nasync function hydratePlayerState() {\n  try {\n    const state = await Player.getPlayerState();\n    _playerState = normalizePlayerState(state, _playerState);\n    notifyPlayerListeners();\n  } catch {\n    // Ignore one-shot hydration failures (e.g., connection races). Event stream\n    // updates still populate this store once available.\n  }\n}\n\nfunction initPlayerStore() {\n  if (_playerStoreInitialised) return;\n  _playerStoreInitialised = true;\n\n  // Hydrate immediately if the module is already connected before any consumer\n  // subscribes to player events.\n  AppRemote.getConnectionState().then((state) => {\n    if (state === \"connected\") {\n      void hydratePlayerState();\n    }\n  });\n\n  // Refresh the one-shot snapshot whenever App Remote reconnects, and clear on\n  // disconnect so stale \"now playing\" data is not retained.\n  AppRemote.addListener(\"connectionStateChange\", ({ state }) => {\n    if (state === \"connected\") {\n      void hydratePlayerState();\n      return;\n    }\n\n    if (_playerState !== null) {\n      _playerState = null;\n      notifyPlayerListeners();\n    }\n  });\n\n  Player.addListener(\"playerStateChange\", (state) => {\n    _playerState = normalizePlayerState(state, _playerState);\n    notifyPlayerListeners();\n  });\n}\n\nfunction subscribePlayerState(listener: Listener): () => void {\n  initPlayerStore();\n  _playerListeners.add(listener);\n  return () => _playerListeners.delete(listener);\n}\n\nfunction getPlayerSnapshot(): PlayerState | null {\n  return _playerState;\n}\n\n// ---------------------------------------------------------------------------\n// Capabilities store\n// ---------------------------------------------------------------------------\n\nlet _capabilities: Capabilities | null = null;\nconst _capabilitiesListeners = new Set<Listener>();\nlet _capabilitiesStoreInitialised = false;\n\nfunction initCapabilitiesStore() {\n  if (_capabilitiesStoreInitialised) return;\n  _capabilitiesStoreInitialised = true;\n\n  User.getCapabilities()\n    .then((capabilities) => {\n      _capabilities = capabilities;\n      _capabilitiesListeners.forEach((l) => l());\n    })\n    .catch(() => {\n      // Swallow initial read failures (e.g., not connected yet). The event\n      // stream will hydrate this later.\n    });\n\n  User.addListener(\"capabilitiesChange\", (capabilities) => {\n    _capabilities = capabilities;\n    _capabilitiesListeners.forEach((l) => l());\n  });\n}\n\nfunction subscribeCapabilities(listener: Listener): () => void {\n  initCapabilitiesStore();\n  _capabilitiesListeners.add(listener);\n  return () => _capabilitiesListeners.delete(listener);\n}\n\nfunction getCapabilitiesSnapshot(): Capabilities | null {\n  return _capabilities;\n}\n\n// ---------------------------------------------------------------------------\n// Per-URI library-state store\n// ---------------------------------------------------------------------------\n\ninterface LibraryStore {\n  state: LibraryState | null;\n  listeners: Set<Listener>;\n  initialised: boolean;\n}\n\nconst _libraryStores = new Map<string, LibraryStore>();\n\nfunction getOrCreateLibraryStore(uri: SpotifyURIType): LibraryStore {\n  const key = String(uri);\n  let store = _libraryStores.get(key);\n  if (!store) {\n    store = { state: null, listeners: new Set(), initialised: false };\n    _libraryStores.set(key, store);\n  }\n  return store;\n}\n\nfunction initLibraryStore(uri: SpotifyURIType) {\n  const store = getOrCreateLibraryStore(uri);\n  if (store.initialised) return;\n  store.initialised = true;\n\n  User.getLibraryState(uri)\n    .then((state) => {\n      store.state = state;\n      store.listeners.forEach((l) => l());\n    })\n    .catch(() => {\n      // Not connected / unavailable yet; listener updates can still arrive later.\n    });\n\n  User.addLibraryStateListener(uri, (state) => {\n    const next = getOrCreateLibraryStore(uri);\n    next.state = state;\n    next.listeners.forEach((l) => l());\n  });\n}\n\nfunction subscribeLibraryState(uri: SpotifyURIType, listener: Listener): () => void {\n  const key = String(uri);\n  initLibraryStore(uri);\n  const store = getOrCreateLibraryStore(uri);\n  store.listeners.add(listener);\n  return () => {\n    const current = _libraryStores.get(key);\n    if (!current) return;\n    current.listeners.delete(listener);\n  };\n}\n\nfunction getLibrarySnapshot(uri: SpotifyURIType): LibraryState | null {\n  return _libraryStores.get(String(uri))?.state ?? null;\n}\n\n// ---------------------------------------------------------------------------\n// Public hooks\n// ---------------------------------------------------------------------------\n\n/**\n * Returns the current Spotify OAuth session, or `null` when not authenticated.\n * Updates automatically whenever `Auth.authenticate()` or `Auth.refresh()`\n * resolves, and on session failure.\n *\n * Built on `useSyncExternalStore` for tearing-free React rendering.\n */\nexport function useSession(): SpotifySession | null {\n  return useSyncExternalStore(subscribeSession, getSessionSnapshot, getSessionSnapshot);\n}\n\n/**\n * Returns the current App Remote {@link ConnectionState}\n * (`\"disconnected\"` | `\"connecting\"` | `\"connected\"`). Updates automatically\n * on every state transition driven by `AppRemote.connect()` and `disconnect()`.\n *\n * Built on `useSyncExternalStore` for tearing-free React rendering.\n *\n * @example\n * ```tsx\n * function ConnectionBanner() {\n *   const state = useConnectionState();\n *   return <Text>{state === \"connected\" ? \"Connected\" : \"Disconnected\"}</Text>;\n * }\n * ```\n */\nexport function useConnectionState(): ConnectionState {\n  return useSyncExternalStore(\n    subscribeConnectionState,\n    getConnectionSnapshot,\n    getConnectionSnapshot,\n  );\n}\n\n/**\n * Returns the latest {@link PlayerState} from the Spotify app, or `null`\n * before the first update arrives (i.e., before `AppRemote.connect()` resolves\n * and the native subscription emits its first event).\n *\n * Updates on every state change reported by the Spotify app (track change,\n * pause/resume, seek, shuffle/repeat toggle, etc.).\n *\n * Built on `useSyncExternalStore` for tearing-free React rendering.\n *\n * @example\n * ```tsx\n * function NowPlaying() {\n *   const state = usePlayerState();\n *   if (!state) return <Text>Not playing</Text>;\n *   return <Text>{state.track.name} — {state.isPaused ? \"Paused\" : \"Playing\"}</Text>;\n * }\n * ```\n */\nexport function usePlayerState(): PlayerState | null {\n  return useSyncExternalStore(subscribePlayerState, getPlayerSnapshot, getPlayerSnapshot);\n}\n\n/**\n * Returns the currently playing {@link Track}, or `null` when nothing is\n * playing or before the first state update arrives.\n *\n * Derived from `usePlayerState`.\n */\nexport function useCurrentTrack(): Track | null {\n  return usePlayerState()?.track ?? null;\n}\n\n/**\n * Returns `true` when the Spotify player is actively playing (not paused),\n * and `false` otherwise (including before the first state update arrives).\n *\n * Derived from `usePlayerState`.\n */\nexport function useIsPlaying(): boolean {\n  const state = usePlayerState();\n  return state !== null && !state.isPaused;\n}\n\n/**\n * Returns the current playback position in milliseconds. Returns `0` before\n * the first state update arrives.\n *\n * **Note:** This value updates whenever the native side emits a player state\n * change (track transitions, pause/resume, seek, etc.) — not on a fixed timer.\n * For a progress bar that ticks smoothly, combine this with a local `Date.now`\n * offset and `requestAnimationFrame`.\n *\n * Derived from `usePlayerState`.\n */\nexport function usePlaybackPosition(): number {\n  return usePlayerState()?.playbackPosition ?? 0;\n}\n\n/**\n * Returns the latest Spotify user capabilities, or `null` before the first\n * snapshot arrives.\n *\n * Derived from `User.getCapabilities()` + `User.addListener(\"capabilitiesChange\")`.\n */\nexport function useCapabilities(): Capabilities | null {\n  return useSyncExternalStore(\n    subscribeCapabilities,\n    getCapabilitiesSnapshot,\n    getCapabilitiesSnapshot,\n  );\n}\n\n/**\n * Returns the library state for a specific URI, or `null` before the first\n * snapshot arrives.\n *\n * Derived from `User.getLibraryState(uri)` + `User.addLibraryStateListener(uri, ...)`.\n */\nexport function useLibraryState(uri: SpotifyURIType): LibraryState | null {\n  return useSyncExternalStore(\n    (listener) => subscribeLibraryState(uri, listener),\n    () => getLibrarySnapshot(uri),\n    () => getLibrarySnapshot(uri),\n  );\n}\n"]}

package/build/images/error.d.ts

@@ -0,0 +1,8 @@
+import { SpotifyError } from "../error";
+export type ImagesErrorCode = "NOT_CONNECTED" | "INVALID_URI" | "IMAGE_LOAD_FAILED" | "UNKNOWN";
+export declare class ImagesError extends SpotifyError {
+    readonly namespace: "Images";
+    readonly code: ImagesErrorCode;
+    constructor(code: ImagesErrorCode, message: string);
+}
+//# sourceMappingURL=error.d.ts.map

package/build/images/error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../../src/images/error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAExC,MAAM,MAAM,eAAe,GACvB,eAAe,GACf,aAAa,GACb,mBAAmB,GACnB,SAAS,CAAC;AAEd,qBAAa,WAAY,SAAQ,YAAY;IAC3C,QAAQ,CAAC,SAAS,EAAG,QAAQ,CAAU;IACvC,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;gBAEnB,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM;CAInD"}

package/build/images/error.js

@@ -0,0 +1,10 @@
+import { SpotifyError } from "../error";
+export class ImagesError extends SpotifyError {
+    namespace = "Images";
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+//# sourceMappingURL=error.js.map

package/build/images/error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error.js","sourceRoot":"","sources":["../../src/images/error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAQxC,MAAM,OAAO,WAAY,SAAQ,YAAY;IAClC,SAAS,GAAG,QAAiB,CAAC;IAC9B,IAAI,CAAkB;IAE/B,YAAY,IAAqB,EAAE,OAAe;QAChD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF","sourcesContent":["import { SpotifyError } from \"../error\";\n\nexport type ImagesErrorCode =\n  | \"NOT_CONNECTED\"\n  | \"INVALID_URI\"\n  | \"IMAGE_LOAD_FAILED\"\n  | \"UNKNOWN\";\n\nexport class ImagesError extends SpotifyError {\n  readonly namespace = \"Images\" as const;\n  readonly code: ImagesErrorCode;\n\n  constructor(code: ImagesErrorCode, message: string) {\n    super(message);\n    this.code = code;\n  }\n}\n"]}

package/build/images/index.d.ts

@@ -0,0 +1,36 @@
+export type { ImagesErrorCode } from "./error";
+export { ImagesError } from "./error";
+import type { ContentItem } from "../content";
+import type { Track } from "../player";
+export type ImageSize = "small" | "medium" | "large";
+export interface ImageResult {
+    uri: string;
+}
+/** Minimal shape required to fetch an image by identifier. */
+interface HasImageIdentifier {
+    imageIdentifier?: string | null;
+}
+/** Minimal album/artist representation for image loading. */
+interface BasicImageEntity {
+    imageIdentifier?: string | null;
+}
+export type ImageRepresentable = Track | ContentItem | BasicImageEntity | HasImageIdentifier;
+/**
+ * Spotify Images namespace. Fetches cover art for tracks, albums, artists,
+ * and content items via the App Remote SDK, writing the bitmap to a temp file
+ * and returning its local URI. Requires `AppRemote.connect()` to be resolved.
+ *
+ * @example
+ * ```ts
+ * import { Images } from "@wwdrew/expo-spotify-sdk";
+ *
+ * const { uri } = await Images.load(track, "large");
+ * ```
+ */
+export declare const Images: {
+    /**
+     * Loads a Spotify image and returns a local file URI.
+     */
+    readonly load: (item: ImageRepresentable, size: ImageSize) => Promise<ImageResult>;
+};
+//# sourceMappingURL=index.d.ts.map

package/build/images/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/images/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAC/C,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAOtC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,WAAW,CAAC;AAGvC,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAC;AAErD,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;CACb;AAED,8DAA8D;AAC9D,UAAU,kBAAkB;IAC1B,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACjC;AAED,6DAA6D;AAC7D,UAAU,gBAAgB;IACxB,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACjC;AAED,MAAM,MAAM,kBAAkB,GAAG,KAAK,GAAG,WAAW,GAAG,gBAAgB,GAAG,kBAAkB,CAAC;AAwC7F;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,MAAM;IACjB;;OAEG;0BACQ,kBAAkB,QAAQ,SAAS,KAAG,OAAO,CAAC,WAAW,CAAC;CAM7D,CAAC"}

package/build/images/index.js

@@ -0,0 +1,59 @@
+export { ImagesError } from "./error";
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+import ExpoSpotifySDKModule from "../ExpoSpotifySDKModule";
+import { ImagesError } from "./error";
+const VALID_IMAGE_CODES = new Set([
+    "NOT_CONNECTED",
+    "INVALID_URI",
+    "IMAGE_LOAD_FAILED",
+    "UNKNOWN",
+]);
+const CAUSE_SEPARATOR = "→ Caused by: ";
+function unwrapReason(message) {
+    const idx = message.lastIndexOf(CAUSE_SEPARATOR);
+    return idx === -1 ? message : message.slice(idx + CAUSE_SEPARATOR.length);
+}
+function rethrowAsImagesError(err) {
+    if (err instanceof ImagesError)
+        throw err;
+    if (err instanceof Error) {
+        const reason = unwrapReason(err.message);
+        const maybeCode = err.code;
+        if (maybeCode && VALID_IMAGE_CODES.has(maybeCode)) {
+            throw new ImagesError(maybeCode, reason);
+        }
+        throw new ImagesError("UNKNOWN", reason);
+    }
+    throw new ImagesError("UNKNOWN", String(err));
+}
+function getImageIdentifier(item) {
+    const value = item?.imageIdentifier;
+    if (!value || !value.trim()) {
+        throw new ImagesError("INVALID_URI", "Images.load(): item does not contain a valid imageIdentifier");
+    }
+    return value;
+}
+/**
+ * Spotify Images namespace. Fetches cover art for tracks, albums, artists,
+ * and content items via the App Remote SDK, writing the bitmap to a temp file
+ * and returning its local URI. Requires `AppRemote.connect()` to be resolved.
+ *
+ * @example
+ * ```ts
+ * import { Images } from "@wwdrew/expo-spotify-sdk";
+ *
+ * const { uri } = await Images.load(track, "large");
+ * ```
+ */
+export const Images = {
+    /**
+     * Loads a Spotify image and returns a local file URI.
+     */
+    load(item, size) {
+        const imageIdentifier = getImageIdentifier(item);
+        return ExpoSpotifySDKModule.imagesLoad(imageIdentifier, size).catch(rethrowAsImagesError);
+    },
+};
+//# sourceMappingURL=index.js.map

package/build/images/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/images/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAEtC,8EAA8E;AAC9E,QAAQ;AACR,8EAA8E;AAE9E,OAAO,oBAAoB,MAAM,yBAAyB,CAAC;AAG3D,OAAO,EAAE,WAAW,EAAmB,MAAM,SAAS,CAAC;AAoBvD,MAAM,iBAAiB,GAAG,IAAI,GAAG,CAAkB;IACjD,eAAe;IACf,aAAa;IACb,mBAAmB;IACnB,SAAS;CACV,CAAC,CAAC;AAEH,MAAM,eAAe,GAAG,eAAe,CAAC;AAExC,SAAS,YAAY,CAAC,OAAe;IACnC,MAAM,GAAG,GAAG,OAAO,CAAC,WAAW,CAAC,eAAe,CAAC,CAAC;IACjD,OAAO,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,GAAG,eAAe,CAAC,MAAM,CAAC,CAAC;AAC5E,CAAC;AAED,SAAS,oBAAoB,CAAC,GAAY;IACxC,IAAI,GAAG,YAAY,WAAW;QAAE,MAAM,GAAG,CAAC;IAC1C,IAAI,GAAG,YAAY,KAAK,EAAE,CAAC;QACzB,MAAM,MAAM,GAAG,YAAY,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QACzC,MAAM,SAAS,GAAI,GAAiC,CAAC,IAAI,CAAC;QAC1D,IAAI,SAAS,IAAI,iBAAiB,CAAC,GAAG,CAAC,SAA4B,CAAC,EAAE,CAAC;YACrE,MAAM,IAAI,WAAW,CAAC,SAA4B,EAAE,MAAM,CAAC,CAAC;QAC9D,CAAC;QACD,MAAM,IAAI,WAAW,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;IAC3C,CAAC;IACD,MAAM,IAAI,WAAW,CAAC,SAAS,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;AAChD,CAAC;AAED,SAAS,kBAAkB,CAAC,IAAwB;IAClD,MAAM,KAAK,GAAG,IAAI,EAAE,eAAe,CAAC;IACpC,IAAI,CAAC,KAAK,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,EAAE,CAAC;QAC5B,MAAM,IAAI,WAAW,CACnB,aAAa,EACb,8DAA8D,CAC/D,CAAC;IACJ,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG;IACpB;;OAEG;IACH,IAAI,CAAC,IAAwB,EAAE,IAAe;QAC5C,MAAM,eAAe,GAAG,kBAAkB,CAAC,IAAI,CAAC,CAAC;QACjD,OAAO,oBAAoB,CAAC,UAAU,CAAC,eAAe,EAAE,IAAI,CAAC,CAAC,KAAK,CACjE,oBAAoB,CACrB,CAAC;IACJ,CAAC;CACO,CAAC","sourcesContent":["export type { ImagesErrorCode } from \"./error\";\nexport { ImagesError } from \"./error\";\n\n// ---------------------------------------------------------------------------\n// Types\n// ---------------------------------------------------------------------------\n\nimport ExpoSpotifySDKModule from \"../ExpoSpotifySDKModule\";\nimport type { ContentItem } from \"../content\";\nimport type { Track } from \"../player\";\nimport { ImagesError, ImagesErrorCode } from \"./error\";\n\nexport type ImageSize = \"small\" | \"medium\" | \"large\";\n\nexport interface ImageResult {\n  uri: string;\n}\n\n/** Minimal shape required to fetch an image by identifier. */\ninterface HasImageIdentifier {\n  imageIdentifier?: string | null;\n}\n\n/** Minimal album/artist representation for image loading. */\ninterface BasicImageEntity {\n  imageIdentifier?: string | null;\n}\n\nexport type ImageRepresentable = Track | ContentItem | BasicImageEntity | HasImageIdentifier;\n\nconst VALID_IMAGE_CODES = new Set<ImagesErrorCode>([\n  \"NOT_CONNECTED\",\n  \"INVALID_URI\",\n  \"IMAGE_LOAD_FAILED\",\n  \"UNKNOWN\",\n]);\n\nconst CAUSE_SEPARATOR = \"→ Caused by: \";\n\nfunction unwrapReason(message: string): string {\n  const idx = message.lastIndexOf(CAUSE_SEPARATOR);\n  return idx === -1 ? message : message.slice(idx + CAUSE_SEPARATOR.length);\n}\n\nfunction rethrowAsImagesError(err: unknown): never {\n  if (err instanceof ImagesError) throw err;\n  if (err instanceof Error) {\n    const reason = unwrapReason(err.message);\n    const maybeCode = (err as Error & { code?: string }).code;\n    if (maybeCode && VALID_IMAGE_CODES.has(maybeCode as ImagesErrorCode)) {\n      throw new ImagesError(maybeCode as ImagesErrorCode, reason);\n    }\n    throw new ImagesError(\"UNKNOWN\", reason);\n  }\n  throw new ImagesError(\"UNKNOWN\", String(err));\n}\n\nfunction getImageIdentifier(item: ImageRepresentable): string {\n  const value = item?.imageIdentifier;\n  if (!value || !value.trim()) {\n    throw new ImagesError(\n      \"INVALID_URI\",\n      \"Images.load(): item does not contain a valid imageIdentifier\",\n    );\n  }\n  return value;\n}\n\n/**\n * Spotify Images namespace. Fetches cover art for tracks, albums, artists,\n * and content items via the App Remote SDK, writing the bitmap to a temp file\n * and returning its local URI. Requires `AppRemote.connect()` to be resolved.\n *\n * @example\n * ```ts\n * import { Images } from \"@wwdrew/expo-spotify-sdk\";\n *\n * const { uri } = await Images.load(track, \"large\");\n * ```\n */\nexport const Images = {\n  /**\n   * Loads a Spotify image and returns a local file URI.\n   */\n  load(item: ImageRepresentable, size: ImageSize): Promise<ImageResult> {\n    const imageIdentifier = getImageIdentifier(item);\n    return ExpoSpotifySDKModule.imagesLoad(imageIdentifier, size).catch(\n      rethrowAsImagesError,\n    );\n  },\n} as const;\n"]}

package/build/index.d.ts

@@ -1,59 +1,47 @@
-import { EventSubscription } from "expo-modules-core";
-import { SpotifyConfig, SpotifyError, SpotifyRefreshConfig, SpotifySession, SpotifySessionChangeEvent } from "./ExpoSpotifySDK.types";
+export { useSession, useConnectionState, usePlayerState, useCurrentTrack, useIsPlaying, usePlaybackPosition, useCapabilities, useLibraryState, } from "./hooks";
+export { Auth } from "./auth";
+export { AppRemote } from "./app-remote";
+export { Player } from "./player";
+export { User } from "./user";
+export { Content } from "./content";
+export { Images } from "./images";
+export { SpotifyError } from "./error";
+export { AuthError } from "./auth";
+export { AppRemoteError } from "./app-remote";
+export { PlayerError } from "./player";
+export { UserError } from "./user";
+export { ContentError } from "./content";
+export { ImagesError } from "./images";
+export type { AuthErrorCode } from "./auth";
+export type { AppRemoteErrorCode } from "./app-remote";
+export type { PlayerErrorCode } from "./player";
+export type { UserErrorCode } from "./user";
+export type { ContentErrorCode } from "./content";
+export type { ImagesErrorCode } from "./images";
+export { SpotifyURI } from "./uri";
+export type { SpotifyResourceType, SpotifyURI as SpotifyURIType } from "./uri";
+export type { SpotifySession, SpotifyScope, AuthenticateConfig, RefreshConfig, SessionChangeEvent, } from "./auth";
+export type { ConnectionState, ConnectionStateChangeEvent, ConnectionErrorEvent, } from "./app-remote";
+export type { RepeatMode, PodcastPlaybackSpeed, Artist, Album, Track, PlaybackOptions, PlaybackRestrictions, PlayerState, CrossfadeState, } from "./player";
+export type { Capabilities, LibraryState } from "./user";
+export type { ContentType, ContentItem } from "./content";
+export type { ImageSize, ImageResult, ImageRepresentable } from "./images";
+import { Auth } from "./auth";
+import type { AuthenticateConfig as SpotifyConfig, RefreshConfig as SpotifyRefreshConfig } from "./auth";
+/** @deprecated Use `Auth.isAvailable()` */
+export declare function isAvailable(): boolean;
+/** @deprecated Use `Auth.authenticate(config)` */
+export declare function authenticateAsync(config: SpotifyConfig): Promise<import("./auth").SpotifySession>;
+/** @deprecated Use `Auth.cancelPending()` */
+export declare function cancelPendingAuthAsync(): Promise<void>;
+/** @deprecated Use `Auth.refresh(config)` */
+export declare function refreshSessionAsync(config: SpotifyRefreshConfig): Promise<import("./auth").SpotifySession>;
+/** @deprecated Use `Auth.addListener("sessionChange", cb)` */
+export declare function addSessionChangeListener(listener: Parameters<typeof Auth.addListener>[1]): import("expo-modules-core").EventSubscription;
+export type { SpotifyConfig, SpotifyRefreshConfig };
 /**
- * Returns `true` if the Spotify app is installed on the device.
- * Always returns `false` on web.
+ * @deprecated `SpotifyErrorCode` is now `AuthErrorCode`. Import via:
+ * `import type { AuthErrorCode } from "@wwdrew/expo-spotify-sdk"`
  */
-declare function isAvailable(): boolean;
-/**
- * Starts a Spotify OAuth flow. Resolves with a {@link SpotifySession};
- * rejects with a {@link SpotifyError} carrying a `code`.
- */
-declare function authenticateAsync(config: SpotifyConfig): Promise<SpotifySession>;
-/**
- * Forcibly cancel any in-flight `authenticateAsync` call. Resolves once the
- * native coordinator's pending continuation has been cleared. No-op when
- * nothing is in flight, and a no-op on Android (the Android coordinator
- * self-cleans via structured concurrency).
- *
- * Recovery hatch for the iOS coordinator's stuck-state class of bugs: the
- * SPTSessionManager delegate callbacks are not guaranteed to fire — e.g. when
- * Spotify never redirects back to the host app — leaving the coordinator's
- * `pending` continuation set forever and every subsequent `authenticateAsync`
- * rejecting with `AUTH_IN_PROGRESS` until the process restarts. Call this
- * before `authenticateAsync` to defensively clear any leaked state.
- */
-declare function cancelPendingAuthAsync(): Promise<void>;
-/**
- * Exchanges a refresh token for a new access token via your token refresh
- * server. Resolves with a fresh {@link SpotifySession}; rejects with a
- * {@link SpotifyError}.
- */
-declare function refreshSessionAsync(config: SpotifyRefreshConfig): Promise<SpotifySession>;
-/**
- * Subscribes to session lifecycle events emitted by the native module.
- *
- * Events are fired for every `authenticateAsync` and `refreshSessionAsync`
- * call, regardless of whether the call was awaited. Useful for persisting
- * tokens in a central store without coupling the store to the call sites.
- *
- * Returns a {@link Subscription} — call `.remove()` to unsubscribe.
- *
- * @example
- * ```ts
- * const sub = addSessionChangeListener((event) => {
- *   if (event.type === "didInitiate" || event.type === "didRenew") {
- *     store.setSession(event.session);
- *   }
- * });
- * // later:
- * sub.remove();
- * ```
- */
-declare function addSessionChangeListener(listener: (event: SpotifySessionChangeEvent) => void): EventSubscription;
-declare const Authenticate: {
-    authenticateAsync: typeof authenticateAsync;
-};
-export { isAvailable, authenticateAsync, cancelPendingAuthAsync, refreshSessionAsync, addSessionChangeListener, Authenticate, SpotifyError, };
-export type { SpotifyConfig, SpotifyRefreshConfig, SpotifySession, SpotifySessionChangeEvent, SpotifyErrorCode, SpotifyScope, } from "./ExpoSpotifySDK.types";
+export type { AuthErrorCode as SpotifyErrorCode } from "./auth";
 //# sourceMappingURL=index.d.ts.map

package/build/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAY,MAAM,mBAAmB,CAAC;AAEhE,OAAO,EACL,aAAa,EACb,YAAY,EAEZ,oBAAoB,EACpB,cAAc,EACd,yBAAyB,EAC1B,MAAM,wBAAwB,CAAC;AAWhC;;;GAGG;AACH,iBAAS,WAAW,IAAI,OAAO,CAE9B;AAED;;;GAGG;AACH,iBAAS,iBAAiB,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,cAAc,CAAC,CAqBzE;AAED;;;;;;;;;;;;GAYG;AACH,iBAAS,sBAAsB,IAAI,OAAO,CAAC,IAAI,CAAC,CAK/C;AAgCD;;;;GAIG;AACH,iBAAS,mBAAmB,CAC1B,MAAM,EAAE,oBAAoB,GAC3B,OAAO,CAAC,cAAc,CAAC,CAczB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,iBAAS,wBAAwB,CAC/B,QAAQ,EAAE,CAAC,KAAK,EAAE,yBAAyB,KAAK,IAAI,GACnD,iBAAiB,CAKnB;AAgCD,QAAA,MAAM,YAAY;;CAEjB,CAAC;AAEF,OAAO,EACL,WAAW,EACX,iBAAiB,EACjB,sBAAsB,EACtB,mBAAmB,EACnB,wBAAwB,EACxB,YAAY,EACZ,YAAY,GACb,CAAC;AACF,YAAY,EACV,aAAa,EACb,oBAAoB,EACpB,cAAc,EACd,yBAAyB,EACzB,gBAAgB,EAChB,YAAY,GACb,MAAM,wBAAwB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,OAAO,EACL,UAAU,EACV,kBAAkB,EAClB,cAAc,EACd,eAAe,EACf,YAAY,EACZ,mBAAmB,EACnB,eAAe,EACf,eAAe,GAChB,MAAM,SAAS,CAAC;AAMjB,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAC9B,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAClC,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAC9B,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAMlC,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AACnC,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AACvC,OAAO,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AACnC,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAMvC,YAAY,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AAC5C,YAAY,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AACvD,YAAY,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAChD,YAAY,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AAC5C,YAAY,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAClD,YAAY,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAMhD,OAAO,EAAE,UAAU,EAAE,MAAM,OAAO,CAAC;AACnC,YAAY,EAAE,mBAAmB,EAAE,UAAU,IAAI,cAAc,EAAE,MAAM,OAAO,CAAC;AAM/E,YAAY,EACV,cAAc,EACd,YAAY,EACZ,kBAAkB,EAClB,aAAa,EACb,kBAAkB,GACnB,MAAM,QAAQ,CAAC;AAMhB,YAAY,EACV,eAAe,EACf,0BAA0B,EAC1B,oBAAoB,GACrB,MAAM,cAAc,CAAC;AAMtB,YAAY,EACV,UAAU,EACV,oBAAoB,EACpB,MAAM,EACN,KAAK,EACL,KAAK,EACL,eAAe,EACf,oBAAoB,EACpB,WAAW,EACX,cAAc,GACf,MAAM,UAAU,CAAC;AAMlB,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AAMzD,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAM1D,YAAY,EAAE,SAAS,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAS3E,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAC9B,OAAO,KAAK,EACV,kBAAkB,IAAI,aAAa,EACnC,aAAa,IAAI,oBAAoB,EACtC,MAAM,QAAQ,CAAC;AAEhB,2CAA2C;AAC3C,wBAAgB,WAAW,IAAI,OAAO,CAErC;AAED,kDAAkD;AAClD,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,aAAa,4CAEtD;AAED,6CAA6C;AAC7C,wBAAgB,sBAAsB,kBAErC;AAED,6CAA6C;AAC7C,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,oBAAoB,4CAE/D;AAED,8DAA8D;AAC9D,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,UAAU,CAAC,OAAO,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,iDAGjD;AAID,YAAY,EAAE,aAAa,EAAE,oBAAoB,EAAE,CAAC;AAEpD;;;GAGG;AACH,YAAY,EAAE,aAAa,IAAI,gBAAgB,EAAE,MAAM,QAAQ,CAAC"}