@sharedex/ui 0.0.0-stage → 0.10.0

package/dist/backgrounds/effects/cursor/waterRipple.d.ts

@@ -0,0 +1,30 @@
+import type { EffectMeta, LayerOptions, WebglEffect } from "../../types.js";
+export declare const WATER_RIPPLE_META: EffectMeta;
+export interface WaterRippleOptions extends LayerOptions {
+    /** Your image under the water (same origin, or served with CORS). Default: pool tiles in theme colours. */
+    readonly src?: string;
+    /** Ripple strength of a tap, 0–1. */
+    readonly strength?: number;
+    /** Leave small ripples behind the moving pointer. Default true. */
+    readonly trail?: boolean;
+    /** Drops fall on their own while nobody interacts. Default true. */
+    readonly rain?: boolean;
+    /** How fast ripples die out, 0 (never) to 1 (at once). */
+    readonly damping?: number;
+    /** Pool tiles per layer height (the default floor). */
+    readonly tiles?: number;
+    /** Three colours: water, tile lines, highlights. */
+    readonly colors?: readonly string[];
+    readonly seed?: number;
+}
+/** A drop for the shader: centre (0–1), radius (fraction of the height), strength. */
+export type Drop = readonly [x: number, y: number, radius: number, strength: number];
+/** The simulation grid for a layer of `width` × `height`: `long` cells on the longer side. Pure. */
+export declare function rippleGrid(width: number, height: number, long: number): readonly [number, number];
+export declare const WATER_RIPPLE_SHADERS: {
+    readonly vertex: "attribute vec2 a_pos;\nvarying vec2 v_uv;\nvoid main() {\n  v_uv = a_pos * 0.5 + 0.5;\n  gl_Position = vec4(a_pos, 0.0, 1.0);\n}";
+    readonly step: "precision highp float;\nvarying vec2 v_uv;\nuniform sampler2D u_state;\nuniform vec2 u_texel;\nuniform float u_damping;\nuniform float u_aspect;\nuniform vec4 u_drops[8];\nuniform float u_dropCount;\n\nvec2 enc(float h) {\n  float v = clamp(h * 0.5 + 0.5, 0.0, 1.0) * 255.0;\n  float hi = floor(v);\n  return vec2(hi / 255.0, v - hi);\n}\nfloat dec(vec2 c) {\n  return (floor(c.x * 255.0 + 0.5) + c.y) / 255.0 * 2.0 - 1.0;\n}\n\nvoid main() {\n  vec4 s = texture2D(u_state, v_uv);\n  float now = dec(s.xy);\n  float before = dec(s.zw);\n  float sum = dec(texture2D(u_state, v_uv + vec2(u_texel.x, 0.0)).xy)\n            + dec(texture2D(u_state, v_uv - vec2(u_texel.x, 0.0)).xy)\n            + dec(texture2D(u_state, v_uv + vec2(0.0, u_texel.y)).xy)\n            + dec(texture2D(u_state, v_uv - vec2(0.0, u_texel.y)).xy);\n  float next = (sum * 0.5 - before) * u_damping;\n  for (int i = 0; i < 8; i++) {\n    if (float(i) >= u_dropCount) break;\n    vec4 d = u_drops[i];\n    float r = length((v_uv - d.xy) * vec2(u_aspect, 1.0)) / d.z;\n    if (r < 1.0) next += d.w * (0.5 + 0.5 * cos(r * 3.14159));\n  }\n  gl_FragColor = vec4(enc(next), enc(now));\n}";
+    readonly display: "precision highp float;\nvarying vec2 v_uv;\nuniform sampler2D u_state;\nuniform sampler2D u_image;\nuniform vec2 u_texel;\nuniform float u_aspect;\nuniform float u_imageAspect;\nuniform float u_hasImage;\nuniform float u_tiles;\nuniform vec4 u_c0;\nuniform vec4 u_c1;\nuniform vec4 u_c2;\n\nvec2 enc(float h) {\n  float v = clamp(h * 0.5 + 0.5, 0.0, 1.0) * 255.0;\n  float hi = floor(v);\n  return vec2(hi / 255.0, v - hi);\n}\nfloat dec(vec2 c) {\n  return (floor(c.x * 255.0 + 0.5) + c.y) / 255.0 * 2.0 - 1.0;\n}\n\nvoid main() {\n  float hl = dec(texture2D(u_state, v_uv - vec2(u_texel.x, 0.0)).xy);\n  float hr = dec(texture2D(u_state, v_uv + vec2(u_texel.x, 0.0)).xy);\n  float hb = dec(texture2D(u_state, v_uv - vec2(0.0, u_texel.y)).xy);\n  float ht = dec(texture2D(u_state, v_uv + vec2(0.0, u_texel.y)).xy);\n  vec2 slope = vec2(hr - hl, ht - hb);\n  vec2 uv = v_uv + slope * 0.08;\n  vec3 floorColour;\n  if (u_hasImage > 0.5) {\n    // cover-fit the image\n    vec2 scale = u_aspect > u_imageAspect ? vec2(1.0, u_imageAspect / u_aspect) : vec2(u_aspect / u_imageAspect, 1.0);\n    floorColour = texture2D(u_image, (uv - 0.5) * scale + 0.5).rgb;\n  } else {\n    vec2 g = uv * vec2(u_aspect, 1.0) * u_tiles;\n    vec2 f = abs(fract(g) - 0.5);\n    float line = smoothstep(0.44, 0.5, max(f.x, f.y));\n    floorColour = mix(u_c0.rgb, u_c1.rgb, line * 0.7);\n  }\n  vec3 n = normalize(vec3(-slope * 24.0, 1.0));\n  float light = pow(clamp(dot(n, normalize(vec3(-0.35, 0.45, 0.82))), 0.0, 1.0), 40.0);\n  float shade = 1.0 + dot(slope, vec2(-0.7, 0.7)) * 5.0;\n  gl_FragColor = vec4(clamp(floorColour * shade + u_c2.rgb * light * 0.9, 0.0, 1.0), 1.0);\n}";
+};
+/** Water over a pool floor (or your image) that ripples where you tap, and rains while nobody does. */
+export declare function waterRipple(options?: WaterRippleOptions): WebglEffect;

