@sharedex/ui 0.0.0-stage → 0.9.0

package/dist/backgrounds/hosts/WebglHost.js

@@ -0,0 +1,181 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useRef, useState } from "react";
+import { useBackgroundRuntime } from "../runtime/context.js";
+import { capped, onFrame } from "../runtime/clock.js";
+import { createColorResolver, watchTheme } from "../runtime/color.js";
+import { rng } from "../runtime/rng.js";
+import { createGpuSurface } from "../../gpu/surface.js";
+import { useLayerNeeds } from "./useLayerNeeds.js";
+// a cycle (Layer renders this host), but only used at render time, so safe
+import { Layer } from "../parts/Layer.js";
+/** Longest step a simulation is given after a stall (a tab coming back). */
+const MAX_DELTA_S = 1 / 20;
+/**
+ * Runs a WebGL effect's GPU program. Like the canvas host it owns size
+ * (capped DPR × the effect's `resolution`), the shared frame loop, pausing,
+ * reduced motion, theme colours and input (pointer, taps). On top of that it
+ * manages the context itself (`gpu/surface.ts`), because a page gets only
+ * ~16 live WebGL contexts:
+ *
+ * - the context is created when the layer first comes on screen, not on mount;
+ * - after 3 s off screen it is handed back (`loseContext`), and a fresh canvas
+ *   (a new context) is made when the layer returns;
+ * - if the browser takes it away (too many contexts, GPU reset) the same
+ *   happens on return; and if WebGL, an extension or a compile is missing,
+ *   the effect's fallback renders instead.
+ */
+export function WebglHost({ effect, className }) {
+    const runtime = useBackgroundRuntime("Background.Layer");
+    const { onVisibility, visible, pointer, onTap, config } = runtime;
+    const layerRef = useRef(null);
+    const canvasRef = useRef(null);
+    // a new canvas element is the only way to get a new context after losing one
+    const [generation, setGeneration] = useState(0);
+    const [failed, setFailed] = useState(false);
+    const losses = useRef([]);
+    const latest = useRef(effect);
+    latest.current = effect;
+    useLayerNeeds(effect.meta, layerRef);
+    useEffect(() => {
+        const layer = layerRef.current;
+        const canvas = canvasRef.current;
+        if (failed || !layer || !canvas)
+            return;
+        const e = latest.current;
+        const { program } = e;
+        const fps = config.fps > 0 && e.fps > 0 ? Math.min(config.fps, e.fps) : config.fps || e.fps;
+        const resolver = createColorResolver(layer);
+        const reduce = matchMedia("(prefers-reduced-motion: reduce)");
+        const coarse = matchMedia("(pointer: coarse)").matches;
+        const resolveColors = () => e.colors.map((c) => {
+            const [r, g, b, a] = resolver.resolve(c);
+            return [r / 255, g / 255, b / 255, a];
+        });
+        let colors = resolveColors();
+        const rtl = getComputedStyle(layer).direction === "rtl";
+        let stop = null;
+        let time = e.stillTime;
+        let taps = [];
+        const motion = () => (reduce.matches ? config.reducedMotion : "ignore");
+        const frameData = (delta) => {
+            const scale = Math.min(window.devicePixelRatio || 1, config.maxDpr) * e.resolution;
+            const w = layer.clientWidth;
+            const h = layer.clientHeight;
+            const width = Math.max(1, Math.round(w * scale));
+            const height = Math.max(1, Math.round(h * scale));
+            if (canvas.width !== width || canvas.height !== height) {
+                canvas.width = width;
+                canvas.height = height;
+            }
+            const f = {
+                time,
+                delta,
+                width,
+                height,
+                dpr: scale,
+                pointer: [w ? pointer.x / w : 0.5, h ? 1 - pointer.y / h : 0.5],
+                pointerIn: pointer.inside,
+                taps,
+                rtl,
+                coarse,
+                colors,
+            };
+            taps = [];
+            return f;
+        };
+        const surface = createGpuSurface(canvas, {
+            api: program.api,
+            label: e.meta.id,
+            init: (gl) => program.init(gl, frameData(0), rng(e.seed)),
+            dispose: (gl, state) => program.dispose(gl, state),
+            isVisible: () => visible.current,
+            onRelease: () => {
+                stop?.();
+                stop = null;
+            },
+            renew: () => setGeneration((g) => g + 1),
+            fail: () => setFailed(true),
+            losses,
+        });
+        const draw = (delta) => {
+            const live = surface.live;
+            if (live)
+                program.frame(live.gl, live.state, frameData(delta));
+        };
+        /** Under reduced motion `still`: simulate the warm-up with no input, then show one frame. */
+        const paintStill = () => {
+            time = e.stillTime - program.warmup / 60;
+            for (let i = 0; i < program.warmup; i++) {
+                draw(1 / 60);
+                time += 1 / 60;
+            }
+            time = e.stillTime;
+            draw(program.warmup > 0 ? 1 / 60 : 0);
+        };
+        const tick = (deltaMs) => {
+            const delta = Math.min(deltaMs / 1000, MAX_DELTA_S) * (motion() === "slow" ? 0.35 : 1);
+            time += delta;
+            draw(delta);
+        };
+        const sync = () => {
+            if (!visible.current) {
+                stop?.();
+                stop = null;
+                surface.hidden();
+                return;
+            }
+            if (!surface.shown())
+                return; // a fresh canvas is coming
+            const fresh = !surface.live;
+            if (!surface.ensure())
+                return;
+            const still = motion() === "still";
+            if (still) {
+                stop?.();
+                stop = null;
+                paintStill();
+                return;
+            }
+            if (!stop)
+                stop = onFrame(capped(fps, tick));
+            if (fresh)
+                draw(0); // the first frame now, not one frame later
+        };
+        const repaint = () => {
+            colors = resolveColors();
+            if (!stop && surface.live && motion() !== "still")
+                draw(0);
+            else if (!stop && surface.live)
+                paintStill();
+        };
+        const offTap = onTap((x, y) => {
+            const w = layer.clientWidth;
+            const h = layer.clientHeight;
+            if (w && h)
+                taps.push([x / w, 1 - y / h]);
+        });
+        sync();
+        const offVisibility = onVisibility(sync);
+        reduce.addEventListener("change", sync);
+        const stopTheme = watchTheme(repaint);
+        const ro = new ResizeObserver(() => {
+            if (!stop && surface.live)
+                draw(0); // a running loop picks the new size up on its next frame
+        });
+        ro.observe(layer);
+        return () => {
+            offTap();
+            offVisibility();
+            reduce.removeEventListener("change", sync);
+            stopTheme();
+            ro.disconnect();
+            stop?.();
+            surface.destroy();
+            resolver.dispose();
+        };
+    }, [effect.meta.id, effect.signature, generation, failed, config.maxDpr, config.fps, config.reducedMotion, onVisibility, visible, pointer, onTap]);
+    if (failed)
+        return _jsx(Layer, { effect: effect.fallback, className: className });
+    return (_jsx("div", { ref: layerRef, "data-sx-bg": effect.meta.id, className: className, style: effect.vars, children: _jsx("canvas", { ref: canvasRef, "data-sx-bg-part": "canvas" }, generation) }));
+}

