@sharedex/ui 0.0.0-stage → 0.9.0

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

@@ -0,0 +1,145 @@
+import { link, renderTo, setUniform, WebglUnavailable } from "../../runtime/webgl.js";
+import { defineGpuEffect } from "../define.js";
+import { slots, stillFallback } from "../shaderKit.js";
+export const WIREFRAME_OCEAN_META = {
+    id: "wireframe-ocean",
+    label: "Wireframe Ocean Vector Waves",
+    category: "wave",
+    family: "webgl",
+    cost: { kb: "~3 KB (own runner instead of Three.js)", cpu: 1, gpu: 2 },
+    tier: "mid",
+    note: "Vertex work is cheap; the grid is capped at 100×100 (60×45 on touch screens).",
+};
+export const OCEAN_MAX = 100;
+const COARSE_COLS = 60;
+const COARSE_ROWS = 45;
+/**
+ * The grid as line segments: `grid` holds (x, depth) per vertex, x in
+ * [-1, 1], depth in [0, 1] (near to far); `indices` pairs vertices into
+ * segments along each row and each column. Pure.
+ */
+export function oceanMesh(cols, rows) {
+    const c = Math.min(OCEAN_MAX, Math.max(2, Math.round(cols)));
+    const r = Math.min(OCEAN_MAX, Math.max(2, Math.round(rows)));
+    const grid = new Float32Array(c * r * 2);
+    for (let j = 0; j < r; j++) {
+        for (let i = 0; i < c; i++) {
+            grid[(j * c + i) * 2] = (i / (c - 1)) * 2 - 1;
+            grid[(j * c + i) * 2 + 1] = j / (r - 1);
+        }
+    }
+    const indices = new Uint16Array(((c - 1) * r + (r - 1) * c) * 2);
+    let k = 0;
+    for (let j = 0; j < r; j++) {
+        for (let i = 0; i < c; i++) {
+            const v = j * c + i;
+            if (i < c - 1) {
+                indices[k++] = v;
+                indices[k++] = v + 1;
+            }
+            if (j < r - 1) {
+                indices[k++] = v;
+                indices[k++] = v + c;
+            }
+        }
+    }
+    return { grid, indices };
+}
+// Each vertex sits on a flat plane seen from above the water: depth grows
+// with the square of the row (rows bunch up toward the horizon), x spreads
+// with depth so the grid always fills the width, and four travelling sine
+// waves lift it. Lines fade toward the horizon. In RTL the swell runs the
+// other way.
+export const WIREFRAME_OCEAN_SHADERS = {
+    vertex: `attribute vec2 a_grid;
+uniform float u_time;
+uniform float u_aspect;
+uniform float u_height;
+uniform float u_horizon;
+uniform float u_rtl;
+varying float v_far;
+varying float v_crest;
+float waves(vec2 p, float t) {
+  float s = u_rtl > 0.5 ? -1.0 : 1.0;
+  float h = 0.30 * sin(dot(p, vec2(0.9 * s, 0.45)) * 1.3 + t * 1.1);
+  h += 0.18 * sin(dot(p, vec2(-0.6 * s, 0.8)) * 2.1 + t * 1.6);
+  h += 0.10 * sin(dot(p, vec2(0.2 * s, 1.0)) * 3.7 + t * 2.3);
+  h += 0.05 * sin(dot(p, vec2(1.0 * s, -0.3)) * 6.1 + t * 3.1);
+  return h;
+}
+void main() {
+  float z = mix(1.2, 14.0, a_grid.y * a_grid.y);
+  float x = a_grid.x * z * u_aspect * 0.9;
+  float y = waves(vec2(x, z), u_time) * u_height;
+  gl_Position = vec4(x / (z * 0.75 * u_aspect), (y - 1.6) / (z * 0.75) + u_horizon * 2.0 - 1.0, 0.0, 1.0);
+  v_far = a_grid.y;
+  v_crest = y / max(u_height, 0.001);
+}`,
+    fragment: `precision mediump float;
+uniform vec4 u_c0;
+uniform vec4 u_c1;
+varying float v_far;
+varying float v_crest;
+void main() {
+  float fade = 1.0 - smoothstep(0.45, 1.0, v_far);
+  vec3 c = mix(u_c0.rgb, u_c1.rgb, clamp(v_crest * 1.6 + 0.5, 0.0, 1.0));
+  float a = fade * mix(u_c0.a, u_c1.a, 0.5);
+  gl_FragColor = vec4(c * a, a);
+}`,
+};
+function program(cols, rows, speed, height, horizon) {
+    return {
+        api: "webgl",
+        warmup: 0,
+        init(gl, frame) {
+            const linked = link(gl, WIREFRAME_OCEAN_SHADERS.vertex, WIREFRAME_OCEAN_SHADERS.fragment, ["a_grid"]);
+            const mesh = oceanMesh(frame.coarse ? Math.min(cols, COARSE_COLS) : cols, frame.coarse ? Math.min(rows, COARSE_ROWS) : rows);
+            const vertices = gl.createBuffer();
+            const elements = gl.createBuffer();
+            if (!vertices || !elements)
+                throw new WebglUnavailable("could not create buffers");
+            gl.bindBuffer(gl.ARRAY_BUFFER, vertices);
+            gl.bufferData(gl.ARRAY_BUFFER, mesh.grid, gl.STATIC_DRAW);
+            gl.bindBuffer(gl.ELEMENT_ARRAY_BUFFER, elements);
+            gl.bufferData(gl.ELEMENT_ARRAY_BUFFER, mesh.indices, gl.STATIC_DRAW);
+            return { linked, vertices, elements, count: mesh.indices.length };
+        },
+        frame(gl, s, f) {
+            renderTo(gl, null, f.width, f.height);
+            gl.clearColor(0, 0, 0, 0);
+            gl.clear(gl.COLOR_BUFFER_BIT);
+            gl.enable(gl.BLEND);
+            gl.blendFunc(gl.ONE, gl.ONE_MINUS_SRC_ALPHA);
+            gl.useProgram(s.linked.program);
+            setUniform(gl, s.linked.loc("u_time"), f.time * speed);
+            setUniform(gl, s.linked.loc("u_aspect"), f.width / f.height);
+            setUniform(gl, s.linked.loc("u_height"), height);
+            setUniform(gl, s.linked.loc("u_horizon"), horizon);
+            setUniform(gl, s.linked.loc("u_rtl"), f.rtl ? 1 : 0);
+            setUniform(gl, s.linked.loc("u_c0"), f.colors[0] ?? [1, 1, 1, 1]);
+            setUniform(gl, s.linked.loc("u_c1"), f.colors[1] ?? [1, 1, 1, 1]);
+            gl.bindBuffer(gl.ARRAY_BUFFER, s.vertices);
+            gl.enableVertexAttribArray(0);
+            gl.vertexAttribPointer(0, 2, gl.FLOAT, false, 0, 0);
+            gl.bindBuffer(gl.ELEMENT_ARRAY_BUFFER, s.elements);
+            gl.drawElements(gl.LINES, s.count, gl.UNSIGNED_SHORT, 0);
+            gl.disable(gl.BLEND);
+        },
+        dispose(gl, s) {
+            gl.deleteBuffer(s.vertices);
+            gl.deleteBuffer(s.elements);
+            s.linked.dispose();
+        },
+    };
+}
+/** A wireframe sea rolling toward a horizon. */
+export function wireframeOcean(options = {}) {
+    const colors = slots(options.colors, [
+        "color-mix(in oklab, var(--color-sx-accent) 55%, transparent)",
+        "color-mix(in oklab, var(--color-sx-accent) 50%, var(--color-sx-ink))",
+    ]);
+    return defineGpuEffect(WIREFRAME_OCEAN_META, program(Math.min(OCEAN_MAX, Math.max(2, options.cols ?? 90)), Math.min(OCEAN_MAX, Math.max(2, options.rows ?? 70)), options.speed ?? 1, Math.min(2, Math.max(0, options.height ?? 1)), Math.min(1, Math.max(0, options.horizon ?? 0.68))), options, {
+        colors,
+        fallback: stillFallback(WIREFRAME_OCEAN_META, "A still perspective grid: lines converging toward the horizon.", "linear-gradient(to top, color-mix(in oklab, var(--sx-bg-c1) 70%, transparent) 1px, transparent 1px) 0 100% / 100% 14px, linear-gradient(90deg, color-mix(in oklab, var(--sx-bg-c1) 50%, transparent) 1px, transparent 1px) 0 0 / 28px 100%", options, colors),
+    });
+}

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

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

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

