@sharedex/ui 0.0.0-stage → 0.10.0

package/dist/backgrounds/effects/three/spectralGhost.schema.js

@@ -0,0 +1,15 @@
+import { defineSchema } from "../../../schema/define.js";
+import { layerFields, speedField, seedField, colorsField } from "../../../schema/common.js";
+export const SPECTRAL_GHOST_SCHEMA = defineSchema()({
+    id: "spectral-ghost",
+    family: "background",
+    factory: "spectralGhost",
+    entry: "@sharedex/ui/three",
+    fields: {
+        ...layerFields(),
+        speed: speedField(),
+        bloom: { kind: "number", label: "Bloom", min: 0, max: 3, step: 0.05, default: 1.1 },
+        colors: { ...colorsField(["var(--color-sx-accent)", "color-mix(in oklab, var(--color-sx-accent) 55%, var(--color-sx-primary))", "color-mix(in oklab, var(--color-sx-accent) 50%, var(--color-sx-secondary))"], 1, 3), help: "The rim shifts through them." },
+        seed: seedField(),
+    },
+});

package/dist/backgrounds/effects/three/stage.d.ts

@@ -0,0 +1,13 @@
+import type { GpuFrame } from "../../types.js";
+import { THREE, type ThreeContext } from "./kit.js";
+export interface Stage {
+    readonly camera: THREE.PerspectiveCamera;
+    /** Put the shapes in here: it leans toward the pointer. */
+    readonly group: THREE.Group;
+    update(f: GpuFrame): void;
+    resize(width: number, height: number): void;
+}
+export declare function stage(ctx: ThreeContext, opts: {
+    readonly backdrop: boolean;
+    readonly lean: number;
+}): Stage;

package/dist/backgrounds/effects/three/stage.js

@@ -0,0 +1,45 @@
+// The set the glass and chrome effects share: a camera, the procedural room
+// for reflections, an optional painted backdrop for glass to refract (glass
+// can only bend what is in the scene, not the page behind the canvas), and a
+// group that leans toward the pointer.
+import { THREE, aimPoint, backdropTexture, roomEnvironment } from "./kit.js";
+const DISTANCE = 6;
+const BACKDROP_Z = -3;
+export function stage(ctx, opts) {
+    const { renderer, scene, frame } = ctx;
+    const camera = new THREE.PerspectiveCamera(35, frame.width / frame.height, 0.1, 50);
+    camera.position.set(0, 0, DISTANCE);
+    scene.environment = roomEnvironment(renderer);
+    const group = new THREE.Group();
+    scene.add(group);
+    let back = null;
+    const paint = opts.backdrop ? backdropTexture() : null;
+    if (paint) {
+        paint.paint(frame.colors);
+        back = new THREE.Mesh(new THREE.PlaneGeometry(1, 1), new THREE.MeshBasicMaterial({ map: paint.texture }));
+        back.position.z = BACKDROP_Z;
+        scene.add(back);
+    }
+    const resize = (width, height) => {
+        camera.aspect = width / height;
+        camera.updateProjectionMatrix();
+        if (back) {
+            // exactly fill the view at the backdrop's distance
+            const h = 2 * (DISTANCE - BACKDROP_Z) * Math.tan(THREE.MathUtils.degToRad(camera.fov / 2));
+            back.scale.set(h * camera.aspect * 1.05, h * 1.05, 1);
+        }
+    };
+    resize(frame.width, frame.height);
+    return {
+        camera,
+        group,
+        resize,
+        update(f) {
+            paint?.paint(f.colors);
+            const [x, y] = aimPoint(f);
+            // ease toward the target lean, so a jumpy pointer still turns smoothly
+            group.rotation.y += ((x - 0.5) * opts.lean - group.rotation.y) * 0.06;
+            group.rotation.x += (-(y - 0.5) * opts.lean * 0.7 - group.rotation.x) * 0.06;
+        },
+    };
+}

package/dist/backgrounds/effects/three/wovenLight.d.ts

