use-scroll-animate 5.3.0 → 5.5.0

package/dist/components/effects.d.ts

@@ -1,5 +1,14 @@
 type MotionSensitivity = 'full' | 'gentle' | 'minimal' | 'static';
 type Cleanup = () => void;
+/**
+ * Members shared by every `<usa-*>` element. Attribute helpers, a cleanup
+ * bag that is emptied on disconnect, and motion helpers that degrade to the
+ * final state without WAAPI or under reduced motion.
+ */
+interface UsaElement extends HTMLElement {
+    /** `true` while reduced motion applies to this element. */
+    readonly reduced: boolean;
+}
 
 /**
  * 5.0 — unified plugin-style effect registration. Every effect (built-in or
@@ -97,6 +106,84 @@ declare const PHYSICS_FX: EffectDefinition[];
 
 declare const PAGE_FX: EffectDefinition[];
 
+/**
+ * 5.5 — generative backgrounds on Canvas 2D, registered through
+ * `registerEffect()` (kind `background`): `flow-field`, `voronoi`,
+ * `mesh-gradient`, `starfield`, `metaballs`, `contours`.
+ *
+ * Shared runner (`canvasBackground()`): a canvas behind the element's content
+ * (`aria-hidden`, pointer-transparent), rendering only while visible
+ * (IntersectionObserver) and the tab is shown, with adaptive quality — the
+ * render scale drops when frames get slow and recovers when they are fast.
+ * Reduced motion: one static frame, no loop.
+ */
+
+interface GenFrame {
+    ctx: CanvasRenderingContext2D;
+    /** CSS-pixel size of the canvas. */
+    w: number;
+    h: number;
+    /** Seconds since start (0 for the static reduced-motion frame). */
+    t: number;
+    /** Render scale 0.35–1 (adaptive quality). */
+    quality: number;
+    /** Per-effect state, created by `init`. */
+    state: any;
+    /** Merged options. */
+    o: any;
+}
+interface GenerativeSpec {
+    init?: (w: number, h: number, o: any) => any;
+    draw: (f: GenFrame) => void;
+}
+/** Deterministic smooth pseudo-noise in [-1, 1] (sum of sines — cheap, no tables). */
+declare function noise2(x: number, y: number, t?: number): number;
+/** Hex `#rrggbb` → [r, g, b]. */
+declare function hexRgb(hex: string): [number, number, number];
+/**
+ * Mount a generative canvas behind `el` and run `spec` on it. Returns the
+ * cleanup. Exposed for custom generative effects.
+ */
+declare function canvasBackground(el: HTMLElement, fx: EffectContext, spec: GenerativeSpec, o: any): () => void;
+declare const GENERATIVE_FX: EffectDefinition[];
+
+/**
+ * 5.4 — `<usa-story template="…">` scroll-storytelling templates.
+ *
+ * - `pin` — a sticky `[data-stage]` while `[data-step]` sections scroll past; the
+ *   step in view gets `data-active`, the stage gets `data-active-step="<index>"`.
+ * - `gallery` — a horizontal `[data-track]` slides sideways as you scroll down.
+ * - `zoom` — the `[data-stage]` zooms toward the viewer (`zoom="6"`) and fades.
+ * - `compare` — before / after (`[data-before]`, `[data-after]`) wipe driven by
+ *   scroll, plus a draggable, keyboard-accessible handle (`role="slider"`).
+ * - `counter` — `[data-count="1234"]` numbers count up when they enter view.
+ * - `highlight` — paragraphs dim except the one crossing the viewport center.
+ *
+ * Every template sets `--usa-story-progress` (0–1) on the host and dispatches
+ * `usa-story-step` (`detail: { index }`). Reduced motion: no sliding / zooming
+ * (the gallery stacks vertically), counters show final values, the rest is
+ * class changes only.
+ */
+
+declare const STORY_TEMPLATES: readonly ["pin", "gallery", "zoom", "compare", "counter", "highlight"];
+type StoryTemplate = (typeof STORY_TEMPLATES)[number];
+interface UsaStoryElement extends UsaElement {
+    /** Scroll progress through the story, 0–1. */
+    readonly progress: number;
+    /** Index of the active step (pin / highlight), or -1. */
+    readonly step: number;
+}
+/** Progress of `el` through the viewport: 0 when its top hits the viewport top, 1 when its bottom hits the viewport bottom. */
+declare function storyProgress(el: Element, vh?: number): number;
+/** Format a counted value like the target (`1,234`, `12.5`, prefix / suffix kept). */
+declare function formatCount(target: string, t: number): string;
+declare function defineStory(tag?: string): CustomElementConstructor | undefined;
+declare global {
+    interface HTMLElementTagNameMap {
+        'usa-story': UsaStoryElement;
+    }
+}
+
 /** Helpers shared by the 5.x effect packs. */
 
 /** A fixed, pointer-transparent, aria-hidden layer for transient particles. */