package/dist/backgrounds/hosts/svgElement.d.ts

@@ -0,0 +1,7 @@
+import { type ReactNode } from "react";
+import type { SvgElement } from "../types.js";
+/**
+ * One element of an SVG tree, as React. `{uid}` in attribute values becomes
+ * `uid`; `part` goes into `partAttr` (transitions use `data-sx-tr-part`).
+ */
+export declare function renderSvgElement(el: SvgElement, uid: string, key: number, partAttr?: string): ReactNode;

package/dist/backgrounds/hosts/svgElement.js

@@ -0,0 +1,19 @@
+// One element of an SVG tree as React, with no host attached: backgrounds' SvgHost, buttons and text layers share it.
+import { createElement } from "react";
+/** `stroke-width` -> `strokeWidth`: React's names for SVG attributes (`data-*` / `aria-*` stay as they are). */
+const reactName = (name) => name.startsWith("data-") || name.startsWith("aria-") ? name : name.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+/**
+ * One element of an SVG tree, as React. `{uid}` in attribute values becomes
+ * `uid`; `part` goes into `partAttr` (transitions use `data-sx-tr-part`).
+ */
+export function renderSvgElement(el, uid, key, partAttr = "data-sx-bg-part") {
+    const props = { key };
+    for (const [name, value] of Object.entries(el.attrs ?? {})) {
+        props[reactName(name)] = typeof value === "string" ? value.split("{uid}").join(uid) : value;
+    }
+    if (el.part)
+        props[partAttr] = el.part;
+    if (el.vars)
+        props.style = el.vars;
+    return createElement(el.tag, props, ...(el.children ?? []).map((child, i) => renderSvgElement(child, uid, i, partAttr)));
+}