package/dist/backgrounds/effects/cursor/waterRipple.js

@@ -0,0 +1,239 @@
+import { FULLSCREEN_VERTEX, bindTexture, fullscreenTriangle, link, pingPong, renderTo, setUniform, } from "../../runtime/webgl.js";
+import { defineGpuEffect } from "../define.js";
+import { slots, stillFallback } from "../shaderKit.js";
+export const WATER_RIPPLE_META = {
+    id: "water-ripple",
+    label: "Water ripple on click",
+    category: "cursor",
+    family: "webgl",
+    cost: { kb: "~4 KB (own runner)", cpu: 1, gpu: 3 },
+    tier: "mid",
+    needs: { pointer: true },
+    note: "Plain WebGL1 with 8-bit textures (height packed into two channels), so no float extensions are needed.",
+};
+/** Simulation cells along the layer's longer side (fewer on touch screens). */
+const SIM_LONG = 256;
+const SIM_LONG_COARSE = 160;
+const MAX_DROPS = 8;
+/** The simulation grid for a layer of `width` × `height`: `long` cells on the longer side. Pure. */
+export function rippleGrid(width, height, long) {
+    const aspect = width / Math.max(1, height);
+    return aspect >= 1
+        ? [long, Math.max(8, Math.round(long / aspect))]
+        : [Math.max(8, Math.round(long * aspect)), long];
+}
+// The classic two-buffer ripple: next = (sum of the 4 neighbours of now) / 2
+// − before, times damping. Both "now" and "before" live in ONE 8-bit RGBA
+// texture: height is packed into two bytes (rg = now, ba = before), so plain
+// WebGL1 runs it. Drops add a cosine bump. The display pass bends the floor
+// by the water's slope (refraction) and adds a highlight where a slope faces
+// the light.
+const PACK = `
+vec2 enc(float h) {
+  float v = clamp(h * 0.5 + 0.5, 0.0, 1.0) * 255.0;
+  float hi = floor(v);
+  return vec2(hi / 255.0, v - hi);
+}
+float dec(vec2 c) {
+  return (floor(c.x * 255.0 + 0.5) + c.y) / 255.0 * 2.0 - 1.0;
+}
+`;
+export const WATER_RIPPLE_SHADERS = {
+    vertex: FULLSCREEN_VERTEX,
+    step: `precision highp float;
+varying vec2 v_uv;
+uniform sampler2D u_state;
+uniform vec2 u_texel;
+uniform float u_damping;
+uniform float u_aspect;
+uniform vec4 u_drops[${MAX_DROPS}];
+uniform float u_dropCount;
+${PACK}
+void main() {
+  vec4 s = texture2D(u_state, v_uv);
+  float now = dec(s.xy);
+  float before = dec(s.zw);
+  float sum = dec(texture2D(u_state, v_uv + vec2(u_texel.x, 0.0)).xy)
+            + dec(texture2D(u_state, v_uv - vec2(u_texel.x, 0.0)).xy)
+            + dec(texture2D(u_state, v_uv + vec2(0.0, u_texel.y)).xy)
+            + dec(texture2D(u_state, v_uv - vec2(0.0, u_texel.y)).xy);
+  float next = (sum * 0.5 - before) * u_damping;
+  for (int i = 0; i < ${MAX_DROPS}; i++) {
+    if (float(i) >= u_dropCount) break;
+    vec4 d = u_drops[i];
+    float r = length((v_uv - d.xy) * vec2(u_aspect, 1.0)) / d.z;
+    if (r < 1.0) next += d.w * (0.5 + 0.5 * cos(r * 3.14159));
+  }
+  gl_FragColor = vec4(enc(next), enc(now));
+}`,
+    display: `precision highp float;
+varying vec2 v_uv;
+uniform sampler2D u_state;
+uniform sampler2D u_image;
+uniform vec2 u_texel;
+uniform float u_aspect;
+uniform float u_imageAspect;
+uniform float u_hasImage;
+uniform float u_tiles;
+uniform vec4 u_c0;
+uniform vec4 u_c1;
+uniform vec4 u_c2;
+${PACK}
+void main() {
+  float hl = dec(texture2D(u_state, v_uv - vec2(u_texel.x, 0.0)).xy);
+  float hr = dec(texture2D(u_state, v_uv + vec2(u_texel.x, 0.0)).xy);
+  float hb = dec(texture2D(u_state, v_uv - vec2(0.0, u_texel.y)).xy);
+  float ht = dec(texture2D(u_state, v_uv + vec2(0.0, u_texel.y)).xy);
+  vec2 slope = vec2(hr - hl, ht - hb);
+  vec2 uv = v_uv + slope * 0.08;
+  vec3 floorColour;
+  if (u_hasImage > 0.5) {
+    // cover-fit the image
+    vec2 scale = u_aspect > u_imageAspect ? vec2(1.0, u_imageAspect / u_aspect) : vec2(u_aspect / u_imageAspect, 1.0);
+    floorColour = texture2D(u_image, (uv - 0.5) * scale + 0.5).rgb;
+  } else {
+    vec2 g = uv * vec2(u_aspect, 1.0) * u_tiles;
+    vec2 f = abs(fract(g) - 0.5);
+    float line = smoothstep(0.44, 0.5, max(f.x, f.y));
+    floorColour = mix(u_c0.rgb, u_c1.rgb, line * 0.7);
+  }
+  vec3 n = normalize(vec3(-slope * 24.0, 1.0));
+  float light = pow(clamp(dot(n, normalize(vec3(-0.35, 0.45, 0.82))), 0.0, 1.0), 40.0);
+  float shade = 1.0 + dot(slope, vec2(-0.7, 0.7)) * 5.0;
+  gl_FragColor = vec4(clamp(floorColour * shade + u_c2.rgb * light * 0.9, 0.0, 1.0), 1.0);
+}`,
+};
+function program(opts) {
+    const long = (f) => (f.coarse ? SIM_LONG_COARSE : SIM_LONG);
+    return {
+        api: "webgl",
+        warmup: 120,
+        init(gl, frame, random) {
+            const step = link(gl, WATER_RIPPLE_SHADERS.vertex, WATER_RIPPLE_SHADERS.step);
+            const display = link(gl, WATER_RIPPLE_SHADERS.vertex, WATER_RIPPLE_SHADERS.display);
+            const grid = rippleGrid(frame.width, frame.height, long(frame));
+            const sim = pingPong(gl, grid[0], grid[1], { linear: false });
+            // mid-grey is height 0 in the packing: start flat, not at -1
+            for (const t of [sim.read, sim.write]) {
+                gl.bindFramebuffer(gl.FRAMEBUFFER, t.fbo);
+                gl.clearColor(0.5, 0.5, 0.5, 0.5);
+                gl.clear(gl.COLOR_BUFFER_BIT);
+            }
+            gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+            const texture = opts.src ? gl.createTexture() : null;
+            const state = {
+                step, display, triangle: fullscreenTriangle(gl), sim, grid,
+                image: texture, imageAspect: 1, imageReady: false,
+                // start as if idle for a while: it rains from the first frame
+                acc: 0, idle: 1.5, rainIn: 0, last: null, random,
+            };
+            if (opts.src && texture) {
+                const img = document.createElement("img");
+                img.crossOrigin = "anonymous";
+                img.decoding = "async";
+                img.onload = () => {
+                    if (gl.isContextLost())
+                        return;
+                    gl.bindTexture(gl.TEXTURE_2D, texture);
+                    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);
+                    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+                    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+                    gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, true);
+                    gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGB, gl.RGB, gl.UNSIGNED_BYTE, img);
+                    gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, false);
+                    state.imageAspect = img.naturalWidth / Math.max(1, img.naturalHeight);
+                    state.imageReady = true;
+                };
+                img.src = opts.src;
+            }
+            return state;
+        },
+        frame(gl, s, f) {
+            const grid = rippleGrid(f.width, f.height, long(f));
+            if (grid[0] !== s.grid[0] || grid[1] !== s.grid[1]) {
+                s.sim.dispose();
+                s.sim = pingPong(gl, grid[0], grid[1], { linear: false });
+                s.grid = grid;
+            }
+            const aspect = f.width / f.height;
+            // input: taps make big drops, a moving pointer a trail, and with nobody around it rains
+            const drops = f.taps.map(([x, y]) => [x, y, 0.05, opts.strength * 0.5]);
+            if (f.pointerIn && opts.trail) {
+                if (s.last && Math.hypot(f.pointer[0] - s.last[0], f.pointer[1] - s.last[1]) > 0.004) {
+                    drops.push([f.pointer[0], f.pointer[1], 0.025, opts.strength * 0.12]);
+                }
+                s.last = f.pointer;
+            }
+            else {
+                s.last = null;
+            }
+            s.idle = drops.length > 0 || f.pointerIn ? 0 : s.idle + f.delta;
+            if (opts.rain && s.idle > 1.5) {
+                s.rainIn -= f.delta;
+                if (s.rainIn <= 0) {
+                    s.rainIn = 0.5 + s.random() * 0.7;
+                    drops.push([0.1 + s.random() * 0.8, 0.1 + s.random() * 0.8, 0.03 + s.random() * 0.03, opts.strength * (0.2 + s.random() * 0.25)]);
+                }
+            }
+            // a fixed 60 Hz step, so the waves travel at the same speed on any display
+            s.acc = Math.min(s.acc + f.delta, 3 / 60);
+            let steps = Math.floor(s.acc * 60);
+            s.acc -= steps / 60;
+            if (steps === 0 && drops.length > 0)
+                steps = 1;
+            gl.useProgram(s.step.program);
+            setUniform(gl, s.step.loc("u_texel"), [1 / s.grid[0], 1 / s.grid[1]]);
+            setUniform(gl, s.step.loc("u_damping"), 1 - opts.damping * 0.06);
+            setUniform(gl, s.step.loc("u_aspect"), aspect);
+            for (let i = 0; i < steps; i++) {
+                const now = i === 0 ? drops.slice(0, MAX_DROPS) : [];
+                setUniform(gl, s.step.loc("u_dropCount"), now.length);
+                now.forEach((d, k) => setUniform(gl, s.step.loc(`u_drops[${k}]`), d));
+                renderTo(gl, s.sim.write, f.width, f.height);
+                bindTexture(gl, s.step.loc("u_state"), s.sim.read.texture, 0);
+                s.triangle.draw();
+                s.sim.swap();
+            }
+            renderTo(gl, null, f.width, f.height);
+            gl.useProgram(s.display.program);
+            bindTexture(gl, s.display.loc("u_state"), s.sim.read.texture, 0);
+            if (s.image)
+                bindTexture(gl, s.display.loc("u_image"), s.image, 1);
+            setUniform(gl, s.display.loc("u_texel"), [1 / s.grid[0], 1 / s.grid[1]]);
+            setUniform(gl, s.display.loc("u_aspect"), aspect);
+            setUniform(gl, s.display.loc("u_imageAspect"), s.imageAspect);
+            setUniform(gl, s.display.loc("u_hasImage"), s.imageReady ? 1 : 0);
+            setUniform(gl, s.display.loc("u_tiles"), opts.tiles);
+            for (let i = 0; i < 3; i++)
+                setUniform(gl, s.display.loc(`u_c${i}`), f.colors[i] ?? [1, 1, 1, 1]);
+            s.triangle.draw();
+        },
+        dispose(gl, s) {
+            s.sim.dispose();
+            s.triangle.dispose();
+            s.step.dispose();
+            s.display.dispose();
+            if (s.image)
+                gl.deleteTexture(s.image);
+        },
+    };
+}
+/** Water over a pool floor (or your image) that ripples where you tap, and rains while nobody does. */
+export function waterRipple(options = {}) {
+    const colors = slots(options.colors, [
+        "color-mix(in oklab, var(--color-sx-accent) 45%, var(--color-sx-secondary))",
+        "color-mix(in oklab, var(--color-sx-accent) 25%, var(--color-sx-secondary))",
+        "color-mix(in oklab, var(--color-sx-accent) 30%, white)",
+    ]);
+    return defineGpuEffect(WATER_RIPPLE_META, program({
+        src: options.src,
+        strength: Math.min(1, Math.max(0, options.strength ?? 0.8)),
+        trail: options.trail ?? true,
+        rain: options.rain ?? true,
+        damping: Math.min(1, Math.max(0, options.damping ?? 0.3)),
+        tiles: Math.max(1, options.tiles ?? 7),
+    }), options, {
+        colors,
+        fallback: stillFallback(WATER_RIPPLE_META, "The still pool floor: tile lines over the water colour.", "linear-gradient(var(--sx-bg-c2) 1px, transparent 1px) 0 0 / 40px 40px, linear-gradient(90deg, var(--sx-bg-c2) 1px, transparent 1px) 0 0 / 40px 40px, var(--sx-bg-c1)", options, colors),
+    });
+}