@@ -0,0 +1,17 @@
+import { defineSchema } from "../../../schema/define.js";
+import { layerFields, speedField, seedField, colorsField } from "../../../schema/common.js";
+export const WIREFRAME_OCEAN_SCHEMA = defineSchema()({
+    id: "wireframe-ocean",
+    family: "background",
+    factory: "wireframeOcean",
+    fields: {
+        ...layerFields(),
+        speed: speedField(),
+        cols: { kind: "integer", label: "Lines across", min: 2, max: 100, default: 90 },
+        rows: { kind: "integer", label: "Lines into the distance", min: 2, max: 100, default: 70 },
+        height: { kind: "number", label: "Wave height", min: 0, max: 2, step: 0.05, default: 1 },
+        horizon: { kind: "number", label: "Horizon", min: 0, max: 1, step: 0.01, default: 0.68, help: "0 bottom, 1 top." },
+        colors: { ...colorsField(["color-mix(in oklab, var(--color-sx-accent) 55%, transparent)", "color-mix(in oklab, var(--color-sx-accent) 50%, var(--color-sx-ink))"], 1, 2), help: "Troughs, then crests." },
+        seed: seedField(),
+    },
+});

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

@@ -0,0 +1,13 @@
+import type { CanvasEffect } from "../types.js";
+/**
+ * Runs a canvas effect. The host owns everything an effect must not:
+ * the backing-store size (capped DPR), resizing, the shared frame loop,
+ * pausing off screen / in hidden tabs / under reduced motion, the frame-rate
+ * cap, and resolving theme colours (again when the theme changes).
+ *
+ * React renders the two elements once; per-frame work never touches React.
+ */
+export declare function CanvasHost({ effect, className }: {
+    readonly effect: CanvasEffect;
+    readonly className?: string | undefined;
+}): import("react").JSX.Element;

