@sharedex/ui 0.0.0-stage → 0.9.0

package/dist/transitions/shader/textures.d.ts

@@ -0,0 +1,40 @@
+import type { GpuContext } from "../../backgrounds/types.js";
+/** Textures one stage holds at most: previous / current / next. */
+export declare const MAX_TEXTURES = 3;
+/** Largest texture side: beyond this the canvas is drawn upscaled. */
+export declare const MAX_TEXTURE_SIDE = 2048;
+/**
+ * Loads and decodes `url` (CORS: same origin, or served with
+ * `Access-Control-Allow-Origin`), once per page.
+ */
+export declare function decodeImage(url: string): Promise<HTMLImageElement>;
+/** Something `texImage2D` can upload, with its natural size. */
+export interface PictureSource {
+    readonly width: number;
+    readonly height: number;
+    readonly image: TexImageSource;
+}
+export interface TexturePoolOptions {
+    /** Called when a picture finishes loading: draw again. */
+    readonly onReady: () => void;
+    readonly max?: number;
+    /** Load a picture. Default: `decodeImage`. */
+    readonly load?: (url: string) => Promise<PictureSource>;
+    /** Upload `source` into `texture`, cover-cropped to `width` × `height`. Default: through a 2D canvas. */
+    readonly upload?: (gl: GpuContext, texture: WebGLTexture, source: PictureSource, width: number, height: number) => void;
+}
+export interface TexturePool {
+    /**
+     * The pictures to keep, most needed first: the first `max` distinct ones stay
+     * (and load if new), every other texture is deleted now.
+     */
+    want(urls: readonly (string | undefined)[]): void;
+    /** The texture for `url`, uploaded at the current size, or null while it loads (or failed). */
+    get(url: string | undefined): WebGLTexture | null;
+    /** The canvas size; textures are re-uploaded at it when next asked for. */
+    resize(width: number, height: number): void;
+    /** Textures held now. */
+    readonly size: number;
+    dispose(): void;
+}
+export declare function createTexturePool(gl: GpuContext, options: TexturePoolOptions): TexturePool;

package/dist/transitions/shader/textures.js