package/dist/backgrounds/effects/cursor/waterRipple.schema.d.ts

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

package/dist/backgrounds/effects/cursor/waterRipple.schema.js

@@ -0,0 +1,22 @@
+import { defineSchema } from "../../../schema/define.js";
+import { colorsField, layerFields, seedField } from "../../../schema/common.js";
+export const WATER_RIPPLE_SCHEMA = defineSchema()({
+    id: "water-ripple",
+    family: "background",
+    factory: "waterRipple",
+    fields: {
+        ...layerFields(),
+        src: { kind: "text", label: "Image under the water", url: true, autoNote: "pool tiles in the theme colours", help: "Same origin, or served with CORS." },
+        strength: { kind: "number", label: "Tap strength", min: 0, max: 1, step: 0.05, default: 0.8 },
+        trail: { kind: "boolean", label: "Ripples behind the pointer", default: true },
+        rain: { kind: "boolean", label: "Rain while idle", default: true },
+        damping: { kind: "number", label: "Damping", min: 0, max: 1, step: 0.01, default: 0.3, help: "0 never dies out, 1 stops at once." },
+        tiles: { kind: "integer", label: "Pool tiles", min: 1, max: 20, default: 7, help: "Per layer height." },
+        colors: { ...colorsField([
+                "color-mix(in oklab, var(--color-sx-accent) 45%, var(--color-sx-secondary))",
+                "color-mix(in oklab, var(--color-sx-accent) 25%, var(--color-sx-secondary))",
+                "color-mix(in oklab, var(--color-sx-accent) 30%, white)",
+            ], 1, 3), help: "Water, tile lines, highlights (a shorter list repeats)." },
+        seed: seedField(),
+    },
+});

