use-scroll-animate 5.5.0 → 5.7.0

package/dist/components/effects.cjs

@@ -1115,6 +1115,714 @@ const GENERATIVE_FX = [
     }),
 ];
 
+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 = base.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 (!base.prefersReducedMotion())
+            components_fx.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 base.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 (base.prefersReducedMotion())
+                        return;
+                    this.querySelectorAll('[data-usa-beat]').forEach((el) => {
+                        let opts = {};
+                        try {
+                            opts = JSON.parse(el.dataset.usaBeatOptions || '{}') || {};
+                        }
+                        catch {
+                            /* ignore bad JSON */
+                        }
+                        components_fx.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}' });
+}
+
+const touchOk = (e, o) => o.touch || e.pointerType !== 'touch';
+/** A fixed, viewport-sized canvas in the fx layer, redrawn while `draw` returns true. */
+function overlayCanvas(draw) {
+    const c = document.createElement('canvas');
+    c.style.cssText = 'position:absolute;inset:0;width:100%;height:100%';
+    fxLayer().appendChild(c);
+    const g = c.getContext('2d');
+    let raf = 0;
+    const frame = (now) => {
+        raf = 0;
+        if (!g)
+            return;
+        const w = innerWidth;
+        const h = innerHeight;
+        const dpr = Math.min(2, devicePixelRatio || 1);
+        if (c.width !== Math.round(w * dpr) || c.height !== Math.round(h * dpr)) {
+            c.width = Math.round(w * dpr);
+            c.height = Math.round(h * dpr);
+        }
+        g.setTransform(dpr, 0, 0, dpr, 0, 0);
+        g.clearRect(0, 0, w, h);
+        if (draw(g, w, h, now))
+            raf = requestAnimationFrame(frame);
+    };
+    return {
+        kick: () => {
+            if (!raf && g)
+                raf = requestAnimationFrame(frame);
+        },
+        stop: () => {
+            cancelAnimationFrame(raf);
+            raf = 0;
+            c.remove();
+        },
+    };
+}
+/** Pointer trail on `el`: keeps the last `life` ms of points and redraws them. */
+function trail(el, o, paint) {
+    const pts = [];
+    const oc = overlayCanvas((g, _w, _h, now) => {
+        while (pts.length && now - pts[0].t > o.life)
+            pts.shift();
+        if (pts.length > 1)
+            paint(g, pts, now);
+        return pts.length > 0;
+    });
+    const move = (e) => {
+        if (!touchOk(e, o))
+            return;
+        pts.push({ x: e.clientX, y: e.clientY, t: performance.now() });
+        if (pts.length > 64)
+            pts.shift();
+        oc.kick();
+    };
+    el.addEventListener('pointermove', move, { passive: true });
+    return () => {
+        el.removeEventListener('pointermove', move);
+        oc.stop();
+    };
+}
+const CURSOR_FX = [
+    {
+        name: 'comet-trail',
+        kind: 'cursor',
+        description: 'A glowing comet tail follows the pointer over the element (persistent; `color`, `width`, `life`).',
+        defaults: { color: '#7c5cff', width: 10, life: 320, touch: false },
+        run: (el, o) => trail(el, o, (g, pts, now) => {
+            const [r, gg, b] = hexRgb(o.color);
+            g.lineCap = 'round';
+            for (let i = 1; i < pts.length; i++) {
+                const k = 1 - (now - pts[i].t) / o.life;
+                g.strokeStyle = `rgba(${r},${gg},${b},${(k * 0.9).toFixed(3)})`;
+                g.lineWidth = Math.max(0.5, o.width * k);
+                g.beginPath();
+                g.moveTo(pts[i - 1].x, pts[i - 1].y);
+                g.lineTo(pts[i].x, pts[i].y);
+                g.stroke();
+            }
+        }),
+    },
+    {
+        name: 'ribbon-trail',
+        kind: 'cursor',
+        description: 'A smooth rainbow ribbon flows behind the pointer (persistent; `width`, `life`).',
+        defaults: { width: 18, life: 600, touch: false },
+        run: (el, o) => trail(el, o, (g, pts, now) => {
+            for (let i = 2; i < pts.length; i++) {
+                const k = 1 - (now - pts[i].t) / o.life;
+                const a = pts[i - 2];
+                const m = pts[i - 1];
+                const b = pts[i];
+                g.strokeStyle = `hsla(${(pts[i].t / 6) % 360},90%,62%,${(k * 0.85).toFixed(3)})`;
+                g.lineWidth = Math.max(0.5, o.width * k * Math.sin(Math.PI * Math.min(1, (i / pts.length) * 1.1)));
+                g.lineCap = 'round';
+                g.beginPath();
+                g.moveTo((a.x + m.x) / 2, (a.y + m.y) / 2);
+                g.quadraticCurveTo(m.x, m.y, (m.x + b.x) / 2, (m.y + b.y) / 2);
+                g.stroke();
+            }
+        }),
+    },
+    {
+        name: 'sparkle-trail',
+        kind: 'cursor',
+        description: 'Little stars twinkle off the pointer as it moves (persistent; `colors`, `spacing` px between stars).',
+        defaults: { colors: PALETTE, spacing: 14, size: 14, touch: false },
+        run: (el, o, ctx) => {
+            let lx = -1e4;
+            let ly = -1e4;
+            const move = (e) => {
+                if (!touchOk(e, o) || Math.hypot(e.clientX - lx, e.clientY - ly) < o.spacing)
+                    return;
+                lx = e.clientX;
+                ly = e.clientY;
+                const s = o.size * rand(0.6, 1.2);
+                spawn(e.clientX - s / 2, e.clientY - s / 2, `font-size:${s}px;line-height:1;color:${o.colors[Math.floor(rand(0, o.colors.length))]}`, ctx, [{ transform: 'translate(0,0) scale(0) rotate(0deg)', opacity: 1 }, { transform: `translate(${rand(-14, 14)}px,${rand(4, 26)}px) scale(1) rotate(${rand(-90, 90)}deg)`, opacity: 0 }], { duration: rand(500, 800), easing: 'ease-out' }, '✦');
+            };
+            el.addEventListener('pointermove', move, { passive: true });
+            return () => el.removeEventListener('pointermove', move);
+        },
+    },
+    {
+        name: 'magnetic-dots',
+        kind: 'cursor',
+        description: 'A grid of dots behind the content leans toward the pointer like iron filings to a magnet (persistent; `gap`, `radius`, `color`).',
+        defaults: { gap: 22, radius: 120, color: '#7c5cff', background: 'transparent', touch: false },
+        reduced: 'skip',
+        run: (el, o, ctx) => {
+            const p = { x: -1e4, y: -1e4 };
+            const move = (e) => {
+                if (!touchOk(e, o))
+                    return;
+                const r = el.getBoundingClientRect();
+                p.x = e.clientX - r.left;
+                p.y = e.clientY - r.top;
+            };
+            const leave = () => ((p.x = -1e4), (p.y = -1e4));
+            el.addEventListener('pointermove', move, { passive: true });
+            el.addEventListener('pointerleave', leave);
+            const off = canvasBackground(el, ctx, {
+                draw: ({ ctx: g, w, h }) => {
+                    g.clearRect(0, 0, w, h);
+                    if (o.background !== 'transparent') {
+                        g.fillStyle = o.background;
+                        g.fillRect(0, 0, w, h);
+                    }
+                    g.fillStyle = o.color;
+                    for (let y = o.gap / 2; y < h; y += o.gap)
+                        for (let x = o.gap / 2; x < w; x += o.gap) {
+                            const dx = p.x - x;
+                            const dy = p.y - y;
+                            const d = Math.hypot(dx, dy);
+                            const k = d < o.radius ? (1 - d / o.radius) ** 2 : 0;
+                            const s = 1.5 + k * 3;
+                            g.globalAlpha = 0.35 + k * 0.65;
+                            g.fillRect(x + dx * k * 0.35 - s / 2, y + dy * k * 0.35 - s / 2, s, s);
+                        }
+                    g.globalAlpha = 1;
+                },
+            }, o);
+            return () => {
+                el.removeEventListener('pointermove', move);
+                el.removeEventListener('pointerleave', leave);
+                off();
+            };
+        },
+    },
+    {
+        name: 'spotlight-cursor',
+        kind: 'cursor',
+        description: 'A soft light follows the pointer across the element, easing behind it (persistent; `color`, `size`).',
+        defaults: { color: '#ffffff', size: 260, ease: 0.18, touch: false },
+        run: (el, o) => {
+            const [r, g, b] = hexRgb(o.color);
+            const s = document.createElement('span');
+            s.setAttribute('aria-hidden', 'true');
+            s.style.cssText = `position:absolute;inset:0;pointer-events:none;border-radius:inherit;opacity:0;transition:opacity .25s;mix-blend-mode:soft-light;background:radial-gradient(circle ${o.size / 2}px at var(--sx,50%) var(--sy,50%),rgba(${r},${g},${b},.75),transparent)`;
+            const restore = el.style.position;
+            if (getComputedStyle(el).position === 'static')
+                el.style.position = 'relative';
+            el.appendChild(s);
+            let tx = 0;
+            let ty = 0;
+            let x = 0;
+            let y = 0;
+            let raf = 0;
+            const tick = () => {
+                x += (tx - x) * o.ease;
+                y += (ty - y) * o.ease;
+                s.style.setProperty('--sx', `${x.toFixed(1)}px`);
+                s.style.setProperty('--sy', `${y.toFixed(1)}px`);
+                raf = Math.abs(tx - x) + Math.abs(ty - y) > 0.3 ? requestAnimationFrame(tick) : 0;
+            };
+            const move = (e) => {
+                if (!touchOk(e, o))
+                    return;
+                const rc = el.getBoundingClientRect();
+                tx = e.clientX - rc.left;
+                ty = e.clientY - rc.top;
+                if (s.style.opacity !== '1')
+                    ((x = tx), (y = ty), (s.style.opacity = '1'));
+                if (!raf)
+                    raf = requestAnimationFrame(tick);
+            };
+            const leave = () => (s.style.opacity = '0');
+            el.addEventListener('pointermove', move, { passive: true });
+            el.addEventListener('pointerleave', leave);
+            return () => {
+                cancelAnimationFrame(raf);
+                el.removeEventListener('pointermove', move);
+                el.removeEventListener('pointerleave', leave);
+                s.remove();
+                el.style.position = restore;
+            };
+        },
+    },
+];
+// --- gestures → effects ------------------------------------------------------
+const GESTURES = ['fling', 'twist', 'long-press'];
+/** Release velocity (px/ms) from recent pointer samples: uses the last `window` ms (pure). */
+function flingVelocity(pts, window = 90) {
+    if (pts.length < 2)
+        return { vx: 0, vy: 0, speed: 0 };
+    const last = pts[pts.length - 1];
+    let first = pts[0];
+    for (let i = pts.length - 2; i >= 0; i--) {
+        first = pts[i];
+        if (last.t - pts[i].t >= window)
+            break;
+    }
+    const dt = Math.max(1, last.t - first.t);
+    const vx = (last.x - first.x) / dt;
+    const vy = (last.y - first.y) / dt;
+    return { vx, vy, speed: Math.hypot(vx, vy) };
+}
+/** Signed smallest difference between two angles in degrees, in (-180, 180] (pure). */
+function angleDelta(a, b) {
+    let d = (b - a) % 360;
+    if (d > 180)
+        d -= 360;
+    if (d <= -180)
+        d += 360;
+    return d;
+}
+/**
+ * Fire `effect` (a registered effect name, or a callback) when `gesture`
+ * happens on `el`. Returns an unbind.
+ */
+function bindGesture(el, gesture, effect, o = {}) {
+    const { velocity = 0.8, angle = 30, duration = 650, tolerance = 10, effectOptions = {} } = o;
+    const pts = new Map();
+    let path = [];
+    let base = null;
+    let press = null;
+    const fire = (d, e) => {
+        el.dispatchEvent(new CustomEvent('usa-gesture', { detail: d, bubbles: true }));
+        if (typeof effect === 'function')
+            effect(d, e);
+        else
+            components_fx.playEffect(el, effect, effectOptions, e).catch(() => undefined);
+    };
+    const twistAngle = () => {
+        const [a, b] = [...pts.values()];
+        return (Math.atan2(b.y - a.y, b.x - a.x) * 180) / Math.PI;
+    };
+    const charge = (k) => {
+        el.style.setProperty('--usa-charge', k.toFixed(3));
+        el.toggleAttribute('data-charging', k > 0 && k < 1);
+    };
+    const endPress = () => {
+        if (!press)
+            return;
+        cancelAnimationFrame(press.raf);
+        press = null;
+        charge(0);
+    };
+    const down = (e) => {
+        pts.set(e.pointerId ?? 1, { x: e.clientX, y: e.clientY });
+        if (gesture === 'fling')
+            path = [{ x: e.clientX, y: e.clientY, t: e.timeStamp || performance.now() }];
+        if (gesture === 'twist' && pts.size === 2)
+            base = twistAngle();
+        if (gesture === 'long-press' && pts.size === 1) {
+            press = { x: e.clientX, y: e.clientY, t0: performance.now(), raf: 0 };
+            const step = (now) => {
+                if (!press)
+                    return;
+                const k = Math.min(1, (now - press.t0) / duration);
+                charge(k);
+                if (k >= 1) {
+                    endPress();
+                    el.style.setProperty('--usa-charge', '1');
+                    fire({ gesture, charge: 1 }, e);
+                }
+                else
+                    press.raf = requestAnimationFrame(step);
+            };
+            press.raf = requestAnimationFrame(step);
+        }
+    };
+    const move = (e) => {
+        if (!pts.has(e.pointerId ?? 1))
+            return;
+        pts.set(e.pointerId ?? 1, { x: e.clientX, y: e.clientY });
+        if (gesture === 'fling') {
+            path.push({ x: e.clientX, y: e.clientY, t: e.timeStamp || performance.now() });
+            if (path.length > 20)
+                path.shift();
+        }
+        else if (gesture === 'twist' && pts.size >= 2 && base !== null) {
+            const now = twistAngle();
+            const d = angleDelta(base, now);
+            if (Math.abs(d) >= angle) {
+                base = now;
+                fire({ gesture, angle: d, direction: d > 0 ? 'cw' : 'ccw' }, e);
+            }
+        }
+        else if (gesture === 'long-press' && press && Math.hypot(e.clientX - press.x, e.clientY - press.y) > tolerance)
+            endPress();
+    };
+    const up = (e) => {
+        pts.delete(e.pointerId ?? 1);
+        if (gesture === 'fling' && path.length) {
+            path.push({ x: e.clientX, y: e.clientY, t: e.timeStamp || performance.now() });
+            const v = flingVelocity(path);
+            path = [];
+            if (v.speed >= velocity) {
+                const direction = Math.abs(v.vx) > Math.abs(v.vy) ? (v.vx > 0 ? 'right' : 'left') : v.vy > 0 ? 'down' : 'up';
+                fire({ gesture, ...v, direction }, e);
+            }
+        }
+        if (pts.size < 2)
+            base = null;
+        endPress();
+    };
+    el.addEventListener('pointerdown', down);
+    el.addEventListener('pointermove', move);
+    el.addEventListener('pointerup', up);
+    el.addEventListener('pointercancel', up);
+    if (gesture === 'twist' && !el.style.touchAction)
+        el.style.touchAction = 'none';
+    return () => {
+        endPress();
+        el.removeEventListener('pointerdown', down);
+        el.removeEventListener('pointermove', move);
+        el.removeEventListener('pointerup', up);
+        el.removeEventListener('pointercancel', up);
+    };
+}
+/**
+ * `<usa-gesture-fx gesture="fling | twist | long-press" effect="tada"
+ * options='{"…"}' velocity angle duration>` — plays `effect` on its first
+ * child (or itself with `self`) when the gesture happens.
+ */
+function defineGestureFx(tag = 'usa-gesture-fx') {
+    return base.defineElement(tag, (Base) => class UsaGestureFx extends Base {
+        static get observedAttributes() {
+            return ['gesture', 'effect', 'options'];
+        }
+        get gesture() {
+            const g = this.str('gesture', 'fling');
+            return GESTURES.includes(g) ? g : 'fling';
+        }
+        mount() {
+            let effectOptions = {};
+            try {
+                effectOptions = JSON.parse(this.str('options', '{}')) || {};
+            }
+            catch {
+                /* ignore bad JSON */
+            }
+            const target = this.flag('self') ? this : this.firstElementChild || this;
+            const effect = this.str('effect', 'pulse');
+            this.onCleanup(bindGesture(this, this.gesture, (_d, e) => void components_fx.playEffect(target, effect, effectOptions, e).catch(() => undefined), {
+                velocity: this.num('velocity', 0.8),
+                angle: this.num('angle', 30),
+                duration: this.num('duration', 650),
+            }));
+        }
+    }, { id: 'usa-gesture-fx', text: 'usa-gesture-fx{display:inline-block;touch-action:none;user-select:none}' });
+}
+
 /**
  * use-scroll-animate/components/effects — the 5.x effect packs, all
  * registered through `registerEffect()` (5.0) and playable with
@@ -1133,6 +1841,8 @@ const EFFECT_PACKS = {
     physics: PHYSICS_FX,
     page: PAGE_FX,
     generative: GENERATIVE_FX,
+    audio: AUDIO_FX,
+    cursor: CURSOR_FX,
 };
 /** 5.1: card & click effects 2.0. */
 function registerCardClickEffects() {
@@ -1150,9 +1860,19 @@ function registerPageEffects() {
 function registerGenerativeEffects() {
     components_fx.registerEffects(EFFECT_PACKS.generative);
 }
+/** 5.6: sound-reactive (Web Audio) backgrounds. */
+function registerAudioEffects() {
+    components_fx.registerEffects(EFFECT_PACKS.audio);
+}
+/** 5.7: cursor trails, magnetic dots, spotlight cursor. */
+function registerCursorEffects() {
+    components_fx.registerEffects(EFFECT_PACKS.cursor);
+}
 /** Define the 5.x elements of this entry (`<usa-story>`, …) under their default tags. */
 function defineEffectElements() {
     defineStory();
+    defineAudio();
+    defineGestureFx();
 }
 /** Register the built-ins and every pack (idempotent). */
 function registerAllEffects() {
@@ -1161,23 +1881,39 @@ function registerAllEffects() {
         components_fx.registerEffects(defs);
 }
 
+exports.AUDIO_FX = AUDIO_FX;
 exports.CARD_FX = CARD_FX;
 exports.CLICK_FX = CLICK_FX;
+exports.CURSOR_FX = CURSOR_FX;
 exports.EFFECT_PACKS = EFFECT_PACKS;
 exports.GENERATIVE_FX = GENERATIVE_FX;
+exports.GESTURES = GESTURES;
 exports.PAGE_FX = PAGE_FX;
 exports.PHYSICS_FX = PHYSICS_FX;
 exports.STORY_TEMPLATES = STORY_TEMPLATES;
+exports.angleDelta = angleDelta;
+exports.bindBeat = bindBeat;
+exports.bindGesture = bindGesture;
 exports.bounceKeyframes = bounceKeyframes;
 exports.canvasBackground = canvasBackground;
+exports.createBeatDetector = createBeatDetector;
+exports.defineAudio = defineAudio;
 exports.defineEffectElements = defineEffectElements;
+exports.defineGestureFx = defineGestureFx;
 exports.defineStory = defineStory;
+exports.disableAudio = disableAudio;
+exports.enableAudio = enableAudio;
+exports.flingVelocity = flingVelocity;
 exports.formatCount = formatCount;
 exports.fxLayer = fxLayer;
+exports.getAudio = getAudio;
 exports.hexRgb = hexRgb;
 exports.noise2 = noise2;
+exports.onBeat = onBeat;
 exports.registerAllEffects = registerAllEffects;
+exports.registerAudioEffects = registerAudioEffects;
 exports.registerCardClickEffects = registerCardClickEffects;
+exports.registerCursorEffects = registerCursorEffects;
 exports.registerGenerativeEffects = registerGenerativeEffects;
 exports.registerPageEffects = registerPageEffects;
 exports.registerPhysicsEffects = registerPhysicsEffects;