@@ -0,0 +1,134 @@
+// ---------------------------------------------------------------------------
+// Pictures for shader transitions (atlas rules 1 and 5: preload the next
+// slide, watch WebGL memory).
+//
+// - `decodeImage` loads and decodes a picture once per page (shared by every
+//   stage), so the next one is ready before the user asks for it.
+// - A `TexturePool` keeps at most MAX_TEXTURES pictures on the GPU: the two a
+//   frame blends and the next one. Each is uploaded cropped to the canvas
+//   (cover fit) at the canvas size, never at the picture's own size, and
+//   uploaded again only when the canvas size changes.
+// ---------------------------------------------------------------------------
+import { pictureTexture } from "./program.js";
+/** Textures one stage holds at most: previous / current / next. */
+export const MAX_TEXTURES = 3;
+/** Decoded pictures kept for the page (the browser cache holds the bytes anyway). */
+const MAX_DECODED = 24;
+/** Largest texture side: beyond this the canvas is drawn upscaled. */
+export const MAX_TEXTURE_SIDE = 2048;
+const decoded = new Map();
+/**
+ * Loads and decodes `url` (CORS: same origin, or served with
+ * `Access-Control-Allow-Origin`), once per page.
+ */
+export function decodeImage(url) {
+    const known = decoded.get(url);
+    if (known)
+        return known;
+    const img = new Image();
+    img.crossOrigin = "anonymous";
+    img.decoding = "async";
+    img.src = url;
+    const ready = img.decode().then(() => img);
+    ready.catch(() => decoded.delete(url)); // a failed load may succeed later
+    decoded.set(url, ready);
+    if (decoded.size > MAX_DECODED) {
+        const oldest = decoded.keys().next().value;
+        if (oldest !== undefined)
+            decoded.delete(oldest);
+    }
+    return ready;
+}
+const loadPicture = (url) => decodeImage(url).then((img) => ({ width: img.naturalWidth, height: img.naturalHeight, image: img }));
+let scratch = null;
+/** Draws the picture cover-fitted into a scratch canvas of the texture size, then uploads that. */
+function coverUpload(gl, texture, source, width, height) {
+    scratch ?? (scratch = document.createElement("canvas"));
+    scratch.width = width;
+    scratch.height = height;
+    const ctx = scratch.getContext("2d");
+    if (!ctx)
+        return;
+    const scale = Math.max(width / Math.max(1, source.width), height / Math.max(1, source.height));
+    const w = source.width * scale;
+    const h = source.height * scale;
+    ctx.clearRect(0, 0, width, height);
+    ctx.drawImage(source.image, (width - w) / 2, (height - h) / 2, w, h);
+    pictureTexture(gl, texture);
+    gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, true);
+    gl.pixelStorei(gl.UNPACK_PREMULTIPLY_ALPHA_WEBGL, true);
+    gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, scratch);
+    gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, false);
+    gl.pixelStorei(gl.UNPACK_PREMULTIPLY_ALPHA_WEBGL, false);
+    // keep the scratch canvas, but not its pixels
+    scratch.width = 1;
+    scratch.height = 1;
+}
+export function createTexturePool(gl, options) {
+    const max = options.max ?? MAX_TEXTURES;
+    const load = options.load ?? loadPicture;
+    const upload = options.upload ?? coverUpload;
+    const entries = new Map();
+    let width = 1;
+    let height = 1;
+    let disposed = false;
+    const drop = (url, entry) => {
+        entry.dead = true;
+        entries.delete(url);
+        gl.deleteTexture(entry.texture);
+    };
+    return {
+        want(urls) {
+            const keep = [];
+            for (const url of urls)
+                if (url && !keep.includes(url) && keep.length < max)
+                    keep.push(url);
+            for (const [url, entry] of entries)
+                if (!keep.includes(url))
+                    drop(url, entry);
+            for (const url of keep) {
+                if (entries.has(url))
+                    continue;
+                const texture = gl.createTexture();
+                if (!texture)
+                    continue;
+                const entry = { texture, source: null, uploaded: "", dead: false };
+                entries.set(url, entry);
+                load(url).then((source) => {
+                    if (entry.dead || disposed)
+                        return;
+                    entry.source = source;
+                    options.onReady();
+                }, () => {
+                    if (!entry.dead && !disposed)
+                        console.warn(`[@sharedex/ui] could not load "${url}" for a shader transition (CORS?).`);
+                });
+            }
+        },
+        get(url) {
+            const entry = url ? entries.get(url) : undefined;
+            if (!entry?.source)
+                return null;
+            const key = `${width}x${height}`;
+            if (entry.uploaded !== key) {
+                upload(gl, entry.texture, entry.source, width, height);
+                entry.uploaded = key;
+            }
+            return entry.texture;
+        },
+        resize(w, h) {
+            // beyond the side cap, keep the aspect and let the canvas upscale
+            const scale = Math.min(1, MAX_TEXTURE_SIDE / Math.max(w, h, 1));
+            width = Math.max(1, Math.round(w * scale));
+            height = Math.max(1, Math.round(h * scale));
+        },
+        get size() {
+            return entries.size;
+        },
+        dispose() {
+            disposed = true;
+            for (const [url, entry] of entries)
+                drop(url, entry);
+        },
+    };
+}

package/dist/transitions/stage.d.ts

@@ -0,0 +1,25 @@
+import type { CarouselOptions } from "../carousel/config.js";
+import type { SlotSizing } from "../carousel/engine/types.js";
+import { type CarouselLayout } from "../carousel/layout/types.js";
+import type { CssTransition } from "./types.js";
+/** Slot = viewport: one card fills the stage. Give the Viewport a height (e.g. `aspect-video`). */
+export declare const fillViewport: SlotSizing;
+/** The layout that plays a CSS transition: cards stacked, the incoming one on top, its CSS reading `--sx-p`. */
+export declare function transitionLayout(transition: CssTransition): CarouselLayout;
+/**
+ * Turn a carousel into the one-card mode: each card fills the viewport and
+ * `look` plays when it changes. Returns `CarouselOptions` for `Carousel.Root`'s
+ * `config`; anything in `options` wins, section by section.
+ *
+ * ```tsx
+ * const config = useMemo(() => stage(cube()), []);
+ * <Carousel.Root items={slides} config={config}>…</Carousel.Root>
+ * ```
+ *
+ * - `look` is a stage layout (`cube()`, `tinder()` …) or a CSS transition
+ *   (`wipe()`, `iris()` …, the same ones `Reveal` plays). No look = a plain slide.
+ * - Under reduced motion every look plays as `fade()`.
+ * - The mount buffer grows with the look's `reach` (card stacks keep a few
+ *   cards visible behind the top one).
+ */
+export declare function stage(look?: CarouselLayout | CssTransition, options?: CarouselOptions): CarouselOptions;