package/dist/backgrounds/effects/define.d.ts

@@ -0,0 +1,75 @@
+import type { BackgroundMask, BackgroundNode, CanvasEffect, CanvasProgram, CssEffect, CssVars, EffectMeta, FallbackEffect, GpuProgram, LayerOptions, SvgEffect, UniformValue, WebglEffect } from "../types.js";
+export declare function maskValue(mask: BackgroundMask): string;
+/** The custom properties the shared layer rule reads (opacity, blend, mask). */
+export declare function layerVars(options: LayerOptions): CssVars;
+/**
+ * An animation duration that follows the effect's `speed` option and the
+ * root's reduced-motion tempo. `base` is a CSS time: `"18s"` or `"var(--d)"`.
+ */
+export declare function duration(base: string): string;
+/** Drop undefined values so callers can write `{ "--x": options.x }`. */
+export declare function vars(input: Record<`--${string}`, string | number | undefined>): CssVars;
+/**
+ * Metadata for the all-tier stand-in of a `mid` / `high` effect: same look,
+ * without the costly part. Its id is `<id>-lite`, so its stylesheet never
+ * clashes with the full effect's.
+ */
+export declare function liteMeta(meta: EffectMeta, note: string): EffectMeta;
+/** An inline SVG as a CSS `url()`, for masks and tiles (no asset download). */
+export declare function svgUrl(svg: string): string;
+export declare function defineCssEffect(meta: EffectMeta, css: string, options: LayerOptions & {
+    readonly speed?: number;
+}, parts?: {
+    readonly vars?: CssVars;
+    readonly nodes?: readonly BackgroundNode[];
+    readonly fallback?: FallbackEffect;
+}): CssEffect;
+/**
+ * A canvas effect. `options` become the signature, so the host restarts the
+ * simulation only when an option actually changes, not on every render.
+ */
+export declare function defineCanvasEffect<S>(meta: EffectMeta, program: CanvasProgram<S>, options: LayerOptions & {
+    readonly seed?: number;
+}, parts: {
+    readonly colors: readonly string[];
+    /** The effect's own frame-rate cap; 0 = the display's rate. */
+    readonly fps?: number;
+    readonly fallback?: FallbackEffect;
+}): CanvasEffect;
+/** An SVG effect: an element tree drawn as one inline `<svg>`, styled and animated by `css`. */
+export declare function defineSvgEffect(meta: EffectMeta, css: string, svg: SvgEffect["svg"], options: LayerOptions & {
+    readonly speed?: number;
+}, parts?: {
+    readonly vars?: CssVars;
+    readonly fallback?: FallbackEffect;
+}): SvgEffect;
+/**
+ * A WebGL effect: one fragment shader. `fallback` is required: it renders on
+ * weaker devices, without WebGL, if the shader fails to compile, and before
+ * the device tier is known (so there is never a blank first frame).
+ */
+export declare function defineWebglEffect(meta: EffectMeta, fragment: string, options: LayerOptions & {
+    readonly seed?: number;
+}, parts: {
+    readonly colors: readonly string[];
+    readonly uniforms?: Readonly<Record<string, UniformValue>>;
+    readonly fallback: FallbackEffect;
+    /** Fraction of the backing size to render at (default 1). */
+    readonly resolution?: number;
+    readonly fps?: number;
+    /** Shader seconds for the still frame (default: 7 + the seed, so seeds differ when still). */
+    readonly stillTime?: number;
+}): WebglEffect;
+/**
+ * A WebGL effect with its own GPU program (several passes, simulation state,
+ * point or line meshes). Same contract as `defineWebglEffect` otherwise.
+ */
+export declare function defineGpuEffect(meta: EffectMeta, program: GpuProgram<any>, options: LayerOptions & {
+    readonly seed?: number;
+}, parts: {
+    readonly colors: readonly string[];
+    readonly fallback: FallbackEffect;
+    readonly resolution?: number;
+    readonly fps?: number;
+    readonly stillTime?: number;
+}): WebglEffect;

