use-scroll-animate 5.4.0 → 5.6.0

package/dist/components/effects.js

@@ -1,5 +1,5 @@
-import { registerBuiltinEffects, registerEffects } from './fx.js';
-import { x as defineElement } from '../chunks/base-C3Sw9sAO.js';
+import { playEffect, registerBuiltinEffects, registerEffects } from './fx.js';
+import { x as defineElement, p as prefersReducedMotion } from '../chunks/base-C3Sw9sAO.js';
 import '../chunks/core-DN3hHbHh.js';
 import './tokens.js';
 import '../chunks/fx-ChjxrMBo.js';
@@ -827,6 +827,618 @@ function defineStory(tag = 'usa-story') {
     }, { id: 'usa-story', text: CSS });
 }
 
+/** Deterministic smooth pseudo-noise in [-1, 1] (sum of sines — cheap, no tables). */
+function noise2(x, y, t = 0) {
+    return (Math.sin(x * 1.7 + t) * Math.cos(y * 1.3 - t * 0.7) + Math.sin((x + y) * 0.9 + t * 0.5) * 0.5 + Math.cos(x * 0.6 - y * 1.1 - t * 0.3) * 0.5) / 2;
+}
+/** Hex `#rrggbb` → [r, g, b]. */
+function hexRgb(hex) {
+    const m = /^#?([\da-f]{2})([\da-f]{2})([\da-f]{2})$/i.exec(hex.trim());
+    return m ? [parseInt(m[1], 16), parseInt(m[2], 16), parseInt(m[3], 16)] : [124, 92, 255];
+}
+/**
+ * Mount a generative canvas behind `el` and run `spec` on it. Returns the
+ * cleanup. Exposed for custom generative effects.
+ */
+function canvasBackground(el, fx, spec, o) {
+    const canvas = document.createElement('canvas');
+    canvas.setAttribute('aria-hidden', 'true');
+    canvas.setAttribute('data-usa-fx-canvas', '');
+    canvas.style.cssText = 'position:absolute;inset:0;width:100%;height:100%;pointer-events:none;z-index:-1;border-radius:inherit';
+    const restore = [];
+    const set = (k, v) => {
+        restore.push([k, el.style[k]]);
+        el.style[k] = v;
+    };
+    if (getComputedStyle(el).position === 'static')
+        set('position', 'relative');
+    set('isolation', 'isolate');
+    el.prepend(canvas);
+    const ctx = canvas.getContext('2d');
+    let raf = 0;
+    let visible = true;
+    let quality = Math.min(1, Math.max(0.35, Number(o.quality) || 1));
+    let w = 0;
+    let h = 0;
+    let state = null;
+    const t0 = performance.now();
+    let last = t0;
+    let slow = 0;
+    let fast = 0;
+    const resize = () => {
+        const r = el.getBoundingClientRect();
+        w = Math.max(1, Math.round(r.width));
+        h = Math.max(1, Math.round(r.height));
+        const dpr = Math.min(2, (typeof devicePixelRatio === 'number' ? devicePixelRatio : 1) || 1) * quality;
+        canvas.width = Math.max(1, Math.round(w * dpr));
+        canvas.height = Math.max(1, Math.round(h * dpr));
+        if (ctx)
+            ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
+        state = spec.init ? spec.init(w, h, o) : {};
+    };
+    const frame = (now) => {
+        raf = 0;
+        if (!ctx)
+            return;
+        const dt = now - last;
+        last = now;
+        // adaptive quality: sustained slow frames lower the render scale, fast ones raise it
+        if (dt > 28)
+            slow++;
+        else if (dt < 18)
+            fast++;
+        if (slow > 20 && quality > 0.35) {
+            quality = Math.max(0.35, quality - 0.15);
+            slow = fast = 0;
+            resize();
+        }
+        else if (fast > 240 && quality < 1) {
+            quality = Math.min(1, quality + 0.15);
+            slow = fast = 0;
+            resize();
+        }
+        spec.draw({ ctx, w, h, t: (now - t0) / 1000, quality, state, o });
+        if (visible && !document.hidden)
+            raf = requestAnimationFrame(frame);
+    };
+    const start = () => {
+        if (!raf && ctx && !fx.reduced) {
+            last = performance.now();
+            raf = requestAnimationFrame(frame);
+        }
+    };
+    resize();
+    if (ctx)
+        spec.draw({ ctx, w, h, t: 0, quality, state, o }); // first / static frame
+    const io = typeof IntersectionObserver === 'function' ? new IntersectionObserver((es) => {
+        visible = es.some((e) => e.isIntersecting);
+        if (visible)
+            start();
+    }) : null;
+    io?.observe(el);
+    const ro = typeof ResizeObserver === 'function' ? new ResizeObserver(() => {
+        resize();
+        if (ctx && fx.reduced)
+            spec.draw({ ctx, w, h, t: 0, quality, state, o });
+    }) : null;
+    ro?.observe(el);
+    const vis = () => !document.hidden && visible && start();
+    document.addEventListener('visibilitychange', vis);
+    start();
+    return () => {
+        cancelAnimationFrame(raf);
+        raf = 0;
+        io?.disconnect();
+        ro?.disconnect();
+        document.removeEventListener('visibilitychange', vis);
+        canvas.remove();
+        for (const [k, v] of restore)
+            el.style[k] = v;
+    };
+}
+const gen = (name, description, defaults, spec) => ({
+    name,
+    kind: 'background',
+    description,
+    reduced: 'run',
+    defaults: { colors: PALETTE, background: '#0b0d12', speed: 1, quality: 1, ...defaults },
+    run: (el, o, ctx) => canvasBackground(el, ctx, spec, o),
+});
+/** Low-resolution scalar field → ImageData, drawn scaled up (used by voronoi / metaballs / contours). */
+function field(f, cell, px) {
+    const step = Math.max(2, Math.round(cell / f.quality));
+    const cw = Math.max(1, Math.ceil(f.w / step));
+    const ch = Math.max(1, Math.ceil(f.h / step));
+    const st = f.state;
+    if (!st.buf || st.buf.width !== cw || st.buf.height !== ch) {
+        st.buf = document.createElement('canvas');
+        st.buf.width = cw;
+        st.buf.height = ch;
+        st.bctx = st.buf.getContext('2d');
+        st.img = st.bctx?.createImageData(cw, ch);
+    }
+    if (!st.bctx || !st.img)
+        return;
+    const d = st.img.data;
+    for (let y = 0; y < ch; y++)
+        for (let x = 0; x < cw; x++)
+            px(x * step, y * step, d, (y * cw + x) * 4);
+    st.bctx.putImageData(st.img, 0, 0);
+    f.ctx.imageSmoothingEnabled = true;
+    f.ctx.drawImage(st.buf, 0, 0, f.w, f.h);
+}
+const GENERATIVE_FX = [
+    gen('flow-field', 'Particles drift along a slowly changing flow field, leaving silky trails.', { count: 600, fade: 0.06 }, {
+        init: (w, h, o) => ({ p: Array.from({ length: o.count }, () => [Math.random() * w, Math.random() * h]) }),
+        draw: ({ ctx, w, h, t, state, o, quality }) => {
+            ctx.fillStyle = o.background;
+            ctx.globalAlpha = t === 0 ? 1 : o.fade;
+            ctx.fillRect(0, 0, w, h);
+            ctx.globalAlpha = 0.8;
+            const n = Math.round(state.p.length * quality);
+            const steps = t === 0 ? 40 : 1;
+            for (let i = 0; i < n; i++) {
+                const q = state.p[i];
+                ctx.fillStyle = o.colors[i % o.colors.length];
+                for (let s = 0; s < steps; s++) {
+                    const a = noise2(q[0] * 0.004, q[1] * 0.004, t * 0.15 * o.speed) * Math.PI * 2;
+                    q[0] += Math.cos(a) * 1.2 * o.speed;
+                    q[1] += Math.sin(a) * 1.2 * o.speed;
+                    if (q[0] < 0 || q[0] > w || q[1] < 0 || q[1] > h)
+                        (q[0] = Math.random() * w), (q[1] = Math.random() * h);
+                    ctx.fillRect(q[0], q[1], 1.4, 1.4);
+                }
+            }
+            ctx.globalAlpha = 1;
+        },
+    }),
+    gen('voronoi', 'Drifting Voronoi cells in the palette, with darker borders.', { seeds: 14, cell: 6 }, {
+        init: (w, h, o) => ({ s: Array.from({ length: o.seeds }, (_, i) => ({ x: Math.random() * w, y: Math.random() * h, vx: Math.random() - 0.5, vy: Math.random() - 0.5, c: hexRgb(o.colors[i % o.colors.length]) })) }),
+        draw: (f) => {
+            const { w, h, state, o } = f;
+            for (const s of state.s) {
+                s.x += s.vx * o.speed;
+                s.y += s.vy * o.speed;
+                if (s.x < 0 || s.x > w)
+                    s.vx *= -1;
+                if (s.y < 0 || s.y > h)
+                    s.vy *= -1;
+            }
+            field(f, o.cell, (x, y, d, i) => {
+                let b = Infinity;
+                let b2 = Infinity;
+                let c = state.s[0].c;
+                for (const s of state.s) {
+                    const dd = (s.x - x) ** 2 + (s.y - y) ** 2;
+                    if (dd < b)
+                        (b2 = b), (b = dd), (c = s.c);
+                    else if (dd < b2)
+                        b2 = dd;
+                }
+                const edge = Math.sqrt(b2) - Math.sqrt(b) < 6 ? 0.55 : 1;
+                d[i] = c[0] * edge;
+                d[i + 1] = c[1] * edge;
+                d[i + 2] = c[2] * edge;
+                d[i + 3] = 255;
+            });
+        },
+    }),
+    gen('mesh-gradient', 'Soft blobs of colour orbit and blend into a living mesh gradient.', { blobs: 4, blur: 0.65 }, {
+        draw: ({ ctx, w, h, t, o }) => {
+            ctx.fillStyle = o.background;
+            ctx.fillRect(0, 0, w, h);
+            const r = Math.max(w, h) * o.blur;
+            for (let i = 0; i < o.blobs; i++) {
+                const a = t * 0.25 * o.speed + (i * Math.PI * 2) / o.blobs;
+                const x = w / 2 + Math.cos(a * (1 + i * 0.13)) * w * 0.32;
+                const y = h / 2 + Math.sin(a * (0.8 + i * 0.11)) * h * 0.32;
+                const [cr, cg, cb] = hexRgb(o.colors[i % o.colors.length]);
+                const g = ctx.createRadialGradient(x, y, 0, x, y, r);
+                g.addColorStop(0, `rgba(${cr},${cg},${cb},0.7)`);
+                g.addColorStop(1, `rgba(${cr},${cg},${cb},0)`);
+                ctx.fillStyle = g;
+                ctx.fillRect(0, 0, w, h);
+            }
+        },
+    }),
+    gen('starfield', 'Stars stream toward the viewer (warp speed with `speed: 4`).', { stars: 400, color: '#ffffff' }, {
+        init: (_w, _h, o) => ({ s: Array.from({ length: o.stars }, () => [Math.random() * 2 - 1, Math.random() * 2 - 1, Math.random()]) }),
+        draw: ({ ctx, w, h, t, state, o, quality }) => {
+            ctx.fillStyle = o.background;
+            ctx.fillRect(0, 0, w, h);
+            ctx.fillStyle = o.color;
+            const n = Math.round(state.s.length * quality);
+            for (let i = 0; i < n; i++) {
+                const s = state.s[i];
+                if (t > 0)
+                    s[2] -= 0.004 * o.speed;
+                if (s[2] <= 0.01)
+                    (s[0] = Math.random() * 2 - 1), (s[1] = Math.random() * 2 - 1), (s[2] = 1);
+                const x = w / 2 + (s[0] / s[2]) * w * 0.5;
+                const y = h / 2 + (s[1] / s[2]) * h * 0.5;
+                if (x < 0 || x > w || y < 0 || y > h)
+                    continue;
+                const size = (1 - s[2]) * 2.6;
+                ctx.globalAlpha = Math.min(1, (1 - s[2]) * 1.6);
+                ctx.fillRect(x, y, size, size);
+            }
+            ctx.globalAlpha = 1;
+        },
+    }),
+    gen('metaballs', 'Gooey blobs that merge and split (low-resolution field, scaled up).', { balls: 6, cell: 5, threshold: 1 }, {
+        init: (w, h, o) => ({ b: Array.from({ length: o.balls }, () => ({ x: Math.random() * w, y: Math.random() * h, vx: (Math.random() - 0.5) * 1.6, vy: (Math.random() - 0.5) * 1.6, r: Math.min(w, h) * (0.08 + Math.random() * 0.08) })) }),
+        draw: (f) => {
+            const { w, h, state, o } = f;
+            for (const b of state.b) {
+                b.x += b.vx * o.speed;
+                b.y += b.vy * o.speed;
+                if (b.x < 0 || b.x > w)
+                    b.vx *= -1;
+                if (b.y < 0 || b.y > h)
+                    b.vy *= -1;
+            }
+            const [ar, ag, ab] = hexRgb(o.colors[0]);
+            const [br, bg, bb] = hexRgb(o.colors[1] || o.colors[0]);
+            const [kr, kg, kb] = hexRgb(o.background);
+            field(f, o.cell, (x, y, d, i) => {
+                let v = 0;
+                for (const b of state.b)
+                    v += (b.r * b.r) / ((b.x - x) ** 2 + (b.y - y) ** 2 + 1);
+                const inside = v >= o.threshold;
+                const k = Math.min(1, (v - o.threshold) * 0.8);
+                d[i] = inside ? ar + (br - ar) * k : kr;
+                d[i + 1] = inside ? ag + (bg - ag) * k : kg;
+                d[i + 2] = inside ? ab + (bb - ab) * k : kb;
+                d[i + 3] = 255;
+            });
+        },
+    }),
+    gen('contours', 'Topographic contour lines over a slowly shifting height field.', { levels: 9, cell: 4, color: '#7c5cff' }, {
+        draw: (f) => {
+            const { t, o } = f;
+            const [lr, lg, lb] = hexRgb(o.color);
+            const [kr, kg, kb] = hexRgb(o.background);
+            const z = (x, y) => (noise2(x * 0.006, y * 0.006, t * 0.2 * o.speed) + 1) / 2;
+            const step = Math.max(2, Math.round(o.cell / f.quality));
+            field(f, o.cell, (x, y, d, i) => {
+                const a = Math.floor(z(x, y) * o.levels);
+                const line = a !== Math.floor(z(x + step, y) * o.levels) || a !== Math.floor(z(x, y + step) * o.levels);
+                const shade = 0.12 + (a / o.levels) * 0.18;
+                d[i] = line ? lr : kr + (lr - kr) * shade;
+                d[i + 1] = line ? lg : kg + (lg - kg) * shade;
+                d[i + 2] = line ? lb : kb + (lb - kb) * shade;
+                d[i + 3] = 255;
+            });
+        },
+    }),
+];
+
+let actx = null;
+let current = null;
+const mediaSources = new WeakMap();
+/** The running analyser, if `enableAudio()` was called. */
+const getAudio = () => current;
+function audioContext() {
+    const AC = globalThis.AudioContext || globalThis.webkitAudioContext;
+    if (!AC)
+        throw new Error('[use-scroll-animate] Web Audio is not available');
+    if (!actx || actx.state === 'closed')
+        actx = new AC();
+    return actx;
+}
+/**
+ * Start analysing `input` and make it the source of every sound-reactive
+ * effect. Call from a user gesture. Replaces a previous source.
+ */
+async function enableAudio(input = 'mic', opts = {}) {
+    current?.stop();
+    const ac = audioContext();
+    if (ac.state === 'suspended')
+        await ac.resume().catch(() => undefined);
+    const analyser = ac.createAnalyser();
+    analyser.fftSize = opts.fftSize || 512;
+    analyser.smoothingTimeConstant = opts.smoothing ?? 0.8;
+    let src;
+    let release = () => { };
+    const media = typeof input === 'string' && input !== 'mic' ? document.querySelector(input) : input;
+    if (media === 'mic') {
+        const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
+        src = ac.createMediaStreamSource(stream);
+        src.connect(analyser); // never to the speakers: no feedback
+        release = () => stream.getTracks().forEach((t) => t.stop());
+    }
+    else if (media && typeof media.play === 'function') {
+        const m = media;
+        let node = mediaSources.get(m);
+        if (!node)
+            mediaSources.set(m, (node = ac.createMediaElementSource(m)));
+        try {
+            node.disconnect();
+        }
+        catch {
+            /* not connected */
+        }
+        src = node;
+        src.connect(analyser);
+        analyser.connect(ac.destination);
+        release = () => {
+            try {
+                node.disconnect();
+            }
+            catch {
+                /* already */
+            }
+            node.connect(ac.destination); // keep the media audible
+        };
+        if (m.paused)
+            await m.play()?.catch?.(() => undefined);
+    }
+    else if (media && typeof media.getTracks === 'function') {
+        src = ac.createMediaStreamSource(media);
+        src.connect(analyser);
+    }
+    else
+        throw new Error(`[use-scroll-animate] enableAudio: no audio source for ${String(input)}`);
+    const freq = new Uint8Array(analyser.frequencyBinCount);
+    const wave = new Uint8Array(analyser.fftSize);
+    const self = {
+        context: ac,
+        analyser,
+        sample: () => {
+            analyser.getByteFrequencyData(freq);
+            analyser.getByteTimeDomainData(wave);
+            let sq = 0;
+            for (let i = 0; i < wave.length; i++)
+                sq += ((wave[i] - 128) / 128) ** 2;
+            const n = Math.max(1, Math.round(freq.length * 0.08));
+            let b = 0;
+            for (let i = 0; i < n; i++)
+                b += freq[i];
+            return { level: Math.min(1, Math.sqrt(sq / wave.length) * 2), bass: b / n / 255, freq, wave };
+        },
+        stop: () => {
+            if (current === self) {
+                current = null;
+                if (raf && typeof cancelAnimationFrame === 'function')
+                    cancelAnimationFrame(raf);
+                raf = 0;
+            }
+            try {
+                src.disconnect();
+                analyser.disconnect();
+            }
+            catch {
+                /* already */
+            }
+            release();
+            setVars(0, 0);
+        },
+    };
+    current = self;
+    kick();
+    return self;
+}
+/** Stop the current audio source (if any). */
+function disableAudio() {
+    current?.stop();
+}
+/** A pure beat detector: feed it energy (0–1) and a timestamp per frame; it answers "beat?". */
+function createBeatDetector(o = {}) {
+    const { threshold = 1.35, cooldown = 250, history = 43, floor = 0.08 } = o;
+    const hist = [];
+    let last = -Infinity;
+    return (energy, now) => {
+        const avg = hist.length ? hist.reduce((a, b) => a + b, 0) / hist.length : energy;
+        const ready = hist.length >= 8;
+        hist.push(energy);
+        if (hist.length > history)
+            hist.shift();
+        if (ready && energy > floor && energy > avg * threshold && now - last >= cooldown) {
+            last = now;
+            return true;
+        }
+        return false;
+    };
+}
+const listeners = new Set();
+let raf = 0;
+function setVars(level, bass) {
+    if (typeof document === 'undefined')
+        return;
+    const s = document.documentElement.style;
+    s.setProperty('--usa-audio-level', level.toFixed(3));
+    s.setProperty('--usa-audio-bass', bass.toFixed(3));
+}
+function loop(now) {
+    raf = 0;
+    if (!current)
+        return;
+    const { level, bass } = current.sample();
+    const reduced = prefersReducedMotion();
+    setVars(reduced ? 0 : level, reduced ? 0 : bass);
+    for (const l of Array.from(listeners))
+        if (l.detect(bass, now))
+            l.cb({ energy: bass, time: now });
+    kick();
+}
+function kick() {
+    if (!raf && current && typeof requestAnimationFrame === 'function')
+        raf = requestAnimationFrame(loop);
+}
+/** Call `cb` on every detected beat of the current audio source. Returns an unsubscribe. */
+function onBeat(cb, o = {}) {
+    const l = { detect: createBeatDetector(o), cb };
+    listeners.add(l);
+    kick();
+    return () => void listeners.delete(l);
+}
+/** Play the registered effect `name` on `el` at every beat (not under reduced motion). Returns an unbind. */
+function bindBeat(el, name, options = {}) {
+    const { threshold, cooldown, history, floor, ...fx } = options;
+    return onBeat(() => {
+        if (!prefersReducedMotion())
+            playEffect(el, name, fx).catch(() => undefined);
+    }, { threshold, cooldown, history, floor });
+}
+// --- visual effects ----------------------------------------------------------
+/** The current sample, or a gentle synthetic one while no audio is enabled. */
+function read(t, bins) {
+    if (current)
+        return { ...current.sample(), idle: false };
+    const freq = new Uint8Array(bins);
+    const wave = new Uint8Array(bins * 2);
+    for (let i = 0; i < bins; i++)
+        freq[i] = 70 + 50 * Math.sin(t * 2 + i * 0.35) * Math.cos(t * 0.7 + i * 0.11) * (1 - i / bins);
+    for (let i = 0; i < wave.length; i++)
+        wave[i] = 128 + 22 * Math.sin(t * 3 + i * 0.12);
+    return { level: 0.25 + 0.1 * Math.sin(t * 2), bass: 0.35 + 0.2 * Math.sin(t * 2.4), freq, wave, idle: true };
+}
+const audioFx = (name, description, defaults, spec) => ({
+    name,
+    kind: 'background',
+    description,
+    reduced: 'skip',
+    defaults: { colors: PALETTE, background: '#0b0d12', speed: 1, quality: 1, ...defaults },
+    run: (el, o, ctx) => canvasBackground(el, ctx, spec, o),
+});
+const AUDIO_FX = [
+    audioFx('spectrum-bars', 'Frequency bars dance to the audio (mirror them with `mirror: true`).', { bars: 48, gap: 2, mirror: false }, {
+        draw: ({ ctx, w, h, t, o }) => {
+            ctx.fillStyle = o.background;
+            ctx.fillRect(0, 0, w, h);
+            const s = read(t, o.bars);
+            const per = Math.max(1, Math.floor((s.freq.length * 0.7) / o.bars));
+            const bw = w / o.bars;
+            for (let i = 0; i < o.bars; i++) {
+                let v = 0;
+                for (let k = 0; k < per; k++)
+                    v += s.freq[Math.min(s.freq.length - 1, i * per + k)];
+                const bh = (v / per / 255) * h * (o.mirror ? 0.5 : 0.9);
+                ctx.fillStyle = o.colors[i % o.colors.length];
+                ctx.fillRect(i * bw + o.gap / 2, o.mirror ? h / 2 - bh : h - bh, Math.max(1, bw - o.gap), o.mirror ? bh * 2 : bh);
+            }
+        },
+    }),
+    audioFx('pulse-ring', 'Glowing rings pulse with the bass.', { rings: 3, color: '#7c5cff' }, {
+        draw: ({ ctx, w, h, t, o }) => {
+            ctx.fillStyle = o.background;
+            ctx.fillRect(0, 0, w, h);
+            const s = read(t, 32);
+            const [r, g, b] = hexRgb(o.color);
+            const base = Math.min(w, h) * 0.18;
+            for (let i = 0; i < o.rings; i++) {
+                const rad = base * (1 + i * 0.55) * (1 + s.bass * 0.6);
+                ctx.strokeStyle = `rgba(${r},${g},${b},${(0.9 - i * 0.25) * (0.4 + s.level)})`;
+                ctx.lineWidth = 3 + s.bass * 10 - i;
+                ctx.beginPath();
+                ctx.arc(w / 2, h / 2, rad, 0, Math.PI * 2);
+                ctx.stroke();
+            }
+        },
+    }),
+    audioFx('wave-ring', 'The live waveform wrapped into a circle.', { color: '#22d3ee', amplitude: 0.35 }, {
+        draw: ({ ctx, w, h, t, o }) => {
+            ctx.fillStyle = o.background;
+            ctx.fillRect(0, 0, w, h);
+            const s = read(t, 64);
+            const n = s.wave.length;
+            const base = Math.min(w, h) * 0.28;
+            ctx.strokeStyle = o.color;
+            ctx.lineWidth = 2;
+            ctx.beginPath();
+            for (let i = 0; i <= n; i++) {
+                const a = (i / n) * Math.PI * 2;
+                const rad = base * (1 + ((s.wave[i % n] - 128) / 128) * o.amplitude * 2);
+                const x = w / 2 + Math.cos(a) * rad;
+                const y = h / 2 + Math.sin(a) * rad;
+                if (i)
+                    ctx.lineTo(x, y);
+                else
+                    ctx.moveTo(x, y);
+            }
+            ctx.closePath();
+            ctx.stroke();
+        },
+    }),
+];
+/**
+ * `<usa-audio source="#track | mic" label="…">` — a toggle button (yours, as
+ * `[data-audio-toggle]`, or one it renders) that enables the audio source on
+ * click; children with `data-usa-beat="effect"` play that effect on every
+ * beat (`data-usa-beat-options` JSON; `threshold` / `cooldown` attributes).
+ * Emits `usa-beat` and `usa-audio-error`.
+ */
+function defineAudio(tag = 'usa-audio') {
+    return defineElement(tag, (Base) => class UsaAudio extends Base {
+        constructor() {
+            super(...arguments);
+            this.active = false;
+            this.audio = null;
+            this.off = null;
+        }
+        static get observedAttributes() {
+            return ['source'];
+        }
+        button() {
+            let b = this.querySelector('[data-audio-toggle]');
+            if (!b) {
+                b = document.createElement('button');
+                b.type = 'button';
+                b.setAttribute('data-audio-toggle', '');
+                b.textContent = this.str('label', '🔊 Enable sound-reactive effects');
+                this.prepend(b);
+                this.onCleanup(() => b.remove());
+            }
+            return b;
+        }
+        async toggle() {
+            const b = this.button();
+            if (this.active)
+                return this.stop();
+            try {
+                this.audio = await enableAudio(this.str('source', 'mic'));
+                this.active = true;
+                this.removeAttribute('data-audio-error');
+                b.setAttribute('aria-pressed', 'true');
+                this.off = onBeat((d) => {
+                    this.dispatchEvent(new CustomEvent('usa-beat', { detail: d, bubbles: true }));
+                    if (prefersReducedMotion())
+                        return;
+                    this.querySelectorAll('[data-usa-beat]').forEach((el) => {
+                        let opts = {};
+                        try {
+                            opts = JSON.parse(el.dataset.usaBeatOptions || '{}') || {};
+                        }
+                        catch {
+                            /* ignore bad JSON */
+                        }
+                        playEffect(el, el.dataset.usaBeat || 'pulse', opts).catch(() => undefined);
+                    });
+                }, { threshold: this.num('threshold', 1.35), cooldown: this.num('cooldown', 250) });
+            }
+            catch (err) {
+                this.setAttribute('data-audio-error', '');
+                this.dispatchEvent(new CustomEvent('usa-audio-error', { detail: { error: err }, bubbles: true }));
+            }
+        }
+        stop() {
+            this.off?.();
+            this.off = null;
+            if (this.audio && current === this.audio)
+                this.audio.stop();
+            this.audio = null;
+            this.active = false;
+            this.querySelector('[data-audio-toggle]')?.setAttribute('aria-pressed', 'false');
+        }
+        mount() {
+            const b = this.button();
+            b.setAttribute('aria-pressed', 'false');
+            this.listen(b, 'click', () => void this.toggle());
+            this.onCleanup(() => this.stop());
+        }
+    }, { id: 'usa-audio', text: 'usa-audio{display:block}usa-audio[data-audio-error] [data-audio-toggle]{outline:2px solid #ff5c8a}' });
+}
+
 /**
  * use-scroll-animate/components/effects — the 5.x effect packs, all
  * registered through `registerEffect()` (5.0) and playable with
@@ -844,6 +1456,8 @@ const EFFECT_PACKS = {
     'cards-click': [...CARD_FX, ...CLICK_FX],
     physics: PHYSICS_FX,
     page: PAGE_FX,
+    generative: GENERATIVE_FX,
+    audio: AUDIO_FX,
 };
 /** 5.1: card & click effects 2.0. */
 function registerCardClickEffects() {
@@ -857,9 +1471,18 @@ function registerPhysicsEffects() {
 function registerPageEffects() {
     registerEffects(EFFECT_PACKS.page);
 }
+/** 5.5: generative Canvas 2D backgrounds. */
+function registerGenerativeEffects() {
+    registerEffects(EFFECT_PACKS.generative);
+}
+/** 5.6: sound-reactive (Web Audio) backgrounds. */
+function registerAudioEffects() {
+    registerEffects(EFFECT_PACKS.audio);
+}
 /** Define the 5.x elements of this entry (`<usa-story>`, …) under their default tags. */
 function defineEffectElements() {
     defineStory();
+    defineAudio();
 }
 /** Register the built-ins and every pack (idempotent). */
 function registerAllEffects() {
@@ -868,5 +1491,5 @@ function registerAllEffects() {
         registerEffects(defs);
 }
 
-export { CARD_FX, CLICK_FX, EFFECT_PACKS, PAGE_FX, PHYSICS_FX, STORY_TEMPLATES, bounceKeyframes, defineEffectElements, defineStory, formatCount, fxLayer, registerAllEffects, registerCardClickEffects, registerPageEffects, registerPhysicsEffects, solveSpring, springKeyframes, storyProgress };
+export { AUDIO_FX, CARD_FX, CLICK_FX, EFFECT_PACKS, GENERATIVE_FX, PAGE_FX, PHYSICS_FX, STORY_TEMPLATES, bindBeat, bounceKeyframes, canvasBackground, createBeatDetector, defineAudio, defineEffectElements, defineStory, disableAudio, enableAudio, formatCount, fxLayer, getAudio, hexRgb, noise2, onBeat, registerAllEffects, registerAudioEffects, registerCardClickEffects, registerGenerativeEffects, registerPageEffects, registerPhysicsEffects, solveSpring, springKeyframes, storyProgress };
 //# sourceMappingURL=effects.js.map