4e:I[707087,["/_next/static/immutable/chunks/3arlv5bvukoo2.js","/_next/static/immutable/chunks/39v64hmfyo-sr.js","/_next/static/immutable/chunks/2nvof3-29tvc3.js","/_next/static/immutable/chunks/3tjobt77z_9dj.js","/_next/static/immutable/chunks/04j_o97cgxn2x.js","/_next/static/immutable/chunks/3upr08c9vtj8w.js","/_next/static/immutable/chunks/1ww0328si-u8x.js","/_next/static/immutable/chunks/11mfl5ymqld9-.js","/_next/static/immutable/chunks/2xxcqy6ppds3l.js","/_next/static/immutable/chunks/3j06ow7w40nxu.js","/_next/static/immutable/chunks/31nn7jwsjvqii.js","/_next/static/immutable/chunks/43_s7jweyypoh.js","/_next/static/immutable/chunks/0p6vao205o1jc.js","/_next/static/immutable/chunks/1_kyvgkyokw92.js","/_next/static/immutable/chunks/1lo-zn37dolb5.js","/_next/static/immutable/chunks/1v8k6yxw1rg0u.js"],"RegistryDependencies"] 4f:I[314491,["/_next/static/immutable/chunks/3arlv5bvukoo2.js","/_next/static/immutable/chunks/39v64hmfyo-sr.js","/_next/static/immutable/chunks/2nvof3-29tvc3.js","/_next/static/immutable/chunks/3tjobt77z_9dj.js","/_next/static/immutable/chunks/04j_o97cgxn2x.js","/_next/static/immutable/chunks/3upr08c9vtj8w.js","/_next/static/immutable/chunks/1ww0328si-u8x.js","/_next/static/immutable/chunks/11mfl5ymqld9-.js","/_next/static/immutable/chunks/2xxcqy6ppds3l.js","/_next/static/immutable/chunks/3j06ow7w40nxu.js","/_next/static/immutable/chunks/31nn7jwsjvqii.js","/_next/static/immutable/chunks/43_s7jweyypoh.js","/_next/static/immutable/chunks/0p6vao205o1jc.js","/_next/static/immutable/chunks/1_kyvgkyokw92.js","/_next/static/immutable/chunks/1lo-zn37dolb5.js","/_next/static/immutable/chunks/1v8k6yxw1rg0u.js"],"FilesView"] 50:T1579,"use client"; import { forwardRef } from "react"; import { cn } from "../utils"; import { sound } from "./sound"; import { useSoundEnabled, useSoundEngineState } from "./use-sound"; import "./sound-toggle.css"; export type SoundToggleSize = "sm" | "md" | "lg"; export type SoundToggleVariant = "outline" | "ghost"; export interface SoundToggleProps { /** Visual size of the control; `md` matches header-style triggers */ size?: SoundToggleSize; /** `"outline"` keeps a resting border, `"ghost"` shows one only on hover */ variant?: SoundToggleVariant; /** Renders the label and the On/Off word beside the icon; icon-only otherwise */ showLabel?: boolean; /** Accessible name of the switch. Stays constant — the state is announced through aria-checked */ label?: string; /** Visible state word when `showLabel` is set */ labelOn?: string; /** Visible state word when `showLabel` is set */ labelOff?: string; /** Disables the control. A browser with no Web Audio also disables it — but only while sound is off, so a stored "on" can always be undone */ disabled?: boolean; /** Called after the preference flips, with the new value */ onEnabledChange?: (enabled: boolean) => void; /** Additional CSS classes */ className?: string; } const SIZE_CLASSES = { sm: "h-8 gap-1 rounded-md px-1.5 text-xs", md: "h-9 gap-1.5 rounded-md px-2 text-sm", lg: "h-10 gap-2 rounded-md px-2.5 text-sm", } as const satisfies Record; const ICON_SIZE = { sm: 14, md: 16, lg: 18 } as const satisfies Record; export const SoundToggle = forwardRef(function SoundToggle( { size = "md", variant = "outline", showLabel = false, label = "Sound", labelOn = "On", labelOff = "Off", disabled = false, onEnabledChange, className, }, ref ) { const enabled = useSoundEnabled(); // Web Audio support is a browser fact, not a preference. A switch the engine // can never honour is presented disabled — but only while sound is OFF: // disabling it while it is on would strand the user with a persisted "on" // preference and no control left to undo it. // // The engine state is read through its own selector, not through the whole // `status` object: the object is rebuilt on every cue (lastCue, // lastPlayedAt), which would re-render this toggle every time anything on // the page made a sound. const unsupported = useSoundEngineState() === "unsupported"; const effectiveDisabled = disabled || (unsupported && !enabled); const classes = cn( "ft-sound-toggle text-foreground inline-flex shrink-0 items-center font-medium transition-colors", "focus-visible:outline-none", "disabled:pointer-events-none disabled:opacity-50", SIZE_CLASSES[size], variant === "outline" ? "border-border bg-background hover:bg-accent hover:text-accent-foreground border" : "hover:bg-accent hover:text-accent-foreground", className ); // The only place a confirmation cue plays: the click that just turned // sound on. `unlock()` creates/resumes the AudioContext inside this same // gesture, and the cue only fires once that context is actually running — // never on the click that turns sound off, never speculatively. // // The native `disabled` attribute already blocks a real user's click, but // a synthetic event dispatched straight at the element — as a test does — // walks past that guard the same way it does on Switch/Checkbox/Toggle, // so the early return is repeated here rather than trusted to the // attribute alone. function handleClick() { if (effectiveDisabled) return; const next = sound.toggle(); if (next) { void sound.unlock().then((ok) => { if (ok) sound.play("toggle-on"); }); } onEnabledChange?.(next); } return ( ); }); 51:T4a21,"use client"; /** * 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 { SOUND_LIMITS, SOUND_MIN_INTERVAL_MS, type SoundCue, type SoundEngineState, type SoundLayer, type SoundPlayOptions, type SoundThemeDefinition, } from "./types"; import { FANCY_SOUND_THEME } from "./themes"; 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>; /** 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; /** 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; } interface VoiceHandle { nodes: AudioNode[]; source: OscillatorNode | AudioBufferSourceNode; } /** Where exponential envelope segments bottom out before the final step to 0. */ const EXP_FLOOR = 1e-4; function clamp(value: number, min: number, max: number): number { return Math.min(max, Math.max(min, value)); } function errorMessage(err: unknown): string { return err instanceof Error ? err.message : String(err); } function defaultGetContext(): AudioContext | null { if (typeof window === "undefined") return null; const w = window as unknown as { AudioContext?: typeof AudioContext; webkitAudioContext?: typeof AudioContext; }; const Ctor = w.AudioContext ?? w.webkitAudioContext; return Ctor ? new Ctor() : null; } function defaultCanCreateContext(): boolean { if (typeof navigator === "undefined") return false; const nav = navigator as Navigator & { userActivation?: { isActive: boolean } }; return nav.userActivation?.isActive ?? true; } function defaultNow(): number { return typeof performance !== "undefined" ? performance.now() : Date.now(); } function probeSupported(): boolean { if (typeof window === "undefined") return false; const w = window as unknown as { AudioContext?: unknown; webkitAudioContext?: unknown }; return typeof w.AudioContext !== "undefined" || typeof w.webkitAudioContext !== "undefined"; } /** Seeded xorshift32 noise, mapped to [-1, 1]. Deterministic for a given length. */ function fillNoise(data: Float32Array): void { let s = 0x9e3779b9; 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 / 0xffffffff) * 2 - 1; } } export function createSoundEngine(options: SoundEngineOptions = {}): SoundEngine { 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 as number) : 0.5, 0, 1 ); const onStateChangeCb = options.onStateChange; let ctx: AudioContext | null = null; let master: GainNode | null = null; let limiter: DynamicsCompressorNode | null = null; let statechangeListener: (() => void) | null = null; let noiseBuffer: AudioBuffer | null = null; let resumePromise: Promise | null = null; // Bumped by dispose(). Async continuations captured before a teardown compare // against it and stay silent when they belong to a previous life. let disposeGeneration = 0; let state: SoundEngineState = "idle"; let lastError: string | null = null; let voiceCount = 0; const activeVoices = new Set(); const lastAt: Partial> = {}; function setState(next: SoundEngineState, error: string | null): void { if (next === state) { if (error) lastError = error; return; } state = next; lastError = error; onStateChangeCb?.(next, error); } function syncFromContextState(rawState: string): void { 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: AudioContext): void { 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(); // A safety limiter, not a colour: it only engages near full scale. // Set lower, its ~3 ms attack shaved the first transient of every // short tap (the part that makes a tap sound crisp) by up to 8 dB. comp.threshold.value = -3; comp.knee.value = 0; comp.ratio.value = 20; comp.attack.value = 0.001; 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(): AudioContext | null { if (ctx) return ctx; if (!canCreateContextFn()) return null; let created: AudioContext | null; try { created = getContextFn(); if (!created) { setState("unsupported", null); return null; } // A context whose createGain()/addEventListener throws degrades to // "unsupported" here instead of throwing out through a click handler. attachContext(created); } catch (err) { setState("unsupported", errorMessage(err)); return null; } return created; } function kickResume(context: AudioContext): Promise { if (resumePromise) return resumePromise; // dispose() can land while resume() is still pending. The continuations // below then hold a context this engine no longer owns, so they may only // touch state while that context is still the current one — otherwise a // disposed engine would report itself ready/blocked again and call its // state callback from an obsolete context. const generation = disposeGeneration; const isCurrent = () => generation === disposeGeneration && ctx === context; resumePromise = context .resume() .then(() => { if (isCurrent()) syncFromContextState(context.state); }) .catch((err: unknown) => { if (isCurrent()) setState("blocked", errorMessage(err)); }) .finally(() => { // A dispose() already cleared this slot (and a later kickResume may // own it now); only the current generation may null it out. if (generation === disposeGeneration) resumePromise = null; }); return resumePromise; } // 250 ms is longer than any noise layer a valid theme may contain // (SOUND_LIMITS.MAX_LAYER_MS is 400 but every transient is < 100 ms), and // sources loop — a full second would cost ~190 KiB and ~0.8 ms of fill on // the user's very first cue for nothing. const NOISE_BUFFER_SECONDS = 0.25; function getNoiseBuffer(context: AudioContext): AudioBuffer { 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; } // Each noise voice starts at a different offset into the shared buffer so // consecutive transients are not bit-identical; the rotation is // deterministic (no Math.random) so tests stay reproducible. let noiseOffsetStep = 0; function nextNoiseOffset(buffer: AudioBuffer): number { noiseOffsetStep = (noiseOffsetStep + 1) % 8; return (buffer.duration * noiseOffsetStep) / 8; } function renderLayer( context: AudioContext, masterNode: AudioNode, layer: SoundLayer, recipeGain: number, opts: { volume: number; pitch: number; rate: number } ): VoiceHandle { const { volume, pitch, rate } = opts; const delayMs = layer.delay ?? 0; const t0 = context.currentTime + delayMs / 1000 / rate; // MAX_LAYER_MS is documented as a non-configurable hard guard, but only // validateSoundTheme() enforces it — a theme passed straight to setTheme() // is never validated. Clamp here too so a huge finite duration cannot keep // a source/voice slot alive for minutes. const durationMs = Math.min(layer.duration, SOUND_LIMITS.MAX_LAYER_MS); const durationSec = durationMs / 1000 / rate; const pitchMul = 2 ** (pitch / 12); let source: OscillatorNode | AudioBufferSourceNode; 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; // A glide shorter than the layer lets a fast pitch drop ring out on // its landing note; unset or out-of-range falls back to the whole layer. const glideMs = layer.glide != null && Number.isFinite(layer.glide) && layer.glide > 0 ? Math.min(layer.glide, durationMs) : durationMs; osc.frequency.setValueAtTime(freqStart, t0); osc.frequency.exponentialRampToValueAtTime( Math.max(1, freqEnd), t0 + glideMs / 1000 / rate ); } source = osc; } else { const buf = context.createBufferSource(); buf.buffer = getNoiseBuffer(context); buf.loop = true; source = buf; noiseStartOffset = nextNoiseOffset(buf.buffer); } const nodes: AudioNode[] = [source]; let node: AudioNode = 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) / 1000 / rate; const d = layer.envelope.decay / 1000 / rate; const r = Math.max(layer.envelope.release, SOUND_LIMITS.MIN_RELEASE_MS) / 1000 / rate; const sustain = layer.envelope.sustain; const peak = Math.min(layer.gain * recipeGain * volume, SOUND_LIMITS.LAYER_PEAK_CEILING); const tDecayEnd = t0 + a + d; // Float drift can put `t0 + duration - r` a hair BEFORE `t0 + a + d` even // when the recipe makes them equal; a hold scheduled before the decay // ramp's end turns that whole ramp into a flat hold at the peak. const tRel = Math.max(t0 + durationSec - r, tDecayEnd); gainNode.gain.setValueAtTime(0, t0); gainNode.gain.linearRampToValueAtTime(peak, t0 + a); if (layer.envelope.curve === "exponential" && peak > EXP_FLOOR) { // Exponential ramps cannot reach 0, so they fall to a floor ~-80 dB // below full scale and the final step to 0 lands on silence. const held = Math.max(peak * sustain, EXP_FLOOR); if (d > 0) gainNode.gain.exponentialRampToValueAtTime(held, tDecayEnd); gainNode.gain.setValueAtTime(held, tRel); gainNode.gain.exponentialRampToValueAtTime(EXP_FLOOR, tRel + r); gainNode.gain.setValueAtTime(0, tRel + r); } else { gainNode.gain.linearRampToValueAtTime(peak * sustain, tDecayEnd); gainNode.gain.setValueAtTime(peak * sustain, tRel); gainNode.gain.linearRampToValueAtTime(0, tRel + r); } if (layer.kind === "noise") (source as AudioBufferSourceNode).start(t0, noiseStartOffset); else source.start(t0); source.stop(t0 + durationSec + 0.01); return { nodes, source }; } return { get state(): SoundEngineState { return state; }, get lastError(): string | null { return lastError; }, get voiceCount(): number { return voiceCount; }, get supported(): boolean { return probeSupported(); }, play(cue: SoundCue, options: SoundPlayOptions = {}): boolean { 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; } // Voices are counted per layer, so admit a cue only if ALL its layers fit. if (voiceCount + recipe.layers.length > SOUND_LIMITS.MAX_VOICES) return false; const volume = clamp(Number.isFinite(options.volume) ? (options.volume as number) : 1, 0, 1); const pitch = clamp(Number.isFinite(options.pitch) ? (options.pitch as number) : 0, -24, 24); const rate = clamp( Number.isFinite(options.playbackRate) ? (options.playbackRate as number) : 1, 0.25, 4 ); const recipeGain = recipe.gain ?? 1; const createdVoices: VoiceHandle[] = []; 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 { // already disconnected } } } 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 { // already disconnected } } voiceCount = Math.max(0, voiceCount - 1); }; } lastAt[cue] = nowFn(); return true; }, async unlock(): Promise { try { const context = ensureContext(); if (!context) return false; if (context.state !== "running") { await kickResume(context); } return context.state === "running"; } catch { return false; } }, setMasterVolume(volume: number): void { 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: SoundThemeDefinition): void { theme = next; }, dispose(): void { // Invalidates every async continuation captured before this point. disposeGeneration += 1; // A hard stop by design: dispose() tears the graph down synchronously // (the context is closed right after), so a fade scheduled here could // never render. Voices are ≤ 300 ms and dispose() is not a user path. for (const voice of [...activeVoices]) { try { const now = ctx ? ctx.currentTime : 0; const gainNode = voice.nodes[voice.nodes.length - 1] as GainNode; gainNode.gain.cancelScheduledValues(now); gainNode.gain.setValueAtTime(0, now); voice.source.stop(now); } catch { // best-effort; ignore } for (const n of voice.nodes) { try { n.disconnect(); } catch { // already disconnected } } } activeVoices.clear(); voiceCount = 0; if (master) { try { master.disconnect(); } catch { // already disconnected } master = null; } if (limiter) { try { limiter.disconnect(); } catch { // already disconnected } limiter = null; } if (ctx) { if (statechangeListener) { try { ctx.removeEventListener("statechange", statechangeListener); } catch { // ignore } } try { void ctx.close(); } catch { // ignore } ctx = null; } statechangeListener = null; noiseBuffer = null; resumePromise = null; for (const key of Object.keys(lastAt)) delete lastAt[key as SoundCue]; setState("idle", null); }, }; } 52:T59d,"use client"; // Public barrel of the sound engine — mirrors src/lib/fancy-ui/sound/index.ts // on the Svelte side, plus the React-only hooks (use-sound.ts), which are this // package's counterpart of reading the `sound` controller's runes directly. export { SoundToggle, type SoundToggleProps, type SoundToggleSize, type SoundToggleVariant, } from "./SoundToggle"; export { sound, getSoundStatus, type SoundController, type SoundSnapshot } from "./sound"; export { attachSoundFeedback, useSoundFeedback, DEFAULT_SOUND_FEEDBACK_ON, type SoundFeedbackOptions, type SoundFeedbackHandle, type SoundCueResolver, type SoundCueSpec, } from "./sound-feedback"; export { useSound, useSoundCue, useSoundEnabled, useSoundStatus, type SoundControls, } from "./use-sound"; export { createSoundEngine, type SoundEngine, type SoundEngineOptions } from "./engine"; export { FANCY_SOUND_THEME, SOUND_THEMES, getSoundTheme, validateSoundTheme } from "./themes"; 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"; 53:T2c0c,"use client"; /** * 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 { useEffect } from "react"; import { useElementRef } from "../internals/dom/use-element-ref"; import { useLiveRef } from "../internals/dom/use-live-ref"; import { sound } from "./sound"; import type { SoundCue } from "./types"; /** 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; /** 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 const DEFAULT_SOUND_FEEDBACK_ON: Readonly> = Object.freeze({ click: "press", }); const HOVER_EVENTS = new Set(["pointerenter", "mouseenter"]); const HOVER_POINTER_TYPES = new Set(["mouse", "pen"]); /** A hover needs a pointer that moved this recently; scroll-under enters have no movement. */ const HOVER_RECENCY_MS = 150; // One document-level pointermove listener shared by every instance that maps a // hover event, attached with the first and removed with the last. let lastPointerMoveAt = -Infinity; let hoverInstances = 0; function onDocumentPointerMove(): void { lastPointerMoveAt = performance.now(); } function retainHoverTracking(): void { if (hoverInstances++ === 0) { document.addEventListener("pointermove", onDocumentPointerMove, { capture: true, passive: true, }); } } function releaseHoverTracking(): void { if (--hoverInstances === 0) { document.removeEventListener("pointermove", onDocumentPointerMove, { capture: true }); lastPointerMoveAt = -Infinity; } } /** Test-only: drops the shared pointer-tracking state between tests. Not exported from index.ts. */ export function resetSoundFeedbackForTests(): void { if (hoverInstances > 0 && typeof document !== "undefined") { document.removeEventListener("pointermove", onDocumentPointerMove, { capture: true }); } hoverInstances = 0; lastPointerMoveAt = -Infinity; } /** Test-only leak counter for the shared document-level `pointermove` listener. */ export function __soundFeedbackHoverInstances(): number { return hoverInstances; } /** * The framework-free core: binds the mapped listeners to `node` and hands back * the action's own `{ update, destroy }`. */ export function attachSoundFeedback( node: HTMLElement, initialOptions?: SoundFeedbackOptions ): SoundFeedbackHandle { if (typeof document === "undefined") { // The Svelte action returns a bare `{}` off-browser; the typed handle // makes that two no-ops instead. Nothing is bound either way. return { update() {}, destroy() {} }; } let options = initialOptions ?? {}; let bound: Array<{ event: string; listener: EventListener }> = []; let tracksHover = false; function isDisabled(): boolean { if (options.disabled) return true; return node.matches(':disabled,[aria-disabled="true"],[data-disabled="true"]'); } function isSuppressedHover(event: Event): boolean { if (event.isTrusted === false && !options.allowUntrusted) return true; const pointerType = (event as PointerEvent).pointerType; // pointerenter always carries a pointerType; anything but mouse/pen is a // tap or a synthesized pointer. A bare mouseenter has none — then the only // tell for a tap is sourceCapabilities.firesTouchEvents. if (pointerType !== undefined && !HOVER_POINTER_TYPES.has(pointerType)) return true; const capabilities = ( event as UIEvent & { sourceCapabilities?: { firesTouchEvents?: boolean } } ).sourceCapabilities; if (capabilities?.firesTouchEvents) return true; if (performance.now() - lastPointerMoveAt > HOVER_RECENCY_MS) return true; const relatedTarget = (event as MouseEvent).relatedTarget; if (relatedTarget instanceof Node && node.contains(relatedTarget)) return true; return false; } function makeListener(eventName: string, spec: SoundCueSpec): EventListener { return (event: Event) => { if (isDisabled()) return; if (HOVER_EVENTS.has(eventName) && isSuppressedHover(event)) return; let cue: SoundCue | null | undefined; 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(): void { 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(): void { for (const { event, listener } of bound) { node.removeEventListener(event, listener); } bound = []; if (tracksHover) { tracksHover = false; releaseHoverTracking(); } } bind(); return { update(next?: SoundFeedbackOptions) { options = next ?? {}; unbind(); bind(); }, destroy() { unbind(); }, }; } const EMPTY_OPTIONS: SoundFeedbackOptions = {}; /** Not a character any DOM event name contains, so the joined key is unambiguous. */ const EVENT_KEY_SEPARATOR = ""; /** Duck-typed so it is also correct off-browser, where `Element` may not exist. */ function isElement(value: unknown): value is HTMLElement { return typeof (value as Node | null)?.nodeType === "number"; } /** * 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