package/dist/backgrounds/effects/define.js

@@ -0,0 +1,137 @@
+// ---------------------------------------------------------------------------
+// Helpers every effect factory shares. Pure.
+// ---------------------------------------------------------------------------
+import { fragmentProgram } from "../runtime/webgl.js";
+const MASKS = {
+    radial: "radial-gradient(ellipse at center, black 30%, transparent 75%)",
+    "fade-top": "linear-gradient(to bottom, transparent, black 45%)",
+    "fade-bottom": "linear-gradient(to top, transparent, black 45%)",
+    "fade-edges": "radial-gradient(ellipse at center, black 55%, transparent 100%)",
+};
+export function maskValue(mask) {
+    return MASKS[mask] ?? mask;
+}
+/** The custom properties the shared layer rule reads (opacity, blend, mask). */
+export function layerVars(options) {
+    const vars = {};
+    if (options.opacity !== undefined)
+        vars["--sx-bg-opacity"] = options.opacity;
+    if (options.blend !== undefined)
+        vars["--sx-bg-blend"] = options.blend;
+    if (options.mask !== undefined)
+        vars["--sx-bg-mask"] = maskValue(options.mask);
+    return vars;
+}
+/**
+ * An animation duration that follows the effect's `speed` option and the
+ * root's reduced-motion tempo. `base` is a CSS time: `"18s"` or `"var(--d)"`.
+ */
+export function duration(base) {
+    return `calc(${base} / (var(--sx-bg-speed, 1) * var(--sx-bg-tempo, 1)))`;
+}
+/** Drop undefined values so callers can write `{ "--x": options.x }`. */
+export function vars(input) {
+    const out = {};
+    for (const [key, value] of Object.entries(input)) {
+        if (value !== undefined)
+            out[key] = value;
+    }
+    return out;
+}
+/**
+ * Metadata for the all-tier stand-in of a `mid` / `high` effect: same look,
+ * without the costly part. Its id is `<id>-lite`, so its stylesheet never
+ * clashes with the full effect's.
+ */
+export function liteMeta(meta, note) {
+    return {
+        ...meta,
+        id: `${meta.id}-lite`,
+        label: `${meta.label} (light version)`,
+        tier: "all",
+        cost: { kb: meta.cost.kb, cpu: 1, gpu: 1 },
+        note,
+    };
+}
+/** An inline SVG as a CSS `url()`, for masks and tiles (no asset download). */
+export function svgUrl(svg) {
+    return `url("data:image/svg+xml,${encodeURIComponent(svg)}")`;
+}
+export function defineCssEffect(meta, css, options, parts = {}) {
+    return {
+        kind: "css",
+        meta,
+        css,
+        vars: {
+            ...(options.speed !== undefined ? { "--sx-bg-speed": options.speed } : {}),
+            ...parts.vars,
+            ...layerVars(options),
+        },
+        nodes: parts.nodes ?? [],
+        ...(parts.fallback ? { fallback: parts.fallback } : {}),
+    };
+}
+/**
+ * A canvas effect. `options` become the signature, so the host restarts the
+ * simulation only when an option actually changes, not on every render.
+ */
+export function defineCanvasEffect(meta, program, options, parts) {
+    return {
+        kind: "canvas",
+        meta,
+        program,
+        colors: parts.colors,
+        fps: parts.fps ?? 0,
+        seed: options.seed ?? 1,
+        signature: JSON.stringify(options),
+        vars: layerVars(options),
+        ...(parts.fallback ? { fallback: parts.fallback } : {}),
+    };
+}
+/** An SVG effect: an element tree drawn as one inline `<svg>`, styled and animated by `css`. */
+export function defineSvgEffect(meta, css, svg, options, parts = {}) {
+    return {
+        kind: "svg",
+        meta,
+        css,
+        svg,
+        vars: {
+            ...(options.speed !== undefined ? { "--sx-bg-speed": options.speed } : {}),
+            ...parts.vars,
+            ...layerVars(options),
+        },
+        ...(parts.fallback ? { fallback: parts.fallback } : {}),
+    };
+}
+/**
+ * A WebGL effect: one fragment shader. `fallback` is required: it renders on
+ * weaker devices, without WebGL, if the shader fails to compile, and before
+ * the device tier is known (so there is never a blank first frame).
+ */
+export function defineWebglEffect(meta, fragment, options, parts) {
+    const uniforms = parts.uniforms ?? {};
+    return {
+        ...defineGpuEffect(meta, fragmentProgram(fragment, uniforms, parts.colors.length), options, parts),
+        fragment,
+        uniforms,
+    };
+}
+/**
+ * A WebGL effect with its own GPU program (several passes, simulation state,
+ * point or line meshes). Same contract as `defineWebglEffect` otherwise.
+ */
+export function defineGpuEffect(meta, program, options, parts) {
+    return {
+        kind: "webgl",
+        meta,
+        program,
+        colors: parts.colors,
+        resolution: Math.min(1, Math.max(0.1, parts.resolution ?? 1)),
+        fps: parts.fps ?? 0,
+        stillTime: parts.stillTime ?? 7 + (options.seed ?? 0),
+        seed: options.seed ?? 1,
+        signature: JSON.stringify(options),
+        vars: layerVars(options),
+        fallback: parts.fallback,
+    };
+}

