fancy-ui-react 0.2.0

package/dist/sound/engine.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Sound engine — a lazy, rune-free Web Audio interpreter for cue recipes.
+ *
+ * Owned by Agent 03. Exported names and signatures are the contract
+ * (see workflow/contracts.md §3) and must not change.
+ *
+ * Invariants every implementation must keep:
+ * - `createSoundEngine()` allocates nothing. Only `play()` / `unlock()` may
+ *   touch Web Audio, and only through `ensureContext()`.
+ * - Never throws. Every failure is swallowed into `state` / `lastError`.
+ * - No module-evaluation access to window/navigator/AudioContext.
+ */
+import { type SoundCue, type SoundEngineState, type SoundPlayOptions, type SoundThemeDefinition } from "./types.js";
+export interface SoundEngineOptions {
+    /**
+     * Returns the context to use, or null when none can/should be created.
+     * Default: lazily `new (window.AudioContext ?? window.webkitAudioContext)()`, memoised.
+     * Tests inject a FakeAudioContext here.
+     */
+    getContext?: () => AudioContext | null;
+    /** Monotonic clock in ms for rate limiting. Default `performance.now`, falling back to `Date.now`. */
+    now?: () => number;
+    /**
+     * Whether a context may be created right now. Default:
+     * `typeof navigator === "undefined" ? false : (navigator.userActivation?.isActive ?? true)`.
+     * Keeps context creation inside a user gesture; when it returns false and no
+     * context exists yet, `play()` returns false and state stays "idle".
+     */
+    canCreateContext?: () => boolean;
+    /** Initial theme. Default `FANCY_SOUND_THEME`. */
+    theme?: SoundThemeDefinition;
+    /** Overrides for `SOUND_MIN_INTERVAL_MS`. */
+    minIntervals?: Partial<Record<SoundCue, number>>;
+    /** Initial master volume 0..1. Default 0.5. */
+    masterVolume?: number;
+    /** Mirrors every state transition (the controller lifts this into `$state`). */
+    onStateChange?: (state: SoundEngineState, error: string | null) => void;
+}
+export interface SoundEngine {
+    readonly state: SoundEngineState;
+    readonly lastError: string | null;
+    /** Voices currently sounding (for leak tests and the status line). */
+    readonly voiceCount: number;
+    /**
+     * `true` once an AudioContext constructor was found in this environment
+     * (probed without constructing). `false` on the server.
+     */
+    readonly supported: boolean;
+    /**
+     * Schedules `cue` now. Returns true only if a voice was actually scheduled.
+     * Returns false (never throws) when: unsupported, no context and creation not
+     * allowed, context not running (resume is kicked off, cue dropped), rate-limited,
+     * MAX_VOICES reached, unknown cue.
+     */
+    play(cue: SoundCue, options?: SoundPlayOptions): boolean;
+    /**
+     * Creates the context if allowed and resumes it if suspended. Resolves true
+     * when the context is running afterwards. Never rejects. Call from a gesture.
+     */
+    unlock(): Promise<boolean>;
+    /** 0..1; engine multiplies by SOUND_LIMITS.MASTER_CEILING. Ramped over ~20ms. */
+    setMasterVolume(volume: number): void;
+    setTheme(theme: SoundThemeDefinition): void;
+    /** Fades live voices out, stops/disconnects all nodes, closes an owned context, state → "idle". Idempotent. */
+    dispose(): void;
+}
+export declare function createSoundEngine(options?: SoundEngineOptions): SoundEngine;

package/dist/sound/engine.js