package/dist/transitions/stage.js

@@ -0,0 +1,42 @@
+import { composeLayout } from "../carousel/layout/types.js";
+import { track } from "../carousel/layout/modifiers/track.js";
+import { stack } from "../carousel/layout/modifiers/stack.js";
+import { fade } from "./effects/stage/fade.js";
+/** Slot = viewport: one card fills the stage. Give the Viewport a height (e.g. `aspect-video`). */
+export const fillViewport = {
+    kind: "fn",
+    of: (viewport) => ({ main: viewport.main, cross: viewport.cross }),
+};
+const SLIDE = composeLayout("slide", track());
+const REDUCED = fade();
+/** The layout that plays a CSS transition: cards stacked, the incoming one on top, its CSS reading `--sx-p`. */
+export function transitionLayout(transition) {
+    return { ...composeLayout(transition.id, stack()), transition };
+}
+const isTransition = (look) => "kind" in look && look.kind === "css";
+/**
+ * Turn a carousel into the one-card mode: each card fills the viewport and
+ * `look` plays when it changes. Returns `CarouselOptions` for `Carousel.Root`'s
+ * `config`; anything in `options` wins, section by section.
+ *
+ * ```tsx
+ * const config = useMemo(() => stage(cube()), []);
+ * <Carousel.Root items={slides} config={config}>…</Carousel.Root>
+ * ```
+ *
+ * - `look` is a stage layout (`cube()`, `tinder()` …) or a CSS transition
+ *   (`wipe()`, `iris()` …, the same ones `Reveal` plays). No look = a plain slide.
+ * - Under reduced motion every look plays as `fade()`.
+ * - The mount buffer grows with the look's `reach` (card stacks keep a few
+ *   cards visible behind the top one).
+ */
+export function stage(look = SLIDE, options = {}) {
+    const layout = isTransition(look) ? transitionLayout(look) : look;
+    const reach = layout.reach ?? 1;
+    return {
+        ...options,
+        engine: { gap: 0, sizing: fillViewport, buffer: Math.max(2, reach + 1), ...options.engine },
+        // Past `reach` a stage slot is invisible: publishing a still distance there spares a restyle per frame.
+        layout: { ...layout, distanceRange: layout.distanceRange ?? [-reach, reach], ...(layout.reduced ? {} : { reduced: REDUCED }) },
+    };
+}

package/dist/transitions/types.d.ts