@@ -0,0 +1,19 @@
+import type { LayerOptions, WebglEffect } from "../../types.js";
+export interface WovenLightOptions extends LayerOptions {
+    readonly speed?: number;
+    /** Particles (500–20 000). Default 6 000; touch screens get at most 2 500. */
+    readonly count?: number;
+    /** Particle size in px. */
+    readonly size?: number;
+    /** Three colours: warp threads, weft threads, the glint where they cross. */
+    readonly colors?: readonly string[];
+    readonly seed?: number;
+}
+export declare const WOVEN_MAX = 20000;
+/**
+ * Per particle: [direction (0 warp / 1 weft), thread position across (−1–1),
+ * start along the thread (0–1), random]. Pure.
+ */
+export declare function wovenParticles(count: number, random: () => number): Float32Array;
+/** Thousands of light particles flowing along a woven pattern, parting around the cursor. */
+export declare function wovenLight(options?: WovenLightOptions): WebglEffect;

package/dist/backgrounds/effects/three/wovenLight.js

@@ -0,0 +1,131 @@
+import { defineGpuEffect } from "../define.js";
+import { SX_GLOW, slots, stillFallback } from "../shaderKit.js";
+import { WOVEN_LIGHT_META } from "./metas.js";
+import { THREE, aimPoint, colour, threeProgram } from "./kit.js";
+export const WOVEN_MAX = 20000;
+const COARSE_MAX = 2500;
+const WARP = 22;
+const WEFT = 13;
+/**
+ * Per particle: [direction (0 warp / 1 weft), thread position across (−1–1),
+ * start along the thread (0–1), random]. Pure.
+ */
+export function wovenParticles(count, random) {
+    const n = Math.min(WOVEN_MAX, Math.max(500, Math.round(count)));
+    const data = new Float32Array(n * 4);
+    for (let i = 0; i < n; i++) {
+        const weft = random() < WEFT / (WARP + WEFT) ? 1 : 0;
+        const threads = weft ? WEFT : WARP;
+        data[i * 4] = weft;
+        data[i * 4 + 1] = ((Math.floor(random() * threads) + 0.5) / threads) * 2 - 1;
+        data[i * 4 + 2] = random();
+        data[i * 4 + 3] = random();
+    }
+    return data;
+}
+// Light particles stream along two sets of threads, vertical (warp) and
+// horizontal (weft), dipping over and under each other like a weave. Near the
+// pointer (or a wandering point) they are pushed aside and brighten. All
+// motion is in the vertex shader; the CPU only updates a few uniforms.
+const VERTEX = `attribute vec4 aThread;
+uniform float uTime;
+uniform float uAspect;
+uniform float uSize;
+uniform float uDpr;
+uniform vec2 uPointer;
+uniform float uPush;
+varying float vWeft;
+varying float vGlow;
+void main() {
+  float along = fract(aThread.z + uTime * (0.015 + aThread.w * 0.025)) * 2.0 - 1.0;
+  vec3 p = aThread.x < 0.5
+    ? vec3(aThread.y * uAspect, along, 0.0)
+    : vec3(along * uAspect, aThread.y, 0.0);
+  float across = aThread.x < 0.5 ? along : along * uAspect;
+  float weave = sin(across * 14.0 + aThread.y * 30.0 + aThread.x * 3.14159);
+  p.z = weave * 0.08;
+  p.xy += 0.02 * vec2(sin(uTime * 0.7 + p.y * 3.0), cos(uTime * 0.6 + p.x * 2.0));
+  vec2 d = p.xy - uPointer;
+  float push = uPush * (1.0 - smoothstep(0.0, 0.4, length(d)));
+  p.xy += normalize(d + 1e-4) * push * 0.2;
+  vWeft = aThread.x;
+  vGlow = 0.3 + 0.5 * (0.5 + 0.5 * weave) + push * 1.5;
+  gl_Position = projectionMatrix * modelViewMatrix * vec4(p, 1.0);
+  gl_PointSize = uSize * uDpr * (0.7 + 0.6 * (0.5 + 0.5 * weave));
+}`;
+const FRAGMENT = `uniform vec3 uWarp;
+uniform vec3 uWeft;
+uniform vec3 uGlint;
+varying float vWeft;
+varying float vGlow;
+void main() {
+  float d = length(gl_PointCoord - 0.5);
+  float a = (1.0 - smoothstep(0.05, 0.5, d)) * min(vGlow, 1.4) * 0.7;
+  vec3 c = mix(mix(uWarp, uWeft, vWeft), uGlint, clamp(vGlow - 0.9, 0.0, 1.0));
+  gl_FragColor = vec4(c * a, a);
+}`;
+/** Thousands of light particles flowing along a woven pattern, parting around the cursor. */
+export function wovenLight(options = {}) {
+    const colors = slots(options.colors, SX_GLOW);
+    const speed = options.speed ?? 1;
+    const size = Math.max(0.5, options.size ?? 2.2);
+    const count = Math.min(WOVEN_MAX, Math.max(500, options.count ?? 6000));
+    return defineGpuEffect(WOVEN_LIGHT_META, threeProgram(({ scene, frame, random, renderer }) => {
+        const aspect = () => frame.width / frame.height;
+        const camera = new THREE.OrthographicCamera(-aspect(), aspect(), 1, -1, -5, 5);
+        const geometry = new THREE.BufferGeometry();
+        geometry.setAttribute("aThread", new THREE.BufferAttribute(wovenParticles(frame.coarse ? Math.min(count, COARSE_MAX) : count, random), 4));
+        // positions come from aThread in the shader; three still wants a position attribute for the draw count
+        geometry.setAttribute("position", new THREE.BufferAttribute(new Float32Array((geometry.getAttribute("aThread").count) * 3), 3));
+        const material = new THREE.ShaderMaterial({
+            vertexShader: VERTEX,
+            fragmentShader: FRAGMENT,
+            uniforms: {
+                uTime: { value: 0 },
+                uAspect: { value: aspect() },
+                uSize: { value: size },
+                uDpr: { value: frame.dpr },
+                uPointer: { value: new THREE.Vector2() },
+                uPush: { value: 0 },
+                uWarp: { value: new THREE.Color() },
+                uWeft: { value: new THREE.Color() },
+                uGlint: { value: new THREE.Color() },
+            },
+            transparent: true,
+            depthTest: false,
+            depthWrite: false,
+            blending: THREE.CustomBlending,
+            blendSrc: THREE.OneFactor,
+            blendDst: THREE.OneFactor,
+        });
+        const points = new THREE.Points(geometry, material);
+        points.frustumCulled = false;
+        scene.add(points);
+        const u = material.uniforms;
+        return {
+            resize(width, height) {
+                const a = width / height;
+                camera.left = -a;
+                camera.right = a;
+                camera.updateProjectionMatrix();
+                u.uAspect.value = a;
+            },
+            render(f) {
+                u.uTime.value = f.time * speed;
+                u.uDpr.value = f.dpr;
+                const [x, y] = aimPoint(f);
+                const a = f.width / f.height;
+                u.uPointer.value.set((x * 2 - 1) * a, y * 2 - 1);
+                // a real pointer pushes harder than the wandering one
+                u.uPush.value += ((f.pointerIn ? 1 : 0.5) - u.uPush.value) * 0.1;
+                colour(f.colors[0], u.uWarp.value);
+                colour(f.colors[1], u.uWeft.value);
+                colour(f.colors[2], u.uGlint.value);
+                renderer.render(scene, camera);
+            },
+        };
+    }), options, {
+        colors,
+        fallback: stillFallback(WOVEN_LIGHT_META, "A still woven grid of soft light lines.", "repeating-linear-gradient(90deg, transparent 0 22px, color-mix(in oklab, var(--sx-bg-c1) 35%, transparent) 22px 24px), repeating-linear-gradient(transparent 0 30px, color-mix(in oklab, var(--sx-bg-c2) 30%, transparent) 30px 32px)", options, colors),
+    });
+}