package/dist/backgrounds/hosts/CanvasHost.js

@@ -0,0 +1,116 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useRef } 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 { useLayerNeeds } from "./useLayerNeeds.js";
+/** Frames simulated before a still (reduced-motion) frame, so it looks mid-flow, not empty. */
+const STILL_WARMUP = 90;
+/**
+ * Runs a canvas effect. The host owns everything an effect must not:
+ * the backing-store size (capped DPR), resizing, the shared frame loop,
+ * pausing off screen / in hidden tabs / under reduced motion, the frame-rate
+ * cap, and resolving theme colours (again when the theme changes).
+ *
+ * React renders the two elements once; per-frame work never touches React.
+ */
+export function CanvasHost({ effect, className }) {
+    const runtime = useBackgroundRuntime("Background.Layer");
+    const { onVisibility, visible, pointer, config } = runtime;
+    const layerRef = useRef(null);
+    const canvasRef = useRef(null);
+    // The consumer may build a new descriptor every render; only its signature
+    // (the options) decides when the simulation restarts.
+    const latest = useRef(effect);
+    latest.current = effect;
+    useLayerNeeds(effect.meta, layerRef);
+    useEffect(() => {
+        const layer = layerRef.current;
+        const canvas = canvasRef.current;
+        const ctx = canvas?.getContext("2d");
+        if (!layer || !canvas || !ctx)
+            return;
+        const { program, colors, seed } = latest.current;
+        const fps = config.fps > 0 && latest.current.fps > 0 ? Math.min(config.fps, latest.current.fps) : config.fps || latest.current.fps;
+        const colorResolver = createColorResolver(layer);
+        const reduce = matchMedia("(prefers-reduced-motion: reduce)");
+        const coarse = matchMedia("(pointer: coarse)");
+        const resolvePalette = () => {
+            const list = colors.map((c) => colorResolver.resolve(c));
+            return list.length > 0 ? list : [[0, 0, 0, 1]];
+        };
+        let palette = resolvePalette();
+        let env;
+        let state;
+        let stop = null;
+        const motion = () => (reduce.matches ? config.reducedMotion : "ignore");
+        const build = () => {
+            const width = layer.clientWidth;
+            const height = layer.clientHeight;
+            const dpr = Math.min(window.devicePixelRatio || 1, config.maxDpr);
+            canvas.width = Math.max(1, Math.round(width * dpr));
+            canvas.height = Math.max(1, Math.round(height * dpr));
+            ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
+            env = { width, height, dpr, rtl: getComputedStyle(layer).direction === "rtl", coarse: coarse.matches, palette };
+            state = program.init(env, rng(seed));
+        };
+        const frameFn = (delta) => {
+            program.step(state, motion() === "slow" ? delta * 0.35 : delta, pointer, env);
+            program.draw(ctx, state, env);
+        };
+        /** One representative frame, for reduced motion and while paused. */
+        const paintStill = () => {
+            for (let i = 0; i < STILL_WARMUP; i++)
+                program.step(state, 16, pointer, env);
+            program.draw(ctx, state, env);
+        };
+        const sync = () => {
+            const run = visible.current && motion() !== "still";
+            if (run && !stop)
+                stop = onFrame(capped(fps, frameFn));
+            if (!run && stop) {
+                stop();
+                stop = null;
+            }
+        };
+        const rebuild = () => {
+            build();
+            if (stop)
+                program.draw(ctx, state, env);
+            else
+                paintStill();
+        };
+        const repaint = () => {
+            palette = resolvePalette();
+            env = { ...env, palette };
+            if (!stop)
+                program.draw(ctx, state, env);
+        };
+        build();
+        paintStill();
+        sync();
+        let first = true;
+        const ro = new ResizeObserver(() => {
+            if (first) {
+                first = false; // the initial callback reports the size we just built for
+                return;
+            }
+            rebuild();
+        });
+        ro.observe(layer);
+        const offVisibility = onVisibility(sync);
+        reduce.addEventListener("change", sync);
+        const stopTheme = watchTheme(repaint);
+        return () => {
+            stop?.();
+            ro.disconnect();
+            offVisibility();
+            reduce.removeEventListener("change", sync);
+            stopTheme();
+            colorResolver.dispose();
+        };
+    }, [effect.meta.id, effect.signature, config.maxDpr, config.fps, config.reducedMotion, onVisibility, visible, pointer]);
+    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" }) }));
+}

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