@@ -110,8 +197,12 @@ declare function registerCardClickEffects(): void;
 declare function registerPhysicsEffects(): void;
 /** 5.3: page-wide transitions and effects. */
 declare function registerPageEffects(): void;
+/** 5.5: generative Canvas 2D backgrounds. */
+declare function registerGenerativeEffects(): void;
+/** Define the 5.x elements of this entry (`<usa-story>`, …) under their default tags. */
+declare function defineEffectElements(): void;
 /** Register the built-ins and every pack (idempotent). */
 declare function registerAllEffects(): void;
 
-export { CARD_FX, CLICK_FX, EFFECT_PACKS, PAGE_FX, PHYSICS_FX, bounceKeyframes, fxLayer, registerAllEffects, registerCardClickEffects, registerPageEffects, registerPhysicsEffects, solveSpring, springKeyframes };
-export type { SpringOptions };
+export { CARD_FX, CLICK_FX, EFFECT_PACKS, GENERATIVE_FX, PAGE_FX, PHYSICS_FX, STORY_TEMPLATES, bounceKeyframes, canvasBackground, defineEffectElements, defineStory, formatCount, fxLayer, hexRgb, noise2, registerAllEffects, registerCardClickEffects, registerGenerativeEffects, registerPageEffects, registerPhysicsEffects, solveSpring, springKeyframes, storyProgress };
+export type { GenFrame, GenerativeSpec, SpringOptions, StoryTemplate, UsaStoryElement };

package/dist/components/effects.js

@@ -1,5 +1,5 @@
 import { registerBuiltinEffects, registerEffects } from './fx.js';
-import '../chunks/base-C3Sw9sAO.js';
+import { x as defineElement } from '../chunks/base-C3Sw9sAO.js';
 import '../chunks/core-DN3hHbHh.js';
 import './tokens.js';
 import '../chunks/fx-ChjxrMBo.js';
@@ -617,6 +617,502 @@ const PAGE_FX = [
     },
 ];
 