package/dist/backgrounds/effects/three/wovenLight.schema.d.ts

@@ -0,0 +1 @@
+export declare const WOVEN_LIGHT_SCHEMA: import("../../../schema/types.js").Schema;

package/dist/backgrounds/effects/three/wovenLight.schema.js

@@ -0,0 +1,16 @@
+import { defineSchema } from "../../../schema/define.js";
+import { layerFields, speedField, seedField, colorsField } from "../../../schema/common.js";
+export const WOVEN_LIGHT_SCHEMA = defineSchema()({
+    id: "woven-light",
+    family: "background",
+    factory: "wovenLight",
+    entry: "@sharedex/ui/three",
+    fields: {
+        ...layerFields(),
+        speed: speedField(),
+        count: { kind: "integer", label: "Particles", min: 500, max: 20000, default: 6000, help: "Touch screens get at most 2 500." },
+        size: { kind: "number", label: "Particle size", min: 0.5, max: 8, step: 0.1, unit: "px", default: 2.2 },
+        colors: { ...colorsField(["var(--color-sx-accent)", "color-mix(in oklab, var(--color-sx-accent) 55%, var(--color-sx-primary))", "color-mix(in oklab, var(--color-sx-accent) 50%, var(--color-sx-secondary))"], 1, 3), help: "Warp, weft, and the glint where they cross." },
+        seed: seedField(),
+    },
+});