@@ -0,0 +1,22 @@
+import type { CssEffect } from "../types.js";
+/**
+ * `sx-bg-<id>-<hash of the css>`: React keeps one style per href, so the hash
+ * lets an edited stylesheet (hot reload) or a second package version on the
+ * same page get its own tag instead of silently reusing the first one.
+ */
+export declare function styleHref(id: string, css: string): string;
+/**
+ * Renders a CSS effect: one layer element, its generated nodes, and its
+ * stylesheet. React 19 hoists `<style href precedence>` into <head> and keeps
+ * one copy per `href`, so the CSS ships once per page and only for effects
+ * that are actually mounted.
+ */
+export declare function CssHost({ effect, className }: {
+    readonly effect: CssEffect;
+    readonly className?: string | undefined;
+}): import("react").JSX.Element;
+/** An effect's stylesheet, hoisted into <head> once per page by React. */
+export declare function EffectStyle({ id, css }: {
+    readonly id: string;
+    readonly css: string;
+}): import("react").JSX.Element;

package/dist/backgrounds/hosts/CssHost.js

@@ -0,0 +1,39 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useRef } from "react";
+import { useLayerNeeds } from "./useLayerNeeds.js";
+const hrefs = new Map();
+/**
+ * `sx-bg-<id>-<hash of the css>`: React keeps one style per href, so the hash
+ * lets an edited stylesheet (hot reload) or a second package version on the
+ * same page get its own tag instead of silently reusing the first one.
+ */
+export function styleHref(id, css) {
+    let href = hrefs.get(css);
+    if (href === undefined) {
+        let h = 5381;
+        for (let i = 0; i < css.length; i++)
+            h = ((h << 5) + h + css.charCodeAt(i)) >>> 0;
+        href = `sx-bg-${id}-${h.toString(36)}`;
+        hrefs.set(css, href);
+    }
+    return href;
+}
+/**
+ * Renders a CSS effect: one layer element, its generated nodes, and its
+ * stylesheet. React 19 hoists `<style href precedence>` into <head> and keeps
+ * one copy per `href`, so the CSS ships once per page and only for effects
+ * that are actually mounted.
+ */
+export function CssHost({ effect, className }) {
+    const layer = useRef(null);
+    useLayerNeeds(effect.meta, layer);
+    return (_jsxs("div", { ref: layer, "data-sx-bg": effect.meta.id, className: className, style: effect.vars, children: [_jsx(EffectStyle, { id: effect.meta.id, css: effect.css }), effect.nodes.map(renderNode)] }));
+}
+/** An effect's stylesheet, hoisted into <head> once per page by React. */
+export function EffectStyle({ id, css }) {
+    return (_jsx("style", { href: styleHref(id, css), precedence: "sx", children: css }));
+}
+function renderNode(node, i) {
+    return (_jsx("span", { "data-sx-bg-part": node.part, style: node.vars, children: node.children?.map(renderNode) }, i));
+}

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