@@ -0,0 +1,97 @@
+import type { SvgElement, UniformValue } from "../backgrounds/types.js";
+/**
+ * - `stage`: a carousel layout for the one-card mode (transform buffer).
+ * - `css` / `svg`: a stylesheet driven by `--sx-p` (Phase 2+).
+ * - `webgl`: a shader blending two pictures (`ShaderTransition`).
+ */
+export type TransitionKind = "stage" | "css" | "svg" | "webgl";
+/** Where a transition can play: a one-card carousel, a section reveal, or both. */
+export type TransitionMode = "carousel" | "reveal";
+/** The atlas group a transition comes from. */
+export type TransitionGroup = "cfree" | "cpaid" | "shader" | "mask" | "scroll";
+/** The lowest device tier that runs it (same scale as backgrounds). */
+export type TransitionTier = "all" | "mid" | "high";
+/** CSS custom properties, as written inline on the element. */
+export type TransitionVars = Readonly<Record<`--${string}`, string | number>>;
+/**
+ * A generated child (a strip, a cell). Rendered as `<span data-sx-tr-node={part}>`
+ * after the content. `media: true` puts the transition's picture inside it.
+ */
+export interface TransitionNode {
+    readonly part: string;
+    /** Inline custom properties. `{uid}` in a value becomes an id unique to the element (`url(#{uid}-goo)`). */
+    readonly vars?: TransitionVars;
+    readonly media?: boolean;
+    readonly children?: readonly TransitionNode[];
+    /** An inline `<svg>` inside the node (strokes, filters). Colours come from the CSS, never attributes. */
+    readonly svg?: TransitionSvg;
+}
+export interface TransitionSvg {
+    readonly viewBox: string;
+    readonly preserveAspectRatio?: string;
+    readonly children: readonly SvgElement[];
+}
+/**
+ * A CSS / SVG transition: a stylesheet driven by `--sx-p` (0 = hidden,
+ * 1 = shown), plus the option values as custom properties and any generated
+ * nodes. The same descriptor plays in a one-card carousel (`stage(wipe())`) and
+ * in a section reveal (`<Reveal effect={wipe()}>`). See ./CLAUDE.md.
+ *
+ * Structurally a `LayoutTransition`, so a carousel layout can carry it.
+ */
+export interface CssTransition {
+    readonly kind: "css";
+    /** The `data-sx-tr` value its stylesheet is keyed on (`meta.id`, or `<id>-lite`). */
+    readonly id: string;
+    readonly tier: TransitionTier;
+    readonly meta: TransitionMeta;
+    readonly css: string;
+    readonly vars: TransitionVars;
+    readonly nodes: readonly TransitionNode[];
+    /** The picture a carousel card shows in this transition (`slicer`). */
+    readonly media?: ((item: unknown) => string | undefined) | undefined;
+    /** Used instead on devices below `tier`. Every `mid` / `high` transition has one. */
+    readonly fallback?: CssTransition | undefined;
+}
+/**
+ * A shader transition: one fragment shader that blends two pictures (`from`,
+ * `to`) by `u_progress`. It plays in `Carousel.Shader` (the carousel's
+ * pictures) and in `<Reveal image>` (from nothing to the picture). The
+ * fragment defines `vec4 transition(vec2 uv)` and may call `getFrom(uv)` /
+ * `getTo(uv)`; see `shader/program.ts` for everything it gets. See ./CLAUDE.md.
+ *
+ * Structurally a `LayoutTransition` (empty `css`, no vars or nodes), so the
+ * device-tier pick walks its fallback chain like any other transition.
+ */
+export interface ShaderTransition {
+    readonly kind: "webgl";
+    readonly id: string;
+    readonly tier: TransitionTier;
+    readonly meta: TransitionMeta;
+    /** GLSL ES 1.0 defining `vec4 transition(vec2 uv)`, plus its own uniform declarations. */
+    readonly fragment: string;
+    /** The values of the uniforms `fragment` declares (set once per program). */
+    readonly uniforms: Readonly<Record<string, UniformValue>>;
+    /** CSS colours (var() allowed), resolved on the host as `u_c0`, `u_c1` … */
+    readonly colors: readonly string[];
+    /** A picture the shader samples as `u_map` (a displacement map). */
+    readonly map?: string | undefined;
+    /** Stable string of the options: the host rebuilds the program only when it changes. */
+    readonly signature: string;
+    readonly css: "";
+    readonly vars: TransitionVars;
+    readonly nodes: readonly TransitionNode[];
+    /** Plays instead (on the pictures, as `<img>`s) without WebGL or on a weaker device. */
+    readonly fallback: CssTransition;
+}
+export interface TransitionMeta {
+    /** The factory's name in the barrel (`cube`, `noiseBurn` …). */
+    readonly id: string;
+    readonly label: string;
+    readonly kind: TransitionKind;
+    readonly modes: readonly TransitionMode[];
+    readonly group: TransitionGroup;
+    readonly tier: TransitionTier;
+    /** One line for the docs table. */
+    readonly description: string;
+}

package/dist/transitions/types.js

@@ -0,0 +1,4 @@
+// ---------------------------------------------------------------------------
+// Transition descriptors and their metadata. See ./CLAUDE.md.
+// ---------------------------------------------------------------------------
+export {};

package/guides/README.md