package/dist/backgrounds/effects/wave/drawingLines.d.ts

@@ -0,0 +1,13 @@
+import type { EffectMeta, LayerOptions, SvgEffect } from "../../types.js";
+export declare const DRAWING_LINES_META: EffectMeta;
+export interface DrawingLinesOptions extends LayerOptions {
+    readonly speed?: number;
+    /** Number of lines (1–24). */
+    readonly count?: number;
+    /** Stroke width in px at a 1600 px wide layer (lines scale with the layer). */
+    readonly width?: number;
+    readonly colors?: readonly string[];
+    readonly seed?: number;
+}
+/** Flowing lines that draw themselves across the layer, one after another. */
+export declare function drawingLines(options?: DrawingLinesOptions): SvgEffect;

package/dist/backgrounds/effects/wave/drawingLines.js

@@ -0,0 +1,70 @@
+import { between, rng, round } from "../../runtime/rng.js";
+import { defineSvgEffect, duration } from "../define.js";
+import { paletteRef, paletteVars } from "../palette.js";
+import { smoothPath } from "../svgKit.js";
+export const DRAWING_LINES_META = {
+    id: "drawing-lines",
+    label: "Animated SVG Background (drawing lines)",
+    category: "wave",
+    family: "svg",
+    cost: { kb: "~1 KB (CSS keyframes, no Motion)", cpu: 1, gpu: 1 },
+    tier: "all",
+    note: "Plain CSS keyframes on stroke-dashoffset instead of Motion: ~1 KB.",
+};
+const W = 1600;
+const H = 900;
+// Every line has pathLength="1", so a dash of 1 is the whole line whatever its
+// real length. Moving the dash offset from 1 to 0 draws it from start to end;
+// then it holds and fades, and starts again on its own staggered clock.
+// stroke-dashoffset is not a transform, but a dozen thin strokes repaint for
+// almost nothing (the atlas's CPU 1). In RTL the drawing mirrors, so lines
+// are drawn from the reading start.
+const CSS = `@layer components {
+  :where([data-sx-bg="drawing-lines"] [data-sx-bg-part="line"]) {
+    fill: none;
+    stroke: var(--c);
+    stroke-width: var(--sx-bg-width);
+    stroke-linecap: round;
+    stroke-dasharray: 1 1;
+    stroke-dashoffset: 1;
+    animation: sx-bg-draw-line ${duration("var(--d)")} ease-in-out var(--delay) infinite;
+  }
+  :where([dir="rtl"] [data-sx-bg="drawing-lines"] [data-sx-bg-part="svg"]) {
+    scale: -1 1;
+  }
+  @keyframes sx-bg-draw-line {
+    0% { stroke-dashoffset: 1; opacity: 1; }
+    50% { stroke-dashoffset: 0; opacity: 1; }
+    80% { stroke-dashoffset: 0; opacity: 1; }
+    100% { stroke-dashoffset: 0; opacity: 0; }
+  }
+}`;
+/** Flowing lines that draw themselves across the layer, one after another. */
+export function drawingLines(options = {}) {
+    const r = rng(options.seed ?? 9);
+    const count = Math.min(24, Math.max(1, Math.round(options.count ?? 9)));
+    const palette = paletteVars(options.colors);
+    const lines = [];
+    for (let i = 0; i < count; i++) {
+        // a meandering line from beyond the start edge to beyond the end edge
+        const steps = 6;
+        let y = between(r, 0.1, 0.9) * H;
+        const pts = [];
+        for (let k = 0; k <= steps; k++) {
+            pts.push([-60 + ((W + 120) * k) / steps, y]);
+            y = Math.min(H * 0.95, Math.max(H * 0.05, y + between(r, -0.22, 0.22) * H));
+        }
+        const d = round(between(r, 7, 13), 1);
+        lines.push({
+            tag: "path",
+            part: "line",
+            attrs: { d: smoothPath(pts), pathLength: 1 },
+            vars: {
+                "--c": paletteRef(i, palette.count),
+                "--d": `${d}s`,
+                "--delay": `${-round((d * i) / count + between(r, 0, 1), 1)}s`,
+            },
+        });
+    }
+    return defineSvgEffect(DRAWING_LINES_META, CSS, { viewBox: `0 0 ${W} ${H}`, preserveAspectRatio: "xMidYMid slice", children: lines }, options, { vars: { ...palette.vars, "--sx-bg-width": `${options.width ?? 2.5}px` } });
+}