@@ -0,0 +1,6 @@
+import type { MediaEffect } from "../types.js";
+/** The consumer's own image or video, decorative (empty alt, aria-hidden root). */
+export declare function MediaHost({ effect, className }: {
+    readonly effect: MediaEffect;
+    readonly className?: string | undefined;
+}): import("react").JSX.Element;

package/dist/backgrounds/hosts/MediaHost.js

@@ -0,0 +1,202 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useRef } from "react";
+import { useBackgroundRuntime } from "../runtime/context.js";
+import { useLayerNeeds } from "./useLayerNeeds.js";
+/** The consumer's own image or video, decorative (empty alt, aria-hidden root). */
+export function MediaHost({ effect, className }) {
+    const layer = useRef(null);
+    useLayerNeeds(effect.meta, layer);
+    const { media } = effect;
+    if (media.type === "image" && media.fit === "tile") {
+        const style = {
+            ...effect.vars,
+            backgroundImage: `url("${media.src}")`,
+            backgroundRepeat: "repeat",
+            backgroundSize: media.tileSize ?? "auto",
+            backgroundPosition: media.position ?? "center",
+        };
+        return _jsx("div", { ref: layer, "data-sx-bg": effect.meta.id, className: className, style: style });
+    }
+    return (_jsx("div", { ref: layer, "data-sx-bg": effect.meta.id, className: className, style: effect.vars, children: media.type === "image" ? (_jsx(Image, { media: media })) : media.type === "video" ? (_jsx(Video, { media: media })) : media.frames ? (_jsx(FrameScrub, { media: media, frames: media.frames })) : (_jsx(VideoScrub, { media: media })) }));
+}
+function Image({ media }) {
+    return (_jsx("img", { "data-sx-bg-part": "media", src: media.src, srcSet: media.srcSet, sizes: media.sizes, alt: "", loading: media.loading, decoding: "async", style: { objectFit: media.fit === "contain" ? "contain" : "cover", objectPosition: media.position } }));
+}
+/**
+ * Plays only while visible, never under reduced motion `still` (the poster
+ * stays), and at a third of the speed under `slow`. Play is started from JS,
+ * not `autoPlay`, so a video scrolled out of view never starts decoding.
+ */
+function Video({ media }) {
+    const ref = useRef(null);
+    const runtime = useBackgroundRuntime("Background.Layer");
+    const { onVisibility, visible, config } = runtime;
+    useEffect(() => {
+        const el = ref.current;
+        if (!el)
+            return;
+        el.muted = true; // React does not reliably set the `muted` attribute
+        const reduce = matchMedia("(prefers-reduced-motion: reduce)");
+        const sync = () => {
+            const reduced = reduce.matches ? config.reducedMotion : "ignore";
+            el.playbackRate = media.playbackRate * (reduced === "slow" ? 0.35 : 1);
+            if (visible.current && reduced !== "still") {
+                el.play().catch(() => {
+                    /* autoplay refused (e.g. low-power mode): the poster stays */
+                });
+            }
+            else {
+                el.pause();
+            }
+        };
+        sync();
+        reduce.addEventListener("change", sync);
+        const unsubscribe = onVisibility(sync);
+        return () => {
+            reduce.removeEventListener("change", sync);
+            unsubscribe();
+        };
+    }, [onVisibility, visible, config.reducedMotion, media.playbackRate]);
+    return (_jsx("video", { ref: ref, "data-sx-bg-part": "media", muted: true, loop: true, playsInline: true, preload: "metadata", poster: media.poster, style: { objectFit: media.fit, objectPosition: media.position }, children: media.sources.map((s) => (_jsx("source", { src: s.src, type: s.type }, s.src))) }));
+}
+/** The scroll progress a scrub follows, read live from the runtime. */
+function useProgress(media) {
+    const { scroll } = useBackgroundRuntime("Background.Layer");
+    return () => (media.range === "exit" ? scroll.exit : scroll.progress);
+}
+/**
+ * An image sequence on a canvas: the frame nearest the scroll progress. Frames
+ * start loading only when the layer first comes on screen; until a frame has
+ * loaded, the nearest earlier loaded one is shown (and the poster before any).
+ */
+function FrameScrub({ media, frames }) {
+    const ref = useRef(null);
+    const { onScroll, onVisibility, visible, config } = useBackgroundRuntime("Background.Layer");
+    const progress = useProgress(media);
+    const latest = useRef(progress);
+    latest.current = progress;
+    useEffect(() => {
+        const canvas = ref.current;
+        const ctx = canvas?.getContext("2d");
+        if (!canvas || !ctx || frames.length === 0)
+            return;
+        const images = [];
+        const ready = (img) => !!img && img.complete && img.naturalWidth > 0;
+        const current = () => Math.round(latest.current() * (frames.length - 1));
+        let shown = null;
+        const draw = (force = false) => {
+            let i = current();
+            while (i > 0 && !ready(images[i]))
+                i--;
+            const img = images[i];
+            if (!ready(img) || (img === shown && !force))
+                return;
+            shown = img;
+            const { width, height } = canvas;
+            const scale = (media.fit === "contain" ? Math.min : Math.max)(width / img.naturalWidth, height / img.naturalHeight);
+            const w = img.naturalWidth * scale;
+            const h = img.naturalHeight * scale;
+            ctx.clearRect(0, 0, width, height);
+            ctx.drawImage(img, (width - w) / 2, (height - h) / 2, w, h);
+        };
+        const load = () => {
+            if (images.length > 0)
+                return;
+            frames.forEach((src, i) => {
+                const img = document.createElement("img");
+                img.decoding = "async";
+                img.onload = () => {
+                    if (i <= current())
+                        draw();
+                };
+                img.src = src;
+                images.push(img);
+            });
+        };
+        const resize = () => {
+            const dpr = Math.min(window.devicePixelRatio || 1, config.maxDpr);
+            canvas.width = Math.max(1, Math.round(canvas.clientWidth * dpr));
+            canvas.height = Math.max(1, Math.round(canvas.clientHeight * dpr));
+            draw(true);
+        };
+        resize();
+        if (visible.current)
+            load();
+        const offVisibility = onVisibility((isVisible) => {
+            if (isVisible)
+                load();
+        });
+        const offScroll = onScroll(() => draw());
+        const ro = new ResizeObserver(resize);
+        ro.observe(canvas);
+        return () => {
+            offVisibility();
+            offScroll();
+            ro.disconnect();
+            for (const img of images)
+                img.onload = null;
+        };
+    }, [frames, media.fit, config.maxDpr, onScroll, onVisibility, visible]);
+    return (_jsx("canvas", { ref: ref, "data-sx-bg-part": "canvas", style: media.poster
+            ? { backgroundImage: `url("${media.poster}")`, backgroundSize: media.fit, backgroundPosition: media.position ?? "center" }
+            : undefined }));
+}
+/**
+ * A paused video whose currentTime follows the scroll progress; it never
+ * plays. The file is fetched only once the layer first comes on screen, and
+ * seeks are coalesced: while one is in flight, only the latest target waits.
+ */
+function VideoScrub({ media }) {
+    const ref = useRef(null);
+    const { onScroll, onVisibility, visible } = useBackgroundRuntime("Background.Layer");
+    const progress = useProgress(media);
+    const latest = useRef(progress);
+    latest.current = progress;
+    useEffect(() => {
+        const el = ref.current;
+        if (!el)
+            return;
+        el.muted = true;
+        let pending = null;
+        const seek = () => {
+            if (!Number.isFinite(el.duration) || el.duration <= 0)
+                return;
+            const t = latest.current() * Math.max(0, el.duration - 0.05);
+            if (el.seeking)
+                pending = t;
+            else if (Math.abs(el.currentTime - t) > 1 / 60)
+                el.currentTime = t;
+        };
+        const seeked = () => {
+            if (pending === null)
+                return;
+            const t = pending;
+            pending = null;
+            if (Math.abs(el.currentTime - t) > 1 / 60)
+                el.currentTime = t;
+        };
+        const load = () => {
+            if (el.preload === "auto")
+                return;
+            el.preload = "auto";
+            el.load();
+        };
+        if (visible.current)
+            load();
+        const offVisibility = onVisibility((isVisible) => {
+            if (isVisible)
+                load();
+        });
+        const offScroll = onScroll(seek);
+        el.addEventListener("loadedmetadata", seek);
+        el.addEventListener("seeked", seeked);
+        return () => {
+            offVisibility();
+            offScroll();
+            el.removeEventListener("loadedmetadata", seek);
+            el.removeEventListener("seeked", seeked);
+        };
+    }, [onScroll, onVisibility, visible]);
+    return (_jsx("video", { ref: ref, "data-sx-bg-part": "media", muted: true, playsInline: true, preload: "none", poster: media.poster, style: { objectFit: media.fit, objectPosition: media.position }, children: media.sources.map((s) => (_jsx("source", { src: s.src, type: s.type }, s.src))) }));
+}

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