package/dist/backgrounds/hosts/useLayerNeeds.d.ts

@@ -0,0 +1,10 @@
+import { type RefObject } from "react";
+import type { EffectMeta } from "../types.js";
+import { nativeScrollTimelineWorks } from "../runtime/nativeScroll.js";
+export { nativeScrollTimelineWorks };
+/**
+ * Starts the runtime services an effect's meta asks for (`needs.pointer`,
+ * `needs.scroll`) while the layer is mounted. Every host calls it, so no
+ * effect starts its own listener.
+ */
+export declare function useLayerNeeds(meta: EffectMeta, layer: RefObject<HTMLElement | null>): void;

package/dist/backgrounds/hosts/useLayerNeeds.js

@@ -0,0 +1,33 @@
+"use client";
+import { useEffect } from "react";
+import { useBackgroundRuntime } from "../runtime/context.js";
+import { nativeScrollTimelineWorks } from "../runtime/nativeScroll.js";
+export { nativeScrollTimelineWorks };
+/**
+ * Starts the runtime services an effect's meta asks for (`needs.pointer`,
+ * `needs.scroll`) while the layer is mounted. Every host calls it, so no
+ * effect starts its own listener.
+ */
+export function useLayerNeeds(meta, layer) {
+    const { trackPointer, trackScroll, root } = useBackgroundRuntime("Background.Layer");
+    const pointer = meta.needs?.pointer === true;
+    const scroll = meta.needs?.scroll ?? false;
+    useEffect(() => (pointer ? trackPointer() : undefined), [pointer, trackPointer]);
+    useEffect(() => {
+        if (!scroll)
+            return;
+        if (scroll !== "native")
+            return trackScroll();
+        const el = layer.current;
+        const box = root.current;
+        if (!el || !box || nativeScrollTimelineWorks(box))
+            return;
+        // the effect's CSS switches from the native timeline to --sx-scroll
+        el.setAttribute("data-sx-scroll", "js");
+        const release = trackScroll();
+        return () => {
+            el.removeAttribute("data-sx-scroll");
+            release();
+        };
+    }, [scroll, trackScroll, root, layer]);
+}

package/dist/backgrounds/parts/Layer.d.ts

@@ -0,0 +1,11 @@
+import type { BackgroundEffect } from "../types.js";
+export interface LayerProps {
+    readonly effect: BackgroundEffect;
+    readonly className?: string;
+}
+/**
+ * One effect. Picks the host for `effect.kind`; on a device below the
+ * effect's tier it follows the fallback chain to the first one it can run,
+ * or renders nothing. Layers stack in source order: the first is at the back.
+ */
+export declare function Layer({ effect, className }: LayerProps): import("react").JSX.Element | null;

package/dist/backgrounds/parts/Layer.js