package/dist/backgrounds/effects/wave/drawingLines.schema.d.ts

@@ -0,0 +1 @@
+export declare const DRAWING_LINES_SCHEMA: import("../../../schema/types.js").Schema;

package/dist/backgrounds/effects/wave/drawingLines.schema.js

@@ -0,0 +1,15 @@
+import { defineSchema } from "../../../schema/define.js";
+import { layerFields, speedField, seedField, colorsField } from "../../../schema/common.js";
+export const DRAWING_LINES_SCHEMA = defineSchema()({
+    id: "drawing-lines",
+    family: "background",
+    factory: "drawingLines",
+    fields: {
+        ...layerFields(),
+        speed: speedField(),
+        count: { kind: "integer", label: "Lines", min: 1, max: 24, default: 9 },
+        width: { kind: "number", label: "Stroke width", min: 0.5, max: 10, step: 0.25, unit: "px", default: 2.5, help: "At a 1600 px wide layer." },
+        colors: { ...colorsField(["var(--color-sx-accent)", "color-mix(in oklab, var(--color-sx-accent) 55%, var(--color-sx-primary))", "color-mix(in oklab, var(--color-sx-accent) 60%, var(--color-sx-secondary))"], 1, 6) },
+        seed: seedField(9),
+    },
+});

package/dist/backgrounds/effects/wave/flowField.d.ts

@@ -0,0 +1,15 @@
+import type { CanvasEffect, EffectMeta, LayerOptions } from "../../types.js";
+export declare const FLOW_FIELD_META: EffectMeta;
+export interface FlowFieldOptions extends LayerOptions {
+    /** Number of tracers; touch screens get at most 450. */
+    readonly count?: number;
+    readonly speed?: number;
+    /** Zoom of the field: smaller = broader currents. */
+    readonly scale?: number;
+    /** 0–1, how fast trails fade. */
+    readonly fade?: number;
+    readonly colors?: readonly string[];
+    readonly seed?: number;
+}
+/** Streamlines tracing an invisible current that slowly changes. */
+export declare function flowField(options?: FlowFieldOptions): CanvasEffect;

package/dist/backgrounds/effects/wave/flowField.js