@@ -0,0 +1,12 @@
+import type { SvgEffect } from "../types.js";
+import { renderSvgElement } from "./svgElement.js";
+export { renderSvgElement };
+/**
+ * Renders an SVG effect: one layer element, its stylesheet and one inline
+ * `<svg>` built from the effect's element tree. Animation is the
+ * stylesheet's job; React renders this once.
+ */
+export declare function SvgHost({ effect, className }: {
+    readonly effect: SvgEffect;
+    readonly className?: string | undefined;
+}): import("react").JSX.Element;

package/dist/backgrounds/hosts/SvgHost.js

@@ -0,0 +1,21 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useId, useRef } from "react";
+import { EffectStyle } from "./CssHost.js";
+import { useLayerNeeds } from "./useLayerNeeds.js";
+import { renderSvgElement } from "./svgElement.js";
+export { renderSvgElement };
+const render = (el, uid, key) => renderSvgElement(el, uid, key);
+/**
+ * Renders an SVG effect: one layer element, its stylesheet and one inline
+ * `<svg>` built from the effect's element tree. Animation is the
+ * stylesheet's job; React renders this once.
+ */
+export function SvgHost({ effect, className }) {
+    const layer = useRef(null);
+    useLayerNeeds(effect.meta, layer);
+    // ids for filters / gradients / clip paths, unique per layer and valid in url(#…)
+    const uid = `sx${useId().replace(/[^\w-]/g, "")}`;
+    const { svg } = effect;
+    return (_jsxs("div", { ref: layer, "data-sx-bg": effect.meta.id, className: className, style: effect.vars, children: [_jsx(EffectStyle, { id: effect.meta.id, css: effect.css }), _jsx("svg", { "data-sx-bg-part": "svg", viewBox: svg.viewBox, preserveAspectRatio: svg.preserveAspectRatio, focusable: "false", children: svg.children.map((child, i) => render(child, uid, i)) })] }));
+}

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

@@ -0,0 +1,19 @@
+import type { WebglEffect } from "../types.js";
+/**
+ * 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 declare function WebglHost({ effect, className }: {
+    readonly effect: WebglEffect;
+    readonly className?: string | undefined;
+}): import("react").JSX.Element;