@@ -0,0 +1,370 @@
+"use client";
+import { SOUND_MIN_INTERVAL_MS, SOUND_LIMITS } from "./types.js";
+import { FANCY_SOUND_THEME } from "./themes.js";
+function clamp(value, min, max) {
+  return Math.min(max, Math.max(min, value));
+}
+function errorMessage(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+function defaultGetContext() {
+  if (typeof window === "undefined") return null;
+  const w = window;
+  const Ctor = w.AudioContext ?? w.webkitAudioContext;
+  return Ctor ? new Ctor() : null;
+}
+function defaultCanCreateContext() {
+  if (typeof navigator === "undefined") return false;
+  const nav = navigator;
+  return nav.userActivation?.isActive ?? true;
+}
+function defaultNow() {
+  return typeof performance !== "undefined" ? performance.now() : Date.now();
+}
+function probeSupported() {
+  if (typeof window === "undefined") return false;
+  const w = window;
+  return typeof w.AudioContext !== "undefined" || typeof w.webkitAudioContext !== "undefined";
+}
+function fillNoise(data) {
+  let s = 2654435769;
+  for (let i = 0; i < data.length; i++) {
+    s ^= s << 13;
+    s >>>= 0;
+    s ^= s >>> 17;
+    s >>>= 0;
+    s ^= s << 5;
+    s >>>= 0;
+    data[i] = s / 4294967295 * 2 - 1;
+  }
+}
+function createSoundEngine(options = {}) {
+  const getContextFn = options.getContext ?? defaultGetContext;
+  const canCreateContextFn = options.canCreateContext ?? defaultCanCreateContext;
+  const nowFn = options.now ?? defaultNow;
+  const minIntervals = options.minIntervals ?? {};
+  let theme = options.theme ?? FANCY_SOUND_THEME;
+  let masterVolume = clamp(
+    Number.isFinite(options.masterVolume) ? options.masterVolume : 0.5,
+    0,
+    1
+  );
+  const onStateChangeCb = options.onStateChange;
+  let ctx = null;
+  let master = null;
+  let limiter = null;
+  let statechangeListener = null;
+  let noiseBuffer = null;
+  let resumePromise = null;
+  let disposeGeneration = 0;
+  let state = "idle";
+  let lastError = null;
+  let voiceCount = 0;
+  const activeVoices = /* @__PURE__ */ new Set();
+  const lastAt = {};
+  function setState(next, error) {
+    if (next === state) {
+      if (error) lastError = error;
+      return;
+    }
+    state = next;
+    lastError = error;
+    onStateChangeCb?.(next, error);
+  }
+  function syncFromContextState(rawState) {
+    if (rawState === "running") setState("ready", null);
+    else if (rawState === "suspended" || rawState === "interrupted") setState("suspended", null);
+    else if (rawState === "closed") setState("blocked", null);
+  }
+  function attachContext(context) {
+    ctx = context;
+    const listener = () => syncFromContextState(context.state);
+    context.addEventListener("statechange", listener);
+    statechangeListener = listener;
+    master = context.createGain();
+    master.gain.value = masterVolume * SOUND_LIMITS.MASTER_CEILING;
+    if (typeof context.createDynamicsCompressor === "function") {
+      try {
+        const comp = context.createDynamicsCompressor();
+        comp.threshold.value = -12;
+        comp.knee.value = 6;
+        comp.ratio.value = 12;
+        comp.attack.value = 3e-3;
+        comp.release.value = 0.1;
+        master.connect(comp);
+        comp.connect(context.destination);
+        limiter = comp;
+      } catch {
+        limiter = null;
+        master.connect(context.destination);
+      }
+    } else {
+      master.connect(context.destination);
+    }
+    syncFromContextState(context.state);
+  }
+  function ensureContext() {
+    if (ctx) return ctx;
+    if (!canCreateContextFn()) return null;
+    let created;
+    try {
+      created = getContextFn();
+      if (!created) {
+        setState("unsupported", null);
+        return null;
+      }
+      attachContext(created);
+    } catch (err) {
+      setState("unsupported", errorMessage(err));
+      return null;
+    }
+    return created;
+  }
+  function kickResume(context) {
+    if (resumePromise) return resumePromise;
+    const generation = disposeGeneration;
+    const isCurrent = () => generation === disposeGeneration && ctx === context;
+    resumePromise = context.resume().then(() => {
+      if (isCurrent()) syncFromContextState(context.state);
+    }).catch((err) => {
+      if (isCurrent()) setState("blocked", errorMessage(err));
+    }).finally(() => {
+      if (generation === disposeGeneration) resumePromise = null;
+    });
+    return resumePromise;
+  }
+  const NOISE_BUFFER_SECONDS = 0.25;
+  function getNoiseBuffer(context) {
+    if (noiseBuffer) return noiseBuffer;
+    const length = Math.max(1, Math.round(context.sampleRate * NOISE_BUFFER_SECONDS));
+    const buffer = context.createBuffer(1, length, context.sampleRate);
+    fillNoise(buffer.getChannelData(0));
+    noiseBuffer = buffer;
+    return buffer;
+  }
+  let noiseOffsetStep = 0;
+  function nextNoiseOffset(buffer) {
+    noiseOffsetStep = (noiseOffsetStep + 1) % 8;
+    return buffer.duration * noiseOffsetStep / 8;
+  }
+  function renderLayer(context, masterNode, layer, recipeGain, opts) {
+    const { volume, pitch, rate } = opts;
+    const delayMs = layer.delay ?? 0;
+    const t0 = context.currentTime + delayMs / 1e3 / rate;
+    const durationMs = Math.min(layer.duration, SOUND_LIMITS.MAX_LAYER_MS);
+    const durationSec = durationMs / 1e3 / rate;
+    const pitchMul = 2 ** (pitch / 12);
+    let source;
+    let noiseStartOffset = 0;
+    if (layer.kind === "oscillator") {
+      const osc = context.createOscillator();
+      osc.type = layer.wave;
+      const freqStart = layer.frequency * pitchMul;
+      osc.frequency.value = freqStart;
+      if (layer.detune) osc.detune.value = layer.detune;
+      if (layer.frequencyEnd != null) {
+        const freqEnd = layer.frequencyEnd * pitchMul;
+        osc.frequency.setValueAtTime(freqStart, t0);
+        osc.frequency.exponentialRampToValueAtTime(Math.max(1, freqEnd), t0 + durationSec);
+      }
+      source = osc;
+    } else {
+      const buf = context.createBufferSource();
+      buf.buffer = getNoiseBuffer(context);
+      buf.loop = true;
+      source = buf;
+      noiseStartOffset = nextNoiseOffset(buf.buffer);
+    }
+    const nodes = [source];
+    let node = source;
+    if (layer.filter) {
+      const filterNode = context.createBiquadFilter();
+      filterNode.type = layer.filter.type;
+      filterNode.frequency.value = layer.filter.frequency;
+      if (layer.filter.q != null) filterNode.Q.value = layer.filter.q;
+      if (layer.filter.frequencyEnd != null) {
+        filterNode.frequency.setValueAtTime(layer.filter.frequency, t0);
+        filterNode.frequency.exponentialRampToValueAtTime(
+          Math.max(1, layer.filter.frequencyEnd),
+          t0 + durationSec
+        );
+      }
+      node.connect(filterNode);
+      node = filterNode;
+      nodes.push(filterNode);
+    }
+    const gainNode = context.createGain();
+    node.connect(gainNode);
+    gainNode.connect(masterNode);
+    nodes.push(gainNode);
+    const a = Math.max(layer.envelope.attack, SOUND_LIMITS.MIN_ATTACK_MS) / 1e3 / rate;
+    const d = layer.envelope.decay / 1e3 / rate;
+    const r = Math.max(layer.envelope.release, SOUND_LIMITS.MIN_RELEASE_MS) / 1e3 / rate;
+    const sustain = layer.envelope.sustain;
+    const peak = Math.min(layer.gain * recipeGain * volume, SOUND_LIMITS.LAYER_PEAK_CEILING);
+    const tRel = t0 + durationSec - r;
+    gainNode.gain.setValueAtTime(0, t0);
+    gainNode.gain.linearRampToValueAtTime(peak, t0 + a);
+    gainNode.gain.linearRampToValueAtTime(peak * sustain, t0 + a + d);
+    gainNode.gain.setValueAtTime(peak * sustain, tRel);
+    gainNode.gain.linearRampToValueAtTime(0, tRel + r);
+    if (layer.kind === "noise") source.start(t0, noiseStartOffset);
+    else source.start(t0);
+    source.stop(t0 + durationSec + 0.01);
+    return { nodes, source };
+  }
+  return {
+    get state() {
+      return state;
+    },
+    get lastError() {
+      return lastError;
+    },
+    get voiceCount() {
+      return voiceCount;
+    },
+    get supported() {
+      return probeSupported();
+    },
+    play(cue, options2 = {}) {
+      if (state === "unsupported") return false;
+      const recipe = theme.cues[cue];
+      if (!recipe) return false;
+      const interval = minIntervals[cue] ?? SOUND_MIN_INTERVAL_MS[cue] ?? 15;
+      const last = lastAt[cue] ?? Number.NEGATIVE_INFINITY;
+      if (nowFn() - last < interval) return false;
+      const context = ensureContext();
+      if (!context) return false;
+      if (context.state !== "running") {
+        void kickResume(context);
+        return false;
+      }
+      if (voiceCount + recipe.layers.length > SOUND_LIMITS.MAX_VOICES) return false;
+      const volume = clamp(Number.isFinite(options2.volume) ? options2.volume : 1, 0, 1);
+      const pitch = clamp(Number.isFinite(options2.pitch) ? options2.pitch : 0, -24, 24);
+      const rate = clamp(
+        Number.isFinite(options2.playbackRate) ? options2.playbackRate : 1,
+        0.25,
+        4
+      );
+      const recipeGain = recipe.gain ?? 1;
+      const createdVoices = [];
+      try {
+        if (!master) throw new Error("master gain missing");
+        for (const layer of recipe.layers) {
+          createdVoices.push(
+            renderLayer(context, master, layer, recipeGain, { volume, pitch, rate })
+          );
+        }
+      } catch (err) {
+        for (const voice of createdVoices) {
+          for (const n of voice.nodes) {
+            try {
+              n.disconnect();
+            } catch {
+            }
+          }
+        }
+        lastError = errorMessage(err);
+        return false;
+      }
+      voiceCount += createdVoices.length;
+      for (const voice of createdVoices) {
+        activeVoices.add(voice);
+        voice.source.onended = () => {
+          activeVoices.delete(voice);
+          for (const n of voice.nodes) {
+            try {
+              n.disconnect();
+            } catch {
+            }
+          }
+          voiceCount = Math.max(0, voiceCount - 1);
+        };
+      }
+      lastAt[cue] = nowFn();
+      return true;
+    },
+    async unlock() {
+      try {
+        const context = ensureContext();
+        if (!context) return false;
+        if (context.state !== "running") {
+          await kickResume(context);
+        }
+        return context.state === "running";
+      } catch {
+        return false;
+      }
+    },
+    setMasterVolume(volume) {
+      const v = clamp(Number.isFinite(volume) ? volume : 0, 0, 1);
+      masterVolume = v;
+      if (master && ctx) {
+        const now = ctx.currentTime;
+        const target = v * SOUND_LIMITS.MASTER_CEILING;
+        master.gain.cancelScheduledValues(now);
+        master.gain.linearRampToValueAtTime(target, now + 0.02);
+      }
+    },
+    setTheme(next) {
+      theme = next;
+    },
+    dispose() {
+      disposeGeneration += 1;
+      for (const voice of [...activeVoices]) {
+        try {
+          const now = ctx ? ctx.currentTime : 0;
+          const gainNode = voice.nodes[voice.nodes.length - 1];
+          gainNode.gain.cancelScheduledValues(now);
+          gainNode.gain.setValueAtTime(0, now);
+          voice.source.stop(now);
+        } catch {
+        }
+        for (const n of voice.nodes) {
+          try {
+            n.disconnect();
+          } catch {
+          }
+        }
+      }
+      activeVoices.clear();
+      voiceCount = 0;
+      if (master) {
+        try {
+          master.disconnect();
+        } catch {
+        }
+        master = null;
+      }
+      if (limiter) {
+        try {
+          limiter.disconnect();
+        } catch {
+        }
+        limiter = null;
+      }
+      if (ctx) {
+        if (statechangeListener) {
+          try {
+            ctx.removeEventListener("statechange", statechangeListener);
+          } catch {
+          }
+        }
+        try {
+          void ctx.close();
+        } catch {
+        }
+        ctx = null;
+      }
+      statechangeListener = null;
+      noiseBuffer = null;
+      resumePromise = null;
+      for (const key of Object.keys(lastAt)) delete lastAt[key];
+      setState("idle", null);
+    }
+  };
+}
+export {
+  createSoundEngine
+};

package/dist/sound/index.d.ts

@@ -0,0 +1,7 @@
+export { SoundToggle, type SoundToggleProps, type SoundToggleSize, type SoundToggleVariant, } from "./SoundToggle.js";
+export { sound, getSoundStatus, type SoundController, type SoundSnapshot } from "./sound.js";
+export { attachSoundFeedback, useSoundFeedback, DEFAULT_SOUND_FEEDBACK_ON, type SoundFeedbackOptions, type SoundFeedbackHandle, type SoundCueResolver, type SoundCueSpec, } from "./sound-feedback.js";
+export { useSound, useSoundCue, useSoundEnabled, useSoundStatus, type SoundControls, } from "./use-sound.js";
+export { createSoundEngine, type SoundEngine, type SoundEngineOptions } from "./engine.js";
+export { FANCY_SOUND_THEME, SOUND_THEMES, getSoundTheme, validateSoundTheme } from "./themes.js";
+export { SOUND_CUES, SOUND_THEME_NAMES, SOUND_STORAGE_KEY, SOUND_MIN_INTERVAL_MS, SOUND_LIMITS, DEFAULT_SOUND_PREFERENCES, type SoundCue, type SoundThemeName, type SoundPlayOptions, type SoundPreferences, type SoundPreferencesV1, type SoundStatus, type SoundEngineState, type SoundThemeDefinition, type CueRecipe, type SoundLayer, type SoundOscillatorLayer, type SoundNoiseLayer, type SoundEnvelope, type SoundFilter, type SoundWave, } from "./types.js";

package/dist/sound/sound-feedback.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Declarative event → cue mapping for any element.
+ *
+ * Semantics:
+ * - SSR (`typeof document === "undefined"`) → an inert handle, nothing bound.
+ * - Listeners are bound `{ passive: true }`; this module never calls
+ *   `preventDefault`/`stopPropagation` — it only listens.
+ * - Defaults to `{ click: "press" }`. Hover is opt-in (`on: { pointerenter:
+ *   "hover" }`) — a hover cue is a deliberate choice for dense pointer UI, not
+ *   something every button should inherit. `on` REPLACES the defaults.
+ * - Universal guard: `opts.disabled` or the node matching
+ *   `:disabled,[aria-disabled="true"],[data-disabled="true"]` → silent.
+ * - Hover guard (pointerenter/mouseenter only), all of which must pass:
+ *   · `event.isTrusted` unless `allowUntrusted`;
+ *   · `pointerType` is "mouse" or "pen" — a touch tap fires pointerenter and
+ *     then click, and one tap must be one cue; "" is a synthesized pointer; a
+ *     compatibility mouseenter from a tap carries `sourceCapabilities.firesTouchEvents`;
+ *   · a pointer actually moved within the last HOVER_RECENCY_MS — content
+ *     scrolling under a stationary pointer also fires pointerenter, and that
+ *     is not a hover;
+ *   · `relatedTarget` is not inside the node (re-entry from a descendant).
+ * - Resolver errors are swallowed — a broken resolver silences that event,
+ *   it never throws into the DOM dispatch.
+ * - `update()` unbinds every listener and rebinds from the new options.
+ *   `destroy()` unbinds every listener.
+ */
+import type { SoundCue } from "./types.js";
+/** Return a cue to play, or null/undefined to stay silent for this event. */
+export type SoundCueResolver = (event: Event) => SoundCue | null | undefined;
+export type SoundCueSpec = SoundCue | SoundCueResolver;
+export interface SoundFeedbackOptions {
+    /**
+     * DOM event name → cue. When omitted the default is `{ click: "press" }`.
+     * When given it REPLACES the defaults — add `pointerenter: "hover"` to opt
+     * into hover feedback.
+     */
+    on?: Record<string, SoundCueSpec>;
+    /** Skips every cue while true. */
+    disabled?: boolean;
+    /** Forwarded to `sound.play` for every cue. */
+    volume?: number;
+    pitch?: number;
+    /** Let `isTrusted === false` hover events through (tests, programmatic pointer events). Default false. */
+    allowUntrusted?: boolean;
+}
+/** The handle `attachSoundFeedback` returns — the action's `{ update, destroy }`. */
+export interface SoundFeedbackHandle {
+    update(next?: SoundFeedbackOptions): void;
+    destroy(): void;
+}
+export declare const DEFAULT_SOUND_FEEDBACK_ON: Readonly<Record<string, SoundCue>>;
+/** Test-only: drops the shared pointer-tracking state between tests. Not exported from index.ts. */
+export declare function resetSoundFeedbackForTests(): void;
+/** Test-only leak counter for the shared document-level `pointermove` listener. */
+export declare function __soundFeedbackHoverInstances(): number;
+/**
+ * The framework-free core: binds the mapped listeners to `node` and hands back
+ * the action's own `{ update, destroy }`.
+ */
+export declare function attachSoundFeedback(node: HTMLElement, initialOptions?: SoundFeedbackOptions): SoundFeedbackHandle;
+/**
+ * The hook binding, in two shapes.
+ *
+ * `useSoundFeedback(options?)` returns a callback ref to put straight on the
+ * element — the common case, and the idiomatic React answer to `use:soundFeedback`:
+ *
+ *     const soundRef = useSoundFeedback({ on: { click: "press" } });
+ *     return <button ref={soundRef} />;
+ *
+ * `useSoundFeedback(node, options?)` takes a node you already hold (convention
+ * C-1, paired with `useElementRef`); `null` binds nothing. Use it when the same
+ * element is already published for another hook, so it is not published twice.
+ *
+ * The two are the same binding — the first just owns the node state for you.
+ */
+export declare function useSoundFeedback(node: HTMLElement | null, options?: SoundFeedbackOptions): void;
+export declare function useSoundFeedback(options?: SoundFeedbackOptions): (node: HTMLElement | null) => void;

package/dist/sound/sound-feedback.js

@@ -0,0 +1,152 @@
+"use client";
+import { useEffect } from "react";
+import { useElementRef } from "../internals/dom/use-element-ref.js";
+import { useLiveRef } from "../internals/dom/use-live-ref.js";
+import { sound } from "./sound.js";
+const DEFAULT_SOUND_FEEDBACK_ON = Object.freeze({
+  click: "press"
+});
+const HOVER_EVENTS = /* @__PURE__ */ new Set(["pointerenter", "mouseenter"]);
+const HOVER_POINTER_TYPES = /* @__PURE__ */ new Set(["mouse", "pen"]);
+const HOVER_RECENCY_MS = 150;
+let lastPointerMoveAt = -Infinity;
+let hoverInstances = 0;
+function onDocumentPointerMove() {
+  lastPointerMoveAt = performance.now();
+}
+function retainHoverTracking() {
+  if (hoverInstances++ === 0) {
+    document.addEventListener("pointermove", onDocumentPointerMove, {
+      capture: true,
+      passive: true
+    });
+  }
+}
+function releaseHoverTracking() {
+  if (--hoverInstances === 0) {
+    document.removeEventListener("pointermove", onDocumentPointerMove, { capture: true });
+    lastPointerMoveAt = -Infinity;
+  }
+}
+function attachSoundFeedback(node, initialOptions) {
+  if (typeof document === "undefined") {
+    return { update() {
+    }, destroy() {
+    } };
+  }
+  let options = initialOptions ?? {};
+  let bound = [];
+  let tracksHover = false;
+  function isDisabled() {
+    if (options.disabled) return true;
+    return node.matches(':disabled,[aria-disabled="true"],[data-disabled="true"]');
+  }
+  function isSuppressedHover(event) {
+    if (event.isTrusted === false && !options.allowUntrusted) return true;
+    const pointerType = event.pointerType;
+    if (pointerType !== void 0 && !HOVER_POINTER_TYPES.has(pointerType)) return true;
+    const capabilities = event.sourceCapabilities;
+    if (capabilities?.firesTouchEvents) return true;
+    if (performance.now() - lastPointerMoveAt > HOVER_RECENCY_MS) return true;
+    const relatedTarget = event.relatedTarget;
+    if (relatedTarget instanceof Node && node.contains(relatedTarget)) return true;
+    return false;
+  }
+  function makeListener(eventName, spec) {
+    return (event) => {
+      if (isDisabled()) return;
+      if (HOVER_EVENTS.has(eventName) && isSuppressedHover(event)) return;
+      let cue;
+      try {
+        cue = typeof spec === "function" ? spec(event) : spec;
+      } catch {
+        return;
+      }
+      if (cue == null) return;
+      sound.play(cue, { volume: options.volume, pitch: options.pitch });
+    };
+  }
+  function bind() {
+    const on = options.on ?? DEFAULT_SOUND_FEEDBACK_ON;
+    bound = Object.entries(on).map(([event, spec]) => {
+      const listener = makeListener(event, spec);
+      node.addEventListener(event, listener, { passive: true });
+      return { event, listener };
+    });
+    tracksHover = bound.some(({ event }) => HOVER_EVENTS.has(event));
+    if (tracksHover) retainHoverTracking();
+  }
+  function unbind() {
+    for (const { event, listener } of bound) {
+      node.removeEventListener(event, listener);
+    }
+    bound = [];
+    if (tracksHover) {
+      tracksHover = false;
+      releaseHoverTracking();
+    }
+  }
+  bind();
+  return {
+    update(next) {
+      options = next ?? {};
+      unbind();
+      bind();
+    },
+    destroy() {
+      unbind();
+    }
+  };
+}
+const EMPTY_OPTIONS = {};
+const EVENT_KEY_SEPARATOR = "\0";
+function isElement(value) {
+  return typeof value?.nodeType === "number";
+}
+function useSoundFeedback(nodeOrOptions, maybeOptions) {
+  const isNodeForm = nodeOrOptions === null || isElement(nodeOrOptions);
+  const [ownNode, ownRef] = useElementRef();
+  const node = isNodeForm ? nodeOrOptions : ownNode;
+  const options = isNodeForm ? maybeOptions : nodeOrOptions;
+  useSoundFeedbackBinding(node, options);
+  return isNodeForm ? void 0 : ownRef;
+}
+function useSoundFeedbackBinding(node, options) {
+  const optionsRef = useLiveRef(options ?? EMPTY_OPTIONS);
+  const eventKey = Object.keys(options?.on ?? DEFAULT_SOUND_FEEDBACK_ON).sort().join(EVENT_KEY_SEPARATOR);
+  useEffect(() => {
+    if (!node) return;
+    const names = eventKey === "" ? [] : eventKey.split(EVENT_KEY_SEPARATOR);
+    const on = {};
+    for (const name of names) {
+      on[name] = (event) => {
+        const spec = (optionsRef.current.on ?? DEFAULT_SOUND_FEEDBACK_ON)[name];
+        return typeof spec === "function" ? spec(event) : spec;
+      };
+    }
+    const live = {
+      on,
+      get disabled() {
+        return optionsRef.current.disabled;
+      },
+      get volume() {
+        return optionsRef.current.volume;
+      },
+      get pitch() {
+        return optionsRef.current.pitch;
+      },
+      get allowUntrusted() {
+        return optionsRef.current.allowUntrusted;
+      }
+    };
+    const handle = attachSoundFeedback(node, live);
+    return () => {
+      handle.destroy();
+    };
+  }, [node, eventKey, optionsRef]);
+}
+export {
+  DEFAULT_SOUND_FEEDBACK_ON,
+  attachSoundFeedback,
+  useSoundFeedback
+};