@@ -0,0 +1,93 @@
+import { fbm, noise3 } from "../../runtime/noise.js";
+import { defineCanvasEffect, defineCssEffect, liteMeta } from "../define.js";
+import { budget, fadeTrail, paint, rand, TAU } from "../canvasKit.js";
+export const FLOW_FIELD_META = {
+    id: "flow-field",
+    label: "Flow field lines",
+    category: "wave",
+    family: "canvas",
+    cost: { kb: "3–6 KB", cpu: 3, gpu: 1 },
+    tier: "mid",
+    note: "Thousands of line segments per frame on the CPU.",
+};
+const FLOW_LITE_META = liteMeta({ ...FLOW_FIELD_META, family: "css" }, "Still streamlines from two crossing line screens, no simulation.");
+function respawn(t, random, width, height) {
+    t.x = random() * width;
+    t.y = random() * height;
+    t.px = t.x;
+    t.py = t.y;
+    t.life = rand(random, 1500, 5000);
+    t.c = Math.floor(random() * 3);
+}
+// Tracers follow a slowly changing angle field (noise turned into a
+// direction) and draw a short segment each frame. Old segments fade to
+// transparent, so the paths read as flowing streamlines.
+function program(count, speed, scale, fade, seed) {
+    return {
+        init(env, random) {
+            const n = budget(count, 900, 2500, 450, env);
+            const tracers = Array.from({ length: n }, () => {
+                const t = { x: 0, y: 0, px: 0, py: 0, life: 0, c: 0 };
+                respawn(t, random, env.width, env.height);
+                return t;
+            });
+            return { random, noise: noise3(seed), time: 0, tracers };
+        },
+        step(state, deltaMs, _pointer, env) {
+            state.time += deltaMs;
+            const z = state.time * 0.00006;
+            const move = 55 * speed * (deltaMs / 1000);
+            for (const t of state.tracers) {
+                const angle = fbm(state.noise, t.x * scale, t.y * scale, z) * TAU * 1.5;
+                t.px = t.x;
+                t.py = t.y;
+                t.x += Math.cos(angle) * move;
+                t.y += Math.sin(angle) * move;
+                t.life -= deltaMs;
+                if (t.life <= 0 || t.x < 0 || t.y < 0 || t.x > env.width || t.y > env.height) {
+                    respawn(t, state.random, env.width, env.height);
+                }
+            }
+        },
+        draw(ctx, state, env) {
+            fadeTrail(ctx, env, fade);
+            ctx.lineWidth = 1;
+            for (let c = 0; c < 3; c++) {
+                ctx.strokeStyle = paint(env, c, 0.55);
+                ctx.beginPath();
+                for (const t of state.tracers) {
+                    if (t.c !== c)
+                        continue;
+                    ctx.moveTo(t.px, t.py);
+                    ctx.lineTo(t.x, t.y);
+                }
+                ctx.stroke();
+            }
+        },
+    };
+}
+const LITE_CSS = `@layer components {
+  :where([data-sx-bg="flow-field-lite"]) {
+    background:
+      repeating-linear-gradient(118deg, var(--sx-bg-line) 0 1px, transparent 1px 13px),
+      repeating-linear-gradient(104deg, color-mix(in oklab, var(--sx-bg-line) 60%, transparent) 0 1px, transparent 1px 19px);
+  }
+}`;
+/** Streamlines tracing an invisible current that slowly changes. */
+export function flowField(options = {}) {
+    const colors = options.colors ?? [
+        "var(--color-sx-accent)",
+        "color-mix(in oklab, var(--color-sx-accent) 55%, var(--color-sx-primary))",
+        "color-mix(in oklab, var(--color-sx-muted) 70%, transparent)",
+    ];
+    return defineCanvasEffect(FLOW_FIELD_META, program(options.count, options.speed ?? 1, options.scale ?? 0.0028, options.fade ?? 0.06, options.seed ?? 8), options, {
+        colors,
+        fallback: defineCssEffect(FLOW_LITE_META, LITE_CSS, options, {
+            vars: {
+                "--sx-bg-line": `color-mix(in oklab, ${colors[0] ?? "currentColor"} 45%, transparent)`,
+                // a default fade; an explicit `mask` option replaces it
+                "--sx-bg-mask": "radial-gradient(ellipse at 40% 50%, black 20%, transparent 75%)",
+            },
+        }),
+    });
+}

package/dist/backgrounds/effects/wave/flowField.schema.d.ts

@@ -0,0 +1 @@
+export declare const FLOW_FIELD_SCHEMA: import("../../../schema/types.js").Schema;

package/dist/backgrounds/effects/wave/flowField.schema.js

@@ -0,0 +1,16 @@
+import { defineSchema } from "../../../schema/define.js";
+import { layerFields, speedField, seedField, colorsField } from "../../../schema/common.js";
+export const FLOW_FIELD_SCHEMA = defineSchema()({
+    id: "flow-field",
+    family: "background",
+    factory: "flowField",
+    fields: {
+        ...layerFields(),
+        count: { kind: "integer", label: "Tracers", min: 50, max: 1500, autoValue: 600, autoNote: "fits the screen; at most 450 on touch" },
+        speed: speedField(),
+        scale: { kind: "number", label: "Current size", min: 0.0005, max: 0.01, step: 0.0001, default: 0.0028, help: "Smaller = broader currents." },
+        fade: { kind: "number", label: "Trail fade", min: 0, max: 1, step: 0.01, default: 0.06 },
+        colors: { ...colorsField(["var(--color-sx-accent)", "color-mix(in oklab, var(--color-sx-accent) 55%, var(--color-sx-primary))", "color-mix(in oklab, var(--color-sx-muted) 70%, transparent)"], 1, 6) },
+        seed: seedField(),
+    },
+});

