fancy-ui-react 0.2.0

package/dist/sound/sound.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Sound controller — the module-level singleton that owns the user's sound
+ * preference, persists it, and drives the engine. It is a singleton because
+ * `sound.play()` must be callable from anywhere, including code that never
+ * runs inside a React tree.
+ *
+ * Invariants:
+ * - ZERO browser-global access at module evaluation. Preferences hydrate
+ *   lazily on the first IMPERATIVE entry point — any controller getter or
+ *   method, or `hydrateSound()` called from an effect — never on import and
+ *   never from a render path.
+ * - `play()` is a no-op unless in the browser AND enabled AND the engine can
+ *   schedule. It never throws.
+ * - `enable()` never plays a cue itself; the confirmation cue lives in
+ *   SoundToggle (inside the user's click).
+ * - A cue that arrives while the AudioContext is still idle or suspended is
+ *   not lost: exactly ONE pending cue is kept, the context is unlocked inside
+ *   the same gesture, and that cue is replayed once the context runs. Bursts
+ *   are never queued.
+ * - `sound` is a plain object literal so tests can `vi.spyOn(sound, "play")`.
+ *
+ * React binding: a module-scope store read through `useSyncExternalStore`
+ * (`subscribeSound` / `getSoundSnapshot` / `getSoundServerSnapshot`), with no
+ * provider and no context. The `sound` prop is an ordinary boolean on seven
+ * components and must work with zero setup; the state is genuinely global (one
+ * storage key, one cross-tab listener, one AudioContext); and a store
+ * re-renders only the components that actually subscribed, where a provider
+ * would re-render its whole subtree on every volume change.
+ */
+import { type SoundCue, type SoundPlayOptions, type SoundPreferences, type SoundStatus, type SoundThemeName } from "./types.js";
+export interface SoundController {
+    readonly enabled: boolean;
+    readonly volume: number;
+    readonly theme: SoundThemeName;
+    /** Plain snapshot object (new object per read), safe to spread/JSON. */
+    readonly preferences: SoundPreferences;
+    /** Stable view over the live status; `getSoundStatus()` returns the same data as a fresh object. */
+    readonly status: SoundStatus;
+    /** No-op (returns void, never throws) unless in browser AND enabled AND engine can schedule. */
+    play(cue: SoundCue, options?: SoundPlayOptions): void;
+    /** Creates/resumes the AudioContext inside the current gesture. Resolves engine-running. */
+    unlock(): Promise<boolean>;
+    /** Also calls unlock() fire-and-forget — the enabling click IS the gesture. Plays nothing. */
+    enable(): void;
+    disable(): void;
+    /** Returns the new `enabled`. */
+    toggle(): boolean;
+    setEnabled(enabled: boolean): void;
+    /** Clamped [0,1]; NaN ignored. */
+    setVolume(volume: number): void;
+    /** Unknown names ignored. */
+    setTheme(theme: SoundThemeName): void;
+    /** Store contract, unchanged: calls `run` immediately, then on every preference change. */
+    subscribe(run: (prefs: SoundPreferences) => void): () => void;
+}
+/** What a `useSyncExternalStore` reader sees. Identity-cached — see `getSoundSnapshot`. */
+export interface SoundSnapshot {
+    readonly enabled: boolean;
+    readonly volume: number;
+    readonly theme: SoundThemeName;
+    readonly status: SoundStatus;
+}
+/** Pure parser for the stored JSON. Never throws. Exported for tests. */
+export declare function parseStoredPreferences(raw: string | null): SoundPreferences;
+export declare const sound: SoundController;
+/** Non-reactive snapshot for status lines / logging. Always a fresh plain object. */
+export declare function getSoundStatus(): SoundStatus;
+export declare function subscribeSound(listener: () => void): () => void;
+/**
+ * IDENTITY-CACHED, and mandatory: `useSyncExternalStore` calls `getSnapshot`
+ * on every render and infinite-loops if the identity changes with no real
+ * change. `sound.preferences` and `getSoundStatus()` still return a fresh
+ * object per call by design — this cache is additive, rebuilt only when a
+ * mutation path bumped the version.
+ *
+ * It never calls `ensure()`: a render path must not read localStorage. Before
+ * hydration it returns exactly the object `getSoundServerSnapshot()` returns.
+ */
+export declare function getSoundSnapshot(): SoundSnapshot;
+/** The frozen defaults. NEVER calls `ensure()`, never touches localStorage. */
+export declare function getSoundServerSnapshot(): SoundSnapshot;
+/**
+ * Idempotent. Reads localStorage, attaches the cross-tab listener, probes
+ * AudioContext support without constructing one, then wakes every store
+ * reader. Called from an EFFECT (`use-sound.ts`), never from a render.
+ */
+export declare function hydrateSound(): void;
+/**
+ * Test-only: disposes the engine, resets prefs to defaults, clears the storage
+ * listener and the preference subscribers, forgets storage state. Not exported
+ * from index.ts.
+ *
+ * `reactListeners` is deliberately NOT cleared: those subscriptions belong to
+ * `useSyncExternalStore` and are released by its own cleanup. Dropping one
+ * behind React's back would strand a still-mounted component with a store it
+ * can never hear from again.
+ */
+export declare function resetSoundForTests(): void;

package/dist/sound/sound.js

@@ -0,0 +1,309 @@
+"use client";
+import { createSoundEngine } from "./engine.js";
+import { getSoundTheme } from "./themes.js";
+import { SOUND_THEME_NAMES, DEFAULT_SOUND_PREFERENCES, SOUND_STORAGE_KEY } from "./types.js";
+function createInitialStatus() {
+  return {
+    supported: false,
+    enabled: false,
+    volume: DEFAULT_SOUND_PREFERENCES.volume,
+    theme: DEFAULT_SOUND_PREFERENCES.theme,
+    engine: "idle",
+    storage: "untouched",
+    lastCue: null,
+    lastPlayedAt: null,
+    lastError: null
+  };
+}
+const prefs = { ...DEFAULT_SOUND_PREFERENCES };
+const status = createInitialStatus();
+let hydrated = false;
+let storageListenerAttached = false;
+let engine = null;
+let pending = null;
+let unlocking = false;
+const subscribers = /* @__PURE__ */ new Set();
+const reactListeners = /* @__PURE__ */ new Set();
+let version = 0;
+function parseStoredPreferences(raw) {
+  if (raw == null) return { ...DEFAULT_SOUND_PREFERENCES };
+  try {
+    const data = JSON.parse(raw);
+    if (!data || typeof data !== "object" || data.v !== 1) return { ...DEFAULT_SOUND_PREFERENCES };
+    const volume = typeof data.volume === "number" && Number.isFinite(data.volume) ? Math.min(1, Math.max(0, data.volume)) : DEFAULT_SOUND_PREFERENCES.volume;
+    const theme = SOUND_THEME_NAMES.includes(data.theme) ? data.theme : DEFAULT_SOUND_PREFERENCES.theme;
+    return { enabled: data.enabled === true, volume, theme };
+  } catch {
+    return { ...DEFAULT_SOUND_PREFERENCES };
+  }
+}
+function assignPrefs(next) {
+  prefs.enabled = next.enabled;
+  prefs.volume = next.volume;
+  prefs.theme = next.theme;
+}
+function snapshot() {
+  return { enabled: prefs.enabled, volume: prefs.volume, theme: prefs.theme };
+}
+function bump() {
+  version += 1;
+  for (const listener of reactListeners) listener();
+}
+function notify() {
+  bump();
+  const next = snapshot();
+  for (const run of subscribers) run(next);
+}
+function persist() {
+  if (typeof window === "undefined") return;
+  try {
+    window.localStorage.setItem(
+      SOUND_STORAGE_KEY,
+      JSON.stringify({ v: 1, enabled: prefs.enabled, volume: prefs.volume, theme: prefs.theme })
+    );
+    status.storage = "ok";
+  } catch (err) {
+    status.storage = "error";
+    status.lastError = err instanceof Error ? err.message : String(err);
+  }
+  bump();
+}
+function handleStorage(event) {
+  if (event.key !== SOUND_STORAGE_KEY && event.key !== null) return;
+  const next = parseStoredPreferences(event.newValue);
+  assignPrefs(next);
+  status.storage = "ok";
+  engine?.setMasterVolume(next.volume);
+  engine?.setTheme(getSoundTheme(next.theme));
+  notify();
+}
+function ensure() {
+  if (hydrated) return;
+  hydrated = true;
+  if (typeof window === "undefined") return;
+  try {
+    assignPrefs(parseStoredPreferences(window.localStorage.getItem(SOUND_STORAGE_KEY)));
+    status.storage = "ok";
+  } catch {
+    status.storage = "unavailable";
+  }
+  status.supported = typeof window.AudioContext !== "undefined" || "webkitAudioContext" in window;
+  if (!status.supported) status.engine = "unsupported";
+  if (!storageListenerAttached) {
+    storageListenerAttached = true;
+    window.addEventListener("storage", handleStorage);
+  }
+  bump();
+}
+function ensureEngine() {
+  if (!engine) {
+    engine = createSoundEngine({
+      onStateChange: (state, error) => {
+        status.engine = state;
+        if (error) status.lastError = error;
+        bump();
+      },
+      masterVolume: prefs.volume,
+      theme: getSoundTheme(prefs.theme)
+    });
+  }
+  return engine;
+}
+function markPlayed(cue) {
+  status.lastCue = cue;
+  status.lastPlayedAt = performance.now();
+  bump();
+}
+const statusView = {
+  get supported() {
+    return status.supported;
+  },
+  get enabled() {
+    return prefs.enabled;
+  },
+  get volume() {
+    return prefs.volume;
+  },
+  get theme() {
+    return prefs.theme;
+  },
+  get engine() {
+    return status.engine;
+  },
+  get storage() {
+    return status.storage;
+  },
+  get lastCue() {
+    return status.lastCue;
+  },
+  get lastPlayedAt() {
+    return status.lastPlayedAt;
+  },
+  get lastError() {
+    return status.lastError;
+  }
+};
+const sound = {
+  get enabled() {
+    ensure();
+    return prefs.enabled;
+  },
+  get volume() {
+    ensure();
+    return prefs.volume;
+  },
+  get theme() {
+    ensure();
+    return prefs.theme;
+  },
+  get preferences() {
+    ensure();
+    return snapshot();
+  },
+  get status() {
+    ensure();
+    return statusView;
+  },
+  play(cue, options) {
+    ensure();
+    if (typeof window === "undefined") return;
+    if (!prefs.enabled) return;
+    const eng = ensureEngine();
+    if (eng.play(cue, options)) {
+      markPlayed(cue);
+      return;
+    }
+    if (eng.state !== "idle" && eng.state !== "suspended" && eng.state !== "blocked") return;
+    pending = { cue, options };
+    if (unlocking) return;
+    unlocking = true;
+    void eng.unlock().then((ok) => {
+      unlocking = false;
+      const next = pending;
+      pending = null;
+      if (!ok || !next || !prefs.enabled) return;
+      if (eng.play(next.cue, next.options)) markPlayed(next.cue);
+    });
+  },
+  unlock() {
+    ensure();
+    if (typeof window === "undefined") return Promise.resolve(false);
+    return ensureEngine().unlock();
+  },
+  enable() {
+    ensure();
+    prefs.enabled = true;
+    persist();
+    notify();
+    void sound.unlock();
+  },
+  disable() {
+    ensure();
+    prefs.enabled = false;
+    persist();
+    notify();
+  },
+  // toggle() and setEnabled() route through enable()/disable() so all three
+  // share one unlock policy — a consumer building their own control with
+  // `sound.toggle()` gets the same gesture-bound AudioContext as SoundToggle.
+  toggle() {
+    ensure();
+    if (prefs.enabled) sound.disable();
+    else sound.enable();
+    return prefs.enabled;
+  },
+  setEnabled(enabled) {
+    ensure();
+    if (enabled === true) sound.enable();
+    else sound.disable();
+  },
+  setVolume(volume) {
+    ensure();
+    if (!Number.isFinite(volume)) return;
+    prefs.volume = Math.min(1, Math.max(0, volume));
+    persist();
+    engine?.setMasterVolume(prefs.volume);
+    notify();
+  },
+  setTheme(theme) {
+    ensure();
+    if (!SOUND_THEME_NAMES.includes(theme)) return;
+    prefs.theme = theme;
+    persist();
+    engine?.setTheme(getSoundTheme(theme));
+    notify();
+  },
+  subscribe(run) {
+    ensure();
+    subscribers.add(run);
+    run(snapshot());
+    return () => {
+      subscribers.delete(run);
+    };
+  }
+};
+function getSoundStatus() {
+  ensure();
+  return {
+    supported: status.supported,
+    enabled: prefs.enabled,
+    volume: prefs.volume,
+    theme: prefs.theme,
+    engine: status.engine,
+    storage: status.storage,
+    lastCue: status.lastCue,
+    lastPlayedAt: status.lastPlayedAt,
+    lastError: status.lastError
+  };
+}
+const SERVER_SNAPSHOT = Object.freeze({
+  enabled: DEFAULT_SOUND_PREFERENCES.enabled,
+  volume: DEFAULT_SOUND_PREFERENCES.volume,
+  theme: DEFAULT_SOUND_PREFERENCES.theme,
+  status: Object.freeze(createInitialStatus())
+});
+let snapshotCache = SERVER_SNAPSHOT;
+let snapshotVersion = version;
+function subscribeSound(listener) {
+  reactListeners.add(listener);
+  return () => {
+    reactListeners.delete(listener);
+  };
+}
+function getSoundSnapshot() {
+  if (snapshotVersion !== version) {
+    snapshotVersion = version;
+    snapshotCache = {
+      enabled: prefs.enabled,
+      volume: prefs.volume,
+      theme: prefs.theme,
+      status: {
+        supported: status.supported,
+        enabled: prefs.enabled,
+        volume: prefs.volume,
+        theme: prefs.theme,
+        engine: status.engine,
+        storage: status.storage,
+        lastCue: status.lastCue,
+        lastPlayedAt: status.lastPlayedAt,
+        lastError: status.lastError
+      }
+    };
+  }
+  return snapshotCache;
+}
+function getSoundServerSnapshot() {
+  return SERVER_SNAPSHOT;
+}
+function hydrateSound() {
+  ensure();
+}
+export {
+  getSoundServerSnapshot,
+  getSoundSnapshot,
+  getSoundStatus,
+  hydrateSound,
+  parseStoredPreferences,
+  sound,
+  subscribeSound
+};

package/dist/sound/themes.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Sound themes — pure data plus a validator.
+ *
+ * `FANCY_SOUND_THEME` is the original FancyUI palette: glassy sine/triangle
+ * pings with short noise transients. Rising pitch reads as positive/open,
+ * falling pitch as negative/close (workflow/contracts.md §4).
+ */
+import { type SoundThemeDefinition, type SoundThemeName } from "./types.js";
+export declare const FANCY_SOUND_THEME: SoundThemeDefinition;
+export declare const SOUND_THEMES: Readonly<Record<SoundThemeName, SoundThemeDefinition>>;
+/** Falls back to the fancy theme for unknown names (runtime safety for stored prefs). */
+export declare function getSoundTheme(name: SoundThemeName): SoundThemeDefinition;
+/**
+ * Returns human-readable problems; [] when valid. Checks: every cue present, ≥1
+ * layer, all numbers finite/non-negative, gains ≤ 1, sustain 0..1,
+ * duration ≥ attack+decay+release, layer ≤ SOUND_LIMITS.MAX_LAYER_MS, whole-cue
+ * span (max(delay+duration)) ≤ 120ms except success/error ≤ 300ms.
+ */
+export declare function validateSoundTheme(theme: SoundThemeDefinition): string[];