@@ -0,0 +1,38 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useBackgroundRuntime } from "../runtime/context.js";
+import { tierAllows } from "../runtime/tier.js";
+import { CssHost } from "../hosts/CssHost.js";
+import { MediaHost } from "../hosts/MediaHost.js";
+import { CanvasHost } from "../hosts/CanvasHost.js";
+import { SvgHost } from "../hosts/SvgHost.js";
+import { WebglHost } from "../hosts/WebglHost.js";
+/**
+ * One effect. Picks the host for `effect.kind`; on a device below the
+ * effect's tier it follows the fallback chain to the first one it can run,
+ * or renders nothing. Layers stack in source order: the first is at the back.
+ */
+export function Layer({ effect, className }) {
+    const { tier } = useBackgroundRuntime("Background.Layer");
+    const chosen = pick(effect, tier);
+    if (!chosen)
+        return null;
+    switch (chosen.kind) {
+        case "css":
+            return _jsx(CssHost, { effect: chosen, className: className });
+        case "media":
+            return _jsx(MediaHost, { effect: chosen, className: className });
+        case "canvas":
+            return _jsx(CanvasHost, { effect: chosen, className: className });
+        case "svg":
+            return _jsx(SvgHost, { effect: chosen, className: className });
+        case "webgl":
+            return _jsx(WebglHost, { effect: chosen, className: className });
+    }
+}
+/** The effect, or the first fallback down its chain that the device tier allows. */
+function pick(effect, tier) {
+    if (tierAllows(tier, effect.meta.tier))
+        return effect;
+    return effect.fallback ? pick(effect.fallback, tier) : undefined;
+}

package/dist/backgrounds/parts/Root.d.ts

@@ -0,0 +1,17 @@
+import { type ReactNode } from "react";
+import { type BackgroundOptions } from "../config.js";
+import type { BackgroundEffect } from "../types.js";
+export interface RootProps extends BackgroundOptions {
+    /** Shorthand for one layer. Rendered below any `children` layers. */
+    readonly effect?: BackgroundEffect;
+    readonly className?: string;
+    /** `<Background.Layer>` elements, back to front. */
+    readonly children?: ReactNode;
+}
+/**
+ * The background box: fills its parent (which needs `position: relative;
+ * isolation: isolate`), sits behind the parent's content, is hidden from
+ * assistive technology and never takes pointer events. Owns the runtime its
+ * layers share.
+ */
+export declare function Root({ effect, className, children, quality, maxDpr, fps, pauseOffscreen, reducedMotion, }: RootProps): import("react").JSX.Element;

package/dist/backgrounds/parts/Root.js

@@ -0,0 +1,25 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useMemo, useRef } from "react";
+import { resolveBackgroundConfig } from "../config.js";
+import { BackgroundRuntimeContext } from "../runtime/context.js";
+import { useDeviceTier, usePointerTracking, useScrollTracking, useVisibility } from "../runtime/hooks.js";
+import { ROOT_CSS } from "../runtime/rootCss.js";
+import { Layer } from "./Layer.js";
+import { styleHref } from "../hosts/CssHost.js";
+/**
+ * The background box: fills its parent (which needs `position: relative;
+ * isolation: isolate`), sits behind the parent's content, is hidden from
+ * assistive technology and never takes pointer events. Owns the runtime its
+ * layers share.
+ */
+export function Root({ effect, className, children, quality, maxDpr, fps, pauseOffscreen, reducedMotion, }) {
+    const config = useMemo(() => resolveBackgroundConfig({ quality, maxDpr, fps, pauseOffscreen, reducedMotion }), [quality, maxDpr, fps, pauseOffscreen, reducedMotion]);
+    const root = useRef(null);
+    const tier = useDeviceTier(config.quality);
+    const { visible, subscribe } = useVisibility(root, config.pauseOffscreen);
+    const { track: trackPointer, pointer, onTap } = usePointerTracking(root, visible);
+    const { track: trackScroll, scroll, subscribe: onScroll } = useScrollTracking(root, visible, subscribe, config.reducedMotion);
+    const runtime = useMemo(() => ({ config, tier, root, visible, onVisibility: subscribe, trackPointer, pointer, onTap, trackScroll, scroll, onScroll }), [config, tier, visible, subscribe, trackPointer, pointer, onTap, trackScroll, scroll, onScroll]);
+    return (_jsx(BackgroundRuntimeContext.Provider, { value: runtime, children: _jsxs("div", { ref: root, "data-sx-bg-root": "", "data-sx-reduce": config.reducedMotion, "aria-hidden": "true", className: className, children: [_jsx("style", { href: styleHref("root", ROOT_CSS), precedence: "sx", children: ROOT_CSS }), effect ? _jsx(Layer, { effect: effect }) : null, children] }) }));
+}