package/dist/backgrounds/effects/wave/liquidWave.d.ts

@@ -0,0 +1,10 @@
+import type { CssEffect, EffectMeta, LayerOptions } from "../../types.js";
+export declare const LIQUID_WAVE_META: EffectMeta;
+export interface LiquidWaveOptions extends LayerOptions {
+    readonly speed?: number;
+    /** Liquid level from the top, in % of the layer height. */
+    readonly level?: number;
+    readonly colors?: readonly string[];
+}
+/** A liquid surface that sloshes gently, filling the layer below a level. */
+export declare function liquidWave(options?: LiquidWaveOptions): CssEffect;

package/dist/backgrounds/effects/wave/liquidWave.js

@@ -0,0 +1,50 @@
+import { defineCssEffect, duration } from "../define.js";
+import { paletteRef, paletteVars } from "../palette.js";
+export const LIQUID_WAVE_META = {
+    id: "liquid-wave",
+    label: "Pure CSS Liquid Wave Illusion",
+    category: "wave",
+    family: "css",
+    cost: { kb: "<1 KB", cpu: 1, gpu: 1 },
+    tier: "all",
+};
+// The classic illusion: huge rounded squares spinning with their top edge at
+// the liquid level. A rounded square's edge rises and falls as it turns, so
+// the surface seems to slosh. Three of them at different speeds and shades.
+// At 400cqmax with 45% rounding the visible top is nearly flat (it sags about
+// 2.5cqmax across the layer) and a passing corner lifts it about 8cqmax.
+const CSS = `@layer components {
+  :where([data-sx-bg="liquid-wave"] [data-sx-bg-part="body"]) {
+    position: absolute;
+    inset-inline-start: 50%;
+    inset-block-start: var(--sx-bg-level);
+    inline-size: 400cqmax;
+    aspect-ratio: 1;
+    margin-inline-start: -200cqmax;
+    margin-block-start: var(--off);
+    border-radius: 45%;
+    background: var(--c);
+    opacity: var(--o);
+    animation: sx-bg-liquid ${duration("var(--d)")} linear infinite;
+  }
+  @keyframes sx-bg-liquid {
+    to { transform: rotate(360deg); }
+  }
+}`;
+const BODIES = [
+    { off: "0cqmax", o: 0.35, d: "14s" },
+    { off: "1.5cqmax", o: 0.5, d: "19s" },
+    { off: "3cqmax", o: 0.85, d: "25s" },
+];
+/** A liquid surface that sloshes gently, filling the layer below a level. */
+export function liquidWave(options = {}) {
+    const palette = paletteVars(options.colors);
+    const nodes = BODIES.map((b, i) => ({
+        part: "body",
+        vars: { "--off": b.off, "--o": b.o, "--d": b.d, "--c": paletteRef(i, palette.count) },
+    }));
+    return defineCssEffect(LIQUID_WAVE_META, CSS, options, {
+        vars: { ...palette.vars, "--sx-bg-level": `${options.level ?? 55}%` },
+        nodes,
+    });
+}

package/dist/backgrounds/effects/wave/liquidWave.schema.d.ts

@@ -0,0 +1 @@
+export declare const LIQUID_WAVE_SCHEMA: import("../../../schema/types.js").Schema;

package/dist/backgrounds/effects/wave/liquidWave.schema.js

@@ -0,0 +1,13 @@
+import { defineSchema } from "../../../schema/define.js";
+import { layerFields, speedField, colorsField } from "../../../schema/common.js";
+export const LIQUID_WAVE_SCHEMA = defineSchema()({
+    id: "liquid-wave",
+    family: "background",
+    factory: "liquidWave",
+    fields: {
+        ...layerFields(),
+        speed: speedField(),
+        level: { kind: "number", label: "Level", min: 5, max: 95, step: 1, unit: "%", default: 55, help: "From the top." },
+        colors: { ...colorsField(["var(--color-sx-accent)", "color-mix(in oklab, var(--color-sx-accent) 55%, var(--color-sx-primary))", "color-mix(in oklab, var(--color-sx-accent) 60%, var(--color-sx-secondary))"], 1, 6) },
+    },
+});

