@ripple-ui/svelte 0.0.0-stage → 0.9.0-next.0

package/dist/security/illustration-svg.js

@@ -0,0 +1,473 @@
+// security/illustration-svg.ts — the two DOM-side halves of the `illustration`
+// widget contract (design doc 2026-10-09-ripple-illustration-svg.md); the
+// allowlist itself is data in @ripple-ui/core/manifest.
+//
+// - checkIllustrationSvg: the POLICY check a card policy runs before showing a
+//   card. Needs a DOM (browser or jsdom); without DOMParser it refuses. Refuses on the hostile set and the caps; passes harmless unknowns
+//   (`filter`, `class`), which the widget drops.
+// - sanitizeIllustrationSvg: the WIDGET rebuild. Parses with DOMParser and
+//   rebuilds with createElementNS, keeping only allowlisted elements and
+//   attributes and plain text inside text/tspan/title/desc (no CDATA,
+//   comment or PI), and prefixes every id and every reference to one. Never
+//   throws, never uses innerHTML. Returns null on a parse error (a streaming
+//   partial), a DOCTYPE/ENTITY, or any cap.
+//
+// Conventions both halves share (and the pocketpaw validator mirrors):
+// - A null namespace counts as SVG: `<svg viewBox='..'>` with no xmlns parses
+//   to null-namespace elements. Any other non-SVG namespace is hostile.
+// - Caps are measured on the parsed source before anything is dropped
+//   (measureCaps): every element in every namespace counts, the root is depth
+//   1, and `dur` / `repeatCount` are checked only where present. At most
+//   maxUse `use` elements, and no `use` may point at a `use` or at a subtree
+//   holding one (nested or self-referencing use), so fan-out stays bounded.
+//   No number in a kept attribute over maxNumber, no values/keyTimes/keySplines
+//   list over maxListEntries, no `d`/`path` over maxPathChars, and no mask or
+//   clipPath that reaches itself through mask / clip-path / href refs.
+// - The value rules apply to attribute values (as parsed, entities decoded),
+//   never to text content. Refs are exact: `href='#id'` and `url(#id)`, no
+//   trimming, and the id must exist (in the source for the check, in the
+//   rebuilt tree for the rebuild, which drops any href / url() / begin / end
+//   naming a missing id). Ids are `[A-Za-z_][A-Za-z0-9_-]*`; others are dropped.
+// - One `href` per element: two forms (`href` + `xlink:href`) are refused.
+// - checkIllustrationAnnotations: the policy check for the `annotations` prop.
+//   Refuses more than NOTE_CAPS.max entries, overlong or missing text, both or
+//   neither of target/at, a non-finite `at`, and a target id the rebuild does
+//   not keep. The widget drops what this refuses.
+import { ILLUSTRATION_ANIMATABLE as ANIMATABLE, ILLUSTRATION_ANNOTATION_CAPS as NOTE_CAPS, ILLUSTRATION_ANIMATION_ATTRIBUTES as ANIM_ATTRS, ILLUSTRATION_ANIMATION_ELEMENTS as ANIM_ELEMENTS, ILLUSTRATION_ATTRIBUTES as ATTRS, ILLUSTRATION_CAPS as CAPS, ILLUSTRATION_DANGER_TOKENS as DANGER, ILLUSTRATION_ELEMENTS as ELEMENTS, ILLUSTRATION_ENTITIES as ENTITIES, ILLUSTRATION_HOSTILE_ELEMENTS, ILLUSTRATION_HREF_ELEMENTS as HREF_ELEMENTS, ILLUSTRATION_TRANSFORM_TYPES as TRANSFORM_TYPES } from '@ripple-ui/core/manifest';
+export const SVG_NS = 'http://www.w3.org/2000/svg';
+const XLINK_NS = 'http://www.w3.org/1999/xlink';
+const XMLNS_NS = 'http://www.w3.org/2000/xmlns/';
+const HOSTILE = new Set([...ILLUSTRATION_HOSTILE_ELEMENTS].map((n) => n.toLowerCase()));
+const TEXT_PARENTS = new Set(['text', 'tspan', 'title', 'desc']);
+const ID = '[A-Za-z0-9_-]+';
+const ID_RE = new RegExp(`^${ID}$`);
+const HASH_REF = new RegExp(`^#(${ID})$`);
+const URL_REF = new RegExp(`^url\\(#(${ID})\\)$`);
+const FONT_FAMILY = /^[A-Za-z0-9 ,'"-]*$/;
+// `<id>.<event>` in begin/end: the id part takes no dots (SMIL would need them escaped).
+const SYNC_REF = /(^|[\s;+(-])([A-Za-z0-9_-]+)\.(?=[A-Za-z])/g;
+const NUMBER = /\d*\.?\d+(?:e[-+]?\d+)?/gi;
+const NO_NUMBER_SCAN = new Set(['id', 'font-family', 'begin', 'end']);
+const LISTS = new Set(['values', 'keyTimes', 'keySplines']);
+/** Strip whitespace and control characters, lowercase: the form danger tokens are matched in. */
+// oxlint-disable-next-line no-control-regex -- matching control characters is the point
+const squash = (v) => v.replace(/[\s\u0000-\u001f\u007f]+/g, '').toLowerCase();
+const isDangerous = (v) => {
+    const s = squash(v);
+    return DANGER.some((t) => s.includes(t));
+};
+const isSvgNs = (ns) => ns === null || ns === SVG_NS;
+/** The string pre-checks: things a parser must never see. Null when clean. */
+function preCheck(markup) {
+    if (markup.length > CAPS.maxChars)
+        return `markup over ${CAPS.maxChars} chars`;
+    if (/<!DOCTYPE/i.test(markup))
+        return 'DOCTYPE';
+    if (/<!ENTITY/i.test(markup))
+        return 'ENTITY';
+    if (/<\?xml-stylesheet/i.test(markup))
+        return 'xml-stylesheet';
+    if (markup.includes('<![CDATA['))
+        return 'CDATA section';
+    // Only a leading XML declaration may use <? ... ?>; the server refuses every other processing instruction.
+    if (/<\?/.test(markup.replace(/^\uFEFF?\s*<\?xml\s[^?]*\?>/, '')))
+        return 'processing instruction';
+    for (const m of markup.matchAll(/&([^;\s&<]*);/g)) {
+        const name = m[1];
+        if (!ENTITIES.has(name) && !/^#\d+$/.test(name) && !/^#x[0-9a-f]+$/i.test(name))
+            return `entity &${name};`;
+    }
+    return null;
+}
+function parse(markup) {
+    if (typeof DOMParser === 'undefined')
+        return null;
+    try {
+        const doc = new DOMParser().parseFromString(markup, 'image/svg+xml');
+        const root = doc.documentElement;
+        if (!root || doc.getElementsByTagName('parsererror').length > 0)
+            return null;
+        if (root.localName !== 'svg' || !isSvgNs(root.namespaceURI))
+            return null;
+        return root;
+    }
+    catch {
+        return null;
+    }
+}
+/** SMIL clock value in seconds; `Infinity` for indefinite/media; NaN when unparseable. */
+function clockSeconds(raw) {
+    const v = raw.trim();
+    if (v === 'indefinite' || v === 'media')
+        return Infinity;
+    const full = /^(?:(\d+):)?(\d{1,2}):(\d{2}(?:\.\d+)?)$/.exec(v);
+    if (full)
+        return Number(full[1] ?? 0) * 3600 + Number(full[2]) * 60 + Number(full[3]);
+    const t = /^(\d+(?:\.\d+)?|\.\d+)(h|min|s|ms)?$/.exec(v);
+    if (!t)
+        return NaN;
+    const n = Number(t[1]);
+    return t[2] === 'h' ? n * 3600 : t[2] === 'min' ? n * 60 : t[2] === 'ms' ? n / 1000 : n;
+}
+function tooDeep(el, depth) {
+    if (depth > CAPS.maxDepth)
+        return true;
+    for (const c of el.children)
+        if (tooDeep(c, depth + 1))
+            return true;
+    return false;
+}
+/** The caps, on the parsed source before anything is dropped. Null when within. */
+export function measureCaps(root) {
+    const all = root.getElementsByTagName('*');
+    if (all.length + 1 > CAPS.maxElements)
+        return `over ${CAPS.maxElements} elements`;
+    if (tooDeep(root, 1))
+        return `deeper than ${CAPS.maxDepth}`;
+    let anims = 0;
+    for (const el of [root, ...all]) {
+        const attrCap = attrCaps(el);
+        if (attrCap)
+            return attrCap;
+        if (!ANIM_ELEMENTS.has(el.localName))
+            continue;
+        if (++anims > CAPS.maxAnimations)
+            return `over ${CAPS.maxAnimations} animation elements`;
+        const dur = el.getAttribute('dur');
+        if (dur !== null) {
+            const s = clockSeconds(dur);
+            if (!(s >= CAPS.minDurSeconds))
+                return `dur "${dur}" under ${CAPS.minDurSeconds}s`;
+        }
+        const rc = el.getAttribute('repeatCount');
+        if (rc !== null && rc.trim() !== 'indefinite') {
+            const n = Number(rc.trim());
+            if (rc.trim() === '' || !Number.isFinite(n) || n < 0 || n > CAPS.maxRepeatCount)
+                return `repeatCount "${rc}"`;
+        }
+    }
+    return useFanOut(root, all) ?? maskCycle([root, ...all]);
+}
+/** The per-attribute caps (numbers, list lengths, path length) on the attributes the rebuild keeps. */
+function attrCaps(el) {
+    for (const a of el.attributes) {
+        const name = a.localName;
+        if (a.namespaceURI !== null || !(ATTRS.has(name) || ANIM_ATTRS.has(name)))
+            continue;
+        if ((name === 'd' || name === 'path') && a.value.length > CAPS.maxPathChars)
+            return `${name} over ${CAPS.maxPathChars} chars`;
+        if (LISTS.has(name) && a.value.split(';').filter((s) => s.trim()).length > CAPS.maxListEntries)
+            return `${name} over ${CAPS.maxListEntries} entries`;
+        if (NO_NUMBER_SCAN.has(name))
+            continue;
+        for (const m of a.value.replace(/#[\w-]*/g, ' ').matchAll(NUMBER))
+            if (Math.abs(Number(m[0])) > CAPS.maxNumber)
+                return `${name} number ${m[0]} over ${CAPS.maxNumber}`;
+    }
+    return null;
+}
+/** A mask or clipPath that reaches itself through mask / clip-path / href refs, any number of hops. */
+function maskCycle(els) {
+    const byId = new Map();
+    for (const el of els) {
+        const id = el.getAttribute('id');
+        if (id !== null && !byId.has(id))
+            byId.set(id, el);
+    }
+    const memo = new Map();
+    const refsOf = (el) => {
+        let out = memo.get(el);
+        if (out)
+            return out;
+        out = [];
+        for (const e of [el, ...el.getElementsByTagName('*')])
+            for (const a of e.attributes) {
+                const n = a.localName;
+                const m = n === 'href' ? HASH_REF.exec(a.value.trim()) : n === 'mask' || n === 'clip-path' ? /url\(\s*#([^)\s]+)/.exec(a.value) : null;
+                if (m)
+                    out.push(m[1]);
+            }
+        memo.set(el, out);
+        return out;
+    };
+    for (const start of els) {
+        const id = start.getAttribute('id');
+        if ((start.localName !== 'mask' && start.localName !== 'clipPath') || id === null)
+            continue;
+        const seen = new Set();
+        const queue = [...refsOf(start)];
+        while (queue.length) {
+            const x = queue.pop();
+            if (x === id)
+                return `${start.localName} #${id} references itself`;
+            if (seen.has(x))
+                continue;
+            seen.add(x);
+            const target = byId.get(x);
+            if (target)
+                queue.push(...refsOf(target));
+        }
+    }
+    return null;
+}
+/** The `use` cap: at most maxUse, and none pointing at a `use` or a subtree holding one. */
+function useFanOut(root, all) {
+    const els = [root, ...all];
+    const uses = els.filter((el) => el.localName === 'use' && isSvgNs(el.namespaceURI));
+    if (uses.length > CAPS.maxUse)
+        return `over ${CAPS.maxUse} use elements`;
+    if (!uses.length)
+        return null;
+    const byId = new Map();
+    for (const el of els) {
+        const id = el.getAttribute('id');
+        if (id !== null && !byId.has(id))
+            byId.set(id, el);
+    }
+    for (const u of uses)
+        for (const a of u.attributes) {
+            if (a.localName !== 'href' || (a.namespaceURI !== null && a.namespaceURI !== XLINK_NS))
+                continue;
+            const m = HASH_REF.exec(a.value.trim());
+            const target = m ? byId.get(m[1]) : undefined;
+            if (target && (target.localName === 'use' || uses.some((x) => x !== target && target.contains(x))))
+                return `nested use (#${m[1]})`;
+        }
+    return null;
+}
+/** True when `value` is exactly the ref form `re` and names an id in `ids`. */
+const refTo = (re, value, ids) => {
+    const m = re.exec(value);
+    return m !== null && ids.has(m[1]);
+};
+/** Why one attribute is hostile, or null. Unknown-but-harmless attributes pass. */
+function hostileAttr(el, a, ids) {
+    const local = a.localName.toLowerCase();
+    if (a.namespaceURI === XMLNS_NS || a.name === 'xmlns')
+        return null;
+    if (local.startsWith('on'))
+        return `handler ${a.name}`;
+    if (local === 'style')
+        return 'style attribute';
+    if (local === 'attributetype')
+        return 'attributeType';
+    if (a.value.includes('\\'))
+        return `backslash in ${a.name}`;
+    if (local === 'id' && !/^[A-Za-z0-9_-]+$/.test(a.value))
+        return `id "${a.value}"`;
+    if (local === 'begin' || local === 'end') {
+        for (const m of a.value.matchAll(SYNC_REF))
+            if (!ids.has(m[2]))
+                return `${a.name} names missing #${m[2]}`;
+    }
+    if (local === 'href') {
+        if (!HREF_ELEMENTS.has(el.localName) || !refTo(HASH_REF, a.value, ids))
+            return `${a.name}="${a.value}" on <${el.localName}>`;
+    }
+    if (local === 'attributename' && ANIM_ELEMENTS.has(el.localName) && !ANIMATABLE.has(a.value))
+        return `animation of "${a.value}"`;
+    if (/url\(/i.test(a.value) && !refTo(URL_REF, a.value, ids))
+        return `${a.name}="${a.value}"`;
+    if (isDangerous(a.value))
+        return `${a.name}="${a.value}"`;
+    return null;
+}
+/** The policy check: refuse on the hostile set and the caps. */
+export function checkIllustrationSvg(markup) {
+    if (typeof markup !== 'string' || !markup.trim())
+        return { ok: false, reason: 'empty svg' };
+    const pre = preCheck(markup);
+    if (pre)
+        return { ok: false, reason: pre };
+    if (typeof DOMParser === 'undefined')
+        return { ok: false, reason: 'no DOMParser in this runtime (needs a browser or jsdom)' };
+    const root = parse(markup);
+    if (!root)
+        return { ok: false, reason: 'not a well-formed <svg> document' };
+    const cap = measureCaps(root);
+    if (cap)
+        return { ok: false, reason: cap };
+    const els = [root, ...root.getElementsByTagName('*')];
+    const ids = new Set(els.map((el) => el.getAttribute('id')).filter((id) => id !== null));
+    for (const el of els) {
+        if (!isSvgNs(el.namespaceURI))
+            return { ok: false, reason: `<${el.localName}> outside the SVG namespace` };
+        if ([...el.attributes].filter((a) => a.localName.toLowerCase() === 'href').length > 1)
+            return { ok: false, reason: `two hrefs on <${el.localName}>` };
+        if (HOSTILE.has(el.localName.toLowerCase()))
+            return { ok: false, reason: `<${el.localName}>` };
+        // An animation with no target is inert; one with a target is checked by hostileAttr.
+        for (const a of el.attributes) {
+            const why = hostileAttr(el, a, ids);
+            if (why)
+                return { ok: false, reason: why };
+        }
+    }
+    return { ok: true };
+}
+/** The value an allowed attribute is rebuilt with, or null to drop it. */
+function keepValue(el, a, prefix, refs) {
+    const value = a.value;
+    // A backslash could be a CSS escape spelling `url(` some other way; no real SVG value needs one.
+    if (isDangerous(value) || value.includes('\\'))
+        return null;
+    if (/url\(/i.test(value)) {
+        const m = URL_REF.exec(value);
+        if (m)
+            refs.push(m[1]);
+        return m ? `url(#${prefix}${m[1]})` : null;
+    }
+    const name = a.localName;
+    if (name === 'id')
+        return ID_RE.test(value) ? prefix + value : null;
+    if (name === 'font-family')
+        return FONT_FAMILY.test(value) ? value : null;
+    if (name === 'type')
+        return TRANSFORM_TYPES.has(value.trim()) ? value : null;
+    if (name === 'begin' || name === 'end')
+        return value.replace(SYNC_REF, (_m, pre, id) => {
+            refs.push(id);
+            return `${pre}${prefix}${id}.`;
+        });
+    return value;
+}
+function rebuild(src, doc, prefix, pending) {
+    const tag = src.localName;
+    if (!isSvgNs(src.namespaceURI) || !ELEMENTS.has(tag))
+        return null;
+    const anim = ANIM_ELEMENTS.has(tag);
+    if (anim && !ANIMATABLE.has(src.getAttribute('attributeName') ?? '')) {
+        // animateMotion moves along a path and needs no attributeName.
+        if (tag !== 'animateMotion' || src.hasAttribute('attributeName'))
+            return null;
+    }
+    const out = doc.createElementNS(SVG_NS, tag);
+    const hrefs = [...src.attributes].filter((a) => a.localName === 'href' && (a.namespaceURI === null || a.namespaceURI === XLINK_NS));
+    for (const a of src.attributes) {
+        const ns = a.namespaceURI;
+        const name = a.localName;
+        if (name === 'href' && (ns === null || ns === XLINK_NS)) {
+            const m = HREF_ELEMENTS.has(tag) && hrefs.length === 1 ? HASH_REF.exec(a.value) : null;
+            if (m) {
+                out.setAttributeNS(null, 'href', `#${prefix}${m[1]}`);
+                pending.push([out, 'href', [m[1]]]);
+            }
+            continue;
+        }
+        if (ns !== null)
+            continue;
+        const allowed = ATTRS.has(name) || (anim && ANIM_ATTRS.has(name));
+        if (!allowed || name === 'attributeName' && !anim)
+            continue;
+        const refs = [];
+        const v = keepValue(src, a, prefix, refs);
+        if (v === null)
+            continue;
+        out.setAttributeNS(null, name, v);
+        if (refs.length)
+            pending.push([out, name, refs]);
+    }
+    for (const c of src.childNodes) {
+        if (c.nodeType === 1) {
+            const child = rebuild(c, doc, prefix, pending);
+            if (child)
+                out.appendChild(child);
+        }
+        else if (c.nodeType === 3 && TEXT_PARENTS.has(tag)) {
+            out.appendChild(doc.createTextNode(c.nodeValue ?? ''));
+        }
+    }
+    return out;
+}
+/**
+ * The widget rebuild: a fresh SVG element of `doc` holding only the allowlist,
+ * every id prefixed with `idPrefix`. Null on a parse error, a DOCTYPE/ENTITY,
+ * an oversize string or any cap. Never throws.
+ */
+export function sanitizeIllustrationSvg(markup, doc, idPrefix) {
+    try {
+        if (typeof markup !== 'string' || markup.length > CAPS.maxChars || /<!(DOCTYPE|ENTITY)/i.test(markup))
+            return null;
+        const root = parse(markup);
+        if (!root || measureCaps(root))
+            return null;
+        const pending = [];
+        const out = rebuild(root, doc, idPrefix, pending);
+        if (!out)
+            return null;
+        const kept = new Set([out, ...out.querySelectorAll('[id]')].map((el) => el.getAttribute('id')));
+        for (const [el, name, ids] of pending)
+            if (ids.some((id) => !kept.has(idPrefix + id)))
+                el.removeAttribute(name);
+        return out;
+    }
+    catch {
+        return null;
+    }
+}
+/** True when the rebuilt art carries an animation element. */
+export function hasAnimation(svg) {
+    return [...ANIM_ELEMENTS].some((t) => svg.getElementsByTagNameNS(SVG_NS, t).length > 0);
+}
+const refuse = (reason) => ({ ok: false, reason });
+/** Ids the widget's rebuild keeps (unprefixed), or null when the svg does not rebuild. */
+function rebuiltIds(markup) {
+    if (typeof markup !== 'string')
+        return null;
+    const doc = new DOMParser().parseFromString(`<svg xmlns="${SVG_NS}"/>`, 'image/svg+xml');
+    const out = sanitizeIllustrationSvg(markup, doc, '');
+    return out && new Set([out, ...out.querySelectorAll('[id]')].map((el) => el.getAttribute('id') ?? ''));
+}
+/**
+ * The policy check for the `annotations` prop: at most NOTE_CAPS.max entries
+ * of `{ id, label, note, target? | at? }` with plain-text label and note under
+ * their caps, exactly one of `target` (an id the rebuilt svg keeps) or `at`
+ * (two finite viewBox numbers). Absent annotations pass.
+ */
+export function checkIllustrationAnnotations(props) {
+    const list = props?.annotations;
+    if (list === undefined || list === null)
+        return { ok: true };
+    if (!Array.isArray(list))
+        return refuse('annotations is not a list');
+    if (list.length > NOTE_CAPS.max)
+        return refuse(`more than ${NOTE_CAPS.max} annotations`);
+    let ids;
+    const seen = new Set();
+    for (const [i, a] of list.entries()) {
+        const at = `annotation ${i + 1}`;
+        if (!a || typeof a !== 'object' || Array.isArray(a))
+            return refuse(`${at} is not an object`);
+        const { id, label, note, target, at: point } = a;
+        if (typeof id !== 'string' || !id.trim())
+            return refuse(`${at}: no id`);
+        if (seen.has(id))
+            return refuse(`${at}: duplicate id "${id}"`);
+        seen.add(id);
+        if (typeof label !== 'string' || !label.trim())
+            return refuse(`${at}: no label`);
+        if (label.length > NOTE_CAPS.label)
+            return refuse(`${at}: label over ${NOTE_CAPS.label} chars`);
+        if (typeof note !== 'string')
+            return refuse(`${at}: no note`);
+        if (note.length > NOTE_CAPS.note)
+            return refuse(`${at}: note over ${NOTE_CAPS.note} chars`);
+        if ((target === undefined) === (point === undefined))
+            return refuse(`${at}: needs exactly one of target or at`);
+        if (point !== undefined) {
+            if (!Array.isArray(point) || point.length !== 2 || !point.every((n) => typeof n === 'number' && Number.isFinite(n)))
+                return refuse(`${at}: at is not two finite numbers`);
+            continue;
+        }
+        if (typeof target !== 'string' || !target)
+            return refuse(`${at}: target is not an id`);
+        if (ids === undefined) {
+            if (typeof DOMParser === 'undefined')
+                return refuse('no DOMParser in this runtime (needs a browser or jsdom)');
+            ids = rebuiltIds(props.svg);
+        }
+        if (!ids?.has(target))
+            return refuse(`${at}: target "${target}" is not an id in the svg`);
+    }
+    return { ok: true };
+}

package/dist/sound/index.d.ts

@@ -0,0 +1,13 @@
+export declare const CUES: readonly ["complete", "tick", "correct", "wrong", "win", "check", "sent", "phase"];
+export type CueName = (typeof CUES)[number];
+/** Loudest sample any cue reaches, out of 1. */
+export declare const CUE_PEAK = 0.22;
+/** The cue's samples at `sampleRate`: pure, cached, peak = CUE_PEAK * gain. */
+export declare function renderCue(name: CueName, sampleRate: number): Float32Array;
+export declare function soundEnabled(): boolean;
+export declare function setSoundEnabled(on: boolean): void;
+/**
+ * Plays a short, quiet cue, scaled by `volume` (0..1). Safe to call anywhere;
+ * does nothing when it can't or shouldn't.
+ */
+export declare function playCue(name: CueName, volume?: number): void;

package/dist/sound/index.js

@@ -0,0 +1,120 @@
+// sound/index.ts: subtle sound cues for moments in widgets (a workout done, a
+// quiz answer, a habit ticked). Each cue is a few ZzFX notes mixed into one
+// buffer and normalised to a quiet peak, so no cue is louder than CUE_PEAK.
+//
+// Invariants:
+// - Nothing runs at import. The AudioContext is created on the first cue,
+//   one per page, and only after the page has had a user gesture.
+// - playCue never throws and is a no-op on the server, in jsdom (no
+//   AudioContext), on a hidden page, or when sounds are off.
+// - The on/off flag lives in localStorage under STORAGE_KEY, default on.
+//   Storage errors fall back to the in-memory value.
+// - Only call it for discrete moments, never per keystroke or stream update.
+import { zzfxSamples } from './zzfx.js';
+export const CUES = ['complete', 'tick', 'correct', 'wrong', 'win', 'check', 'sent', 'phase'];
+const STORAGE_KEY = 'ripple:sound';
+/** Loudest sample any cue reaches, out of 1. */
+export const CUE_PEAK = 0.22;
+const note = (at, hz, release, vol = 1, shape = 0, extra = []) => [
+    at,
+    [vol, 0, hz, 0.008, 0.02, release, shape, 1, ...extra],
+];
+// Hand-tuned: sine and triangle only, mid register, short tails.
+const SPEC = {
+    complete: { gain: 1, notes: [note(0, 523, 0.22), note(0.1, 659, 0.22), note(0.2, 784, 0.4)] },
+    tick: { gain: 0.35, notes: [note(0, 880, 0.04)] },
+    correct: { gain: 0.8, notes: [note(0, 659, 0.12), note(0.08, 880, 0.22)] },
+    wrong: { gain: 0.7, notes: [note(0, 220, 0.18, 1, 1, [-0.4, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, -900])] },
+    win: { gain: 1, notes: [note(0, 523, 0.15), note(0.07, 659, 0.15), note(0.14, 784, 0.15), note(0.21, 1047, 0.35, 0.8)] },
+    check: { gain: 0.65, notes: [note(0, 784, 0.1, 1, 0, [0, 0, 262, 0.04])] },
+    sent: { gain: 0.6, notes: [note(0, 300, 0.1, 0.6, 0, [12]), note(0.09, 740, 0.08)] },
+    phase: { gain: 0.6, notes: [note(0, 587, 0.12), note(0.13, 587, 0.18)] },
+};
+const rendered = new Map();
+/** The cue's samples at `sampleRate`: pure, cached, peak = CUE_PEAK * gain. */
+export function renderCue(name, sampleRate) {
+    const key = `${name}@${sampleRate}`;
+    const hit = rendered.get(key);
+    if (hit)
+        return hit;
+    const parts = SPEC[name].notes.map(([at, p]) => [Math.round(at * sampleRate), zzfxSamples(sampleRate, p)]);
+    const out = new Float32Array(Math.max(...parts.map(([o, s]) => o + s.length)));
+    for (const [o, s] of parts)
+        for (let i = 0; i < s.length; i++)
+            out[o + i] += s[i];
+    let peak = 0;
+    for (const v of out)
+        peak = Math.max(peak, Math.abs(v));
+    const scale = peak ? (CUE_PEAK * SPEC[name].gain) / peak : 0;
+    for (let i = 0; i < out.length; i++)
+        out[i] *= scale;
+    rendered.set(key, out);
+    return out;
+}
+let enabled;
+export function soundEnabled() {
+    if (enabled === undefined) {
+        try {
+            enabled = globalThis.localStorage?.getItem(STORAGE_KEY) !== 'off';
+        }
+        catch {
+            enabled = true;
+        }
+    }
+    return enabled;
+}
+export function setSoundEnabled(on) {
+    enabled = on;
+    try {
+        globalThis.localStorage?.setItem(STORAGE_KEY, on ? 'on' : 'off');
+    }
+    catch {
+        // private mode or blocked storage: keep the in-memory value
+    }
+}
+let ctx;
+function context() {
+    if (ctx !== undefined)
+        return ctx;
+    const AC = window.AudioContext ?? window.webkitAudioContext;
+    try {
+        ctx = AC ? new AC() : null;
+    }
+    catch {
+        ctx = null;
+    }
+    return ctx;
+}
+/**
+ * Plays a short, quiet cue, scaled by `volume` (0..1). Safe to call anywhere;
+ * does nothing when it can't or shouldn't.
+ */
+export function playCue(name, volume = 1) {
+    if (typeof window === 'undefined' || typeof document === 'undefined')
+        return;
+    if (!soundEnabled() || document.hidden || !SPEC[name])
+        return;
+    // Browsers block audio before a gesture; don't even make the context then.
+    const ua = navigator.userActivation;
+    if (ua && !ua.hasBeenActive)
+        return;
+    const c = context();
+    if (!c)
+        return;
+    try {
+        if (c.state === 'suspended')
+            void c.resume().catch(() => { });
+        const samples = renderCue(name, c.sampleRate);
+        const buf = c.createBuffer(1, samples.length, c.sampleRate);
+        buf.getChannelData(0).set(samples);
+        const src = c.createBufferSource();
+        src.buffer = buf;
+        const gain = c.createGain();
+        gain.gain.value = Math.min(Math.max(volume, 0), 1);
+        src.connect(gain).connect(c.destination);
+        src.start();
+    }
+    catch {
+        // a closed or broken context: stay silent
+    }
+}

package/dist/sound/zzfx.d.ts

@@ -0,0 +1,9 @@
+/**
+ * ZzFX parameters, in order: volume, randomness, frequency, attack, sustain,
+ * release, shape (0 sin, 1 triangle, 2 saw, 3 tan, 4 noise, 5 square),
+ * shapeCurve, slide, deltaSlide, pitchJump, pitchJumpTime, repeatTime, noise,
+ * modulation, bitCrush, delay, sustainVolume, decay, tremolo, filter
+ * (negative is low-pass, positive high-pass). Omitted entries take defaults.
+ */
+export type ZzfxParams = (number | undefined)[];
+export declare function zzfxSamples(sampleRate: number, params: ZzfxParams): Float32Array;