package/dist/backgrounds/parts/index.d.ts

@@ -0,0 +1,21 @@
+import { Root } from "./Root.js";
+import { Layer } from "./Layer.js";
+export type { RootProps as BackgroundRootProps } from "./Root.js";
+export type { LayerProps as BackgroundLayerProps } from "./Layer.js";
+/**
+ * Decorative layers behind a section's content.
+ *
+ * ```tsx
+ * <section className="relative isolate">
+ *   <Background.Root>
+ *     <Background.Layer effect={aurora()} />
+ *     <Background.Layer effect={filmGrain()} />
+ *   </Background.Root>
+ *   …content…
+ * </section>
+ * ```
+ */
+export declare const Background: {
+    Root: typeof Root;
+    Layer: typeof Layer;
+};

package/dist/backgrounds/parts/index.js

@@ -0,0 +1,16 @@
+import { Root } from "./Root.js";
+import { Layer } from "./Layer.js";
+/**
+ * Decorative layers behind a section's content.
+ *
+ * ```tsx
+ * <section className="relative isolate">
+ *   <Background.Root>
+ *     <Background.Layer effect={aurora()} />
+ *     <Background.Layer effect={filmGrain()} />
+ *   </Background.Root>
+ *   …content…
+ * </section>
+ * ```
+ */
+export const Background = { Root, Layer };

package/dist/backgrounds/registry.d.ts

@@ -0,0 +1,5 @@
+import type { EffectMeta } from "./types.js";
+/** Effects, in atlas category order. */
+export declare const BACKGROUND_EFFECTS: readonly EffectMeta[];
+/** The two slots that take the consumer's own file. */
+export declare const BACKGROUND_SLOTS: readonly EffectMeta[];

package/dist/backgrounds/registry.js