package/dist/backgrounds/effects/wave/moireDots.d.ts

@@ -0,0 +1,12 @@
+import type { CssEffect, EffectMeta, LayerOptions } from "../../types.js";
+export declare const MOIRE_DOTS_META: EffectMeta;
+export interface MoireDotsOptions extends LayerOptions {
+    readonly speed?: number;
+    /** Dot radius in px. */
+    readonly size?: number;
+    /** Distance between dots in px. */
+    readonly gap?: number;
+    readonly color?: string;
+}
+/** Moiré waves rippling out of two overlapping dot screens. */
+export declare function moireDots(options?: MoireDotsOptions): CssEffect;

package/dist/backgrounds/effects/wave/moireDots.js

@@ -0,0 +1,45 @@
+import { defineCssEffect, duration, liteMeta } from "../define.js";
+export const MOIRE_DOTS_META = {
+    id: "moire-dots",
+    label: "Pure CSS Moiré Wave Dots",
+    category: "wave",
+    family: "css",
+    cost: { kb: "1–3 KB", cpu: 2, gpu: 2 },
+    tier: "mid",
+    note: "Hundreds of animated elements add up on phones.",
+};
+const MOIRE_LITE_META = liteMeta(MOIRE_DOTS_META, "The same two dot screens, still: the interference pattern without motion.");
+// Two identical dot screens, one turning and breathing very slightly over the
+// other: the interference between them draws the moving waves. Two layers of
+// gradients instead of hundreds of dot elements. Both overhang by half the
+// layer, which covers the corners at any small rotation.
+const sheet = (id, live) => `@layer components {
+  :where([data-sx-bg="${id}"])::before,
+  :where([data-sx-bg="${id}"])::after {
+    content: "";
+    position: absolute;
+    inset: -50%;
+    background-image: radial-gradient(circle at center, var(--sx-bg-color) var(--sx-bg-dot), transparent calc(var(--sx-bg-dot) + 0.6px));
+    background-size: var(--sx-bg-gap) var(--sx-bg-gap);
+    background-position: center;
+  }
+  :where([data-sx-bg="${id}"])::after {
+    ${live ? `animation: sx-bg-moire ${duration("20s")} ease-in-out infinite alternate;` : "transform: rotate(4deg) scale(1.03);"}
+  }
+  ${live ? `@keyframes sx-bg-moire {
+    from { transform: rotate(2deg) scale(1.01); }
+    to { transform: rotate(8deg) scale(1.05); }
+  }` : ""}
+}`;
+/** Moiré waves rippling out of two overlapping dot screens. */
+export function moireDots(options = {}) {
+    const vars = {
+        "--sx-bg-dot": `${options.size ?? 2}px`,
+        "--sx-bg-gap": `${options.gap ?? 9}px`,
+        "--sx-bg-color": options.color ?? "color-mix(in oklab, var(--color-sx-muted) 55%, transparent)",
+    };
+    return defineCssEffect(MOIRE_DOTS_META, sheet(MOIRE_DOTS_META.id, true), options, {
+        vars,
+        fallback: defineCssEffect(MOIRE_LITE_META, sheet(MOIRE_LITE_META.id, false), options, { vars }),
+    });
+}

package/dist/backgrounds/effects/wave/moireDots.schema.d.ts

@@ -0,0 +1 @@
+export declare const MOIRE_DOTS_SCHEMA: import("../../../schema/types.js").Schema;

package/dist/backgrounds/effects/wave/moireDots.schema.js

@@ -0,0 +1,14 @@
+import { defineSchema } from "../../../schema/define.js";
+import { layerFields, speedField } from "../../../schema/common.js";
+export const MOIRE_DOTS_SCHEMA = defineSchema()({
+    id: "moire-dots",
+    family: "background",
+    factory: "moireDots",
+    fields: {
+        ...layerFields(),
+        speed: speedField(),
+        size: { kind: "number", label: "Dot radius", min: 0.5, max: 8, step: 0.1, unit: "px", default: 2 },
+        gap: { kind: "number", label: "Spacing", min: 3, max: 40, step: 0.5, unit: "px", default: 9 },
+        color: { kind: "color", label: "Colour", default: "color-mix(in oklab, var(--color-sx-muted) 55%, transparent)" },
+    },
+});