+/**
+ * 5.4 — `<usa-story template="…">` scroll-storytelling templates.
+ *
+ * - `pin` — a sticky `[data-stage]` while `[data-step]` sections scroll past; the
+ *   step in view gets `data-active`, the stage gets `data-active-step="<index>"`.
+ * - `gallery` — a horizontal `[data-track]` slides sideways as you scroll down.
+ * - `zoom` — the `[data-stage]` zooms toward the viewer (`zoom="6"`) and fades.
+ * - `compare` — before / after (`[data-before]`, `[data-after]`) wipe driven by
+ *   scroll, plus a draggable, keyboard-accessible handle (`role="slider"`).
+ * - `counter` — `[data-count="1234"]` numbers count up when they enter view.
+ * - `highlight` — paragraphs dim except the one crossing the viewport center.
+ *
+ * Every template sets `--usa-story-progress` (0–1) on the host and dispatches
+ * `usa-story-step` (`detail: { index }`). Reduced motion: no sliding / zooming
+ * (the gallery stacks vertically), counters show final values, the rest is
+ * class changes only.
+ */
+const STORY_TEMPLATES = ['pin', 'gallery', 'zoom', 'compare', 'counter', 'highlight'];
+const CSS = `usa-story{display:block;position:relative}
+usa-story[template=pin] [data-stage],usa-story[template=gallery] [data-sticky],usa-story[template=zoom] [data-stage],usa-story[template=compare] [data-sticky]{position:sticky;top:0}
+usa-story[template=pin] [data-stage]{align-self:start}
+usa-story[template=pin] [data-step]{min-height:80vh;opacity:.35;transition:opacity .3s}
+usa-story[template=pin] [data-step][data-active]{opacity:1}
+usa-story[template=gallery] [data-sticky]{height:100vh;overflow:hidden;display:flex;align-items:center}
+usa-story[template=gallery] [data-track]{display:flex;gap:24px;will-change:transform}
+usa-story[template=gallery][data-static] [data-sticky]{position:static;height:auto;overflow:visible}
+usa-story[template=gallery][data-static] [data-track]{flex-direction:column;transform:none!important}
+usa-story[template=zoom] [data-stage]{height:100vh;overflow:hidden;display:grid;place-items:center}
+usa-story[template=compare] [data-sticky]{height:var(--usa-story-h,70vh);overflow:hidden}
+usa-story[template=compare] [data-before],usa-story[template=compare] [data-after]{position:absolute;inset:0}
+usa-story[template=compare] [data-after]{clip-path:inset(0 0 0 var(--usa-split,50%))}
+usa-story [data-handle]{position:absolute;top:0;bottom:0;left:var(--usa-split,50%);width:4px;margin-left:-2px;background:#fff;box-shadow:0 0 0 1px #0003;cursor:ew-resize;touch-action:none}
+usa-story [data-handle]:focus-visible{outline:3px solid #7c5cff;outline-offset:2px}
+usa-story[template=highlight] p,usa-story[template=highlight] [data-step]{opacity:.3;transition:opacity .25s}
+usa-story[template=highlight] [data-active]{opacity:1}`;
+const clamp = (v, a = 0, b = 1) => Math.min(b, Math.max(a, v));
+/** Progress of `el` through the viewport: 0 when its top hits the viewport top, 1 when its bottom hits the viewport bottom. */
+function storyProgress(el, vh = typeof innerHeight === 'number' ? innerHeight : 800) {
+    const r = el.getBoundingClientRect();
+    const span = r.height - vh;
+    return span > 0 ? clamp(-r.top / span) : clamp((vh - r.top) / (vh + r.height));
+}
+/** Format a counted value like the target (`1,234`, `12.5`, prefix / suffix kept). */
+function formatCount(target, t) {
+    const m = target.match(/^(\D*)([\d,]*\.?\d+)(.*)$/);
+    if (!m)
+        return target;
+    const [, pre, num, post] = m;
+    const n = parseFloat(num.replace(/,/g, ''));
+    const dec = (num.split('.')[1] || '').length;
+    let s = (n * t).toFixed(dec);
+    if (num.includes(','))
+        s = Number(s).toLocaleString('en-US', { minimumFractionDigits: dec, maximumFractionDigits: dec });
+    return pre + s + post;
+}
+function defineStory(tag = 'usa-story') {
+    return defineElement(tag, (Base) => class UsaStory extends Base {
+        constructor() {
+            super(...arguments);
+            this.progress = 0;
+            this.step = -1;
+            this.frame = 0;
+        }
+        static get observedAttributes() {
+            return ['template', 'zoom'];
+        }
+        get template() {
+            const t = this.str('template', 'pin');
+            return STORY_TEMPLATES.includes(t) ? t : 'pin';
+        }
+        steps() {
+            const own = Array.from(this.querySelectorAll('[data-step]:not([data-stage])'));
+            return own.length || this.template !== 'highlight' ? own : Array.from(this.querySelectorAll('p'));
+        }
+        setStep(i) {
+            if (i === this.step)
+                return;
+            this.step = i;
+            this.steps().forEach((s, k) => s.toggleAttribute('data-active', k === i));
+            const stage = this.querySelector('[data-stage]');
+            if (stage)
+                stage.dataset.activeStep = String(i);
+            this.dispatchEvent(new CustomEvent('usa-story-step', { detail: { index: i }, bubbles: true }));
+        }
+        /** Recompute from the current scroll position (called on scroll / resize). */
+        update() {
+            this.frame = 0;
+            const p = (this.progress = storyProgress(this));
+            this.style.setProperty('--usa-story-progress', p.toFixed(4));
+            const t = this.template;
+            const vh = innerHeight || 800;
+            if (t === 'pin' || t === 'highlight') {
+                const mid = vh / 2;
+                let best = -1;
+                let bestD = Infinity;
+                this.steps().forEach((s, i) => {
+                    const r = s.getBoundingClientRect();
+                    const d = r.top <= mid && r.bottom >= mid ? 0 : Math.min(Math.abs(r.top - mid), Math.abs(r.bottom - mid));
+                    if (d < bestD)
+                        (bestD = d), (best = i);
+                });
+                this.setStep(best);
+            }
+            else if (t === 'gallery' && !this.reduced) {
+                const track = this.querySelector('[data-track]');
+                const box = this.querySelector('[data-sticky]');
+                if (track && box)
+                    track.style.transform = `translateX(${(-p * Math.max(0, track.scrollWidth - box.clientWidth)).toFixed(1)}px)`;
+            }
+            else if (t === 'zoom' && !this.reduced) {
+                const inner = this.querySelector('[data-stage] > *');
+                if (inner) {
+                    inner.style.transform = `scale(${(1 + p * (this.num('zoom', 6) - 1)).toFixed(3)})`;
+                    inner.style.opacity = String(clamp(1.4 - p * 1.4).toFixed(3));
+                }
+            }
+            else if (t === 'compare' && !this.hasAttribute('data-dragged')) {
+                this.setSplit(p * 100);
+            }
+            else if (t === 'counter') {
+                this.querySelectorAll('[data-count]:not([data-counted])').forEach((el) => {
+                    const r = el.getBoundingClientRect();
+                    if (r.top < vh * 0.9 && r.bottom > 0)
+                        this.count(el);
+                });
+            }
+        }
+        setSplit(pct) {
+            const v = clamp(pct, 0, 100);
+            this.style.setProperty('--usa-split', `${v.toFixed(2)}%`);
+            const h = this.querySelector('[data-handle]');
+            if (h)
+                h.setAttribute('aria-valuenow', String(Math.round(v)));
+        }
+        count(el) {
+            el.dataset.counted = '';
+            const target = el.dataset.count || el.textContent || '0';
+            el.setAttribute('aria-label', target);
+            if (this.reduced) {
+                el.textContent = target;
+                return;
+            }
+            const dur = Number(el.dataset.duration) || 1600;
+            const t0 = performance.now();
+            const tick = (now) => {
+                const k = clamp((now - t0) / dur);
+                el.textContent = formatCount(target, 1 - (1 - k) ** 3);
+                if (k < 1)
+                    requestAnimationFrame(tick);
+            };
+            requestAnimationFrame(tick);
+        }
+        mount() {
+            this.toggleAttribute('data-static', this.reduced);
+            if (this.template === 'compare')
+                this.mountCompare();
+            const kick = () => {
+                if (!this.frame)
+                    this.frame = requestAnimationFrame(() => this.update());
+            };
+            this.listen(window, 'scroll', kick, { passive: true });
+            this.listen(window, 'resize', kick);
+            this.onCleanup(() => cancelAnimationFrame(this.frame));
+            this.update();
+        }
+        mountCompare() {
+            const box = this.querySelector('[data-sticky]') || this;
+            let h = this.querySelector('[data-handle]');
+            if (!h) {
+                h = document.createElement('div');
+                h.setAttribute('data-handle', '');
+                box.appendChild(h);
+                this.onCleanup(() => h.remove());
+            }
+            h.tabIndex = 0;
+            h.setAttribute('role', 'slider');
+            h.setAttribute('aria-label', this.str('label', 'Before / after'));
+            h.setAttribute('aria-valuemin', '0');
+            h.setAttribute('aria-valuemax', '100');
+            const at = (e) => {
+                const r = box.getBoundingClientRect();
+                this.dataset.dragged = '';
+                this.setSplit(((e.clientX - r.left) / (r.width || 1)) * 100);
+            };
+            let drag = false;
+            this.listen(h, 'pointerdown', (e) => {
+                drag = true;
+                h.setPointerCapture?.(e.pointerId);
+            });
+            this.listen(h, 'pointermove', (e) => drag && at(e));
+            this.listen(h, 'pointerup', () => (drag = false));
+            this.listen(h, 'keydown', (e) => {
+                const cur = parseFloat(h.getAttribute('aria-valuenow') || '50');
+                const step = e.shiftKey ? 10 : 2;
+                const next = e.key === 'ArrowLeft' || e.key === 'ArrowDown' ? cur - step : e.key === 'ArrowRight' || e.key === 'ArrowUp' ? cur + step : e.key === 'Home' ? 0 : e.key === 'End' ? 100 : null;
+                if (next == null)
+                    return;
+                e.preventDefault();
+                this.dataset.dragged = '';
+                this.setSplit(next);
+            });
+            this.setSplit(50);
+        }
+        unmount() {
+            this.step = -1;
+            delete this.dataset.dragged;
+        }
+    }, { 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;
+            });
+        },
+    }),
+];
+
 /**
  * use-scroll-animate/components/effects — the 5.x effect packs, all
  * registered through `registerEffect()` (5.0) and playable with
@@ -634,6 +1130,7 @@ const EFFECT_PACKS = {
     'cards-click': [...CARD_FX, ...CLICK_FX],
     physics: PHYSICS_FX,
     page: PAGE_FX,
+    generative: GENERATIVE_FX,
 };
 /** 5.1: card & click effects 2.0. */
 function registerCardClickEffects() {
@@ -647,6 +1144,14 @@ function registerPhysicsEffects() {
 function registerPageEffects() {
     registerEffects(EFFECT_PACKS.page);
 }
+/** 5.5: generative Canvas 2D backgrounds. */
+function registerGenerativeEffects() {
+    registerEffects(EFFECT_PACKS.generative);
+}
+/** Define the 5.x elements of this entry (`<usa-story>`, …) under their default tags. */
+function defineEffectElements() {
+    defineStory();
+}
 /** Register the built-ins and every pack (idempotent). */
 function registerAllEffects() {
     registerBuiltinEffects();
@@ -654,5 +1159,5 @@ function registerAllEffects() {
         registerEffects(defs);
 }
 
-export { CARD_FX, CLICK_FX, EFFECT_PACKS, PAGE_FX, PHYSICS_FX, bounceKeyframes, fxLayer, registerAllEffects, registerCardClickEffects, registerPageEffects, registerPhysicsEffects, solveSpring, springKeyframes };
+export { CARD_FX, CLICK_FX, EFFECT_PACKS, GENERATIVE_FX, PAGE_FX, PHYSICS_FX, STORY_TEMPLATES, bounceKeyframes, canvasBackground, defineEffectElements, defineStory, formatCount, fxLayer, hexRgb, noise2, registerAllEffects, registerCardClickEffects, registerGenerativeEffects, registerPageEffects, registerPhysicsEffects, solveSpring, springKeyframes, storyProgress };
 //# sourceMappingURL=effects.js.map