@@ -0,0 +1,190 @@
+// ---------------------------------------------------------------------------
+// Every background effect's metadata: the atlas as data. The docs gallery and
+// the builder read it; tests check it against the atlas coverage fixture.
+//
+// Importing this module loads every effect module, so components never import
+// it; only catalogs (the docs gallery, the builder) do.
+// ---------------------------------------------------------------------------
+import { DOT_PATTERN_META } from "./effects/grid/dotPattern.js";
+import { GRADIENT_GRID_META } from "./effects/grid/gradientGrid.js";
+import { FADING_GRID_META } from "./effects/grid/fadingGrid.js";
+import { FILM_GRAIN_META } from "./effects/texture/filmGrain.js";
+import { CRT_SCANLINES_META } from "./effects/glitch/crtScanlines.js";
+import { AURORA_META } from "./effects/shader/aurora.js";
+import { BOKEH_META } from "./effects/particle/bokeh.js";
+import { METEORS_META } from "./effects/particle/meteors.js";
+import { RIPPLES_META } from "./effects/wave/ripples.js";
+import { CURSOR_GLOW_META } from "./effects/cursor/cursorGlow.js";
+import { FOGGY_GLASS_META, FROZEN_GLASS_META } from "./effects/texture/glass.js";
+import { DIGITAL_GLITCH_META } from "./effects/glitch/digitalGlitch.js";
+import { RETRO_SCREEN_META } from "./effects/glitch/retroScreen.js";
+import { RGB_SHIFT_META } from "./effects/glitch/rgbShift.js";
+import { ISOMETRIC_LAYERS_META } from "./effects/glass/isometricLayers.js";
+import { RAINBOW_META } from "./effects/shader/rainbow.js";
+import { GRADIENT_BARS_META } from "./effects/shader/gradientBars.js";
+import { IRIDESCENT_META } from "./effects/shader/iridescent.js";
+import { TRIANGLE_GRID_META } from "./effects/grid/triangleGrid.js";
+import { GRID_HOVER_META } from "./effects/grid/gridHover.js";
+import { MORPH_GRID_META } from "./effects/grid/morphGrid.js";
+import { LAYERED_GRID_CARDS_META } from "./effects/grid/layeredGridCards.js";
+import { DATA_GRID_META } from "./effects/grid/dataGrid.js";
+import { GRID_HERO_META } from "./effects/grid/gridHero.js";
+import { ANIMATED_GRID_META } from "./effects/grid/animatedGrid.js";
+import { MAGNET_LINES_META } from "./effects/grid/magnetLines.js";
+import { WAVY_PATTERN_META } from "./effects/wave/wavyPattern.js";
+import { MOIRE_DOTS_META } from "./effects/wave/moireDots.js";
+import { LIQUID_WAVE_META } from "./effects/wave/liquidWave.js";
+import { PARTICLE_ORB_META } from "./effects/particle/particleOrb.js";
+import { CURSOR_DOTS_META } from "./effects/particle/cursorDots.js";
+import { CIRCLES_PATTERN_META, DIAMONDS_PATTERN_META, SCALES_PATTERN_META, LEATHER_PATTERN_META, STRANGE_PATTERN_META } from "./effects/pattern/patterns.js";
+import { MATRIX_RAIN_META } from "./effects/glitch/matrixRain.js";
+import { ASCII_ART_META } from "./effects/glitch/asciiArt.js";
+import { MELTY_LINES_META } from "./effects/grid/meltyLines.js";
+import { QUANTUM_GRID_META } from "./effects/grid/quantumGrid.js";
+import { NEON_GRID_TRAIL_META } from "./effects/grid/neonGridTrail.js";
+import { PARTICLES_META } from "./effects/particle/particles.js";
+import { PARTICLE_HOVER_META } from "./effects/particle/particleHover.js";
+import { STARFIELD_META } from "./effects/particle/starfield.js";
+import { CONSTELLATION_META } from "./effects/particle/constellation.js";
+import { FALLING_PARTICLES_META } from "./effects/particle/fallingParticles.js";
+import { PROXIMITY_MASK_META } from "./effects/cursor/proximityMask.js";
+import { FLOW_FIELD_META } from "./effects/wave/flowField.js";
+import { GOOEY_BLOBS_META } from "./effects/shader/gooeyBlobs.js";
+import { CONTOUR_LINES_META } from "./effects/grid/contourLines.js";
+import { GEOMETRIC_VECTORS_META } from "./effects/grid/geometricVectors.js";
+import { SVG_WAVE_META } from "./effects/wave/svgWave.js";
+import { SVG_COLOR_WAVE_META } from "./effects/wave/svgColorWave.js";
+import { MOUNTAINS_META } from "./effects/wave/mountains.js";
+import { DRAWING_LINES_META } from "./effects/wave/drawingLines.js";
+import { CINEMATIC_REVEAL_META } from "./effects/scroll/cinematicReveal.js";
+import { SCROLL_COLOR_META } from "./effects/scroll/scrollColor.js";
+import { SCROLL_MORPH_META } from "./effects/scroll/scrollMorph.js";
+import { SCROLL_TIMELINE_META } from "./effects/scroll/scrollTimeline.js";
+import { PARALLAX_META } from "./effects/scroll/parallax.js";
+import { VIDEO_SCRUB_META } from "./effects/scroll/videoScrub.js";
+import { HALFTONE_META } from "./effects/texture/halftone.js";
+import { VHS_STATIC_META } from "./effects/glitch/vhsStatic.js";
+import { DITHER_WAVE_META } from "./effects/glitch/ditherWave.js";
+import { SHADER_RIPPLES_META } from "./effects/shader/shaderRipples.js";
+import { SHADER_LINES_META } from "./effects/shader/shaderLines.js";
+import { WAVE_DISTORTION_META } from "./effects/shader/waveDistortion.js";
+import { ANIMATED_GRADIENT_META } from "./effects/shader/animatedGradient.js";
+import { GRAIN_GRADIENT_META } from "./effects/shader/grainGradient.js";
+import { SMOOTH_MESH_META } from "./effects/shader/smoothMesh.js";
+import { PLASMA_GRID_META } from "./effects/shader/plasmaGrid.js";
+import { AETHER_META } from "./effects/shader/aether.js";
+import { CHROMATIC_SINE_META } from "./effects/shader/chromaticSine.js";
+import { LIQUID_META } from "./effects/shader/liquid.js";
+import { MESH_GRADIENT_META } from "./effects/shader/meshGradient.js";
+import { GOD_RAYS_META } from "./effects/shader/godRays.js";
+import { CAUSTICS_META } from "./effects/shader/caustics.js";
+import { LIQUID_SCULPTURE_META } from "./effects/glass/liquidSculpture.js";
+import { WIREFRAME_OCEAN_META } from "./effects/wave/wireframeOcean.js";
+import { FLUID_CURSOR_META } from "./effects/cursor/fluidCursor.js";
+import { WATER_RIPPLE_META } from "./effects/cursor/waterRipple.js";
+// metadata only: the effects themselves live in @sharedex/ui/three
+import { CHROME_META, GLASS_SHAPES_META, LIQUID_GLASS_META, NEON_TUBES_META, SPECTRAL_GHOST_META, WOVEN_LIGHT_META, } from "./effects/three/metas.js";
+import { IMAGE_META, VIDEO_META } from "./effects/media/media.js";
+/** Effects, in atlas category order. */
+export const BACKGROUND_EFFECTS = [
+    // texture
+    FILM_GRAIN_META,
+    FOGGY_GLASS_META,
+    FROZEN_GLASS_META,
+    HALFTONE_META,
+    // glitch
+    DIGITAL_GLITCH_META,
+    VHS_STATIC_META,
+    DITHER_WAVE_META,
+    RETRO_SCREEN_META,
+    RGB_SHIFT_META,
+    MATRIX_RAIN_META,
+    CRT_SCANLINES_META,
+    ASCII_ART_META,
+    // glass
+    LIQUID_GLASS_META,
+    GLASS_SHAPES_META,
+    CHROME_META,
+    SPECTRAL_GHOST_META,
+    ISOMETRIC_LAYERS_META,
+    LIQUID_SCULPTURE_META,
+    WOVEN_LIGHT_META,
+    // shader
+    RAINBOW_META,
+    GRADIENT_BARS_META,
+    AURORA_META,
+    IRIDESCENT_META,
+    GOOEY_BLOBS_META,
+    SHADER_RIPPLES_META,
+    SHADER_LINES_META,
+    WAVE_DISTORTION_META,
+    ANIMATED_GRADIENT_META,
+    GRAIN_GRADIENT_META,
+    SMOOTH_MESH_META,
+    PLASMA_GRID_META,
+    AETHER_META,
+    CHROMATIC_SINE_META,
+    LIQUID_META,
+    MESH_GRADIENT_META,
+    GOD_RAYS_META,
+    CAUSTICS_META,
+    // grid
+    GRADIENT_GRID_META,
+    TRIANGLE_GRID_META,
+    GRID_HOVER_META,
+    FADING_GRID_META,
+    MORPH_GRID_META,
+    LAYERED_GRID_CARDS_META,
+    MELTY_LINES_META,
+    DATA_GRID_META,
+    GRID_HERO_META,
+    ANIMATED_GRID_META,
+    QUANTUM_GRID_META,
+    NEON_GRID_TRAIL_META,
+    DOT_PATTERN_META,
+    MAGNET_LINES_META,
+    CONTOUR_LINES_META,
+    GEOMETRIC_VECTORS_META,
+    // wave
+    WAVY_PATTERN_META,
+    RIPPLES_META,
+    MOIRE_DOTS_META,
+    LIQUID_WAVE_META,
+    FLOW_FIELD_META,
+    SVG_WAVE_META,
+    SVG_COLOR_WAVE_META,
+    MOUNTAINS_META,
+    DRAWING_LINES_META,
+    WIREFRAME_OCEAN_META,
+    // particle
+    PARTICLE_ORB_META,
+    PARTICLES_META,
+    PARTICLE_HOVER_META,
+    STARFIELD_META,
+    CONSTELLATION_META,
+    FALLING_PARTICLES_META,
+    CURSOR_DOTS_META,
+    BOKEH_META,
+    METEORS_META,
+    // cursor
+    CURSOR_GLOW_META,
+    PROXIMITY_MASK_META,
+    NEON_TUBES_META,
+    FLUID_CURSOR_META,
+    WATER_RIPPLE_META,
+    // scroll
+    CINEMATIC_REVEAL_META,
+    SCROLL_COLOR_META,
+    SCROLL_MORPH_META,
+    SCROLL_TIMELINE_META,
+    PARALLAX_META,
+    VIDEO_SCRUB_META,
+    // pattern
+    CIRCLES_PATTERN_META,
+    DIAMONDS_PATTERN_META,
+    SCALES_PATTERN_META,
+    LEATHER_PATTERN_META,
+    STRANGE_PATTERN_META,
+];
+/** The two slots that take the consumer's own file. */
+export const BACKGROUND_SLOTS = [IMAGE_META, VIDEO_META];