package/dist/backgrounds/effects/glass/isometricLayers.d.ts

@@ -0,0 +1,14 @@
+import type { CssEffect, EffectMeta, LayerOptions } from "../../types.js";
+export declare const ISOMETRIC_LAYERS_META: EffectMeta;
+export interface IsometricLayersOptions extends LayerOptions {
+    readonly speed?: number;
+    /** Number of stacked planes (2–7). */
+    readonly layers?: number;
+    /** Plane size in % of the layer's shorter side. */
+    readonly size?: number;
+    /** Gap between planes in % of the shorter side. */
+    readonly gap?: number;
+    readonly colors?: readonly string[];
+}
+/** Stacked isometric planes, gently floating apart and back. */
+export declare function isometricLayers(options?: IsometricLayersOptions): CssEffect;

package/dist/backgrounds/effects/glass/isometricLayers.js

@@ -0,0 +1,57 @@
+import { round } from "../../runtime/rng.js";
+import { defineCssEffect, duration } from "../define.js";
+import { paletteRef, paletteVars } from "../palette.js";
+export const ISOMETRIC_LAYERS_META = {
+    id: "isometric-layers",
+    label: "Isometric Floating Layers Diagram",
+    category: "glass",
+    family: "css",
+    cost: { kb: "<3 KB", cpu: 1, gpu: 1 },
+    tier: "all",
+    note: "Looks 3D but is just transformed flat layers. Very cheap.",
+};
+// Flat squares tilted into an isometric view. Each plane carries its own
+// transform (no shared 3D stage), so translateZ along the tilted normal reads
+// as "higher" on screen. Later planes paint on top, which is the right order.
+const CSS = `@layer components {
+  :where([data-sx-bg="isometric-layers"] [data-sx-bg-part="plane"]) {
+    position: absolute;
+    inset-inline-start: 50%;
+    inset-block-start: 58%;
+    inline-size: var(--sx-bg-size);
+    aspect-ratio: 1;
+    margin-inline-start: calc(var(--sx-bg-size) / -2);
+    margin-block-start: calc(var(--sx-bg-size) / -2);
+    border-radius: 6%;
+    border: 1px solid color-mix(in oklab, var(--c) 70%, transparent);
+    background-color: color-mix(in oklab, var(--c) 16%, transparent);
+    background-image:
+      linear-gradient(to right, color-mix(in oklab, var(--c) 30%, transparent) 1px, transparent 1px),
+      linear-gradient(to bottom, color-mix(in oklab, var(--c) 30%, transparent) 1px, transparent 1px);
+    background-size: 12.5% 12.5%;
+    transform: rotateX(58deg) rotateZ(-45deg) translateZ(var(--z));
+    animation: sx-bg-iso ${duration("var(--d)")} ease-in-out var(--delay) infinite alternate;
+  }
+  @keyframes sx-bg-iso {
+    to { transform: rotateX(58deg) rotateZ(-45deg) translateZ(calc(var(--z) + 4cqmin)); }
+  }
+}`;
+/** Stacked isometric planes, gently floating apart and back. */
+export function isometricLayers(options = {}) {
+    const palette = paletteVars(options.colors);
+    const count = Math.min(7, Math.max(2, Math.round(options.layers ?? 4)));
+    const gap = options.gap ?? 9;
+    const nodes = Array.from({ length: count }, (_, i) => ({
+        part: "plane",
+        vars: {
+            "--z": `${round(i * gap, 1)}cqmin`,
+            "--c": paletteRef(i, palette.count),
+            "--d": `${round(4 + i * 0.6, 1)}s`,
+            "--delay": `${-round(i * 0.7, 1)}s`,
+        },
+    }));
+    return defineCssEffect(ISOMETRIC_LAYERS_META, CSS, options, {
+        vars: { ...palette.vars, "--sx-bg-size": `${options.size ?? 46}cqmin` },
+        nodes,
+    });
+}