@@ -0,0 +1,61 @@
+# @sharedex/ui section guides (for Claude Code)
+
+One guide per headless section. Read the guide for a section before building or
+restyling it. They ship inside the package, so they always match the installed
+version: `node_modules/@sharedex/ui/guides/<section>.md`.
+
+| Section | Guide |
+|---|---|
+| Hero | [hero.md](hero.md) |
+| About | [about.md](about.md) |
+| Services | [services.md](services.md) |
+| Contact | [contact.md](contact.md) |
+| Backgrounds (any section) | [backgrounds.md](backgrounds.md) |
+| Transitions (reveals, slideshows, scroll effects) | [transitions.md](transitions.md) |
+| Galleries: 3D carousels, Ticker, Grid | [gallery.md](gallery.md) |
+| Buttons and their effects (any section's actions) | [buttons.md](buttons.md) |
+| Text effects (titles, eyebrows, cycling words, rolling figures) | [text.md](text.md) |
+
+## Rules for every section
+
+- **Layout and content come from the package; the look comes from the project.**
+  Pick the layout with the `layout` prop and pass the client's real copy in
+  `content`. Don't rebuild a section from scratch with divs.
+- **The default look reads only the `sx-*` tokens.** In a project generated by
+  the sharedex Design System Builder, `design/theme.css` already points them at
+  the project's brand, so sections match before you change anything.
+- **Configured pieces are already in `design/effects.ts`** (in a project the
+  builder generated): the primary buttons' effects, backgrounds, reveals,
+  slideshow looks, carousel configs, and the props of tickers, grids and scroll
+  effects, the headings' text effects (`titleEffects`, `eyebrowEffects`), as
+  named constants.
+  Import them by the names `design/page-plan.md` uses and spread or pass them
+  as it shows; don't re-create them, and never call an effect factory during
+  render (a new object every render restarts it).
+- **Server Components (Next.js App Router)**: sections, CSS / SVG / image
+  backgrounds, reveals and scroll effects work in a Server Component. Carousels,
+  slideshows, Tickers and Grids take functions as children, and canvas / WebGL /
+  Three.js backgrounds are programs: a page using them is `"use client"`, or
+  keeps them in a client component of its own.
+- **Restyle with `className` on any part.** Defaults sit in Tailwind's
+  `components` layer; your utility classes always win. Never use `!important`.
+- **`unstyled` on `Root`** removes every visual default and keeps the layout.
+  Use it only when the design differs from the default in most parts.
+- **`background` on `Root`** takes a decorative layer, usually
+  `<Background.Root effect={…} />`. It sits behind the content automatically.
+  See [backgrounds.md](backgrounds.md) for picking an effect.
+- **`reveal` on `Root`** makes the main parts appear one after another when the
+  section scrolls into view: `reveal` (fadeUp), `reveal={blurFade()}`, or
+  `reveal={{ effect, stagger, delay }}`. See [transitions.md](transitions.md).
+- **`actionEffect` on `Hero.Root`** turns the actions into `Button`s, the first
+  wearing the effects. See [buttons.md](buttons.md).
+- **`titleEffect` / `eyebrowEffect` on every `Root`** put text effects on the
+  title and the eyebrow; the Hero's `titleWords` + `titleCycle` add a cycling
+  word, About's `statRoll` rolls the figures. See [text.md](text.md).
+- **Compose parts to change structure**: render `<X.Root>` with your own
+  children and place the parts (and your own elements) in the order you need.
+- **Layouts respond to the section's own width** (container queries), not the
+  viewport. Don't add breakpoint classes to change a layout's column count;
+  pick another layout instead.
+- **RTL works through logical properties.** Use `ms-*`/`me-*`/`ps-*`/`pe-*` and
+  `text-start`/`text-end` in your own classes too.

package/guides/about.md

@@ -0,0 +1,80 @@
+# About
+
+Who the client is: a few paragraphs, optional key figures and an image.
+
+```tsx
+import { About } from "@sharedex/ui";
+
+<About.Root
+  layout="story"
+  content={{
+    eyebrow: "About us",
+    title: "Three generations, one oven",
+    body: [
+      "Maria opened the bakery with a single wood-fired oven.",
+      "Today her grandchildren run the shop with the same recipes.",
+    ],
+    stats: [
+      { value: "1998", label: "Year we opened" },
+      { value: "400", label: "Loaves a day" },
+    ],
+    media: { kind: "image", src: "/team.jpg", alt: "The family behind the counter" },
+  }}
+/>
+```
+
+## Layouts
+
+| `layout` | Use when |
+|---|---|
+| `story` | A portrait photo of people or place. Tall image beside text and figures. |
+| `split-stats` | The figures are the point. Text beside a figure grid, wide image below. |
+| `centered` | Short text, no strong image. One centred column. |
+
+## Content
+
+```ts
+interface AboutContent {
+  eyebrow?: string;
+  title: string;                       // <h2>
+  body: string | string[];             // one string per paragraph
+  stats?: { value: string; label: string }[];  // "1998" / "Year we opened"
+  media?: SectionMedia;                // same shape as the Hero's media
+}
+```
+
+## Parts
+
+`About.Root` › `About.Text` (`About.Eyebrow`, `About.Title` `<h2>`,
+`About.Body`) · `About.Stats` (`<dl>`: `<dt>` label, `<dd>` value, shown value
+first) · `About.Media`.
+
+## Background
+
+`<About.Root background={<Background.Root effect={dotPattern()} />}>` draws a decorative layer behind
+the content (the section is its stacking context, so the content needs no z-index). Any effect from
+`@sharedex/ui` works, or from `@sharedex/ui/three` for the Three.js ones. Keep it quiet: a pattern or a still texture (`dotPattern`, `filmGrain`), not a second hero. Read
+`node_modules/@sharedex/ui/guides/backgrounds.md` before picking one.
+
+## Reveal
+
+`reveal` on `Root` plays a transition on the main parts as the section scrolls into view, once:
+the text, then the stats, then the media. `reveal` alone is `fadeUp()`, 0.12 s apart; `reveal={blurFade()}` picks the transition;
+`reveal={{ effect, stagger, delay, duration }}` sets the timing. See
+`node_modules/@sharedex/ui/guides/transitions.md`.
+
+## Text effects
+
+`titleEffect` and `eyebrowEffect` on `Root` put text effects on the title and the eyebrow (one, or a list that
+stacks): they render as `Text` wearing them. Left out, they stay plain elements. In a project the sharedex Design
+System Builder generated, pass the configured constants: `titleEffect={titleEffects}`, `eyebrowEffect={eyebrowEffects}`
+from `design/effects.ts`.
+
+**Rolling figures.** `statRoll` on `Root` (`true`, or `{ look: "spin", duration: 2 }`) rolls each figure written as
+one number to it once in view, keeping what surrounds it: `"40+"` rolls to 40 and keeps its `+`. A figure that isn't
+one plain number (`"1 000"`) stays as written; the final value is in the HTML. Read `node_modules/@sharedex/ui/guides/text.md`.
+
+## Don't
+
+- Don't invent figures. Ask the client; leave `stats` out if there are none.
+- Don't write more than three short paragraphs; link to a full story page instead.

package/guides/backgrounds.md

@@ -0,0 +1,107 @@
+# Backgrounds (for Claude Code)
+
+`Background` draws decorative layers behind content: patterns, gradients, particles, shaders, 3D.
+Every effect is a factory returning a plain description (`aurora({ speed: 0.6 })`); one runtime
+under `<Background.Root>` handles timing, pausing off screen, reduced motion, device tiers and the
+pixel-ratio cap, so the effects never need tuning for that.
+
+## Use it
+
+```tsx
+import { Background, aurora, filmGrain, Hero } from "@sharedex/ui";
+
+// inside a section: the section is its stacking context
+<Hero.Root content={heroContent} background={<Background.Root effect={aurora()} />} />
+
+// anywhere else: the parent needs `relative isolate` (position + its own stacking context)
+<div className="relative isolate">
+  <Background.Root>
+    <Background.Layer effect={aurora({ speed: 0.6 })} />
+    <Background.Layer effect={filmGrain({ opacity: 0.08 })} />
+  </Background.Root>
+  …content, no z-index needed…
+</div>
+```
+
+Layers stack back to front. Every factory takes `opacity`, `blend` (a mix-blend-mode) and `mask`
+(`"radial"`, `"fade-top"`, `"fade-bottom"`, `"fade-edges"` or any CSS mask image). The background is
+`aria-hidden` and never takes pointer events: it must never carry content.
+
+## Pick an effect
+
+The docs site's atlas lists every effect with its cost. In short:
+
+| Kind | Examples | Cost |
+|---|---|---|
+| CSS | `aurora`, `dotPattern`, `gradientGrid`, `filmGrain`, `meteors`, patterns | Tiny; runs everywhere |
+| SVG | `svgWave`, `contourLines`, `drawingLines`, `mountains` | Tiny; runs everywhere (`gooeyBlobs`: mid) |
+| Scroll | `parallax`, `scrollColor`, `scrollTimeline`, `cinematicReveal` | Tiny; follow scroll position |
+| Canvas | `particles`, `starfield`, `constellation`, `matrixRain`, `flowField` | Some CPU per frame |
+| WebGL | `meshGradient`, `grainGradient`, `aether`, `caustics`, `liquid` | GPU; mid tier and up |
+| Advanced WebGL | `fluidCursor`, `waterRipple`, `liquidSculpture`, `wireframeOcean` | Heavy GPU; mid / high tier |
+| Three.js | `liquidGlass`, `chrome`, `neonTubes` … from `@sharedex/ui/three` | ~170 KB of Three.js; high tier |
+
+- **Default to CSS or SVG.** They cost almost nothing and run on every phone.
+- **WebGL and Three.js effects have a tier** (`mid`, `high`). On a weaker device, before the device
+  is known, during server rendering, and when WebGL fails, they show their still CSS fallback. You
+  don't need to handle this. Phones get `mid` at most, except those with a flagship GPU (Snapdragon 8
+  Gen 1 or newer, Immortalis, recent Mali / Xclipse), which get `high`.
+- **`@sharedex/ui/three` needs `three`** (an optional peer): `npm i three`. Import those effects
+  from `@sharedex/ui/three`, and `Background` itself from `@sharedex/ui`.
+- **One expensive effect per page**, at most. A hero with `meshGradient` is fine; three WebGL
+  sections on one page are not (browsers allow ~16 WebGL contexts, and every one costs battery).
+- **Keep text readable.** Use the theme's colours (the defaults already do), lower `opacity`, or a
+  `mask`. `aether` has a built-in `veil` behind the text side.
+
+## Root options
+
+`<Background.Root quality="auto" maxDpr={1.5} fps={0} pauseOffscreen reducedMotion="still">`
+
+- `quality`: `"auto"` detects the device tier; force `"low"` / `"mid"` / `"high"` to test fallbacks.
+- `reducedMotion`: `"still"` (default) shows one frame, `"slow"` runs at a third of the speed,
+  `"ignore"` keeps full motion. Respect the default unless the client explicitly decides otherwise.
+- `fps` caps canvas / WebGL frame rates (0 = the display's rate).
+
+## Colours
+
+Effects take `colors` (or `color`) as any CSS colours; the defaults are the `sx-*` tokens, so a
+theme switch recolours them, WebGL ones included. Prefer `var(--color-sx-*)` and `color-mix()`
+over literal colours.
+
+## Your own file
+
+`image({ src })` and `video({ src, poster })` are layers too: a texture, a paper edge, a dust
+overlay, a looping clip (muted, paused off screen, poster under reduced motion).
+`videoScrub({ src | frames })` ties a video or image sequence to scroll position.
+
+## Spline, Lottie, Rive
+
+Their runtimes are not bundled. Put the player inside `Background.Root` as a child, load it after
+the first paint, and keep a still image underneath as the fallback:
+
+```tsx
+import { lazy, Suspense } from "react";
+import { Background, image } from "@sharedex/ui";
+
+const Spline = lazy(() => import("@splinetool/react-spline"));
+
+<Background.Root>
+  <Background.Layer effect={image({ src: "/scene-still.webp", loading: "eager" })} />
+  <Suspense fallback={null}>
+    <div data-sx-bg="spline" style={{ position: "absolute", inset: 0 }}>
+      <Spline scene="https://prod.spline.design/…/scene.splinecode" />
+    </div>
+  </Suspense>
+</Background.Root>
+```
+
+Lottie (`lottie-react` or `@lottiefiles/dotlottie-react`) and Rive (`@rive-app/react-canvas`) follow
+the same pattern: lazy import, absolutely positioned wrapper, still image below. Under reduced
+motion, don't mount the player at all (keep the still).
+
+## Don't
+
+- Don't put text, links or buttons inside `Background.Root`.
+- Don't animate the background with your own `requestAnimationFrame`; write an effect instead
+  (`defineCssEffect`, `defineCanvasEffect`, `defineWebglEffect`, `defineGpuEffect`).
+- Don't give content a `z-index` to sit above the background; the stacking context does it.