package/dist/backgrounds/runtime/clock.d.ts

@@ -0,0 +1,8 @@
+/** Called once per frame with the time since the last frame, in ms. */
+export type FrameListener = (deltaMs: number, nowMs: number) => void;
+export declare function onFrame(listener: FrameListener): () => void;
+/**
+ * Wraps a listener so it runs at most `fps` times a second (0 = every frame),
+ * passing the time accumulated since its last run.
+ */
+export declare function capped(fps: number, listener: FrameListener): FrameListener;

package/dist/backgrounds/runtime/clock.js

@@ -0,0 +1,43 @@
+// ---------------------------------------------------------------------------
+// One frame loop for every JS background on the page, riding motion's own
+// frame loop (as the carousel's autoplay does), so backgrounds and carousels
+// share a single requestAnimationFrame. A layer subscribes only while it is
+// visible and animating; with no subscribers nothing is scheduled at all.
+// ---------------------------------------------------------------------------
+import { cancelFrame, frame } from "motion/react";
+const listeners = new Set();
+function tick(data) {
+    // A tab coming back from the background reports one huge delta; cap it so
+    // nothing jumps across the screen.
+    const delta = Math.min(data.delta, 50);
+    for (const listener of listeners)
+        listener(delta, data.timestamp);
+}
+export function onFrame(listener) {
+    if (listeners.size === 0)
+        frame.update(tick, true);
+    listeners.add(listener);
+    return () => {
+        listeners.delete(listener);
+        if (listeners.size === 0)
+            cancelFrame(tick);
+    };
+}
+/**
+ * Wraps a listener so it runs at most `fps` times a second (0 = every frame),
+ * passing the time accumulated since its last run.
+ */
+export function capped(fps, listener) {
+    if (fps <= 0)
+        return listener;
+    const step = 1000 / fps;
+    let acc = 0;
+    return (delta, now) => {
+        acc += delta;
+        if (acc < step)
+            return;
+        const elapsed = acc;
+        acc %= step;
+        listener(elapsed, now);
+    };
+}

package/dist/backgrounds/runtime/color.d.ts

@@ -0,0 +1,22 @@
+import type { Rgb } from "../types.js";
+export type Rgba = Rgb;
+/** Parses `rgb(…)` / `rgba(…)` in both comma and space syntax. Null for anything else. */
+export declare function parseRgb(css: string): Rgba | null;
+/** A canvas fill string, with the colour's own alpha multiplied by `alpha`. */
+export declare function rgba(c: Rgba, alpha?: number): string;
+/**
+ * Resolves any CSS colour, var() included, in the context of `host` (so the
+ * host's theme applies). The browser computes it on a hidden probe; anything
+ * it does not report as rgb() (oklch, color(srgb …)) goes through a 1×1 canvas,
+ * which returns sRGB bytes for every colour syntax the browser knows.
+ */
+export declare function createColorResolver(host: HTMLElement): {
+    resolve(css: string): Rgba;
+    dispose(): void;
+};
+/**
+ * Calls `listener` when the theme may have changed: the colour scheme, or the
+ * `class` / `data-theme` / `style` of <html> (how sites switch themes).
+ * Returns the stop function.
+ */
+export declare function watchTheme(listener: () => void): () => void;