package/dist/backgrounds/effects/glass/isometricLayers.schema.d.ts

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

package/dist/backgrounds/effects/glass/isometricLayers.schema.js

@@ -0,0 +1,16 @@
+import { defineSchema } from "../../../schema/define.js";
+import { colorsField, layerFields, speedField } from "../../../schema/common.js";
+import { SX_PALETTE } from "../palette.js";
+export const ISOMETRIC_LAYERS_SCHEMA = defineSchema()({
+    id: "isometric-layers",
+    family: "background",
+    factory: "isometricLayers",
+    fields: {
+        ...layerFields(),
+        speed: speedField(),
+        layers: { kind: "integer", label: "Planes", min: 2, max: 7, default: 4 },
+        size: { kind: "number", label: "Plane size", min: 10, max: 90, step: 1, unit: "%", default: 46, help: "Of the layer's shorter side." },
+        gap: { kind: "number", label: "Gap", min: 0, max: 30, step: 0.5, unit: "%", default: 9, help: "Of the layer's shorter side." },
+        colors: colorsField(SX_PALETTE),
+    },
+});

package/dist/backgrounds/effects/glass/liquidSculpture.d.ts

@@ -0,0 +1,24 @@
+import type { EffectMeta, LayerOptions, WebglEffect } from "../../types.js";
+export declare const LIQUID_SCULPTURE_META: EffectMeta;
+export interface LiquidSculptureOptions extends LayerOptions {
+    readonly speed?: number;
+    /** Number of particles (1 000–200 000). Default 125 000; touch screens get at most 40 000. */
+    readonly count?: number;
+    /** Particle size in px at the sculpture's centre. */
+    readonly size?: number;
+    /** Three colours: two for the body, one for the bright near side. */
+    readonly colors?: readonly string[];
+    readonly seed?: number;
+}
+export declare const SCULPTURE_MAX = 200000;
+/**
+ * Per particle: (u, v) where it sits on the shape's surface and a random
+ * value for its own wobble and colour. Three floats each. Pure.
+ */
+export declare function sculptureParticles(count: number, random: () => number): Float32Array;
+export declare const LIQUID_SCULPTURE_SHADERS: {
+    readonly vertex: "attribute vec3 a_p;\nuniform float u_time;\nuniform float u_aspect;\nuniform float u_size;\nuniform float u_dpr;\nuniform vec2 u_pointer;\nuniform float u_pointer_in;\nvarying float v_shade;\nvarying float v_tone;\nconst float TAU = 6.2831853;\nvec3 knotCentre(float t) {\n  float c = cos(3.0 * t);\n  return vec3((2.0 + c) * cos(2.0 * t), (2.0 + c) * sin(2.0 * t), sin(3.0 * t)) * 0.28;\n}\nvec3 knot(float u, float v) {\n  float t = u * TAU;\n  vec3 c = knotCentre(t);\n  vec3 tangent = normalize(knotCentre(t + 0.01) - c);\n  vec3 n = normalize(cross(tangent, vec3(0.0, 0.0, 1.0)));\n  vec3 b = cross(tangent, n);\n  float a = v * TAU;\n  return c + (n * cos(a) + b * sin(a)) * 0.11;\n}\nvec3 blob(float u, float v, float t) {\n  float theta = u * TAU;\n  float phi = acos(2.0 * v - 1.0);\n  vec3 d = vec3(sin(phi) * cos(theta), cos(phi), sin(phi) * sin(theta));\n  float n = sin(d.x * 4.0 + t) * sin(d.y * 5.0 - t * 1.3) * sin(d.z * 3.0 + t * 0.7);\n  return d * (0.7 + 0.16 * n);\n}\nmat3 turnY(float a) {\n  float c = cos(a);\n  float s = sin(a);\n  return mat3(c, 0.0, -s, 0.0, 1.0, 0.0, s, 0.0, c);\n}\nmat3 turnX(float a) {\n  float c = cos(a);\n  float s = sin(a);\n  return mat3(1.0, 0.0, 0.0, 0.0, c, s, 0.0, -s, c);\n}\nvoid main() {\n  float t = u_time * 0.35;\n  float morph = smoothstep(0.15, 0.85, 0.5 + 0.5 * sin(t * 0.6));\n  vec3 p = mix(blob(a_p.x, a_p.y, t), knot(a_p.x, a_p.y), morph);\n  p += 0.012 * vec3(sin(t * 3.0 + a_p.z * 40.0), cos(t * 2.6 + a_p.z * 31.0), sin(t * 2.2 + a_p.z * 17.0));\n  float yaw = t * 0.5 + (u_pointer.x - 0.5) * 1.4 * u_pointer_in;\n  float pitch = 0.35 - (u_pointer.y - 0.5) * 0.9 * u_pointer_in;\n  p = turnX(pitch) * turnY(yaw) * p;\n  float depth = 2.6 - p.z;\n  float k = 1.9 * min(1.0, u_aspect);\n  gl_Position = vec4(p.x * k / (depth * u_aspect), p.y * k / depth, 0.0, 1.0);\n  gl_PointSize = u_size * u_dpr * 2.6 / depth;\n  v_shade = clamp(0.55 + p.z * 0.7, 0.15, 1.0);\n  v_tone = a_p.z;\n}";
+    readonly fragment: "precision mediump float;\nuniform vec4 u_c0;\nuniform vec4 u_c1;\nuniform vec4 u_c2;\nuniform float u_alpha;\nvarying float v_shade;\nvarying float v_tone;\nvoid main() {\n  float d = length(gl_PointCoord - 0.5);\n  float a = (1.0 - smoothstep(0.1, 0.5, d)) * u_alpha * v_shade;\n  vec3 c = mix(mix(u_c0.rgb, u_c1.rgb, v_tone), u_c2.rgb, v_shade * v_shade * 0.6);\n  gl_FragColor = vec4(c * a, a);\n}";
+};
+/** A glowing sculpture of particles that melts between a liquid blob and a knot. */
+export declare function liquidSculpture(options?: LiquidSculptureOptions): WebglEffect;